@super-hands/connect 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Superhands
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,33 @@
+# @super-hands/connect
+
+Connect the coding agents on this machine to your team's
+[Superhands](https://app.superhands.ai) MCP server, in one command.
+
+Superhands setup generates the command for you, credential included:
+
+```
+SUPERHANDS_MCP_TOKEN="…" SUPERHANDS_MCP_URL="…" npx -y @super-hands/connect@latest
+```
+
+## What it does
+
+- **Cursor** — merges the `superhands` server into `~/.cursor/mcp.json`.
+  Every other server in the file is preserved; a file that does not parse is
+  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.
+
+With no flags it connects every client it finds; `--cursor` or `--claude`
+narrow it to one.
+
+## What it does not do
+
+It reads no repository, runs none of your code, and uploads nothing. The one
+secret it holds is the token in its own environment, and it is written only
+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)
+in the Superhands repository — the published bytes are that commit's, and are
+not minified.

package/client.mjs

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+// GENERATED by scripts/build-capture-toolkit.mjs — do not edit by hand.
+//
+// The Superhands connect client. Bundled from this commit's
+// `lib/connect-client-entry.ts`.
+//
+// It writes this team's MCP server into the coding agents installed on this
+// machine — Cursor's mcp.json, Claude Code through its own CLI — and nothing
+// else. It reads no repository, uploads nothing, and the credential it
+// carries arrived in its own environment. Read on — it is not minified.
+
+// lib/connect-client-entry.ts
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+// lib/mcp-token.ts
+var MCP_ACCESS_TOKEN_TTL_SECONDS = 30 * 24 * 60 * 60;
+
+// lib/mcp-clients.ts
+var CONNECT_TOKEN_ENV = "SUPERHANDS_MCP_TOKEN";
+var CONNECT_URL_ENV = "SUPERHANDS_MCP_URL";
+var CONNECT_CLIENT_PACKAGE = "@super-hands/connect";
+var CONNECT_CLIENT_SPEC = `${CONNECT_CLIENT_PACKAGE}@latest`;
+var MCP_SERVER_KEY = "superhands";
+function mcpAuthorizationHeader(token) {
+  return `Bearer ${token}`;
+}
+function codexConfigBlock(args) {
+  return [
+    `[mcp_servers.${MCP_SERVER_KEY}]`,
+    `url = "${args.endpoint}"`,
+    `bearer_token = "${args.token}"`
+  ].join("\n");
+}
+
+// lib/connect-client-entry.ts
+function say(line) {
+  process.stdout.write(`superhands: ${line}
+`);
+}
+function stop(message) {
+  process.stdout.write(`superhands: connect failed \u2014 ${message}
+`);
+  process.exit(1);
+}
+function mergedCursorConfig(existing, args) {
+  let config = {};
+  if (existing !== null && existing.trim() !== "") {
+    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");
+    }
+    config = parsed;
+  }
+  const serversRaw = config.mcpServers;
+  const servers = typeof serversRaw === "object" && serversRaw !== null && !Array.isArray(serversRaw) ? serversRaw : {};
+  const replaced = MCP_SERVER_KEY in servers;
+  servers[MCP_SERVER_KEY] = {
+    url: args.endpoint,
+    headers: { Authorization: mcpAuthorizationHeader(args.token) }
+  };
+  config.mcpServers = servers;
+  return { text: `${JSON.stringify(config, null, 2)}
+`, replaced };
+}
+function appendedCodexConfig(existing, args) {
+  if (existing.includes(`[mcp_servers.${MCP_SERVER_KEY}]`)) {
+    return { text: existing, alreadyPresent: true };
+  }
+  const sep = existing === "" || existing.endsWith("\n\n") ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
+  return { text: `${existing}${sep}${codexConfigBlock(args)}
+`, alreadyPresent: false };
+}
+function hasCli(bin) {
+  try {
+    execFileSync(bin, ["--version"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function main() {
+  const token = process.env[CONNECT_TOKEN_ENV]?.trim();
+  const endpoint = process.env[CONNECT_URL_ENV]?.trim();
+  if (!token || !endpoint) {
+    stop(
+      `this command needs ${CONNECT_TOKEN_ENV} and ${CONNECT_URL_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;
+  let connected = 0;
+  let attempted = 0;
+  const cursorDir = join(homedir(), ".cursor");
+  if (onlyCursor || autodetect && existsSync(cursorDir)) {
+    attempted += 1;
+    const configPath = join(cursorDir, "mcp.json");
+    let existing = null;
+    try {
+      existing = readFileSync(configPath, "utf8");
+    } catch {
+      existing = null;
+    }
+    try {
+      const merged = mergedCursorConfig(existing, { endpoint, token });
+      mkdirSync(dirname(configPath), { recursive: true });
+      writeFileSync(configPath, merged.text);
+      say(
+        merged.replaced ? `Cursor \u2014 updated the ${MCP_SERVER_KEY} server in ${configPath}.` : `Cursor \u2014 added the ${MCP_SERVER_KEY} server to ${configPath}.`
+      );
+      say("  Restart Cursor, then enable superhands under Settings \u2192 MCP.");
+      connected += 1;
+    } catch {
+      say(`Cursor \u2014 ${configPath} is not valid JSON, so it was left untouched.`);
+      say("  Fix or remove that file, then run this command again.");
+    }
+  }
+  if (onlyClaude || autodetect && hasCli("claude")) {
+    attempted += 1;
+    try {
+      try {
+        execFileSync("claude", ["mcp", "remove", "--scope", "user", MCP_SERVER_KEY], {
+          stdio: "ignore"
+        });
+      } catch {
+      }
+      execFileSync(
+        "claude",
+        [
+          "mcp",
+          "add",
+          "--transport",
+          "http",
+          "--scope",
+          "user",
+          MCP_SERVER_KEY,
+          endpoint,
+          "--header",
+          `Authorization: ${mcpAuthorizationHeader(token)}`
+        ],
+        { stdio: "ignore" }
+      );
+      say(`Claude Code \u2014 added the ${MCP_SERVER_KEY} server (user scope).`);
+      say("  Open a new claude session and it connects on start.");
+      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"))) {
+    attempted += 1;
+    const configPath = join(codexDir, "config.toml");
+    let existing = "";
+    try {
+      existing = readFileSync(configPath, "utf8");
+    } catch {
+      existing = "";
+    }
+    const result = appendedCodexConfig(existing, { endpoint, token });
+    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 bearer_token there by hand.");
+      connected += 1;
+    } else {
+      mkdirSync(dirname(configPath), { recursive: true });
+      writeFileSync(configPath, result.text);
+      say(`Codex \u2014 added the ${MCP_SERVER_KEY} server to ${configPath}.`);
+      say("  Start a new codex session and it connects on start.");
+      connected += 1;
+    }
+  }
+  if (connected === 0) {
+    stop(
+      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)}".`
+    );
+  }
+  say("Done. Superhands notices the moment an agent connects \u2014 setup ticks by itself.");
+}
+
+// connect-client.ts
+await main();

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@super-hands/connect",
+  "version": "0.1.0",
+  "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.",
+  "bin": {
+    "superhands-connect": "./client.mjs"
+  },
+  "files": [
+    "client.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/superhandsai/superhandsmcp.git",
+    "directory": "packages/connect-client"
+  },
+  "homepage": "https://app.superhands.ai",
+  "keywords": [
+    "superhands",
+    "mcp",
+    "design-system",
+    "design-tokens",
+    "components"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}