IdeA/.ideai/tickets/294/carnet.md

issueRef, version, updatedBy, updatedAt

issueRef	version	updatedBy	updatedAt
#294	4	kind agent_id agent a6c6ea12-bfc6-4bdc-8031-324102dfa34d	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 :

git status --short --branch

Sortie :

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

git diff --stat

Sortie :

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

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 :

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

npm run check

Sortie essentielle :

> @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.