@super-hands/connect 0.1.6 → 0.1.9

package/README.md

@@ -20,9 +20,34 @@ variable too.
   left untouched. Restart Cursor and enable the server under Settings → MCP.
 - **Claude Code** — registers the server through Claude Code's own CLI
   (`claude mcp add`, user scope). A new `claude` session connects on start.
+- **Codex** — appends the `superhands` block to `~/.codex/config.toml`, and
+  only when no such block is there. Both the app and the CLI read that file.
+- **The skill** — writes `skills/superhands/SKILL.md` under each connected
+  client's own directory. It routes UI work through the team's guidance and
+  carries no credential.
 
-With no flags it connects every client it finds; `--cursor` or `--claude`
-narrow it to one.
+With no flags it connects every client it finds; `--cursor`, `--claude` or
+`--codex` narrow it to one.
+
+## Removing it
+
+```
+npx -y @super-hands/connect@latest uninstall
+```
+
+The exact inverse, in this order: it reads every Superhands credential on the
+machine out of the configs, hands each one back to the deployment that issued
+it, and only then removes the entries and the skill files. The other way round
+would delete the only copy of the credential needed to tell the server
+anything.
+
+It removes only what this tool wrote — one key out of `~/.cursor/mcp.json`,
+its own block out of `~/.codex/config.toml`, and the Claude Code entry through
+`claude mcp remove`. Everything else in those files stays. Running it twice, or
+on a machine that was never connected, does nothing and says so; a machine that
+cannot reach the internet is still cleaned locally, with a warning that the
+credential is still live. The same `--cursor` / `--claude` / `--codex` flags
+remove one client and leave the rest.
 
 ## What it does not do
 

package/client.mjs

@@ -11,7 +11,7 @@
 
 // lib/connect-client-entry.ts
 import { execFileSync, spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, rmSync, rmdirSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 
@@ -28,6 +28,9 @@ var MCP_SERVER_KEY = "superhands";
 function mcpAuthorizationHeader(token) {
   return `Bearer ${token}`;
 }
+function mcpRevokeEndpoint(mcpEndpoint) {
+  return `${mcpEndpoint.replace(/\/+$/, "")}/oauth/revoke`;
+}
 function codexConfigBlock(args) {
   return [
     `[mcp_servers.${MCP_SERVER_KEY}]`,
@@ -37,7 +40,7 @@ function codexConfigBlock(args) {
 }
 
 // lib/connect-skill.ts
-var CONNECT_SKILL_VERSION = 2;
+var CONNECT_SKILL_VERSION = 4;
 var CONNECT_SKILL_DIR = MCP_SERVER_KEY;
 var CONNECT_SKILL_FILENAME = "SKILL.md";
 var VERSION_MARKER = `[//]: # (superhands-skill-version: ${CONNECT_SKILL_VERSION})`;
@@ -60,8 +63,10 @@ Before you build, change, or restyle any UI:
 
 1. Call the \`superhands_get_guidance\` MCP tool with \`intent\` set to what
    you have been asked to build, in plain language \u2014 for example "a sign-in
-   page with email and password and an error state". The decisions that govern
-   that work come back in full, ahead of the rest.
+   page with email and password and an error state", and
+   \`skill_version: ${CONNECT_SKILL_VERSION}\` \u2014 the version of this file, so
+   the server can tell you when this file is out of date. The decisions that
+   govern that work come back in full, ahead of the rest.
 2. Build to what comes back. Where a decision names a case it deliberately
    does not govern, your own judgment resumes there.
 3. When you have finished \u2014 not part-way through \u2014 send the files you wrote or
@@ -78,6 +83,23 @@ mention that the team writes its guidance on the Superhands Guidance page.
 If the \`${MCP_SERVER_KEY}\` MCP server is not reachable in this session, say
 so rather than guessing at the team's decisions \u2014 it is configured on this
 machine, so a missing connection is worth telling the person about.
+
+## Removing Superhands from this machine
+
+If the person asks to uninstall, remove, or disconnect Superhands, run:
+
+\`\`\`
+npx -y ${CONNECT_CLIENT_SPEC} uninstall
+\`\`\`
+
+and tell them what it printed. It hands every Superhands credential on this
+machine back to the server, then takes the MCP entries and this file out of
+each client it finds. Add \`--claude\`, \`--cursor\` or \`--codex\` to remove
+one client and leave the rest.
+
+Do not do this by hand. Editing an MCP config to take one server out is how
+every other server in that file gets lost, and deleting the files without the
+command leaves credentials live on the server with nothing left to end them.
 `;
 function installedSkillVersion(contents) {
   const match = contents.match(/superhands-skill-version:\s*(\d+)/);
@@ -94,6 +116,11 @@ function stop(message) {
 `);
   process.exit(1);
 }
+function bearerToken(value) {
+  if (typeof value !== "string") return null;
+  const match = /^Bearer\s+(\S+)$/i.exec(value.trim());
+  return match ? match[1] : null;
+}
 function cursorServerEntry(args) {
   return {
     url: args.endpoint,
@@ -122,6 +149,59 @@ function mergedCursorConfig(existing, args) {
   return { text: `${JSON.stringify(config, null, 2)}
 `, replaced };
 }
+function cursorConfigWithoutServer(existing) {
+  if (existing === null || existing.trim() === "") return { text: existing ?? "", removed: false };
+  let parsed;
+  try {
+    parsed = JSON.parse(existing);
+  } catch {
+    throw new Error("not valid JSON");
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error("not a JSON object");
+  }
+  const config = parsed;
+  const serversRaw = config.mcpServers;
+  if (typeof serversRaw !== "object" || serversRaw === null || Array.isArray(serversRaw)) {
+    return { text: existing, removed: false };
+  }
+  const servers = serversRaw;
+  if (!(MCP_SERVER_KEY in servers)) return { text: existing, removed: false };
+  delete servers[MCP_SERVER_KEY];
+  return { text: `${JSON.stringify(config, null, 2)}
+`, removed: true };
+}
+function cursorConnection(existing) {
+  if (!existing || existing.trim() === "") return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(existing);
+  } catch {
+    return null;
+  }
+  const entry = parsed?.mcpServers?.[MCP_SERVER_KEY];
+  if (!entry || typeof entry.url !== "string") return null;
+  const token = bearerToken(entry.headers?.Authorization);
+  return token ? { endpoint: entry.url, token } : null;
+}
+var CODEX_OWN_BLOCK = `\\[mcp_servers\\.${MCP_SERVER_KEY}\\]\\nurl = "([^"\\n]*)"\\n(?:http_headers = \\{ "Authorization" = "([^"\\n]*)" \\}|bearer_token = "([^"\\n]*)")`;
+function codexConfigWithoutServer(existing) {
+  const block = new RegExp(`${CODEX_OWN_BLOCK}\\n?`);
+  if (block.test(existing)) {
+    return { text: existing.replace(block, ""), removed: true, foreign: false };
+  }
+  return {
+    text: existing,
+    removed: false,
+    foreign: existing.includes(`[mcp_servers.${MCP_SERVER_KEY}]`)
+  };
+}
+function codexConnection(existing) {
+  const match = new RegExp(CODEX_OWN_BLOCK).exec(existing);
+  if (!match) return null;
+  const token = match[2] ? bearerToken(match[2]) : match[3] ?? null;
+  return token ? { endpoint: match[1], token } : null;
+}
 function appendedCodexConfig(existing, args) {
   const staleOwnBlock = new RegExp(
     `\\[mcp_servers\\.${MCP_SERVER_KEY}\\]\\nurl = "[^"\\n]*"\\nbearer_token = "[^"\\n]*"`
@@ -142,19 +222,92 @@ function appendedCodexConfig(existing, args) {
 }
 function writeSkill(clientDir) {
   const skillPath = join(clientDir, "skills", CONNECT_SKILL_DIR, CONNECT_SKILL_FILENAME);
+  let existing = "";
+  try {
+    existing = readFileSync(skillPath, "utf8");
+  } catch {
+    existing = "";
+  }
+  const existingVersion = existing === "" ? 0 : installedSkillVersion(existing);
+  if (existingVersion >= CONNECT_SKILL_VERSION) return existingVersion;
   try {
-    let existing = "";
-    try {
-      existing = readFileSync(skillPath, "utf8");
-    } catch {
-      existing = "";
-    }
-    if (existing !== "" && installedSkillVersion(existing) >= CONNECT_SKILL_VERSION) return;
     mkdirSync(dirname(skillPath), { recursive: true });
     writeFileSync(skillPath, CONNECT_SKILL_CONTENT);
     say(`  Wrote the ${CONNECT_SKILL_DIR} skill to ${skillPath} \u2014 it routes UI work through the team's guidance.`);
+    return CONNECT_SKILL_VERSION;
   } catch {
     say(`  Could not write the ${CONNECT_SKILL_DIR} skill at ${skillPath}. The connection works without it.`);
+    return existingVersion;
+  }
+}
+function connectReportUrl(endpoint) {
+  return `${endpoint.replace(/\/+$/, "")}/connect`;
+}
+async function reportSkillVersion(args) {
+  try {
+    await fetch(connectReportUrl(args.endpoint), {
+      method: "POST",
+      headers: {
+        Authorization: mcpAuthorizationHeader(args.token),
+        "content-type": "application/json"
+      },
+      body: JSON.stringify({ skill_version: args.version }),
+      signal: AbortSignal.timeout(5e3)
+    });
+  } catch {
+  }
+}
+function removeSkill(clientDir) {
+  const skillPath = join(clientDir, "skills", CONNECT_SKILL_DIR, CONNECT_SKILL_FILENAME);
+  if (!existsSync(skillPath)) return false;
+  try {
+    rmSync(skillPath);
+    try {
+      rmdirSync(dirname(skillPath));
+    } catch {
+    }
+    say(`  Removed the ${CONNECT_SKILL_DIR} skill at ${skillPath}.`);
+    return true;
+  } catch {
+    say(`  Could not remove the ${CONNECT_SKILL_DIR} skill at ${skillPath} \u2014 delete it by hand.`);
+    return false;
+  }
+}
+async function revokeToken(connection) {
+  try {
+    const response = await fetch(mcpRevokeEndpoint(connection.endpoint), {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({ token: connection.token }).toString(),
+      // Bounded, because an unreachable host is the expected failure here and
+      // a hung uninstall is worse than one that says it could not revoke.
+      signal: AbortSignal.timeout(15e3)
+    });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+function claudeConnectionFrom(output) {
+  const url = /^\s*URL:\s*(\S+)\s*$/m.exec(output);
+  const authorization = /^\s*Authorization:\s*(Bearer\s+\S+)\s*$/m.exec(output);
+  if (!url) return null;
+  const token = bearerToken(authorization?.[1]);
+  return token ? { endpoint: url[1], token } : null;
+}
+function claudeSaysNothingToRemove(output) {
+  return new RegExp(`No MCP server named\\s+"?${MCP_SERVER_KEY}"?`, "i").test(output);
+}
+function claudeConnection() {
+  try {
+    return claudeConnectionFrom(
+      execFileSync("claude", ["mcp", "get", MCP_SERVER_KEY], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"]
+      })
+    );
+  } catch {
+    return null;
   }
 }
 function hasCli(bin) {
@@ -176,7 +329,24 @@ function openCursor() {
   }
   return false;
 }
+function chosenClients(flags) {
+  const cursor = flags.has("--cursor");
+  const claude = flags.has("--claude");
+  const codex = flags.has("--codex");
+  const explicit = cursor || claude || codex;
+  return explicit ? { cursor, claude, codex, explicit } : { cursor: true, claude: true, codex: true, explicit };
+}
 async function main() {
+  const argv = process.argv.slice(2);
+  const flags = new Set(argv.filter((arg) => arg.startsWith("--")));
+  const command = argv.find((arg) => !arg.startsWith("--")) ?? "install";
+  if (command === "uninstall") return uninstall(flags);
+  if (command !== "install") {
+    stop(`unknown command "${command}". This tool takes "install" (the default) or "uninstall".`);
+  }
+  return install(flags);
+}
+async function install(flags) {
   const token = process.env[CONNECT_TOKEN_ENV]?.trim();
   const endpoint = process.env[CONNECT_URL_ENV]?.trim() || CONNECT_DEFAULT_MCP_URL;
   if (!token) {
@@ -184,15 +354,12 @@ async function main() {
       `this command needs ${CONNECT_TOKEN_ENV} set on the same line. Copy the whole command from Superhands setup and run it unchanged.`
     );
   }
-  const flags = new Set(process.argv.slice(2));
-  const onlyCursor = flags.has("--cursor");
-  const onlyClaude = flags.has("--claude");
-  const onlyCodex = flags.has("--codex");
-  const autodetect = !onlyCursor && !onlyClaude && !onlyCodex;
+  const wanted = chosenClients(flags);
   let connected = 0;
   let attempted = 0;
+  const skillVersions = [];
   const cursorDir = join(homedir(), ".cursor");
-  if (onlyCursor || autodetect && existsSync(cursorDir)) {
+  if (wanted.cursor && (wanted.explicit || existsSync(cursorDir))) {
     attempted += 1;
     const configPath = join(cursorDir, "mcp.json");
     let existing = null;
@@ -222,7 +389,7 @@ async function main() {
         } else {
           say(`  Open Cursor (restart it if it was running), then enable ${MCP_SERVER_KEY} under Settings \u2192 MCP.`);
         }
-        writeSkill(cursorDir);
+        skillVersions.push(writeSkill(cursorDir));
         connected += 1;
       } catch {
         say(`Cursor \u2014 ${configPath} could not be written, so it was left as it was.`);
@@ -236,7 +403,7 @@ async function main() {
       }
     }
   }
-  if (onlyClaude || autodetect && hasCli("claude")) {
+  if (wanted.claude && (wanted.explicit || hasCli("claude"))) {
     attempted += 1;
     try {
       try {
@@ -263,14 +430,14 @@ async function main() {
       );
       say(`Claude Code \u2014 added the ${MCP_SERVER_KEY} server (user scope).`);
       say("  Open a new claude session and it connects on start.");
-      writeSkill(join(homedir(), ".claude"));
+      skillVersions.push(writeSkill(join(homedir(), ".claude")));
       connected += 1;
     } catch {
       say("Claude Code \u2014 `claude mcp add` failed. Run it by hand from the Superhands MCP page.");
     }
   }
   const codexDir = join(homedir(), ".codex");
-  if (onlyCodex || autodetect && (existsSync(codexDir) || hasCli("codex"))) {
+  if (wanted.codex && (wanted.explicit || existsSync(codexDir) || hasCli("codex"))) {
     attempted += 1;
     const configPath = join(codexDir, "config.toml");
     let existing = "";
@@ -283,7 +450,7 @@ async function main() {
     if (result.alreadyPresent) {
       say(`Codex \u2014 ${configPath} already names a ${MCP_SERVER_KEY} server, so it was left as it is.`);
       say("  If that connection is stale, update the http_headers Authorization value there by hand.");
-      writeSkill(codexDir);
+      skillVersions.push(writeSkill(codexDir));
       connected += 1;
     } else {
       try {
@@ -293,7 +460,7 @@ async function main() {
           result.repaired ? `Codex \u2014 replaced the ${MCP_SERVER_KEY} entry in ${configPath}: its old bearer_token spelling makes current Codex reject the whole config.` : `Codex \u2014 added the ${MCP_SERVER_KEY} server to ${configPath}.`
         );
         say("  The app and the CLI both read this config \u2014 open either and it connects when a session starts.");
-        writeSkill(codexDir);
+        skillVersions.push(writeSkill(codexDir));
         connected += 1;
       } catch {
         say(`Codex \u2014 ${configPath} could not be written, so it was left as it was.`);
@@ -310,8 +477,124 @@ async function main() {
       attempted > 0 ? "nothing was connected. Fix the issue above, then run this command again." : `no supported client was found on this machine. Add it to yours by hand: the server URL is ${endpoint}, sent with the header "Authorization: ${mcpAuthorizationHeader(token)}".`
     );
   }
+  const installed = skillVersions.length > 0 ? Math.min(...skillVersions) : 0;
+  if (installed > 0) {
+    await reportSkillVersion({ endpoint, token, version: installed });
+  }
   say("Done. Superhands notices the moment an agent connects \u2014 setup ticks by itself.");
 }
+async function uninstall(flags) {
+  const wanted = chosenClients(flags);
+  const cursorDir = join(homedir(), ".cursor");
+  const codexDir = join(homedir(), ".codex");
+  const cursorConfigPath = join(cursorDir, "mcp.json");
+  const codexConfigPath = join(codexDir, "config.toml");
+  const found = [];
+  const claudeAvailable = wanted.claude && hasCli("claude");
+  let cursorText = null;
+  if (wanted.cursor) {
+    try {
+      cursorText = readFileSync(cursorConfigPath, "utf8");
+    } catch {
+      cursorText = null;
+    }
+    const connection = cursorConnection(cursorText);
+    if (connection) found.push(connection);
+  }
+  if (claudeAvailable) {
+    const connection = claudeConnection();
+    if (connection) found.push(connection);
+  }
+  let codexText = "";
+  if (wanted.codex) {
+    try {
+      codexText = readFileSync(codexConfigPath, "utf8");
+    } catch {
+      codexText = "";
+    }
+    const connection = codexConnection(codexText);
+    if (connection) found.push(connection);
+  }
+  const unique = new Map(found.map((c) => [`${c.endpoint}\0${c.token}`, c]));
+  let revoked = 0;
+  let unreachable = 0;
+  for (const connection of unique.values()) {
+    if (await revokeToken(connection)) revoked += 1;
+    else unreachable += 1;
+  }
+  if (revoked > 0) {
+    say(
+      `Ended ${revoked} credential${revoked === 1 ? "" : "s"} on the server \u2014 those agents now show as disconnected in Superhands.`
+    );
+  }
+  if (unreachable > 0) {
+    say(
+      `Could not reach Superhands to end ${unreachable} credential${unreachable === 1 ? "" : "s"} \u2014 cleaning this machine anyway. Press Disconnect on the Superhands Agents page to finish it.`
+    );
+  }
+  let removed = 0;
+  if (wanted.cursor) {
+    let stripped = null;
+    try {
+      stripped = cursorConfigWithoutServer(cursorText);
+    } catch {
+      say(`Cursor \u2014 ${cursorConfigPath} is not valid JSON, so it was left untouched.`);
+      say(`  Remove the "${MCP_SERVER_KEY}" entry under "mcpServers" by hand.`);
+    }
+    if (stripped?.removed) {
+      try {
+        writeFileSync(cursorConfigPath, stripped.text);
+        say(`Cursor \u2014 removed the ${MCP_SERVER_KEY} server from ${cursorConfigPath}.`);
+        removed += 1;
+      } catch {
+        say(`Cursor \u2014 ${cursorConfigPath} could not be written, so it was left as it was.`);
+        say(
+          `  A sandboxed agent usually cannot write outside its workspace. Run this same command in a regular terminal, or delete the "${MCP_SERVER_KEY}" entry under "mcpServers" in that file yourself.`
+        );
+      }
+    }
+    if (removeSkill(cursorDir)) removed += 1;
+  }
+  if (claudeAvailable) {
+    const result = spawnSync("claude", ["mcp", "remove", "--scope", "user", MCP_SERVER_KEY], {
+      encoding: "utf8"
+    });
+    const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
+    if (!result.error && result.status === 0) {
+      say(`Claude Code \u2014 removed the ${MCP_SERVER_KEY} server (user scope).`);
+      removed += 1;
+    } else if (!claudeSaysNothingToRemove(output)) {
+      say(
+        `Claude Code \u2014 \`claude mcp remove --scope user ${MCP_SERVER_KEY}\` failed. Run it by hand.`
+      );
+    }
+    if (removeSkill(join(homedir(), ".claude"))) removed += 1;
+  }
+  if (wanted.codex) {
+    const stripped = codexConfigWithoutServer(codexText);
+    if (stripped.removed) {
+      try {
+        writeFileSync(codexConfigPath, stripped.text);
+        say(`Codex \u2014 removed the ${MCP_SERVER_KEY} server from ${codexConfigPath}.`);
+        removed += 1;
+      } catch {
+        say(`Codex \u2014 ${codexConfigPath} could not be written, so it was left as it was.`);
+        say(
+          `  A sandboxed agent usually cannot write outside its workspace. Run this same command in a regular terminal, or delete the [mcp_servers.${MCP_SERVER_KEY}] block from that file yourself.`
+        );
+      }
+    } else if (stripped.foreign) {
+      say(`Codex \u2014 ${codexConfigPath} names a ${MCP_SERVER_KEY} server this tool did not write.`);
+      say(`  Delete its [mcp_servers.${MCP_SERVER_KEY}] block by hand.`);
+    }
+    if (removeSkill(codexDir)) removed += 1;
+  }
+  if (removed === 0 && unique.size === 0) {
+    say("Nothing to remove \u2014 Superhands is not installed for these clients on this machine.");
+    return;
+  }
+  say("Done. Restart any client that was open to drop the connection it already loaded.");
+}
 
 // connect-client.ts
 await main();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@super-hands/connect",
-  "version": "0.1.6",
-  "description": "Connect the coding agents on this machine to your team's Superhands MCP server. Writes each client's own config; reads no repository, uploads nothing.",
+  "version": "0.1.9",
+  "description": "Connect the coding agents on this machine to your team's Superhands MCP server, and take it back off again with `uninstall`. Writes each client's own config; reads no repository, uploads nothing.",
   "bin": {
     "superhands-connect": "client.mjs"
   },