@attrkit/mcp 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -1,6 +1,20 @@
 # Changelog
 
-## 1.1.0 (unreleased: not yet published to npm)
+## 1.2.0 (2026-10-03)
+
+### Added
+
+- `attrkit-mcp login` (macOS): asks for the management key with echo off, checks it against the
+  API, and stores it in the Keychain item `attrkit-mcp` through `security -i` with the key on
+  stdin, so it never appears in argv. `attrkit-mcp logout` removes the item.
+- The server reads the key from that Keychain item on macOS when `ATTRKIT_API_KEY` is unset, empty,
+  or an unexpanded client placeholder (`$ATTRKIT_API_KEY`, `${ATTRKIT_API_KEY}`,
+  `${ATTRKIT_API_KEY:-}`, `${env:ATTRKIT_API_KEY}`, `${input:attrkit-key}`). A real
+  `ATTRKIT_API_KEY` still wins and the Keychain is not consulted, so existing configurations behave
+  exactly as before.
+- The missing-key error now mentions `npx -y @attrkit/mcp login` on macOS.
+
+## 1.1.0 (2026-10-01)
 
 ### Added
 

package/README.md

@@ -45,15 +45,29 @@ Use a read-only or app-scoped key when the client needs less access. App-scoped
 keys cannot read or change the workspace usage cap, create sibling apps, or
 manage workspace-wide integrations.
 
-Load the key into the shell that starts your MCP client:
+### Give the server the key
+
+On macOS, store the key once in the Keychain:
 
 ```bash
-printf "AttriKit management key: "
-IFS= read -r -s ATTRKIT_API_KEY
-export ATTRKIT_API_KEY
-printf "\n"
+npx -y @attrkit/mcp login
 ```
 
+It asks for the key with echo off, checks it against AttriKit (and prints the plan and scopes),
+then stores it in the Keychain item `attrkit-mcp`. The key never appears in a process listing.
+`npx -y @attrkit/mcp logout` removes the item.
+
+On any system you can instead set `ATTRKIT_API_KEY` in the environment of the process that starts
+your MCP client, or in the client's own secret store.
+
+At start the server resolves the key in this order:
+
+1. `ATTRKIT_API_KEY`, when it holds a real value.
+2. On macOS, the Keychain item `attrkit-mcp`. An empty `ATTRKIT_API_KEY`, or one a client left
+   unexpanded (`$ATTRKIT_API_KEY`, `${ATTRKIT_API_KEY}`, `${ATTRKIT_API_KEY:-}`,
+   `${env:ATTRKIT_API_KEY}`, `${input:attrkit-key}`), counts as unset.
+3. Otherwise it exits with an error that names the fix.
+
 ## Codex
 
 Add this server to `~/.codex/config.toml`:

package/dist/cli.js

@@ -14791,7 +14791,7 @@ function validatedApiBaseUrl(value) {
 function readConfig(env = process.env) {
   const apiKey = env.ATTRKIT_API_KEY;
   if (!apiKey) {
-    throw new Error("ATTRKIT_API_KEY is required (create one in AttriKit → Settings → API keys).");
+    throw new Error("ATTRKIT_API_KEY is required (create one in AttriKit → Settings → API keys). On macOS, run `npx -y @attrkit/mcp login` to store it in the Keychain.");
   }
   const apiUrl = (env.ATTRKIT_API_URL ?? "https://attrikit.io").replace(/\/+$/, "");
   validatedApiBaseUrl(apiUrl);
@@ -15055,7 +15055,7 @@ ${body}`
     structuredContent: structured
   }, result.nextCursor);
 }
-var SERVER_VERSION = "1.1.0";
+var SERVER_VERSION = "1.2.0";
 var periodSchema = z5.enum(["7d", "30d", "90d", "all"]).describe("Reporting window. Omit to use the endpoint's documented default.").optional();
 var appIdSchema = z5.string().describe("Optional app id to scope the result to one app.").optional();
 var requiredAppIdSchema = z5.string().min(1).describe("The AttriKit app id.");
@@ -15855,23 +15855,265 @@ function createServer(config, fetchImpl) {
   return server;
 }
 
-// src/cli.ts
-async function main() {
+// src/key.ts
+import { execFile } from "node:child_process";
+var KEYCHAIN_SERVICE = "attrkit-mcp";
+var SECURITY_BIN = "/usr/bin/security";
+var KEY_REQUIRED_MESSAGE = "ATTRKIT_API_KEY is required (create one in AttriKit → Settings → API keys). On macOS, run `npx -y @attrkit/mcp login` to store it in the Keychain.";
+var KEY_REQUIRED_MESSAGE_OTHER_PLATFORM = "ATTRKIT_API_KEY is required (create one in AttriKit → Settings → API keys). Set it in the environment or in your MCP client's secret store.";
+var UNEXPANDED_PLACEHOLDERS = new Set([
+  "$ATTRKIT_API_KEY",
+  "${ATTRKIT_API_KEY}",
+  "${ATTRKIT_API_KEY:-}",
+  "${env:ATTRKIT_API_KEY}",
+  "${input:attrkit-key}"
+]);
+function realEnvKey(env) {
+  const value = env.ATTRKIT_API_KEY;
+  if (value === undefined || value.trim() === "")
+    return;
+  if (UNEXPANDED_PLACEHOLDERS.has(value.trim()))
+    return;
+  return value;
+}
+var realExecFile = (file, args, options, done) => execFile(file, args, options, done);
+function createSecurityRunner(execFileImpl = realExecFile) {
+  return (args, stdin) => new Promise((resolve) => {
+    let writeFailed = false;
+    const child = execFileImpl(SECURITY_BIN, [...args], { encoding: "utf8", timeout: 15000 }, (error, stdout, stderr) => {
+      const code = error === null ? 0 : Number.isInteger(error.code) ? Number(error.code) : 1;
+      resolve(writeFailed ? { code: code === 0 ? 1 : code, stdout, stderr: `${stderr}could not write to security` } : { code, stdout, stderr });
+    });
+    child.stdin?.on("error", () => {
+      writeFailed = true;
+    });
+    if (stdin !== undefined)
+      child.stdin?.end(stdin);
+    else
+      child.stdin?.end();
+  });
+}
+var defaultSecurityRunner = createSecurityRunner();
+async function keychainKey(runSecurity) {
+  const result = await runSecurity(["find-generic-password", "-s", KEYCHAIN_SERVICE, "-w"]);
+  if (result.code !== 0)
+    return;
+  const key = result.stdout.replace(/\r?\n$/, "");
+  return key.trim() === "" ? undefined : key;
+}
+async function resolveApiKey(options = {}) {
+  const env = options.env ?? process.env;
+  const platform = options.platform ?? process.platform;
+  const fromEnv = realEnvKey(env);
+  if (fromEnv !== undefined)
+    return fromEnv;
+  if (platform !== "darwin")
+    throw new Error(KEY_REQUIRED_MESSAGE_OTHER_PLATFORM);
+  const fromKeychain = await keychainKey(options.runSecurity ?? defaultSecurityRunner);
+  if (fromKeychain !== undefined)
+    return fromKeychain;
+  throw new Error(KEY_REQUIRED_MESSAGE);
+}
+
+// src/login.ts
+import { userInfo } from "node:os";
+import { z as z6 } from "zod";
+function quotedForSecurity(key) {
+  if (key === "" || Array.from(key).some(isUnquotable))
+    return null;
+  return `"${key}"`;
+}
+function isUnquotable(character) {
+  const code = character.charCodeAt(0);
+  return character === '"' || character === "\\" || code <= 31 || code === 127;
+}
+function addKeyCommand(username, quotedKey) {
+  return `add-generic-password -U -s ${KEYCHAIN_SERVICE} -a "${Array.from(username).filter((character) => !isUnquotable(character)).join("")}" -w ${quotedKey}
+`;
+}
+function readHidden(input, prompt, write, idleMs = 50) {
+  return new Promise((resolve) => {
+    write(prompt);
+    input.setRawMode(true);
+    input.resume();
+    input.setEncoding("utf8");
+    let value = "";
+    let mode = "text";
+    let idle;
+    const finish = (result) => {
+      if (idle !== undefined)
+        clearTimeout(idle);
+      input.removeListener("data", onData);
+      input.setRawMode(false);
+      input.pause();
+      write(`
+`);
+      resolve(result);
+    };
+    const armIdle = () => {
+      if (idle !== undefined)
+        clearTimeout(idle);
+      idle = setTimeout(() => finish(value), idleMs);
+    };
+    const onData = (chunk) => {
+      for (const character of chunk) {
+        if (mode === "drain")
+          continue;
+        if (mode === "escape") {
+          mode = character === "[" ? "csi" : character === "O" ? "ss3" : "text";
+        } else if (mode === "csi") {
+          if (character >= "@" && character <= "~")
+            mode = "text";
+        } else if (mode === "ss3") {
+          mode = "text";
+        } else if (character === "\x03") {
+          return finish(null);
+        } else if (character === "\x1B") {
+          mode = "escape";
+        } else if (character === "\r" || character === `
+`) {
+          mode = "drain";
+        } else if (character === "" || character === "\b") {
+          value = value.slice(0, -1);
+        } else if (character >= " ") {
+          value += character;
+        }
+      }
+      if (mode === "drain")
+        armIdle();
+    };
+    input.on("data", onData);
+  });
+}
+function readHiddenFromTty(prompt) {
+  return readHidden(process.stdin, prompt, (text) => void process.stderr.write(text));
+}
+var whoamiSchema = z6.object({
+  data: z6.object({
+    plan: z6.string().optional(),
+    scope: z6.object({
+      app_id: z6.string().nullish(),
+      scopes: z6.array(z6.string()).optional()
+    }).optional()
+  })
+});
+function describeWhoami(json) {
+  const parsed = whoamiSchema.safeParse(json);
+  if (!parsed.success)
+    return "Key accepted.";
+  const { plan, scope } = parsed.data.data;
+  const app = scope?.app_id ? `app ${scope.app_id}` : "all apps";
+  return `Key accepted. Plan: ${plan ?? "unknown"}. Scopes: ${scope?.scopes?.join(", ") ?? "unknown"}. Restriction: ${app}.`;
+}
+async function runLogin(options = {}) {
+  const write = options.write ?? ((text) => void process.stderr.write(text));
+  const platform = options.platform ?? process.platform;
+  if (platform !== "darwin") {
+    write(`attrkit-mcp login stores the key in the macOS Keychain. On this system set ATTRKIT_API_KEY in the environment or in your MCP client's secret store.
+`);
+    return 1;
+  }
+  const isTTY = options.isTTY ?? Boolean(process.stdin.isTTY);
+  if (!isTTY) {
+    write(`attrkit-mcp login needs an interactive terminal to ask for the key.
+`);
+    return 1;
+  }
+  const readSecret = options.readSecret ?? readHiddenFromTty;
+  const entered = await readSecret("AttriKit management key: ");
+  if (entered === null)
+    return 130;
+  const key = entered.trim();
+  const quoted = quotedForSecurity(key);
+  if (quoted === null) {
+    write(`That key was not accepted: it is empty or holds a quote, backslash or control character. Nothing was stored.
+`);
+    return 1;
+  }
   let config;
   try {
-    config = readConfig();
+    config = readConfig({ ...options.env ?? process.env, ATTRKIT_API_KEY: key });
   } catch (error) {
-    process.stderr.write(`${error instanceof Error ? error.message : String(error)}
-`, () => process.exit(1));
+    write(`${error instanceof Error ? error.message : String(error)}
+`);
+    return 1;
+  }
+  const result = await callApi(config, "/api/v1/whoami", options.fetchImpl ? { fetchImpl: options.fetchImpl } : {});
+  if (result.status === 401 || result.status === 403) {
+    write(`AttriKit refused that key. Nothing was stored.
+`);
+    return 1;
+  }
+  if (!result.ok) {
+    write(result.status === 0 ? `Could not reach ${new URL(config.apiUrl).origin} to check the key. Nothing was stored.
+` : `Could not check the key (HTTP ${result.status}). Nothing was stored.
+`);
+    return 1;
+  }
+  write(`${describeWhoami(result.json)}
+`);
+  const runSecurity = options.runSecurity ?? defaultSecurityRunner;
+  const stored = await runSecurity(["-i"], addKeyCommand(options.username ?? userInfo().username, quoted));
+  if (stored.code !== 0 || stored.stderr.trim() !== "") {
+    write(`The Keychain refused the item (exit ${stored.code}). Nothing was stored.
+`);
+    return 1;
+  }
+  write(`Stored in the macOS Keychain as attrkit-mcp. Your MCP client can now start the server without ATTRKIT_API_KEY.
+`);
+  return 0;
+}
+async function runLogout(options = {}) {
+  const write = options.write ?? ((text) => void process.stderr.write(text));
+  if ((options.platform ?? process.platform) !== "darwin") {
+    write(`attrkit-mcp logout removes the macOS Keychain item; there is nothing to remove on this system.
+`);
+    return 1;
+  }
+  const result = await (options.runSecurity ?? defaultSecurityRunner)(["delete-generic-password", "-s", KEYCHAIN_SERVICE]);
+  write(result.code === 0 ? `Removed the attrkit-mcp item from the macOS Keychain.
+` : `Nothing was stored in the Keychain for attrkit-mcp.
+`);
+  return 0;
+}
+
+// src/main.ts
+function defaultDeps(startServer) {
+  return {
+    runLogin,
+    runLogout,
+    resolveApiKey,
+    startServer,
+    fail: (message, code) => void process.stderr.write(`${message}
+`, () => process.exit(code)),
+    exit: (code) => process.exit(code)
+  };
+}
+async function runCli(argv, deps) {
+  const command = argv[2];
+  if (command === "login")
+    return deps.exit(await deps.runLogin());
+  if (command === "logout")
+    return deps.exit(await deps.runLogout());
+  let config;
+  try {
+    const apiKey = await deps.resolveApiKey();
+    config = readConfig({ ...process.env, ATTRKIT_API_KEY: apiKey });
+  } catch (error) {
+    deps.fail(error instanceof Error ? error.message : String(error), 1);
     return;
   }
+  await deps.startServer(config);
+}
+
+// src/cli.ts
+runCli(process.argv, defaultDeps(async (config) => {
   const server = createServer(config);
   const transport = new StdioServerTransport;
   await server.connect(transport);
   process.stderr.write(`attrkit-mcp connected (api=${config.apiUrl})
 `);
-}
-main().catch((error) => {
+})).catch((error) => {
   process.stderr.write(`attrkit-mcp failed to start: ${error instanceof Error ? error.stack ?? error.message : String(error)}
 `, () => process.exit(1));
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@attrkit/mcp",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "AttriKit's stdio MCP server for its public Management API",
   "keywords": [
     "attrkit",
@@ -34,7 +34,7 @@
     "prepack": "bun run build",
     "typecheck": "../../node_modules/typescript-7/bin/tsc --noEmit",
     "lint": "eslint .",
-    "test": "cd ../.. && vitest run packages/mcp/src/index.test.ts"
+    "test": "cd ../.. && vitest run packages/mcp/src"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.30.0",