@systemdox/mcp-server 0.1.48 → 0.1.50

package/dist/setup-mcp.d.ts

@@ -0,0 +1,66 @@
+/**
+ * `setup`'s first step: write the SystemDox MCP server into an AI tool's
+ * config (Claude Code's project `.mcp.json` or `~/.claude.json`, Cursor's,
+ * VS Code's). The team setup (`setup-team.ts`) follows it.
+ *
+ * The key is stored once (specs/changes/team-setup/contract.md "The API key",
+ * proposal item 7): in `~/.claude/systemdox/credentials.json` for the key's
+ * workspace, readable by the member alone. The server entry this step writes
+ * carries no key; the local server reads it from SYSTEMDOX_API_KEY, then from
+ * credentials.json (`loadLocalConfig`). A key an earlier `setup` wrote into
+ * the entry is removed from it, and nothing else in that file changes.
+ */
+import type { TeamSetup } from "./lib/team-setup-types.js";
+export interface McpServerEntry {
+    command: string;
+    args: string[];
+    env?: Record<string, string>;
+}
+export interface McpConfigTarget {
+    name: string;
+    path: string;
+    detected: boolean;
+}
+export interface McpSetupOptions {
+    out: (line: string) => void;
+    err: (line: string) => void;
+    ask: (question: string) => Promise<string>;
+    /** The folder whose project configs are offered (default: the current folder). */
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    /** Checks the key against the API (default: `GET /v1/health`). */
+    validateKey?: (apiKey: string, apiUrl: string) => Promise<boolean>;
+    /** Names the key's workspace (default: `GET /team-setup` with the key). */
+    client?: (apiKey: string, apiUrl: string) => {
+        getOwnTeamSetup(): Promise<TeamSetup>;
+    };
+}
+export type McpSetupResult = {
+    code: 0;
+    apiKey: string;
+    apiUrl: string;
+    workspace: string;
+} | {
+    code: 1;
+};
+export declare function findConfigTargets(cwd?: string): McpConfigTarget[];
+/**
+ * The `systemdox` server entry: the command and args, and in `env` only
+ * SYSTEMDOX_API_URL when it is not the default. Never the key. Other variables
+ * the member set on an existing entry are kept, and so is a `${NAME}`
+ * reference for SYSTEMDOX_API_KEY (the member's own environment, not a key).
+ * `workspace` is set as SYSTEMDOX_WORKSPACE when credentials.json holds keys
+ * for several workspaces, so the server knows which one to use.
+ */
+export declare function serverEntry(apiUrl: string, existing?: unknown, workspace?: string): McpServerEntry;
+/**
+ * Set the `systemdox` entry in the config at `path`, creating the file when
+ * absent; every other byte of an existing file is kept. Returns true when the
+ * entry held a key, which it no longer does.
+ */
+export declare function writeServerEntry(path: string, apiUrl: string, workspace?: string): Promise<boolean>;
+/**
+ * The first step of `setup`. Every line goes to `opts.out` / `opts.err`;
+ * code 1 means nothing was changed.
+ */
+export declare function setupMcpServer(opts: McpSetupOptions): Promise<McpSetupResult>;

package/dist/setup-mcp.js

@@ -0,0 +1,630 @@
+#!/usr/bin/env node
+
+// src/setup-mcp.ts
+import { existsSync as existsSync3, readFileSync } from "fs";
+import { join as join4 } from "path";
+
+// src/lib/cache.ts
+var ResponseCache = class {
+  store = /* @__PURE__ */ new Map();
+  ttlMs;
+  constructor(ttlMs) {
+    this.ttlMs = ttlMs;
+  }
+  get(key) {
+    const entry = this.store.get(key);
+    if (!entry) return void 0;
+    if (Date.now() > entry.expiresAt) {
+      this.store.delete(key);
+      return void 0;
+    }
+    return entry.data;
+  }
+  set(key, data) {
+    this.store.set(key, {
+      data,
+      expiresAt: Date.now() + this.ttlMs
+    });
+  }
+  invalidate(key) {
+    this.store.delete(key);
+  }
+  clear() {
+    this.store.clear();
+  }
+};
+
+// src/lib/api-client.ts
+var SystemDoxApiError = class extends Error {
+  constructor(status, text) {
+    super(`SystemDox API error ${status}: ${text}`);
+    this.status = status;
+    this.text = text;
+    let body;
+    try {
+      body = JSON.parse(text);
+    } catch {
+      body = void 0;
+    }
+    this.body = body;
+    const code = body?.code;
+    this.code = typeof code === "string" ? code : /\b(SYD-[A-Z]\d{3})\b/.exec(text)?.[1];
+  }
+  status;
+  text;
+  code;
+  body;
+};
+var TEAM_SETUP = "/v1/team-setup";
+var seg = (s) => encodeURIComponent(String(s));
+var SystemDoxApiClient = class {
+  config;
+  cache;
+  constructor(config) {
+    this.config = config;
+    this.cache = new ResponseCache(config.cacheTtlMs);
+  }
+  async get(path, params) {
+    const url = this.buildUrl(path, params);
+    const cacheKey = url.toString();
+    const cached = this.cache.get(cacheKey);
+    if (cached !== void 0) return cached;
+    const res = await this.fetchRaw(path, params);
+    if (!res.ok) throw new SystemDoxApiError(res.status, await res.text());
+    const data = await res.json();
+    this.cache.set(cacheKey, data);
+    return data;
+  }
+  /** A read that skips the cache: an install must take the version that is
+   * latest now, not the one cached before someone published another. */
+  async getFresh(path, signal) {
+    const res = await this.fetchRaw(path, void 0, signal);
+    if (!res.ok) throw new SystemDoxApiError(res.status, await res.text());
+    return await res.json();
+  }
+  async post(path, body) {
+    return this.mutate("POST", path, body);
+  }
+  async put(path, body) {
+    return this.mutate("PUT", path, body);
+  }
+  async mutate(method, path, body) {
+    const url = this.buildUrl(path);
+    const res = await fetch(url, {
+      method,
+      headers: {
+        // The API Gateway authorizer only reads the Authorization header;
+        // X-API-Key is kept for backwards compatibility.
+        Authorization: `Bearer ${this.config.apiKey}`,
+        "X-API-Key": this.config.apiKey,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(body)
+    });
+    if (!res.ok) throw new SystemDoxApiError(res.status, await res.text());
+    return await res.json();
+  }
+  // ── Team setup (ADR-217, specs/changes/team-setup/openapi.yaml) ──────────
+  // One method per operationId. Every read skips the cache: setup, sync and
+  // plugin-path act on what the workspace holds now.
+  /** getOwnTeamSetup: the key's own workspace, named in `workspace`. */
+  getOwnTeamSetup(signal) {
+    return this.getFresh(TEAM_SETUP, signal);
+  }
+  getTeamSetup(workspace) {
+    return this.getFresh(`${TEAM_SETUP}/${seg(workspace)}`);
+  }
+  getMarketplace(workspace) {
+    return this.getFresh(`${TEAM_SETUP}/${seg(workspace)}/marketplace.json`);
+  }
+  getPart(workspace, part) {
+    return this.getFresh(`${TEAM_SETUP}/${seg(workspace)}/parts/${seg(part)}`);
+  }
+  publishPartVersion(workspace, part, files) {
+    return this.post(`${TEAM_SETUP}/${seg(workspace)}/parts/${seg(part)}/versions`, { files });
+  }
+  getPartVersion(workspace, part, version) {
+    return this.getFresh(
+      `${TEAM_SETUP}/${seg(workspace)}/parts/${seg(part)}/versions/${seg(version)}`
+    );
+  }
+  getSetupSkills(workspace) {
+    return this.getFresh(`${TEAM_SETUP}/${seg(workspace)}/skills`);
+  }
+  setSetupSkills(workspace, skills) {
+    return this.put(`${TEAM_SETUP}/${seg(workspace)}/skills`, { skills });
+  }
+  getPlugin(workspace) {
+    return this.getFresh(`${TEAM_SETUP}/${seg(workspace)}/plugin`);
+  }
+  /** getPluginZip: the zip's bytes as served, and its X-Content-SHA256
+   * header. The caller checks the BYTES against the hash it was given. */
+  async getPluginZip(workspace, version) {
+    const res = await fetch(
+      this.buildUrl(`${TEAM_SETUP}/${seg(workspace)}/plugin/versions/${seg(version)}/zip`),
+      {
+        headers: {
+          Authorization: `Bearer ${this.config.apiKey}`,
+          "X-API-Key": this.config.apiKey,
+          Accept: "application/zip"
+        }
+      }
+    );
+    if (!res.ok) throw new SystemDoxApiError(res.status, await res.text());
+    return { bytes: Buffer.from(await res.arrayBuffer()), sha256: res.headers.get("x-content-sha256") };
+  }
+  listMemoryProjects(workspace) {
+    return this.getFresh(`${TEAM_SETUP}/${seg(workspace)}/memory`);
+  }
+  getMemory(workspace, project) {
+    return this.getFresh(`${TEAM_SETUP}/${seg(workspace)}/memory/${seg(project)}`);
+  }
+  /** pushMemoryVersion: a stale base throws SystemDoxApiError with status 409,
+   * code SYD-K010 and `body.currentVersion`. */
+  pushMemoryVersion(workspace, project, body) {
+    return this.post(`${TEAM_SETUP}/${seg(workspace)}/memory/${seg(project)}/versions`, body);
+  }
+  getMemoryVersion(workspace, project, version) {
+    return this.getFresh(
+      `${TEAM_SETUP}/${seg(workspace)}/memory/${seg(project)}/versions/${seg(version)}`
+    );
+  }
+  findMissingBlobs(workspace, project, hashes) {
+    return this.post(
+      `${TEAM_SETUP}/${seg(workspace)}/memory/${seg(project)}/blobs/missing`,
+      { hashes }
+    );
+  }
+  uploadBlobs(workspace, project, blobs) {
+    return this.post(`${TEAM_SETUP}/${seg(workspace)}/memory/${seg(project)}/blobs`, { blobs });
+  }
+  readBlobs(workspace, project, hashes) {
+    return this.post(`${TEAM_SETUP}/${seg(workspace)}/memory/${seg(project)}/blobs/read`, { hashes });
+  }
+  listValueAnswers(workspace) {
+    return this.getFresh(`${TEAM_SETUP}/${seg(workspace)}/values`);
+  }
+  lookupValues(workspace, values) {
+    return this.post(`${TEAM_SETUP}/${seg(workspace)}/values`, { values });
+  }
+  answerValues(workspace, answers) {
+    return this.put(`${TEAM_SETUP}/${seg(workspace)}/values`, { answers });
+  }
+  fileMemoryPeople(workspace, people) {
+    return this.post(`${TEAM_SETUP}/${seg(workspace)}/people`, { people });
+  }
+  resolvePerson(workspace, personId) {
+    return this.getFresh(`${TEAM_SETUP}/${seg(workspace)}/people/${seg(personId)}`);
+  }
+  invalidateCache(path) {
+    if (path) {
+      this.cache.invalidate(this.buildUrl(path).toString());
+    } else {
+      this.cache.clear();
+    }
+  }
+  buildUrl(path, params) {
+    const base = this.config.apiUrl.replace(/\/+$/, "");
+    const url = new URL(`${base}${path.startsWith("/") ? "" : "/"}${path}`);
+    if (params) {
+      for (const [key, value] of Object.entries(params)) {
+        url.searchParams.set(key, value);
+      }
+    }
+    return url;
+  }
+  async fetchRaw(path, params, signal) {
+    const url = this.buildUrl(path, params);
+    return fetch(url, {
+      headers: {
+        Authorization: `Bearer ${this.config.apiKey}`,
+        "X-API-Key": this.config.apiKey,
+        Accept: "application/json"
+      },
+      signal
+    });
+  }
+};
+
+// src/lib/config.ts
+var API_URL_DEFAULT = "https://api.puglieseweb.com/systemdox";
+function requireHttpsApiUrl(apiUrl) {
+  let parsed;
+  try {
+    parsed = new URL(apiUrl);
+  } catch {
+    throw new Error(
+      `SYSTEMDOX_API_URL is not a valid URL: ${apiUrl}`
+    );
+  }
+  if (parsed.protocol !== "https:") {
+    throw new Error(
+      `SYSTEMDOX_API_URL must use https:// \u2014 refusing to send the API key over ${parsed.protocol}// in cleartext. Got: ${apiUrl}`
+    );
+  }
+  return apiUrl;
+}
+
+// src/lib/team-setup-files.ts
+import { execFile } from "child_process";
+import { chmod, mkdir, readFile, rename, rm, writeFile } from "fs/promises";
+import { homedir, userInfo } from "os";
+import { dirname, join } from "path";
+import { promisify } from "util";
+var SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function isWorkspace(value) {
+  return typeof value === "string" && value.length <= 64 && SLUG_RE.test(value);
+}
+function homeDir() {
+  return homedir();
+}
+function systemdoxDir() {
+  return join(homeDir(), ".claude", "systemdox");
+}
+function credentialsPath() {
+  return join(systemdoxDir(), "credentials.json");
+}
+async function readJson(path, empty) {
+  let text;
+  try {
+    text = await readFile(path, "utf8");
+  } catch (e) {
+    if (e.code === "ENOENT") return empty;
+    throw e;
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(`${path} is not valid JSON: fix or remove it, then run this again`);
+  }
+}
+async function writeJsonAtomically(path, value, mode) {
+  await mkdir(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.tmp`;
+  await writeFile(tmp, JSON.stringify(value, null, 2) + "\n", mode === void 0 ? "utf8" : { encoding: "utf8", mode });
+  await rename(tmp, path);
+}
+async function readCredentials() {
+  return readJson(credentialsPath(), {});
+}
+var run = promisify(execFile);
+async function restrictToMember(path) {
+  await chmod(path, 384);
+  if (process.platform === "win32") {
+    await run("icacls", [path, "/inheritance:r", "/grant:r", `${userInfo().username}:F`], { windowsHide: true });
+  }
+}
+async function writeCredentials(workspace, apiKey) {
+  if (!isWorkspace(workspace)) throw new Error(`${JSON.stringify(workspace)} is not a workspace name`);
+  if (!apiKey) throw new Error("an API key is required");
+  const path = credentialsPath();
+  const credentials = await readCredentials();
+  credentials[workspace] = { apiKey };
+  await writeJsonAtomically(path, credentials, 384);
+  await restrictToMember(path);
+}
+
+// src/setup-team.ts
+import { execFile as execFile2 } from "child_process";
+import { createHash as createHash2 } from "crypto";
+import { existsSync as existsSync2 } from "fs";
+import { mkdir as mkdir3, readdir as readdir2, readFile as readFile3, writeFile as writeFile3 } from "fs/promises";
+import { dirname as dirname3, join as join3, resolve as resolve2 } from "path";
+import { promisify as promisify2 } from "util";
+
+// src/lib/memory-sync.ts
+import { createHash } from "crypto";
+
+// src/lib/person-values.ts
+var W = "[\\p{L}\\p{N}_]";
+var D = "\\p{Nd}";
+var WORD_OR = (extra) => `[\\p{L}\\p{N}_${extra}]`;
+var PERSON_ID = "(?:(?:con|ctc)_[0-9A-Za-z]{10,40}|usr_[0-9A-Za-z-]{10,40})";
+var PERSON_TOKEN = `\`${PERSON_ID}\`(?:[ \\t]*\\([^()\\n]*\\))?`;
+var BEFORE = `(?<!${WORD_OR("+.:/\\\\\\-")})(?<!${D}[ -])`;
+var AFTER = `(?!${WORD_OR(":/\\\\")}|\\.${D}|[ -]?${D}|-${W})`;
+var E164 = `${BEFORE}\\+${D}+(?:[ -]${D}+)*${AFTER}`;
+var NATIONAL = `${BEFORE}0${D}*(?:[ -]${D}+)*${AFTER}`;
+var ATEXT = "[A-Za-z0-9!#$%&'*+/=?^_{|}~\\-]";
+var EMAIL_RE = "(?<![A-Za-z0-9!#$%&*+/=?^_{|}~.@\\-])[A-Za-z0-9_]" + ATEXT + "*(?:\\." + ATEXT + "+)*@(?:[A-Za-z0-9](?:[A-Za-z0-9\\-]{0,61}[A-Za-z0-9])?\\.)+[A-Za-z]{2,63}(?![A-Za-z0-9\\-]|\\.[A-Za-z0-9])";
+var HOME_PREFIX = "(?:[A-Za-z]:\\\\+Users\\\\+|[A-Za-z]:/+Users/+|/Users/|/home/)";
+var HOME = `(?<!${WORD_OR(".~:/\\\\$}\\-")})${HOME_PREFIX}[^\\\\/\\s"'\`<>|:*?]+`;
+var KEY_PREFIX = `(?<!${W})(?:pweb_[a-z]+_key_|sk-ant-|sk_live_|rk_live_|github_pat_|gh[pousr]_|sntrys_|xox[baprs]-)[A-Za-z0-9_\\-]{4,}`;
+
+// src/sync-memory.ts
+import { existsSync } from "fs";
+import { mkdir as mkdir2, readdir, readFile as readFile2, rm as rm2, writeFile as writeFile2 } from "fs/promises";
+import { dirname as dirname2, join as join2, resolve } from "path";
+
+// src/setup-team.ts
+var SetupFailed = class extends Error {
+};
+var run2 = promisify2(execFile2);
+function skipSpace(t, i) {
+  while (i < t.length && /\s/.test(t[i])) i++;
+  return i;
+}
+function skipString(t, i) {
+  for (i++; i < t.length; i++) {
+    if (t[i] === "\\") i++;
+    else if (t[i] === '"') return i + 1;
+  }
+  return i;
+}
+function skipValue(t, i) {
+  if (t[i] === '"') return skipString(t, i);
+  if (t[i] === "{" || t[i] === "[") {
+    let depth = 0;
+    while (i < t.length) {
+      const c = t[i];
+      if (c === '"') {
+        i = skipString(t, i);
+        continue;
+      }
+      if (c === "{" || c === "[") depth++;
+      else if (c === "}" || c === "]") {
+        depth--;
+        if (depth === 0) return i + 1;
+      }
+      i++;
+    }
+    return i;
+  }
+  while (i < t.length && !/[\s,}\]]/.test(t[i])) i++;
+  return i;
+}
+function objectMembers(t, open) {
+  const members = [];
+  let i = skipSpace(t, open + 1);
+  if (t[i] === "}") return { members, close: i };
+  for (; ; ) {
+    i = skipSpace(t, i);
+    const keyStart = i;
+    const keyEnd = skipString(t, i);
+    const key = JSON.parse(t.slice(keyStart, keyEnd));
+    i = skipSpace(t, skipSpace(t, keyEnd) + 1);
+    const valueEnd = skipValue(t, i);
+    members.push({ key, keyStart, valueStart: i, valueEnd });
+    i = skipSpace(t, valueEnd);
+    if (t[i] === ",") i++;
+    else return { members, close: i };
+  }
+}
+function lineIndent(t, pos) {
+  const start = t.lastIndexOf("\n", pos - 1) + 1;
+  return /^[ \t]*/.exec(t.slice(start))[0];
+}
+function setJsonMember(text, keys, value) {
+  const root = JSON.parse(text);
+  if (!root || typeof root !== "object" || Array.isArray(root)) throw new Error("it does not hold a JSON object");
+  const compact = !text.trimEnd().includes("\n");
+  const unit = /^([ \t]+)"/m.exec(text)?.[1] ?? "  ";
+  const eol = text.includes("\r\n") ? "\r\n" : "\n";
+  const render = (v, indent) => compact ? JSON.stringify(v) : JSON.stringify(v, null, unit).split("\n").join(eol + indent);
+  const nest = (from) => keys.slice(from).reduceRight((acc, k) => ({ [k]: acc }), value);
+  let open = skipSpace(text, 0);
+  for (let k = 0; k < keys.length; k++) {
+    const { members, close } = objectMembers(text, open);
+    const found = members.filter((m) => m.key === keys[k]).at(-1);
+    if (found) {
+      if (k < keys.length - 1 && text[found.valueStart] === "{") {
+        open = found.valueStart;
+        continue;
+      }
+      return text.slice(0, found.valueStart) + render(nest(k + 1), lineIndent(text, found.keyStart)) + text.slice(found.valueEnd);
+    }
+    const name = JSON.stringify(keys[k]);
+    if (compact) {
+      const member = `${name}:${render(nest(k + 1), "")}`;
+      if (members.length) return text.slice(0, members.at(-1).valueEnd) + "," + member + text.slice(members.at(-1).valueEnd);
+      return text.slice(0, open + 1) + member + text.slice(close);
+    }
+    if (members.length) {
+      const last = members.at(-1);
+      const indent2 = lineIndent(text, last.keyStart);
+      return text.slice(0, last.valueEnd) + `,${eol}${indent2}${name}: ${render(nest(k + 1), indent2)}` + text.slice(last.valueEnd);
+    }
+    const outer = lineIndent(text, open);
+    const indent = outer + unit;
+    return text.slice(0, open + 1) + `${eol}${indent}${name}: ${render(nest(k + 1), indent)}${eol}${outer}` + text.slice(close);
+  }
+  return text;
+}
+function jsonAt(value, keys) {
+  let v = value;
+  for (const k of keys) v = v && typeof v === "object" ? v[k] : void 0;
+  return v;
+}
+async function setInJsonFile(path, keys, value) {
+  let text;
+  try {
+    text = await readFile3(path, "utf8");
+  } catch (e) {
+    if (e.code !== "ENOENT") throw e;
+  }
+  let next;
+  if (text === void 0 || !text.trim()) {
+    next = JSON.stringify(keys.reduceRight((acc, k) => ({ [k]: acc }), value), null, 2) + "\n";
+  } else {
+    let current;
+    try {
+      current = JSON.parse(text);
+    } catch {
+      throw new SetupFailed(`${path} is not valid JSON: fix it, then run setup again.`);
+    }
+    if (JSON.stringify(jsonAt(current, keys)) === JSON.stringify(value)) return;
+    try {
+      next = setJsonMember(text, keys, value);
+    } catch (e) {
+      throw new SetupFailed(`${path}: ${e.message}; fix it, then run setup again.`);
+    }
+  }
+  await mkdir3(dirname3(path), { recursive: true });
+  await writeFile3(path, next, "utf8");
+}
+
+// src/setup-mcp.ts
+var isReference = (value) => typeof value === "string" && /^\$\{[A-Za-z_][A-Za-z0-9_]*\}$/.test(value);
+async function validateApiKey(apiKey, apiUrl) {
+  try {
+    const res = await fetch(`${apiUrl.replace(/\/+$/, "")}/v1/health`, {
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        "X-API-Key": apiKey,
+        Accept: "application/json"
+      }
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+function findConfigTargets(cwd = process.cwd()) {
+  const home = homeDir();
+  return [
+    // Claude Code: the project's .mcp.json, and ~/.claude.json (all projects)
+    { name: "Claude Code (project)", path: join4(cwd, ".mcp.json"), detected: true },
+    { name: "Claude Code (user \u2014 all projects)", path: join4(home, ".claude.json"), detected: true },
+    { name: "Cursor (project)", path: join4(cwd, ".cursor", "mcp.json"), detected: existsSync3(join4(cwd, ".cursor")) },
+    { name: "VS Code (project)", path: join4(cwd, ".vscode", "mcp.json"), detected: existsSync3(join4(cwd, ".vscode")) },
+    { name: "Cursor (global)", path: join4(home, ".cursor", "mcp.json"), detected: existsSync3(join4(home, ".cursor")) }
+  ];
+}
+function serverEntry(apiUrl, existing, workspace) {
+  const env = {};
+  const old = existing && typeof existing === "object" ? existing.env : void 0;
+  if (old && typeof old === "object" && !Array.isArray(old)) {
+    for (const [name, value] of Object.entries(old)) {
+      if (typeof value !== "string" || name === "SYSTEMDOX_API_URL" || name === "SYSTEMDOX_WORKSPACE") continue;
+      if (name === "SYSTEMDOX_API_KEY" && !isReference(value)) continue;
+      env[name] = value;
+    }
+  }
+  if (apiUrl !== API_URL_DEFAULT) env.SYSTEMDOX_API_URL = apiUrl;
+  if (workspace) env.SYSTEMDOX_WORKSPACE = workspace;
+  const entry = { command: "npx", args: ["@systemdox/mcp-server"] };
+  if (Object.keys(env).length) entry.env = env;
+  return entry;
+}
+function currentEntry(path) {
+  let text;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch (e) {
+    if (e.code === "ENOENT") return void 0;
+    throw e;
+  }
+  if (!text.trim()) return void 0;
+  let config;
+  try {
+    config = JSON.parse(text);
+  } catch {
+    throw new Error(`${path} is not valid JSON: fix it, then run setup again.`);
+  }
+  const servers = config && typeof config === "object" ? config.mcpServers : void 0;
+  return servers && typeof servers === "object" ? servers.systemdox : void 0;
+}
+async function writeServerEntry(path, apiUrl, workspace) {
+  const existing = currentEntry(path);
+  const env = existing && typeof existing === "object" ? existing.env : void 0;
+  const heldKey = !!env && typeof env === "object" && "SYSTEMDOX_API_KEY" in env && !isReference(env.SYSTEMDOX_API_KEY);
+  await setInJsonFile(path, ["mcpServers", "systemdox"], serverEntry(apiUrl, existing, workspace));
+  return heldKey;
+}
+async function keyWorkspace(opts, apiKey, apiUrl) {
+  const client = opts.client?.(apiKey, apiUrl) ?? new SystemDoxApiClient({ apiKey, apiUrl, cacheTtlMs: 0, defaultOrg: void 0 });
+  try {
+    const { workspace } = await client.getOwnTeamSetup();
+    if (isWorkspace(workspace)) return workspace;
+    opts.out(`  SystemDox named the workspace ${JSON.stringify(workspace)}, which is not a workspace name.`);
+  } catch (e) {
+    opts.out(`  SystemDox did not name your key's workspace (${e.message}).`);
+  }
+  const fromEnv = (opts.env ?? process.env).SYSTEMDOX_WORKSPACE;
+  if (isWorkspace(fromEnv)) return fromEnv;
+  const typed = (await opts.ask("  Your workspace (acme in acme.systemdox.com): ")).trim().toLowerCase();
+  return isWorkspace(typed) ? typed : void 0;
+}
+async function setupMcpServer(opts) {
+  const { out, err, ask } = opts;
+  out("\n  SystemDox MCP Server Setup\n");
+  const apiKey = (await ask("  Enter your SystemDox API key: ")).trim();
+  if (!apiKey) {
+    err("\n  Error: API key is required.\n  Generate one at your SystemDox settings page.\n");
+    return { code: 1 };
+  }
+  const apiUrl = (await ask(`  API URL [${API_URL_DEFAULT}]: `)).trim() || API_URL_DEFAULT;
+  try {
+    requireHttpsApiUrl(apiUrl);
+  } catch (e) {
+    err(`
+  Error: ${e.message}
+`);
+    return { code: 1 };
+  }
+  out("\n  Validating API key...");
+  if (!await (opts.validateKey ?? validateApiKey)(apiKey, apiUrl)) {
+    err("\n  Error: Invalid API key or cannot reach the SystemDox API.\n  Check your key and try again.\n");
+    return { code: 1 };
+  }
+  out("  API key validated successfully.\n");
+  const workspace = await keyWorkspace(opts, apiKey, apiUrl);
+  if (!workspace) {
+    err("\n  Error: that is not a workspace name (lower case letters, digits and -). Nothing was changed.\n");
+    return { code: 1 };
+  }
+  const detected = findConfigTargets(opts.cwd).filter((t) => t.detected);
+  out("  Available targets:");
+  detected.forEach((t, i) => out(`    ${i + 1}. ${t.name} (${t.path})`));
+  const choice = (await ask(`
+  Which target? [1-${detected.length}, or 'all']: `)).trim();
+  let selected;
+  if (choice.toLowerCase() === "all") {
+    selected = detected;
+  } else {
+    const idx = parseInt(choice, 10) - 1;
+    if (isNaN(idx) || idx < 0 || idx >= detected.length) {
+      err("\n  Invalid selection.\n");
+      return { code: 1 };
+    }
+    selected = [detected[idx]];
+  }
+  try {
+    if ((await readCredentials())[workspace]?.apiKey !== apiKey) await writeCredentials(workspace, apiKey);
+    const several = Object.keys(await readCredentials()).length > 1;
+    for (const target of selected) {
+      const removed = await writeServerEntry(target.path, apiUrl, several ? workspace : void 0);
+      out(`  Configured: ${target.name}`);
+      if (removed) out(`  The key now lives in ~/.claude/systemdox/credentials.json and was removed from ${target.path}.`);
+    }
+  } catch (e) {
+    err(`
+  Error: ${e.message}
+`);
+    return { code: 1 };
+  }
+  out(
+    `
+  Your key for ${workspace} is in ${credentialsPath()} (readable by you alone), not in these configs.
+
+  Done! Restart your AI coding tool to activate the SystemDox MCP server.
+  The server provides 25 tools: get_context, get_team_setup, get_checks,
+  get_project_rules, get_prompt_templates, get_specs, get_docs,
+  get_tech_stack, get_planning_context, get_plan_board, get_change,
+  get_document_links, trace_document_path, get_graph_stats,
+  create_check, create_project_rule, create_prompt_template,
+  update_spec, report_decision, publish_skill, list_skills,
+  install_skill, publish_setup_part, resolve_person, sync_memory.
+
+  get_guardrails and create_guardrail remain registered as deprecated
+  aliases of get_checks and create_check \u2014 existing configs keep working.
+`
+  );
+  return { code: 0, apiKey, apiUrl, workspace };
+}
+export {
+  findConfigTargets,
+  serverEntry,
+  setupMcpServer,
+  writeServerEntry
+};