@systemdox/mcp-server 0.1.49 → 0.1.51

package/dist/setup-mcp.js

@@ -2,6 +2,7 @@
 
 // src/setup-mcp.ts
 import { existsSync as existsSync3, readFileSync } from "fs";
+import { mkdir as mkdir4 } from "fs/promises";
 import { join as join4 } from "path";
 
 // src/lib/cache.ts
@@ -64,14 +65,6 @@ var SystemDoxApiClient = class {
     this.config = config;
     this.cache = new ResponseCache(config.cacheTtlMs);
   }
-  async validate() {
-    const res = await this.fetchRaw("/v1/health");
-    if (!res.ok) {
-      throw new Error(
-        `SystemDox API authentication failed (${res.status}). Check your SYSTEMDOX_API_KEY.`
-      );
-    }
-  }
   async get(path, params) {
     const url = this.buildUrl(path, params);
     const cacheKey = url.toString();
@@ -85,8 +78,8 @@ var SystemDoxApiClient = class {
   }
   /** 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) {
-    const res = await this.fetchRaw(path);
+  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();
   }
@@ -116,8 +109,8 @@ var SystemDoxApiClient = class {
   // 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() {
-    return this.getFresh(TEAM_SETUP);
+  getOwnTeamSetup(signal) {
+    return this.getFresh(TEAM_SETUP, signal);
   }
   getTeamSetup(workspace) {
     return this.getFresh(`${TEAM_SETUP}/${seg(workspace)}`);
@@ -221,14 +214,15 @@ var SystemDoxApiClient = class {
     }
     return url;
   }
-  async fetchRaw(path, params) {
+  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
     });
   }
 };
@@ -598,6 +592,7 @@ async function setupMcpServer(opts) {
   }
   try {
     if ((await readCredentials())[workspace]?.apiKey !== apiKey) await writeCredentials(workspace, apiKey);
+    await mkdir4(join4(homeDir(), ".claude", "skills"), { recursive: true });
     const several = Object.keys(await readCredentials()).length > 1;
     for (const target of selected) {
       const removed = await writeServerEntry(target.path, apiUrl, several ? workspace : void 0);
@@ -615,9 +610,10 @@ async function setupMcpServer(opts) {
   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 21 tools: get_context, get_checks,
+  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.

package/dist/setup-team.js

@@ -68,14 +68,6 @@ var SystemDoxApiClient = class {
     this.config = config;
     this.cache = new ResponseCache(config.cacheTtlMs);
   }
-  async validate() {
-    const res = await this.fetchRaw("/v1/health");
-    if (!res.ok) {
-      throw new Error(
-        `SystemDox API authentication failed (${res.status}). Check your SYSTEMDOX_API_KEY.`
-      );
-    }
-  }
   async get(path, params) {
     const url = this.buildUrl(path, params);
     const cacheKey = url.toString();
@@ -89,8 +81,8 @@ var SystemDoxApiClient = class {
   }
   /** 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) {
-    const res = await this.fetchRaw(path);
+  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();
   }
@@ -120,8 +112,8 @@ var SystemDoxApiClient = class {
   // 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() {
-    return this.getFresh(TEAM_SETUP);
+  getOwnTeamSetup(signal) {
+    return this.getFresh(TEAM_SETUP, signal);
   }
   getTeamSetup(workspace) {
     return this.getFresh(`${TEAM_SETUP}/${seg(workspace)}`);
@@ -225,14 +217,15 @@ var SystemDoxApiClient = class {
     }
     return url;
   }
-  async fetchRaw(path, params) {
+  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
     });
   }
 };

package/dist/sync-memory.js

@@ -65,14 +65,6 @@ var SystemDoxApiClient = class {
     this.config = config;
     this.cache = new ResponseCache(config.cacheTtlMs);
   }
-  async validate() {
-    const res = await this.fetchRaw("/v1/health");
-    if (!res.ok) {
-      throw new Error(
-        `SystemDox API authentication failed (${res.status}). Check your SYSTEMDOX_API_KEY.`
-      );
-    }
-  }
   async get(path, params) {
     const url = this.buildUrl(path, params);
     const cacheKey = url.toString();
@@ -86,8 +78,8 @@ var SystemDoxApiClient = class {
   }
   /** 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) {
-    const res = await this.fetchRaw(path);
+  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();
   }
@@ -117,8 +109,8 @@ var SystemDoxApiClient = class {
   // 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() {
-    return this.getFresh(TEAM_SETUP);
+  getOwnTeamSetup(signal) {
+    return this.getFresh(TEAM_SETUP, signal);
   }
   getTeamSetup(workspace) {
     return this.getFresh(`${TEAM_SETUP}/${seg(workspace)}`);
@@ -222,14 +214,15 @@ var SystemDoxApiClient = class {
     }
     return url;
   }
-  async fetchRaw(path, params) {
+  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
     });
   }
 };

package/dist/tools/document-graph.d.ts

@@ -0,0 +1,87 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { SystemDoxApiClient } from "../lib/api-client.js";
+/**
+ * The document graph over MCP (ADR-224, specs/changes/document-graph/contract.md §5).
+ * Three read-only tools on the hosted and the local server. Every answer says
+ * how each link is known, and one that was cut says so.
+ */
+interface GraphNode {
+    id: string;
+    label: string;
+    type: string;
+    repo: string;
+    path: string;
+}
+interface NeighbourLink {
+    direction: "out" | "in";
+    relation: string;
+    provenance: string;
+    confidence: number;
+    file: string;
+    line: number;
+    other: GraphNode;
+}
+interface AmbiguousLink {
+    reference: string;
+    file: string;
+    line: number;
+    candidates: GraphNode[];
+}
+interface Neighbours {
+    doc: GraphNode;
+    links: NeighbourLink[];
+    ambiguous: AmbiguousLink[];
+    total: number;
+    truncated: boolean;
+}
+interface PathStep {
+    from: GraphNode;
+    to: GraphNode;
+    relation: string;
+    provenance: string;
+    confidence: number;
+    file: string;
+    line: number;
+    reversed: boolean;
+}
+interface GraphPath {
+    found: boolean;
+    hops: number;
+    confidence: number;
+    steps: PathStep[];
+}
+interface RepoFreshness {
+    repo: string;
+    documents: number;
+    links: number;
+    indexedCommit: string;
+    indexedAt: string;
+    headCommit: string;
+    pushedAt: string;
+    behind: boolean;
+}
+interface GraphStats {
+    nodeCount: number;
+    edgeCount: number;
+    links: {
+        declared: number;
+        extracted: number;
+        inferred: number;
+        ambiguous: number;
+    };
+    repos: RepoFreshness[];
+}
+interface RepoLink {
+    source: string;
+    target: string;
+    relation: string;
+    provenance: string;
+    confidence: number;
+    file: string;
+    line: number;
+}
+export declare function formatNeighbours(answer: Neighbours): string;
+export declare function formatPath(answer: GraphPath, maxHops: number): string;
+export declare function formatStats(stats: GraphStats, repoLinks: RepoLink[]): string;
+export declare function registerDocumentGraph(server: McpServer, apiClient: SystemDoxApiClient): void;
+export {};

package/dist/tools/get-team-setup.d.ts

@@ -0,0 +1,6 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { SystemDoxApiClient } from "../lib/api-client.js";
+export declare function registerGetTeamSetup(server: McpServer, apiClient: SystemDoxApiClient, { localFiles, keyProblem }: {
+    localFiles: boolean;
+    keyProblem?: string;
+}): void;

package/dist/tools/skills.js

@@ -29,6 +29,7 @@ import { homedir } from "os";
 import { dirname, join, relative, resolve, sep } from "path";
 var MANIFEST_FILE = ".systemdox-skill.json";
 var ENTRY_FILE = "SKILL.md";
+var PLUGIN_MANIFEST_FOLDER = ".claude-plugin";
 var MAX_FILES = 100;
 var MAX_FILE_BYTES = 256 * 1024;
 var MAX_TOTAL_BYTES = 1024 * 1024;
@@ -53,7 +54,7 @@ function isValidName(name) {
   return name.length <= 64 && NAME_RE.test(name);
 }
 function isValidPath(path) {
-  return path.length > 0 && path.length <= 512 && !path.startsWith("/") && path.split("/").every((s) => SEGMENT_RE.test(s) && s !== "." && s !== "..");
+  return path.length > 0 && path.length <= 512 && !path.startsWith("/") && path.split("/").every((s) => SEGMENT_RE.test(s) && s !== "." && s !== ".." && s !== PLUGIN_MANIFEST_FOLDER);
 }
 function frontmatterName(skillMd) {
   const block = /^---\r?\n([\s\S]*?)\r?\n---/.exec(skillMd);
@@ -202,6 +203,9 @@ function fenceFor(text2) {
   const longest = Math.max(0, ...(text2.match(/`+/g) ?? []).map((r) => r.length));
   return "`".repeat(Math.max(3, longest + 1));
 }
+function afterInstall(skillMd) {
+  return `No restart is needed: a running Claude Code session picks it up. If one does not list it yet, read ${skillMd} and follow it, or run /reload-skills.`;
+}
 function describeInstall(name, r) {
   const lines = [
     `Installed ${name} version ${r.version} into ${r.dest} (${r.written.length} file(s)).`
@@ -211,7 +215,7 @@ function describeInstall(name, r) {
     lines.push(`Kept, edited here and no longer in the skill: ${r.keptEdited.join(", ")}`);
   }
   if (r.keptUntracked.length) lines.push(`Kept, added here: ${r.keptUntracked.join(", ")}`);
-  lines.push("Start a new Claude Code session to load it.");
+  lines.push(afterInstall(join(r.dest, "SKILL.md")));
   return lines.join("\n");
 }
 
@@ -341,7 +345,7 @@ ${fence}
 ${f.content}${f.content.endsWith("\n") ? "" : "\n"}${fence}`;
       }).join("\n\n");
       return text(
-        `Skill **${version.name}** version ${version.version}: write these ${version.files.length} file(s) into ${dest}/ exactly as shown (the content between the fences), creating folders as needed. If a file there differs from ${MANIFEST_FILE}'s hash for it, it was edited: ask before replacing it. Then write ${MANIFEST_FILE} with this content, and tell the user to start a new Claude Code session.
+        `Skill **${version.name}** version ${version.version}: write these ${version.files.length} file(s) into ${dest}/ exactly as shown (the content between the fences), creating folders as needed. If a file there differs from ${MANIFEST_FILE}'s hash for it, it was edited: ask before replacing it. Then write ${MANIFEST_FILE} with this content. ${afterInstall(`${dest}/SKILL.md`)}
 
 ### ${MANIFEST_FILE}
 

package/dist/tools/team-setup.js

@@ -14,13 +14,14 @@ import { existsSync } from "fs";
 import { homedir } from "os";
 import { dirname, join, relative, resolve, sep } from "path";
 var MANIFEST_FILE = ".systemdox-skill.json";
+var PLUGIN_MANIFEST_FOLDER = ".claude-plugin";
 var MAX_FILES = 100;
 var MAX_FILE_BYTES = 256 * 1024;
 var MAX_TOTAL_BYTES = 1024 * 1024;
 var SEGMENT_RE = /^[A-Za-z0-9._-]+$/;
 var SKIPPED = /* @__PURE__ */ new Set([MANIFEST_FILE, ".git", "node_modules", "__pycache__", ".DS_Store"]);
 function isValidPath(path) {
-  return path.length > 0 && path.length <= 512 && !path.startsWith("/") && path.split("/").every((s) => SEGMENT_RE.test(s) && s !== "." && s !== "..");
+  return path.length > 0 && path.length <= 512 && !path.startsWith("/") && path.split("/").every((s) => SEGMENT_RE.test(s) && s !== "." && s !== ".." && s !== PLUGIN_MANIFEST_FOLDER);
 }
 async function walk(root, { skipHidden }, dir = root, out = { files: [], links: [], hidden: [] }) {
   for (const entry of await readdir(dir, { withFileTypes: true })) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@systemdox/mcp-server",
-  "version": "0.1.49",
+  "version": "0.1.51",
   "mcpName": "io.github.puglieseweb/systemdox",
   "type": "module",
   "description": "Give AI coding agents your architecture context over MCP — checks, specs, ADRs, project rules, and docs from SystemDox, delivered at write time",