sentinel-ir-mcp 0.2.2 → 0.2.3

package/README.md

@@ -90,10 +90,16 @@ npx -y sentinel-ir-mcp@0.2 guide                     # optional: text for AGENTS
 | `--client` | file written by `setup` |
 |---|---|
 | `cursor` | `<project>/.cursor/mcp.json` with `${workspaceFolder}`; `--global`: `~/.cursor/mcp.json` with the absolute path |
-| `windsurf` | `~/.codeium/windsurf/mcp_config.json` |
+| `windsurf` | `~/.config/devin/mcp_config.json` (or `$XDG_CONFIG_HOME/devin/`), Windows `%APPDATA%\devin\mcp_config.json`. Servers from an older `~/.codeium/windsurf/mcp_config.json` are copied over; that file stays unchanged |
 | `claude-desktop` | macOS `~/Library/Application Support/Claude/claude_desktop_config.json`, Windows `%APPDATA%\Claude\claude_desktop_config.json`; elsewhere pass `--config <file>` |
 | `vscode`, `claude-code` | nothing; prints the command to run |
 
+On Windows the entry is `"command": "cmd", "args": ["/c", "npx", "-y",
+"sentinel-ir-mcp@0.2", "<folder>"]`: there `npx` is `npx.cmd`, and starting it
+without a shell failed with `ENOENT` on a real Windows runner. For VS Code and
+Claude Code, `setup` prints a PowerShell and a Command Prompt version of the
+command. What was measured on which system: [COMPATIBILITY.md](COMPATIBILITY.md).
+
 `doctor` checks Node.js, the package version, the client config (valid JSON, a
 `"sentinel-ir"` entry that starts `sentinel-ir-mcp`, existing folders), then
 starts **its own** server with the same folders, performs a real MCP
@@ -161,13 +167,16 @@ Project `.cursor/mcp.json` (or `~/.cursor/mcp.json` for all projects).
 
 #### Windsurf
 
-Cascade panel → `...` → *Open MCP config file* (`mcp_config.json`), then add
-the same entry as for Claude Desktop with your project's absolute path.
+Windsurf 3 (Devin Desktop) reads `~/.config/devin/mcp_config.json`
+(Windows: `%APPDATA%\devin\mcp_config.json`); older versions read
+`~/.codeium/windsurf/mcp_config.json`. Add the same entry as for Claude Desktop
+with your project's absolute path.
 
 #### Other clients
 
 Any MCP client that starts stdio servers works with
-`command: "npx"`, `args: ["-y", "sentinel-ir-mcp@0.2", "<folder>"]`.
+`command: "npx"`, `args: ["-y", "sentinel-ir-mcp@0.2", "<folder>"]`
+(on Windows: `command: "cmd"`, `args: ["/c", "npx", "-y", "sentinel-ir-mcp@0.2", "<folder>"]`).
 Without folder arguments the server uses the client's
 [MCP roots](https://modelcontextprotocol.io/specification/latest/client/roots)
 if the client offers them; if it offers none, only `analyze_code` works.
@@ -244,8 +253,14 @@ size limits, MCP roots from the client, and the command-line options.
 `setup`/`doctor` tests run against temporary `HOME`/`APPDATA` folders: new
 file, keeping other servers and fields, backup, idempotent second run, invalid
 JSON left untouched, `--dry-run`, refused home/root folders, symlinked config,
-Claude Desktop macOS/Windows paths (simulated, not run on those systems), a
-real MCP handshake, failing configs and old Node.js.
+Claude Desktop/Windsurf macOS/Windows paths (simulated), a real MCP
+handshake, failing configs and old Node.js.
+
+A second CI job runs on a real Windows runner (Node 20/22/24): the full test
+suite, the packed package with `setup`/`doctor` against the real `%APPDATA%`,
+starting the published package through `npx`, and the printed VS Code/Claude
+Code commands pasted into PowerShell 5.1, PowerShell 7 and cmd.exe. See
+[COMPATIBILITY.md](COMPATIBILITY.md).
 
 Release: bump `version` in `package.json`, push a protected tag `vX.Y.Z`;
 GitLab CI tests and publishes to npm with provenance.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sentinel-ir-mcp",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "MCP server for sentinel-ir: lets AI agents (Claude Desktop, Cursor, Windsurf, ...) read a compact structural IR of JavaScript and TypeScript files instead of the raw source. Read-only, sandboxed to allowed folders.",
   "main": "src/server.js",
   "bin": {

package/src/clients.js

@@ -11,6 +11,10 @@ function homeOf(env) {
     return env.HOME || env.USERPROFILE || os.homedir();
 }
 
+function configHome(env) {
+    return env.XDG_CONFIG_HOME || path.join(homeOf(env), ".config");
+}
+
 // Clients whose MCP config file is documented as JSON with a top-level
 // "mcpServers" object ("file"), and clients that ship their own install
 // command ("command"), for which setup only prints that command.
@@ -27,7 +31,12 @@ const CLIENTS = Object.freeze({
     windsurf: {
         label: "Windsurf",
         kind: "file",
-        configPath: ({ env }) => path.join(homeOf(env), ".codeium", "windsurf", "mcp_config.json")
+        // Windsurf 3 (Devin Desktop) reads this file and offers to copy the
+        // old ~/.codeium/windsurf one; setup copies it the same way.
+        configPath: ({ env, platform }) => platform === "win32"
+            ? (env.APPDATA ? path.join(env.APPDATA, "devin", "mcp_config.json") : null)
+            : path.join(configHome(env), "devin", "mcp_config.json"),
+        legacyConfigPath: ({ env }) => path.join(homeOf(env), ".codeium", "windsurf", "mcp_config.json")
     },
     "claude-desktop": {
         label: "Claude Desktop",
@@ -47,22 +56,65 @@ const CLIENTS = Object.freeze({
 const CLIENT_NAMES = Object.freeze(Object.keys(CLIENTS));
 const FILE_CLIENTS = Object.freeze(CLIENT_NAMES.filter((name) => CLIENTS[name].kind === "file"));
 
-function serverEntry(folder) {
+function npxEntry(folder) {
     return { command: "npx", args: ["-y", PACKAGE_SPEC, folder] };
 }
 
+// On Windows npx is npx.cmd, which a client cannot start without a shell
+// (measured: spawn("npx") fails with ENOENT), so the entry goes through cmd /c.
+function serverEntry(folder, platform = process.platform) {
+    const { command, args } = npxEntry(folder);
+    return platform === "win32" ? { command: "cmd", args: ["/c", command, ...args] } : { command, args };
+}
+
+function isWindowsNpxWrapper(entry) {
+    return Boolean(entry) && typeof entry.command === "string" && /^cmd(\.exe)?$/i.test(entry.command) &&
+        Array.isArray(entry.args) && String(entry.args[0]).toLowerCase() === "/c" && /^npx(\.cmd)?$/i.test(String(entry.args[1]));
+}
+
 function shellQuote(value) {
     return /^[\w@%+=:,./-]+$/.test(value) ? value : `'${value.replace(/'/g, "'\\''")}'`;
 }
 
+function powershellQuote(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+
+// One argument quoted by the Windows command-line rules (CommandLineToArgvW).
+function windowsArgQuote(value) {
+    return `"${value.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\*)$/, "$1$1")}"`;
+}
+
 function vscodeConfig(project) {
-    return { name: SERVER_NAME, type: "stdio", ...serverEntry(project) };
+    return { name: SERVER_NAME, type: "stdio", ...npxEntry(project) };
+}
+
+// code.cmd/claude.cmd re-read their arguments through cmd.exe, which acts on
+// these characters (measured: "&" breaks the line, "%OS%" is expanded); JSON
+// \u escapes keep them out of the command line.
+function cmdSafeJson(value) {
+    return JSON.stringify(value).replace(/[&|<>^%!]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`);
 }
 
-function installCommand(client, project) {
-    if (client === "vscode") return `code --add-mcp ${shellQuote(JSON.stringify(vscodeConfig(project)))}`;
+// Windows forms were checked in CI against a .cmd shim (like code.cmd and
+// claude.cmd) from PowerShell 5.1, PowerShell 7 and cmd.exe.
+function installCommand(client, project, platform = process.platform, shell = "powershell") {
+    const json = JSON.stringify(vscodeConfig(project));
+    const win = platform === "win32";
+    if (client === "vscode") {
+        if (!win) return `code --add-mcp ${shellQuote(json)}`;
+        return `code ${shell === "cmd" ? "" : "--% "}--add-mcp ${windowsArgQuote(cmdSafeJson(vscodeConfig(project)))}`;
+    }
     if (client === "claude-code") {
-        return `claude mcp add --transport stdio ${SERVER_NAME} -- npx -y ${PACKAGE_SPEC} ${shellQuote(project)}`;
+        if (win && shell !== "cmd") {
+            // PowerShell prefers npm's claude.ps1 shim: a script gets `--` only when quoted, and --% does not apply to it.
+            return `claude mcp add --transport stdio ${SERVER_NAME} '--' cmd /c npx -y ${PACKAGE_SPEC} ${powershellQuote(project)}`;
+        }
+        if (win && project.includes("%")) {
+            const config = { type: "stdio", ...serverEntry(project, "win32") };
+            return `claude mcp add-json ${SERVER_NAME} ${windowsArgQuote(cmdSafeJson(config))}`;
+        }
+        return `claude mcp add --transport stdio ${SERVER_NAME} -- ${win ? "cmd /c npx" : "npx"} -y ${PACKAGE_SPEC} ${win ? `"${project}"` : shellQuote(project)}`;
     }
     throw new Error(`No install command for ${client}`);
 }
@@ -70,7 +122,7 @@ function installCommand(client, project) {
 // One-click links documented by Cursor and VS Code. A link cannot know the
 // project path, so it uses ${workspaceFolder}.
 function installLinks() {
-    const entry = serverEntry(WORKSPACE_VAR);
+    const entry = npxEntry(WORKSPACE_VAR);
     return {
         cursor: `cursor://anysphere.cursor-deeplink/mcp/install?name=${SERVER_NAME}&config=${Buffer.from(JSON.stringify(entry)).toString("base64")}`,
         vscode: `vscode:mcp/install?${encodeURIComponent(JSON.stringify({ name: SERVER_NAME, type: "stdio", ...entry }))}`
@@ -79,5 +131,5 @@ function installLinks() {
 
 module.exports = {
     SERVER_NAME, PACKAGE_SPEC, WORKSPACE_VAR, CLIENTS, CLIENT_NAMES, FILE_CLIENTS,
-    homeOf, serverEntry, shellQuote, installCommand, installLinks
+    homeOf, npxEntry, serverEntry, isWindowsNpxWrapper, shellQuote, powershellQuote, installCommand, installLinks
 };

package/src/doctor.js

@@ -5,7 +5,7 @@ const path = require("path");
 const { Client } = require("@modelcontextprotocol/sdk/client/index.js");
 const { StdioClientTransport } = require("@modelcontextprotocol/sdk/client/stdio.js");
 const { version } = require("../package.json");
-const { SERVER_NAME, PACKAGE_SPEC, WORKSPACE_VAR, CLIENTS, FILE_CLIENTS } = require("./clients");
+const { SERVER_NAME, PACKAGE_SPEC, WORKSPACE_VAR, CLIENTS, FILE_CLIENTS, isWindowsNpxWrapper } = require("./clients");
 const { readConfig } = require("./setup");
 
 const BIN = path.join(__dirname, "..", "bin", "sentinel-ir-mcp.js");
@@ -33,7 +33,7 @@ function entryFolders(args) {
     return folders;
 }
 
-function checkConfig(client, file, explicit, project, add) {
+function checkConfig(client, file, explicit, project, add, platform) {
     const label = CLIENTS[client].label;
     if (!file) {
         if (explicit) add("fail", `${client}.config`, `${label}: config location unknown on this system`, "Pass the config path with --config <file>.");
@@ -64,8 +64,14 @@ function checkConfig(client, file, explicit, project, add) {
             `Run: npx -y ${PACKAGE_SPEC} setup --client ${client}`);
         return null;
     }
-    add(entry.command === "npx" ? "ok" : "warn", `${client}.entry`, `${label}: "${SERVER_NAME}" runs ${entry.command} ${args.join(" ")}`,
-        entry.command === "npx" ? undefined : `Expected "npx"; make sure "${entry.command}" starts sentinel-ir-mcp.`);
+    const runs = `${label}: "${SERVER_NAME}" runs ${entry.command} ${args.join(" ")}`;
+    if (entry.command === "npx" && platform === "win32") {
+        add("warn", `${client}.entry`, runs, `On Windows a client may not find "npx" without a shell. Run: npx -y ${PACKAGE_SPEC} setup --client ${client}`);
+    } else if (entry.command === "npx" || isWindowsNpxWrapper(entry)) {
+        add("ok", `${client}.entry`, runs);
+    } else {
+        add("warn", `${client}.entry`, runs, `Expected "npx"; make sure "${entry.command}" starts sentinel-ir-mcp.`);
+    }
     const resolved = [];
     for (const f of folders) {
         const real = f === WORKSPACE_VAR ? project : path.resolve(f);
@@ -130,8 +136,14 @@ async function runDoctor(opts, io) {
     let folders = null;
     for (const client of names) {
         const ctx = { project, global: Boolean(opts.global), env: io.env, platform: io.platform };
-        const file = opts.config ? path.resolve(io.cwd, opts.config) : CLIENTS[client].configPath(ctx);
-        const found = checkConfig(client, file, Boolean(opts.client), project, add);
+        let file = opts.config ? path.resolve(io.cwd, opts.config) : CLIENTS[client].configPath(ctx);
+        const legacy = !opts.config && CLIENTS[client].legacyConfigPath ? CLIENTS[client].legacyConfigPath(ctx) : null;
+        if (legacy && !(file && fs.existsSync(file)) && fs.existsSync(legacy)) {
+            add("warn", `${client}.location`, `${CLIENTS[client].label}: only the old config ${legacy} exists`,
+                `Current ${CLIENTS[client].label} reads ${file || "a new location"}. Run: npx -y ${PACKAGE_SPEC} setup --client ${client}`);
+            file = legacy;
+        }
+        const found = checkConfig(client, file, Boolean(opts.client), project, add, io.platform);
         if (found && folders === null) folders = found;
     }
     if (folders === null) {

package/src/setup.js

@@ -3,7 +3,7 @@
 const fs = require("fs");
 const path = require("path");
 const { isDeepStrictEqual } = require("util");
-const { SERVER_NAME, PACKAGE_SPEC, CLIENTS, homeOf, serverEntry, installCommand } = require("./clients");
+const { SERVER_NAME, PACKAGE_SPEC, CLIENTS, homeOf, serverEntry, installCommand, shellQuote, powershellQuote } = require("./clients");
 
 class SetupError extends Error {}
 
@@ -57,13 +57,17 @@ function readConfig(file) {
     return { exists: true, original, data };
 }
 
-function planFileChange(file, entry) {
+// seedFile: an older config location whose servers are copied into a new file.
+function planFileChange(file, entry, seedFile = null) {
     const target = fs.existsSync(file) ? fs.realpathSync(file) : file;
-    const { exists, original, data } = readConfig(target);
+    const read = readConfig(target);
+    const seeded = !read.exists && seedFile && fs.existsSync(seedFile) ? seedFile : null;
+    const { exists, original } = read;
+    const data = seeded ? readConfig(seeded).data : read.data;
     const servers = data.mcpServers || {};
     const previous = Object.prototype.hasOwnProperty.call(servers, SERVER_NAME) ? servers[SERVER_NAME] : undefined;
     const others = Object.keys(servers).filter((name) => name !== SERVER_NAME);
-    const base = { file, target, entry, previous, others };
+    const base = { file, target, entry, previous, others, seeded };
     if (previous !== undefined && isDeepStrictEqual(previous, entry)) return { ...base, action: "unchanged" };
     const next = { ...data, mcpServers: { ...servers, [SERVER_NAME]: entry } };
     return {
@@ -112,12 +116,25 @@ function describePlan(client, plan, project) {
         `Access:  ${project} (only this folder, read-only)`,
         `Change:  ${{ create: "create the file with", add: "add", update: "replace", unchanged: "none, already set up:" }[plan.action]} "${SERVER_NAME}"`
     ];
+    if (plan.seeded) lines.push(`Copied from: ${plan.seeded} (old location; that file stays unchanged)`);
     if (plan.action === "update") lines.push(`  before: ${JSON.stringify(plan.previous)}`);
     lines.push(`  ${plan.action === "update" ? "after:  " : ""}${JSON.stringify(plan.entry)}`);
     if (plan.others.length) lines.push(`Kept unchanged: ${plan.others.join(", ")}`);
     return lines.join("\n") + "\n";
 }
 
+function percentNote(project) {
+    return project.includes("%")
+        ? "Note: this folder path contains %. npm 10.8 (measured: 10.8.2, 10.8.3) fails with \"npm error URI malformed\" " +
+          "when npx is started inside such a folder; npm 10.9.9 and 11.19.1 work. If the client reports that error, update npm " +
+          "or use a folder without % in its path.\n"
+        : "";
+}
+
+function hintArg(value, platform) {
+    return platform === "win32" ? powershellQuote(value) : shellQuote(value);
+}
+
 async function runSetup(opts, io) {
     const out = (s) => io.stdout.write(s);
     const err = (s) => io.stderr.write(s);
@@ -140,9 +157,15 @@ async function runSetup(opts, io) {
 
         if (spec.kind === "command") {
             if (opts.config) throw new SetupError(`--config does not apply to ${spec.label}; it installs servers with its own command.`);
-            out(`${spec.label} adds MCP servers with its own command. Nothing was written. Run:\n\n  ${installCommand(client, project)}\n\n`);
+            if (io.platform === "win32") {
+                out(`${spec.label} adds MCP servers with its own command. Nothing was written. Run in PowerShell:\n\n  ${installCommand(client, project, "win32", "powershell")}\n\n` +
+                    `or in Command Prompt (cmd.exe):\n\n  ${installCommand(client, project, "win32", "cmd")}\n\n`);
+            } else {
+                out(`${spec.label} adds MCP servers with its own command. Nothing was written. Run:\n\n  ${installCommand(client, project, io.platform)}\n\n`);
+            }
             out(`Access: ${project} (only this folder, read-only)\n`);
-            out(`Then check the connection: npx -y ${PACKAGE_SPEC} doctor --project ${project}\n`);
+            out(`Then check the connection${io.platform === "win32" ? " (PowerShell)" : ""}: npx -y ${PACKAGE_SPEC} doctor --client ${client} --project ${hintArg(project, io.platform)}\n`);
+            out(percentNote(project));
             return 0;
         }
 
@@ -152,8 +175,10 @@ async function runSetup(opts, io) {
             throw new SetupError(`The ${spec.label} config location is documented for macOS and Windows only. Pass its path with --config <file>.`);
         }
         const folder = opts.config || !spec.folderArg ? project : spec.folderArg(ctx);
-        const plan = planFileChange(file, serverEntry(folder));
+        const seed = !opts.config && spec.legacyConfigPath ? spec.legacyConfigPath(ctx) : null;
+        const plan = planFileChange(file, serverEntry(folder, io.platform), seed);
         out(describePlan(client, plan, project));
+        out(percentNote(project));
 
         if (plan.action === "unchanged") {
             out("Already set up. Nothing was written.\n");
@@ -176,8 +201,8 @@ async function runSetup(opts, io) {
         }
         const { backup } = applyPlan(plan, io.now ? io.now() : Date.now());
         out(`Written.${backup ? ` Backup: ${backup}` : ""}\n`);
-        out(`Next: restart ${spec.label}, then check the connection:\n  npx -y ${PACKAGE_SPEC} doctor --client ${client}` +
-            `${opts.config ? ` --config ${file}` : ""}${client === "cursor" && !opts.global ? ` --project ${project}` : ""}\n`);
+        out(`Next: restart ${spec.label}, then check the connection${io.platform === "win32" ? " (PowerShell)" : ""}:\n  npx -y ${PACKAGE_SPEC} doctor --client ${client}` +
+            `${opts.config ? ` --config ${hintArg(file, io.platform)}` : ""}${client === "cursor" && !opts.global ? ` --project ${hintArg(project, io.platform)}` : ""}\n`);
         out(`Optional instructions for your agent: npx -y ${PACKAGE_SPEC} guide\n`);
         return 0;
     } catch (e) {