totemlayer 0.1.1 → 0.1.3

package/bin/mcp-install.mjs

@@ -0,0 +1,155 @@
+import { spawnSync } from "node:child_process";
+import { stat } from "node:fs/promises";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const DEFAULT_ORIGIN = "https://totemlayer.com";
+const DEFAULT_NAME = "totem-local";
+const SERVER_ENTRY = fileURLToPath(new URL("./totem.mjs", import.meta.url));
+
+export const MCP_INSTALL_HELP = `Connect Totem to an AI app
+
+Usage:
+  totem mcp install codex --key-file /absolute/path/to/agent.key
+  totem mcp install claude --key-file /absolute/path/to/agent.key
+
+Options:
+  --base-url <origin>  Totem origin (default: https://totemlayer.com)
+  --name <name>        MCP server name (default: totem-local)
+  --key-file <path>    Existing private agent key file (required)
+  --help               Show this guide
+
+This installs a user-level local stdio MCP connection. It never puts the key
+value in a command, client config, or repository. It will not overwrite an
+existing MCP server. Restart the AI app afterward and ask for totem_get_identity.
+On macOS/Linux the key file must be mode 0600. The package must remain installed.
+`;
+
+function fail(message) {
+  throw new Error(message);
+}
+
+function parseInstallArgs(args, environment) {
+  if (args.length === 0 || args.includes("--help") || args.includes("-h")) return { help: true };
+  const [client, ...rest] = args;
+  if (client !== "codex" && client !== "claude")
+    fail("Choose codex or claude. Run `totem mcp install --help` for examples.");
+  const values = {};
+  for (let index = 0; index < rest.length; index += 2) {
+    const option = rest[index];
+    const value = rest[index + 1];
+    if (
+      !["--key-file", "--base-url", "--name"].includes(option) ||
+      !value ||
+      value.startsWith("--")
+    )
+      fail(`Invalid option ${option ?? ""}. Run \`totem mcp install --help\`.`);
+    if (values[option] !== undefined) fail(`${option} was provided more than once.`);
+    values[option] = value;
+  }
+  const keyFile = values["--key-file"] ?? environment.TOTEM_NETWORK_API_KEY_FILE;
+  if (!keyFile) fail("Pass --key-file with the path to your own Totem agent key file.");
+  const name = values["--name"] ?? DEFAULT_NAME;
+  if (!/^[A-Za-z][A-Za-z0-9_-]{0,63}$/.test(name))
+    fail(
+      "The MCP name must be 1-64 letters, numbers, hyphens or underscores and start with a letter.",
+    );
+  const rawOrigin = values["--base-url"] ?? environment.TOTEM_BASE_URL ?? DEFAULT_ORIGIN;
+  let url;
+  try {
+    url = new URL(rawOrigin);
+  } catch {
+    fail("--base-url must be a valid HTTPS origin (or HTTP loopback for local development).");
+  }
+  if (
+    url.username ||
+    url.password ||
+    url.search ||
+    url.hash ||
+    url.pathname !== "/" ||
+    (url.protocol !== "https:" &&
+      !(url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)))
+  )
+    fail(
+      "--base-url must be a credential-free HTTPS origin (or HTTP loopback for local development).",
+    );
+  return { client, keyFile: resolve(keyFile), name, baseUrl: url.origin };
+}
+
+async function validateKeyFile(path) {
+  const info = await stat(path);
+  if (!info.isFile() || info.size === 0 || info.size > 8 * 1024)
+    fail("The Totem agent key must be a nonempty regular file no larger than 8 KiB.");
+  if (process.platform !== "win32" && (info.mode & 0o077) !== 0)
+    fail("The Totem agent key file must be private (mode 0600). Fix its permissions and retry.");
+}
+
+function runClient(command, args, environment) {
+  const result = spawnSync(command, args, {
+    encoding: "utf8",
+    env: environment,
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: 20_000,
+  });
+  if (result.error?.code === "ENOENT")
+    fail(
+      `${command} is not installed or is not on PATH. Install and sign in to that AI client first.`,
+    );
+  if (result.error) fail(`${command} could not complete MCP setup: ${result.error.message}`);
+  return result;
+}
+
+export async function installTotemMcp(args, environment = process.env) {
+  const options = parseInstallArgs(args, environment);
+  if (options.help) return MCP_INSTALL_HELP;
+  if (process.platform === "win32")
+    fail(
+      "Automatic MCP setup is not yet supported on Windows. Use the manual stdio MCP configuration in the Totem CLI README.",
+    );
+  await validateKeyFile(options.keyFile);
+
+  const command = options.client;
+  const existing = runClient(command, ["mcp", "get", options.name], environment);
+  if (existing.status === 0)
+    fail(
+      `${options.name} already exists in ${command}. No configuration was changed. Choose another --name or inspect the existing connection first.`,
+    );
+  if (!/no mcp server|not found|does not exist/i.test(`${existing.stderr}\n${existing.stdout}`))
+    fail(
+      `${command} could not check whether ${options.name} already exists. No configuration was changed.`,
+    );
+  const envArgs = [
+    "--env",
+    `TOTEM_BASE_URL=${options.baseUrl}`,
+    "--env",
+    `TOTEM_NETWORK_API_KEY_FILE=${options.keyFile}`,
+  ];
+  const addArgs =
+    options.client === "codex"
+      ? ["mcp", "add", options.name, ...envArgs, "--", process.execPath, SERVER_ENTRY, "mcp"]
+      : [
+          "mcp",
+          "add",
+          ...envArgs,
+          "--scope",
+          "user",
+          "--transport",
+          "stdio",
+          options.name,
+          "--",
+          process.execPath,
+          SERVER_ENTRY,
+          "mcp",
+        ];
+  const added = runClient(command, addArgs, environment);
+  if (added.status !== 0)
+    fail(
+      `${command} could not add ${options.name}. No Totem key value was sent. Check the client's MCP setup and retry.`,
+    );
+  const verified = runClient(command, ["mcp", "get", options.name], environment);
+  if (verified.status !== 0)
+    fail(
+      `${command} reported an install, but ${options.name} could not be verified. Inspect its MCP settings before using it.`,
+    );
+  return `Connected ${options.name} to ${command} at ${options.baseUrl}. Restart ${command}, then ask it to call totem_get_identity. The Totem CLI package must remain installed.\n`;
+}