---
issueRef: "#294"
version: 4
updatedBy: {"kind":"agent","agent_id":"a6c6ea12-bfc6-4bdc-8031-324102dfa34d"}
updatedAt: 1788963918771
---

## QA - 2026-09-09 - Validation doc-only SDK

Périmètre vérifié dans le submodule `sdk/IdeaSDK`, branche `feature/294-node-mcp-launch-docs`.

Diff relu : modifications limitées à `docs/manifest.md`, `docs/services.md` et `docs/packaging-distribution.md`.

Commandes exécutées :

```bash
git status --short --branch
```

Sortie :

```text
## feature/294-node-mcp-launch-docs
 M docs/manifest.md
 M docs/packaging-distribution.md
 M docs/services.md
```

```bash
git diff --stat
```

Sortie :

```text
 docs/manifest.md               | 56 ++++++++++++++++++++++++++++++++++++------
 docs/packaging-distribution.md | 19 ++++++++++++++
 docs/services.md               |  9 ++++++-
 3 files changed, 76 insertions(+), 8 deletions(-)
```

```bash
rg -n "\\$\\{node\\}|\\$\\{runtimeNode\\}|\\$\\{hostNode\\}|runtime Node|plugin-scoped Node|command: \\\"node\\\"|allowAbsoluteCommand|shell|package-relative|runCommand\\(\\)|\\$\\{pluginRoot\\}|\\$\\{appDataDir\\}" docs/manifest.md docs/services.md docs/packaging-distribution.md
```

Sortie essentielle :

```text
docs/packaging-distribution.md:49:starting the declared `command` directly. IdeA does not inject a shell and does
docs/packaging-distribution.md:50:not provide a plugin-scoped Node.js runtime.
docs/packaging-distribution.md:52:For a packaged MCP server, prefer a package-relative executable such as
docs/packaging-distribution.md:61:or declare an explicit absolute host dependency with `allowAbsoluteCommand:
docs/packaging-distribution.md:62:true`. Avoid relying on a bare `command: "node"` in distributed or multi-harness
docs/services.md:45:as read-only. Unlike manifest-declared MCP servers, `runCommand()` does not
docs/services.md:54:  command: "node",
docs/services.md:63:[Manifest](manifest.md), where a bare `command: "node"` is package-relative
docs/manifest.md:313:and no `runtime` field. IdeA does not provide a plugin-scoped Node.js runtime
docs/manifest.md:321:`command` is not shell syntax. IdeA starts it directly and passes `args`
docs/manifest.md:351:Avoid `command: "node"` for a packaged MCP server. With
docs/manifest.md:352:`allowAbsoluteCommand: false`, it is treated as package-relative and resolves to
docs/manifest.md:353:`${pluginRoot}/node`. With `allowAbsoluteCommand: true`, it is passed as a host
```

```bash
npm run check
```

Sortie essentielle :

```text
> @idea/plugin-sdk@0.1.0 check
> npm run build && npm run typecheck:examples && npm run package:hello-plugin

> @idea/plugin-sdk@0.1.0 build
> tsc -p tsconfig.json

> @idea/plugin-sdk@0.1.0 typecheck:examples
> tsc -p examples/hello-plugin/tsconfig.json --noEmit

> @idea/plugin-sdk@0.1.0 package:hello-plugin
> npm run build && npm run build:hello-plugin && node scripts/package-hello-plugin.mjs

> @idea/plugin-sdk@0.1.0 build
> tsc -p tsconfig.json

> @idea/plugin-sdk@0.1.0 build:hello-plugin
> tsc -p examples/hello-plugin/tsconfig.build.json

created /home/anthony/Documents/Projects/IdeA/sdk/IdeaSDK/examples/hello-plugin/build/hello-plugin-0.1.0.zip
```

Lecture QA : la documentation clarifie bien qu'il n'existe pas de substitution `${node}`, `${runtimeNode}`, `${hostNode}` ni de runtime Node plugin fourni par IdeA ; qu'un `command` MCP est lancé directement sans shell ; qu'un `command` relatif est résolu sous `${pluginRoot}` ; que `command: "node"` devient `${pluginRoot}/node` avec `allowAbsoluteCommand: false` ; qu'une dépendance host absolue requiert `allowAbsoluteCommand: true` ; et que les serveurs JS reproductibles doivent vendor/installer un runtime ou déclarer explicitement une dépendance absolue.

Verdict QA : VERT.

## Git - 2026-09-09 - Intégration locale

Cycle Git terminé, sans push.

- SDK submodule `sdk/IdeaSDK` : commit feature `b5a3556` (`docs(sdk): clarifie le lancement Node des serveurs MCP plugins`) puis merge local `fdb3a90` sur `develop`.
- Repo parent IdeA : commit `b1c173f` sur `develop` (`chore(sdk): bump du pointeur IdeaSDK pour #294`).
- Vérification reconfirmée par Git : `npm run check` vert.

Réserves : le submodule SDK est en avance sur origin avec les travaux #293/#294, et le parent `develop` est en avance localement. Aucune action distante effectuée. Fichiers `.ideai/tickets/*` et `scripts/` hors périmètre laissés tels quels.

## Réponse contractuelle pour UnityPlugin #12

1. Pour un serveur MCP stdio JavaScript packagé, le contrat actuel est de lancer un `command` manifest direct, sans shell. Pour ne pas dépendre du PATH shell utilisateur, il faut pointer `command` vers un exécutable reproductible : package-relative sous `${pluginRoot}` ou géré sous `${appDataDir}`. Un `.mjs` avec shebang `#!/usr/bin/env node` reste dépendant du Node visible par le process IdeA, pas du shell interactif.
2. Il n'existe pas de substitution officielle `${node}`, `${runtimeNode}`, `${hostNode}` ni de champ `runtime`. IdeA ne fournit pas actuellement de runtime Node plugin-scoped.
3. `allowAbsoluteCommand: false` rejette les commandes absolues littérales dans le manifest, mais n'interdit pas un `command` qui devient absolu après substitution `${pluginRoot}`/`${appDataDir}`. `command: "bash"` est relatif et devient `${pluginRoot}/bash`; `/bin/bash` exige `allowAbsoluteCommand: true`. Préférer `command: "scripts/wrapper"` pour un wrapper packagé exécutable.
4. Solution compatible aujourd'hui : packager un exécutable MCP autonome ou installer/vendor un runtime sous le package/appData et pointer dessus. À défaut, déclarer explicitement une dépendance host absolue (`/usr/bin/node` ou `/bin/bash`) avec `allowAbsoluteCommand: true`. Un wrapper de résolution Node peut améliorer le diagnostic, mais ne supprime pas la dépendance si aucun runtime n'est fourni.
5. Documentation SDK enrichie dans `docs/manifest.md`, `docs/services.md`, `docs/packaging-distribution.md`.