@chrischall/mcp-utils 3.0.1 → 3.0.2

package/README.md

@@ -2345,10 +2345,39 @@ exit code unless you pass `--strict`**:
   (`server.mcp_config.env` + `user_config`), `server.json`
   (`packages[].environmentVariables`) and `.mcp.json`: undeclared reads, dead
   declarations, a var marked required that the code only reads optionally, a
-  `user_config` entry nothing passes to the server, and a cwd-relative script
-  path in `.mcp.json` (anchor it with `${CLAUDE_PLUGIN_ROOT}`). `MCP_*` keys
-  (this library's own knobs) and runtime vars (`NODE_ENV`, `HOME`, …) are
-  ignored. A key built at runtime (`` readEnvVar(`${P}_TOKEN`) ``) is invisible.
+  `user_config` entry nothing passes to the server, and the
+  `${CLAUDE_PLUGIN_ROOT}` rule below. `MCP_*` keys (this library's own knobs)
+  and runtime vars (`NODE_ENV`, `HOME`, …) are ignored. A key built at runtime
+  (`` readEnvVar(`${P}_TOKEN`) ``) is invisible.
+
+The `${CLAUDE_PLUGIN_ROOT}` rule follows the MCP config the **plugin actually
+uses**, because Claude Code defines `CLAUDE_PLUGIN_ROOT` only for a plugin
+install: a project-scoped `.mcp.json` that uses it launches `node /dist/…`
+and the server dies at startup (office-outlook-mcp; tempo-api-mcp regressed by
+following an earlier version of this lint). `.claude-plugin/plugin.json`
+`mcpServers` is resolved against the plugin root (the directory holding
+`.claude-plugin/`):
+
+| `mcpServers` | Plugin config | Root `.mcp.json` | Warns on |
+| --- | --- | --- | --- |
+| `"./.mcp.json"` | the root `.mcp.json` | plugin config | a cwd-relative path in it |
+| absent | the root `.mcp.json` (Claude Code's default) | plugin config | a cwd-relative path in it |
+| another path, e.g. `"./.claude-plugin/mcp.json"` | that file | project-scoped | a cwd-relative path in that file; `${CLAUDE_PLUGIN_ROOT}` in the root file; a path that does not exist |
+| inline object (or an array mixing shapes) | the inline servers (and any named files) | project-scoped unless the array names it | a cwd-relative path inline; `${CLAUDE_PLUGIN_ROOT}` in the root file |
+| `mcp` instead (any value) | ignored by Claude Code, so the root `.mcp.json` | resolved as if `mcpServers` held the same value | always `plugin-json-mcp-ignored`: softer for `"./.mcp.json"`, stronger for any other path |
+
+`mcp` is not a key Claude Code reads (`claude plugin validate`: "Unknown field
+'mcp'"), so every `mcp` key is reported as `plugin-json-mcp-ignored` (a
+warning; an error only under `--strict`). `"mcp": "./.mcp.json"` names the
+default anyway, so its message says it is harmless today but should be
+renamed to `mcpServers` — copies of the key with other paths broke plugin
+installs. Any other `mcp` value is resolved as the author meant (so the root
+file is not told to use the variable) and reported more strongly, because a
+plugin install really loads the root `.mcp.json`. `.mcpb`/`.dxt` bundles and URLs are skipped. One
+case is not checked: Claude Code loads the root `.mcp.json` first and merges
+the declared config over it, so a project-scoped root server whose name the
+plugin config does not replace also starts in a plugin install whose source
+ships that file.
 
 The env check reads every `.js`/`.mjs`/`.cjs` under the entry's directory,
 skipping `node_modules`, dot-directories, `test`/`tests`/`__tests__`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrischall/mcp-utils",
-  "version": "3.0.1",
+  "version": "3.0.2",
   "description": "Shared scaffolding for the chrischall MCP fleet — server bootstrap, tool-result formatting, helpful errors, hardened env/config, a bearer API-client kit, zod atoms, session registries, a fetchproxy transport adapter, auth resolver skeletons, an in-memory test harness, and opt-in HTML helpers. The generic MCP glue hoisted out of ~19 sibling servers.",
   "type": "module",
   "license": "MIT",