docs(sdk): lancement des serveurs MCP JavaScript packagés — #294 (manifest: aucune substitution ${node}/${runtimeNode}/${hostNode} ni champ runtime, IdeA ne fournit pas de runtime Node plugin-scoped; command n'est pas du shell — démarrage direct avec args séparés, pas de fichiers de startup/alias/PATH du shell de login; command relatif résolu sous pluginRoot — command:"node" sans allowAbsoluteCommand devient ${pluginRoot}/node (cause ENOENT UnityPlugin #12); absolu littéral refusé sans allowAbsoluteCommand=true, command devenu absolu après substitution ${pluginRoot}/${appDataDir} passé tel quel; shebang #!/usr/bin/env node dépend du node visible du process app IdeA; recommandations: exécutable packagé incluant son runtime ou runtime géré sous stockage plugin/app pointé via ${pluginRoot}/${appDataDir}, sinon dépendance hôte explicite absolue /usr/bin/node avec allowAbsoluteCommand=true et scripts dans args; même règle pour command:"bash"; packaging-distribution: section Packaged Executables And Runtimes — bit exécutable et shebang valides dans le package installé, éviter le bare command:"node" en plugins distribués/multi-harness; services: distinction runCommand() (exécutable hôte de l'environnement task, aucune substitution) vs règles manifest mcpServers avec lien croisé; affirmations vérifiées par Git contre l'hôte crates/application/src/plugin/mod.rs:3199 substitution puis looks_absolute/allow_absolute_command sinon préfixage pluginRoot, et validation :3637 absolu littéral sans flag rejeté; QA verte reconfirmée par Git: npm run check — build, typecheck:examples, package:hello-plugin)
This commit is contained in:
@ -283,8 +283,10 @@ MCP server contribution rules:
|
||||
- `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.
|
||||
- A literal absolute `command` is rejected unless `allowAbsoluteCommand: true`
|
||||
is set. Use this only for an intentional dependency on a host binary.
|
||||
- A `command` that becomes absolute after `${pluginRoot}` or `${appDataDir}`
|
||||
substitution is allowed and is passed through as substituted.
|
||||
- `cwd` defaults to `${pluginRoot}` when omitted.
|
||||
|
||||
The tools an agent can call are assigned with the triplet
|
||||
@ -307,16 +309,56 @@ declared MCP server. In `command`, `args`, `env` and `cwd`, the host expands:
|
||||
- `${pluginRoot}` to the installed plugin package root.
|
||||
- `${appDataDir}` to the host-owned application data directory.
|
||||
|
||||
There is currently no `${node}`, `${runtimeNode}`, `${hostNode}` substitution
|
||||
and no `runtime` field. IdeA does not provide a plugin-scoped Node.js runtime
|
||||
for MCP servers.
|
||||
|
||||
This string substitution is limited to manifest-declared MCP server startup.
|
||||
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`.
|
||||
`command` is not shell syntax. IdeA starts it directly and passes `args`
|
||||
separately. Do not rely on shell startup files, shell aliases, or a user's login
|
||||
shell `PATH`.
|
||||
|
||||
Prefer a packaged executable for plugin-owned MCP servers:
|
||||
|
||||
```json
|
||||
{
|
||||
"command": "scripts/unity-mcp-server",
|
||||
"transport": "stdio",
|
||||
"autoStart": true
|
||||
}
|
||||
```
|
||||
|
||||
Because the command is package-relative, IdeA resolves it to
|
||||
`${pluginRoot}/scripts/unity-mcp-server`. If this file is a script, its shebang
|
||||
and executable bit must be valid in the installed package. A JavaScript shebang
|
||||
such as `#!/usr/bin/env node` still depends on a `node` binary visible to the
|
||||
IdeA app process, not necessarily the user's interactive shell.
|
||||
|
||||
For JavaScript MCP servers that must not depend on the user's shell `PATH`, use
|
||||
one of these approaches:
|
||||
|
||||
- Ship an executable server that includes its runtime, or install a managed
|
||||
runtime under plugin/app-owned storage and point `command` at that executable
|
||||
with `${pluginRoot}` or `${appDataDir}`.
|
||||
- Declare an explicit host dependency with an absolute command such as
|
||||
`/usr/bin/node`, set `allowAbsoluteCommand: true`, and keep plugin-owned
|
||||
script paths in `args`.
|
||||
|
||||
Avoid `command: "node"` for a packaged MCP server. With
|
||||
`allowAbsoluteCommand: false`, it is treated as package-relative and resolves to
|
||||
`${pluginRoot}/node`. With `allowAbsoluteCommand: true`, it is passed as a host
|
||||
command name and depends on the environment inherited by IdeA, which may differ
|
||||
from an interactive shell.
|
||||
|
||||
The same rule applies to shell wrappers. `command: "bash"` resolves to
|
||||
`${pluginRoot}/bash` unless absolute-command handling is explicitly enabled. Use
|
||||
a package-relative wrapper executable, or use an absolute shell such as
|
||||
`/bin/bash` with `allowAbsoluteCommand: true` when that host dependency is
|
||||
intentional.
|
||||
|
||||
## Validation
|
||||
|
||||
|
||||
Reference in New Issue
Block a user