docs(sdk): contrat d'exposition des tools MCP par les plugins — #293 (manifest: section MCP Servers And Agent Tools — contributes.mcpServers est le seul canal IdeA-native, aucun registerMcpTool/registerServer dans activate(ctx), règles id/displayName/transport stdio/autoStart requis pour la réconciliation MCP/command relatif résolu sous pluginRoot vs absolu refusé sans allowAbsoluteCommand/cwd défaut ${pluginRoot}, assignation par triplet pluginId/serverId/toolName devant matcher tools/list du serveur, example manifest aligné contributes.skills, guidance script packagé exécutable vs lancement via binaire hôte; activation-context: activate n'expose pas d'API d'enregistrement de tools MCP — ils viennent du process serveur stdio externe et de sa réponse tools/list, ctx.pluginRoot officialisé vs import.meta.url; project-plugin-assignments: assignation résolue vers serveurs manifestés autoStart uniquement, flow skill → serveur MCP → tools assignés sans chemins relatifs depuis le Markdown servi par idea_skill_read; QA verte reconfirmée par Git: npm run check — build, typecheck:examples, package:hello-plugin)

docs/manifest.md

@@ -115,6 +115,7 @@ development loop.
   "capabilities": ["ui", "tooling"],
   "activationScope": "app",
   "contributes": {
+    "skills": [],
     "menus": [],
     "menuItems": [],
     "layouts": [],
@@ -247,6 +248,57 @@ Contribution ids are part of the runtime contract:
 - `services.windows.open({ layoutType })` only accepts a layout type declared by
   the calling plugin.
 
+## MCP Servers And Agent Tools
+
+`contributes.mcpServers` is the IdeA-native contract for plugin-provided
+agent tools. A plugin does not register individual MCP tools from `activate(ctx)`.
+Instead, the plugin ships or references a stdio MCP server process, declares it
+in the manifest, and that server advertises its own tools through the MCP
+`tools/list` protocol.
+
+```json
+{
+  "capabilities": ["mcp"],
+  "contributes": {
+    "mcpServers": [
+      {
+        "id": "unity-editor",
+        "displayName": "Unity Editor Tools",
+        "command": "scripts/unity-mcp-server.mjs",
+        "args": [],
+        "cwd": "${pluginRoot}",
+        "transport": "stdio",
+        "autoStart": true
+      }
+    ]
+  }
+}
+```
+
+MCP server contribution rules:
+
+- `id` is stable within the plugin and is used by project/agent assignments.
+- `displayName` is the human-readable server name shown in plugin settings.
+- `transport` must currently be `"stdio"`.
+- `autoStart: true` is required for IdeA to start the server during plugin MCP
+  reconciliation. Non-auto-start servers are manifest metadata only today.
+- A relative `command` is resolved under the installed plugin package root.
+- An absolute `command` is rejected unless `allowAbsoluteCommand: true` is set.
+  Use this only for an intentional dependency on a host binary.
+- `cwd` defaults to `${pluginRoot}` when omitted.
+
+The tools an agent can call are assigned with the triplet
+`pluginId`/`serverId`/`toolName` in project plugin settings. `toolName` must
+match a tool name advertised by the MCP server. IdeA does not currently provide
+a runtime API such as `ctx.mcp.registerTool()` or `ctx.mcp.registerServer()`.
+
+For multi-harness workflows, keep `contributes.skills` as instructions and
+expose executable behavior through assigned MCP tools. Do not make skill
+Markdown depend on filesystem paths relative to the Markdown returned by
+`idea_skill_read`; that body is served as read-only content, not mounted as a
+working directory. If a skill needs packaged scripts, put the script behind a
+manifest-declared MCP server and tell the agent to call the assigned tool.
+
 ## MCP Server Paths
 
 `contributes.mcpServers` entries are resolved by the host before starting a
@@ -260,6 +312,12 @@ Runtime handlers receive the same installed package location separately as
 `ctx.pluginRoot`; `ctx.services.tasks.runCommand()` does not perform placeholder
 substitution, and workspace APIs remain project-confined.
 
+Prefer a packaged executable script for plugin-owned MCP servers, for example
+`command: "scripts/unity-mcp-server.mjs"` with an appropriate shebang and file
+mode. If the server must be launched through a host executable such as Node,
+use an absolute command with `allowAbsoluteCommand: true` and keep plugin-owned
+paths in `args`, for example `${pluginRoot}/scripts/unity-mcp-server.mjs`.
+
 ## Validation
 
 Use the SDK validator in tests or build tooling: