@super-hands/connect 0.1.7 → 0.1.14

package/README.md

@@ -20,9 +20,54 @@ 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. Re-running it later to pick up a newer skill needs
+no credential — see `update`, below.
+
+## Updating it
+
+```
+npx -y @super-hands/connect@latest update
+```
+
+Brings the skill on an already-connected machine up to whatever this build
+ships. It takes **no token**: it reads the endpoint and the credential back out
+of the configs the install wrote, so there is nothing to fetch from Superhands
+and nothing new is minted. It touches no MCP entry — the entry is how the
+credential was found, so it is already right.
+
+A client counts as connected when its own config names the `superhands` server;
+anything else is skipped, and a machine with no Superhands entry at all is told
+to install first rather than half-connected. An installed skill at the same
+version or newer is left alone, so your own edits survive an update and the run
+says which files it left as they were. The same `--cursor` / `--claude` /
+`--codex` flags narrow it to one client.
+
+## 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
 
@@ -32,6 +77,6 @@ into the client configs above. The token can be revoked at any time from the
 Superhands MCP page.
 
 This file is generated from
-[`lib/connect-client-entry.ts`](https://github.com/superhandsai/superhandsmcp/blob/main/lib/connect-client-entry.ts)
+[`lib/connect-client-entry.ts`](https://github.com/superhandsai/superhands/blob/main/lib/connect-client-entry.ts)
 in the Superhands repository — the published bytes are that commit's, and are
 not minified.

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";
 
@@ -24,10 +24,14 @@ var CONNECT_URL_ENV = "SUPERHANDS_MCP_URL";
 var CONNECT_DEFAULT_MCP_URL = "https://app.superhands.ai/api/mcp";
 var CONNECT_CLIENT_PACKAGE = "@super-hands/connect";
 var CONNECT_CLIENT_SPEC = `${CONNECT_CLIENT_PACKAGE}@latest`;
+var CONNECT_UPDATE_COMMAND = `npx -y ${CONNECT_CLIENT_SPEC} update`;
 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,11 +41,11 @@ function codexConfigBlock(args) {
 }
 
 // lib/connect-skill.ts
-var CONNECT_SKILL_VERSION = 3;
+var CONNECT_SKILL_VERSION = 9;
 var CONNECT_SKILL_DIR = MCP_SERVER_KEY;
 var CONNECT_SKILL_FILENAME = "SKILL.md";
 var VERSION_MARKER = `[//]: # (superhands-skill-version: ${CONNECT_SKILL_VERSION})`;
-var CONNECT_SKILL_DESCRIPTION = `Build UI the way this team has decided it should be built. Use BEFORE building, changing, or restyling any page, screen, view, form, or component \u2014 "build a page", "add a screen", "create a form", "make a dashboard", "redesign this", "new landing page" \u2014 and when asked how this product should look or behave. Reads the team's written product decisions from their Superhands MCP server.`;
+var CONNECT_SKILL_DESCRIPTION = `Build UI the way this team has decided it should be built. Use BEFORE building, changing, or restyling any page, screen, view, form, or component \u2014 "build a page", "add a screen", "create a form", "make a dashboard", "redesign this", "new landing page" \u2014 and when asked how this product should look or behave. Reads the team's Standards and Playbooks from their Superhands MCP server.`;
 var CONNECT_SKILL_CONTENT = `---
 name: ${CONNECT_SKILL_DIR}
 description: ${CONNECT_SKILL_DESCRIPTION}
@@ -52,34 +56,107 @@ ${VERSION_MARKER}
 # Superhands
 
 This machine is connected to the team's Superhands server over MCP (server
-key \`${MCP_SERVER_KEY}\`). It holds the decisions the team has written down
-about how their product should look and behave \u2014 the same decisions their
-engineers' pull requests are reviewed against.
+key \`${MCP_SERVER_KEY}\`). It holds the team's **Instructions** in two kinds:
+their **Standards**, the decisions they have written about how their product
+should look and behave \u2014 the same decisions their engineers' pull requests are
+reviewed against \u2014 and their **Playbooks**, procedures they imported for their
+agents to follow.
 
 Before you build, change, or restyle any UI:
 
-1. Call the \`superhands_get_guidance\` MCP tool with \`intent\` set to what
+1. Call the \`superhands_get_instructions\` 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", 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
+   the server can tell you when this file is out of date. Both sections come
+   back narrowed to that work, with everything not chosen still named.
+   - Pass \`paths\` too, when you already know which files this work touches \u2014
+     the handful you have open or are about to edit, repository-relative, for
+     example \`["app/marketing/pricing.tsx"]\`. The team writes down where each
+     Standard applies, and a path answers that far better than a description
+     does. Leave it out if you do not know yet; it narrows nothing away.
+   - If that tool is not available on this server, it is an older deployment:
+     call \`superhands_get_guidance\` and \`superhands_get_skill\` instead,
+     with the same \`intent\` \u2014 those two are older and take no \`paths\`.
+2. Plan against what comes back, and note which parts of your plan each set of
+   keys covers. The Playbooks section renders what to read first, then names
+   under **Reachable** the modules judged to matter to parts you have not
+   started \u2014 those keys are what the next step asks with \u2014 and ends with an
+   index of the modules it did **not** choose, for anything the selection
+   missed. A part of your plan with no keys against it is a real gap in what
+   the team has written down; say so rather than quietly using your own
+   defaults.
+3. As you start each part \u2014 the sidebar, then the table, then the form \u2014 call
+   \`superhands_get_playbook_modules\` with the reachable keys covering the
+   part you are starting now. A key ending in \`*\` takes everything under
+   it, so \`better-ui/*\` is a whole skill and \`better-ui/SKILL#*\` is one
+   file. It runs no selection and makes no model call, so it is a plain, fast
+   lookup and it returns exactly what you named.
+   - Fetch each part's modules **when you reach that part**, not all of them at
+     the start. These are instructions to follow, not facts to know, so modules
+     for a part you are not building are a page of directions about the wrong
+     thing sitting in your context while you work.
+   - The Standards from step 1 need no such loop. They are a short list of
+     constraints on the whole task, so one read at the start is the right read.
+   - If that tool is not available on this server, it is an older deployment:
+     build from what step 1 already returned and skip this step. Do not ask
+     for the whole library instead \u2014 that is the wall of text step 1 avoided.
+4. Build to what comes back. Apply both sections. Where imported Playbook text
+   directly contradicts a Standard, the Standard governs. Where a Standard
+   names a case it deliberately does not govern, your own judgment resumes
+   there.
+5. When you have finished \u2014 not part-way through \u2014 send the files you wrote or
    changed with \`superhands_report_completed_build\`, naming the \`route\` if
    you know it. The team looks at what their agents build there; it records
    and does not review, so a failed report costs the work nothing.
-4. When you finish, say you followed the team's guidance \u2014 never that your
-   work passes it or was checked. Reading guidance is not a review, reporting
-   a build is not a review, and nothing has looked at what you built.
+6. When you finish, say you followed the team's guidance \u2014 never that your
+   work passes it or was checked. Reading Instructions is not a review,
+   reporting a build is not a review, and nothing has looked at what you built.
 
-If the tool answers \`no-guidance\`, carry on with what you were asked for and
-mention that the team writes its guidance on the Superhands Guidance page.
+If the tool answers \`no-instructions\` (or \`no-guidance\` from an older
+server), carry on with what you were asked for and mention that the team
+writes its Standards and imports its Playbooks on the Superhands Instructions
+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.
+
+## Updating Superhands on this machine
+
+If the person asks to update or upgrade Superhands, or if a Superhands tool
+tells you this file is out of date, run:
+
+\`\`\`
+${CONNECT_UPDATE_COMMAND}
+\`\`\`
+
+and tell them what it printed. It reuses the credential already configured on
+this machine, so it needs no token and mints nothing \u2014 it only brings this file
+up to whatever the team's server now expects. Add \`--claude\`, \`--cursor\` or
+\`--codex\` to update one client and leave the rest.
+
+Run it when you are asked, or when you have finished the work in front of you \u2014
+never in the middle of a build. The guidance you were given came from the
+server, not from this file, so it is current either way and there is nothing to
+redo.
+
+## 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+)/);
@@ -96,6 +173,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,
@@ -124,6 +206,74 @@ 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 cursorNamesServer(existing) {
+  if (!existing || existing.trim() === "") return false;
+  let parsed;
+  try {
+    parsed = JSON.parse(existing);
+  } catch {
+    return false;
+  }
+  const servers = parsed?.mcpServers;
+  if (typeof servers !== "object" || servers === null || Array.isArray(servers)) return false;
+  return MCP_SERVER_KEY in servers;
+}
+function codexNamesServer(existing) {
+  return existing.includes(`[mcp_servers.${MCP_SERVER_KEY}]`);
+}
+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,23 +292,107 @@ function appendedCodexConfig(existing, args) {
   return { text: `${existing}${sep}${codexConfigBlock(args)}
 `, alreadyPresent: false, repaired: false };
 }
+function skillPathIn(clientDir) {
+  return join(clientDir, "skills", CONNECT_SKILL_DIR, CONNECT_SKILL_FILENAME);
+}
+function installedSkillVersionIn(clientDir) {
+  try {
+    return installedSkillVersion(readFileSync(skillPathIn(clientDir), "utf8"));
+  } catch {
+    return 0;
+  }
+}
 function writeSkill(clientDir) {
-  const skillPath = join(clientDir, "skills", CONNECT_SKILL_DIR, CONNECT_SKILL_FILENAME);
+  const skillPath = skillPathIn(clientDir);
+  const existingVersion = installedSkillVersionIn(clientDir);
+  if (existingVersion >= CONNECT_SKILL_VERSION) {
+    return { version: existingVersion, state: "current" };
+  }
   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 { version: CONNECT_SKILL_VERSION, state: "wrote" };
   } catch {
     say(`  Could not write the ${CONNECT_SKILL_DIR} skill at ${skillPath}. The connection works without it.`);
+    return { version: existingVersion, state: "blocked" };
   }
 }
+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 claudeRegistration() {
+  const result = spawnSync("claude", ["mcp", "get", MCP_SERVER_KEY], { encoding: "utf8" });
+  if (result.error || result.status !== 0) return { registered: false, connection: null };
+  return { registered: true, connection: claudeConnectionFrom(result.stdout ?? "") };
+}
 function hasCli(bin) {
   try {
     execFileSync(bin, ["--version"], { stdio: "ignore" });
@@ -178,7 +412,27 @@ 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 === "update") return update(flags);
+  if (command !== "install") {
+    stop(
+      `unknown command "${command}". This tool takes "install" (the default), "update" 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) {
@@ -186,15 +440,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;
@@ -224,7 +475,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).version);
         connected += 1;
       } catch {
         say(`Cursor \u2014 ${configPath} could not be written, so it was left as it was.`);
@@ -238,7 +489,7 @@ async function main() {
       }
     }
   }
-  if (onlyClaude || autodetect && hasCli("claude")) {
+  if (wanted.claude && (wanted.explicit || hasCli("claude"))) {
     attempted += 1;
     try {
       try {
@@ -265,14 +516,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")).version);
       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 = "";
@@ -285,7 +536,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).version);
       connected += 1;
     } else {
       try {
@@ -295,7 +546,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).version);
         connected += 1;
       } catch {
         say(`Codex \u2014 ${configPath} could not be written, so it was left as it was.`);
@@ -312,8 +563,192 @@ 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 update(flags) {
+  const wanted = chosenClients(flags);
+  const cursorDir = join(homedir(), ".cursor");
+  const claudeDir = join(homedir(), ".claude");
+  const codexDir = join(homedir(), ".codex");
+  const found = [];
+  const skillVersions = [];
+  let configured = 0;
+  let rewritten = 0;
+  function refresh(product, clientDir, connection) {
+    configured += 1;
+    if (connection) found.push(connection);
+    const before = installedSkillVersionIn(clientDir);
+    if (before >= CONNECT_SKILL_VERSION) {
+      say(
+        `${product} \u2014 its ${CONNECT_SKILL_DIR} skill is already at version ${before}, so it was left as it is.`
+      );
+    } else if (before === 0) {
+      say(
+        `${product} \u2014 connected, but has no ${CONNECT_SKILL_DIR} skill; writing version ${CONNECT_SKILL_VERSION}.`
+      );
+    } else {
+      say(`${product} \u2014 updating its ${CONNECT_SKILL_DIR} skill from version ${before} to ${CONNECT_SKILL_VERSION}.`);
+    }
+    const result = writeSkill(clientDir);
+    skillVersions.push(result.version);
+    if (result.state === "wrote") rewritten += 1;
+  }
+  if (wanted.cursor) {
+    let text = null;
+    try {
+      text = readFileSync(join(cursorDir, "mcp.json"), "utf8");
+    } catch {
+      text = null;
+    }
+    if (cursorNamesServer(text)) refresh("Cursor", cursorDir, cursorConnection(text));
+  }
+  if (wanted.claude) {
+    const claude = claudeRegistration();
+    if (claude.registered) refresh("Claude Code", claudeDir, claude.connection);
+  }
+  if (wanted.codex) {
+    let text = "";
+    try {
+      text = readFileSync(join(codexDir, "config.toml"), "utf8");
+    } catch {
+      text = "";
+    }
+    if (codexNamesServer(text)) refresh("Codex", codexDir, codexConnection(text));
+  }
+  if (configured === 0) {
+    say(
+      wanted.explicit ? "Nothing to update \u2014 none of the clients you named has a Superhands server configured." : "Nothing to update \u2014 no client on this machine has a Superhands server configured."
+    );
+    say("  Connect one first with the command on the Superhands Agents page; it carries the credential.");
+    return;
+  }
+  const installed = skillVersions.length > 0 ? Math.min(...skillVersions) : 0;
+  if (installed > 0) {
+    const unique = new Map(found.map((c) => [`${c.endpoint}\0${c.token}`, c]));
+    for (const connection of unique.values()) {
+      await reportSkillVersion({ ...connection, version: installed });
+    }
+  }
+  say(
+    rewritten > 0 ? "Done. Open a new session in any client that was already running \u2014 a skill is read when a session starts." : "Done. Everything on this machine was already up to date."
+  );
+}
+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.7",
-  "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.14",
+  "description": "Connect the coding agents on this machine to your team's Superhands MCP server, refresh it later with `update` (no token needed), and take it back off again with `uninstall`. Writes each client's own config; reads no repository, uploads nothing.",
   "bin": {
     "superhands-connect": "client.mjs"
   },
@@ -16,7 +16,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/superhandsai/superhandsmcp.git",
+    "url": "git+https://github.com/superhandsai/superhands.git",
     "directory": "packages/connect-client"
   },
   "homepage": "https://app.superhands.ai",