@systemdox/mcp-server 0.1.48 → 0.1.49

package/dist/install-skill.js

@@ -250,8 +250,7 @@ function requireHttpsApiUrl(apiUrl) {
   }
   return apiUrl;
 }
-function loadConfig() {
-  const apiKey = process.env.SYSTEMDOX_API_KEY;
+function loadConfig(apiKey = process.env.SYSTEMDOX_API_KEY) {
   if (!apiKey) {
     throw new Error(
       "SYSTEMDOX_API_KEY is required. Generate one at your SystemDox settings page."

package/dist/lib/config.d.ts

@@ -18,4 +18,7 @@ export declare const API_URL_DEFAULT = "https://api.puglieseweb.com/systemdox";
  * spare a dev a certificate is not a trade worth making.
  */
 export declare function requireHttpsApiUrl(apiUrl: string): string;
-export declare function loadConfig(): ServerConfig;
+/** The server's settings from the environment. `apiKey` defaults to
+ * SYSTEMDOX_API_KEY; the local server passes the key it resolved (that, then
+ * ~/.claude/systemdox/credentials.json: `loadLocalConfig`). */
+export declare function loadConfig(apiKey?: string | undefined): ServerConfig;

package/dist/lib/config.js

@@ -18,8 +18,7 @@ function requireHttpsApiUrl(apiUrl) {
   }
   return apiUrl;
 }
-function loadConfig() {
-  const apiKey = process.env.SYSTEMDOX_API_KEY;
+function loadConfig(apiKey = process.env.SYSTEMDOX_API_KEY) {
   if (!apiKey) {
     throw new Error(
       "SYSTEMDOX_API_KEY is required. Generate one at your SystemDox settings page."

package/dist/lib/team-setup-files.d.ts

@@ -14,9 +14,11 @@
  * a test points HOME (USERPROFILE on Windows) at a temporary folder.
  *
  * Also here: the API key's order (SYSTEMDOX_API_KEY, then credentials.json for
- * the workspace) and `marketplace-auth`, the marketplace's `headersHelper`,
+ * the workspace; `setup` writes the key there and nowhere else, not into an AI
+ * tool's MCP config) and `marketplace-auth`, the marketplace's `headersHelper`,
  * which reads only these files and the environment.
  */
+import { type ServerConfig } from "./config.js";
 /** A workspace is a tenant slug (openapi Slug): it names a folder, so nothing
  * else is accepted. */
 export declare function isWorkspace(value: unknown): value is string;
@@ -41,6 +43,17 @@ export declare function writeCredentials(workspace: string, apiKey: string): Pro
 /** The key for `workspace`, in the contract's order: SYSTEMDOX_API_KEY, then
  * credentials.json for the workspace. Undefined when neither has one. */
 export declare function apiKeyFor(workspace: string, env?: NodeJS.ProcessEnv): Promise<string | undefined>;
+/**
+ * The key for a command that is not told the workspace: the local MCP server
+ * and `sync-memory`. SYSTEMDOX_API_KEY; then credentials.json: the key of
+ * SYSTEMDOX_WORKSPACE when it is set, otherwise of the one workspace the file
+ * holds. Throws, naming SYSTEMDOX_API_KEY and SYSTEMDOX_WORKSPACE, when that
+ * names no key or several.
+ */
+export declare function localApiKey(env?: NodeJS.ProcessEnv): Promise<string>;
+/** The local (stdio) server's settings: `loadConfig` with the key from
+ * `localApiKey`. The hosted server takes each request's key and never reads this. */
+export declare function loadLocalConfig(env?: NodeJS.ProcessEnv): Promise<ServerConfig>;
 /** SYSTEMDOX_API_URL or the default, https only (throws otherwise). */
 export declare function apiUrlFrom(env?: NodeJS.ProcessEnv): string;
 export interface TeamSetupState {

package/dist/lib/team-setup-files.js

@@ -25,6 +25,22 @@ function requireHttpsApiUrl(apiUrl) {
   }
   return apiUrl;
 }
+function loadConfig(apiKey = process.env.SYSTEMDOX_API_KEY) {
+  if (!apiKey) {
+    throw new Error(
+      "SYSTEMDOX_API_KEY is required. Generate one at your SystemDox settings page."
+    );
+  }
+  const apiUrl = requireHttpsApiUrl(
+    process.env.SYSTEMDOX_API_URL ?? API_URL_DEFAULT
+  );
+  return {
+    apiKey,
+    apiUrl,
+    cacheTtlMs: parseInt(process.env.SYSTEMDOX_CACHE_TTL ?? "300", 10) * 1e3,
+    defaultOrg: process.env.SYSTEMDOX_DEFAULT_ORG
+  };
+}
 
 // src/lib/team-setup-files.ts
 var SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
@@ -97,6 +113,31 @@ async function apiKeyFor(workspace, env = process.env) {
   const entry = (await readCredentials())[workspace];
   return typeof entry?.apiKey === "string" && entry.apiKey ? entry.apiKey : void 0;
 }
+async function localApiKey(env = process.env) {
+  if (env.SYSTEMDOX_API_KEY) return env.SYSTEMDOX_API_KEY;
+  const keys = Object.entries(await readCredentials()).filter(
+    (e) => typeof e[1]?.apiKey === "string" && e[1].apiKey.length > 0
+  );
+  const wanted = env.SYSTEMDOX_WORKSPACE;
+  if (wanted) {
+    const key = keys.find(([ws]) => ws === wanted)?.[1].apiKey;
+    if (key) return key;
+    throw new Error(
+      `~/.claude/systemdox/credentials.json holds no key for ${wanted} (SYSTEMDOX_WORKSPACE). Set SYSTEMDOX_API_KEY, or run npx -y @systemdox/mcp-server setup.`
+    );
+  }
+  if (keys.length === 1) return keys[0][1].apiKey;
+  if (keys.length > 1) {
+    throw new Error(
+      `~/.claude/systemdox/credentials.json holds keys for ${keys.map(([ws]) => ws).join(", ")}: set SYSTEMDOX_WORKSPACE to the workspace to use, or SYSTEMDOX_API_KEY to its key.`
+    );
+  }
+  throw new Error("No SystemDox key. Set SYSTEMDOX_API_KEY, or run npx -y @systemdox/mcp-server setup.");
+}
+async function loadLocalConfig(env = process.env) {
+  const apiKey = await localApiKey(env);
+  return loadConfig(apiKey);
+}
 function apiUrlFrom(env = process.env) {
   return requireHttpsApiUrl(env.SYSTEMDOX_API_URL || API_URL_DEFAULT);
 }
@@ -174,6 +215,8 @@ export {
   credentialsPath,
   homeDir,
   isWorkspace,
+  loadLocalConfig,
+  localApiKey,
   marketplaceWorkspace,
   pluginDir,
   pluginRoot,

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>;