@systemdox/mcp-server 0.1.42 → 0.1.43

package/dist/server.d.ts

@@ -1,8 +1,14 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { SystemDoxApiClient } from "./lib/api-client.js";
+export interface ServerOptions {
+    /** True only on the user's own computer (stdio): the skill tools may read
+     * and write the skill folder there. The hosted server never touches a disk
+     * (ADR-216 §2.2). */
+    localFiles?: boolean;
+}
 /**
  * Build a SystemDox MCP server with all tools registered against the given
  * API client. Shared by the stdio entry point (index.ts) and the hosted
  * Streamable HTTP entry point (http.ts).
  */
-export declare function createServer(apiClient: SystemDoxApiClient): McpServer;
+export declare function createServer(apiClient: SystemDoxApiClient, { localFiles }?: ServerOptions): McpServer;

package/dist/tools/skills.d.ts

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

package/dist/tools/skills.js

@@ -0,0 +1,347 @@
+#!/usr/bin/env node
+
+// src/tools/skills.ts
+import { z } from "zod";
+import { homedir as homedir2 } from "os";
+import { basename, resolve as resolve2 } from "path";
+
+// src/lib/config-links.ts
+async function workspaceBase(apiClient) {
+  try {
+    const access = await apiClient.get(
+      "/v1/docs/portal-access"
+    );
+    const slug = (access.host ?? "").split(".")[0];
+    return slug ? `https://${slug}.systemdox.com` : null;
+  } catch {
+    return null;
+  }
+}
+function configLink(path, base) {
+  return base ? `${base}${path}` : `${path} in your SystemDox workspace`;
+}
+
+// src/lib/skills.ts
+import { createHash } from "crypto";
+import { lstat, mkdir, readdir, readFile, rm, writeFile } from "fs/promises";
+import { existsSync } from "fs";
+import { homedir } from "os";
+import { dirname, join, relative, resolve, sep } from "path";
+var MANIFEST_FILE = ".systemdox-skill.json";
+var ENTRY_FILE = "SKILL.md";
+var MAX_FILES = 100;
+var MAX_FILE_BYTES = 256 * 1024;
+var MAX_TOTAL_BYTES = 1024 * 1024;
+var NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+var SEGMENT_RE = /^[A-Za-z0-9._-]+$/;
+var SKIPPED = /* @__PURE__ */ new Set([MANIFEST_FILE, ".git", "node_modules", "__pycache__", ".DS_Store"]);
+var SkillInstallRefused = class extends Error {
+  constructor(dest, edited) {
+    super(
+      `${dest} has local changes in ${edited.length} file(s): ${edited.join(", ")}. Nothing was written. Move your changes aside, or install again with overwrite.`
+    );
+    this.dest = dest;
+    this.edited = edited;
+  }
+  dest;
+  edited;
+};
+function sha256(content) {
+  return createHash("sha256").update(content, "utf8").digest("hex");
+}
+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 !== "..");
+}
+function frontmatterName(skillMd) {
+  const block = /^---\r?\n([\s\S]*?)\r?\n---/.exec(skillMd);
+  if (!block) return void 0;
+  const line = /^name:[ \t]*(.+?)[ \t]*$/m.exec(block[1]);
+  return line ? line[1].replace(/^(['"])(.*)\1$/, "$2") : void 0;
+}
+function defaultSkillDir(name) {
+  return join(homedir(), ".claude", "skills", name);
+}
+async function walk(root, { skipHidden }, dir = root, out = { files: [], links: [], hidden: [] }) {
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    if (SKIPPED.has(entry.name) || entry.name.endsWith(".pyc")) continue;
+    const full = join(dir, entry.name);
+    const rel = relative(root, full).split(sep).join("/");
+    if (entry.isSymbolicLink()) out.links.push(rel);
+    else if (skipHidden && entry.name.startsWith(".")) out.hidden.push(rel);
+    else if (entry.isDirectory()) await walk(root, { skipHidden }, full, out);
+    else if (entry.isFile()) out.files.push(rel);
+  }
+  out.files.sort();
+  return out;
+}
+async function readSkillDirectory(directory) {
+  const root = resolve(directory);
+  if (!existsSync(join(root, ENTRY_FILE))) {
+    throw new Error(`${root} has no ${ENTRY_FILE}: a skill folder holds SKILL.md at its root`);
+  }
+  const walked = await walk(root, { skipHidden: true });
+  if (walked.links.length) {
+    throw new Error(`${walked.links.join(", ")}: links are not followed; copy the file into the skill folder`);
+  }
+  const paths = walked.files;
+  if (paths.length > MAX_FILES) {
+    throw new Error(`${root} holds ${paths.length} files: a skill holds at most ${MAX_FILES}`);
+  }
+  const decoder = new TextDecoder("utf-8", { fatal: true });
+  const files = [];
+  let total = 0;
+  for (const path of paths) {
+    if (!isValidPath(path)) {
+      throw new Error(`${path}: file names may use letters, digits, ".", "_" and "-" only`);
+    }
+    const raw = await readFile(join(root, ...path.split("/")));
+    if (raw.includes(0)) throw new Error(`${path} is binary: a skill holds text files only`);
+    if (raw.length > MAX_FILE_BYTES) {
+      throw new Error(`${path} is ${raw.length} bytes: a file holds at most ${MAX_FILE_BYTES}`);
+    }
+    total += raw.length;
+    if (total > MAX_TOTAL_BYTES) {
+      throw new Error(`the files pass ${MAX_TOTAL_BYTES} bytes at ${path}`);
+    }
+    let content;
+    try {
+      content = decoder.decode(raw);
+    } catch {
+      throw new Error(`${path} is not UTF-8 text`);
+    }
+    files.push({ path, content });
+  }
+  const skillMd = files.find((f) => f.path === ENTRY_FILE);
+  const name = frontmatterName(skillMd.content);
+  if (!name) throw new Error(`${ENTRY_FILE} has no frontmatter name`);
+  return { name, files, skipped: walked.hidden };
+}
+function within(dest, path) {
+  if (!isValidPath(path)) throw new Error(`refusing to write ${JSON.stringify(path)}: not a skill path`);
+  const full = resolve(dest, ...path.split("/"));
+  if (!full.startsWith(resolve(dest) + sep)) throw new Error(`refusing to write outside ${dest}: ${path}`);
+  return full;
+}
+async function readManifest(dest) {
+  try {
+    return JSON.parse(await readFile(join(dest, MANIFEST_FILE), "utf8"));
+  } catch {
+    return void 0;
+  }
+}
+async function installSkill(version, dest, { overwrite = false } = {}) {
+  if (!isValidName(version.name)) throw new Error(`refusing to install ${JSON.stringify(version.name)}: not a skill name`);
+  const incoming = new Map(version.files.map((f) => [f.path, f]));
+  for (const f of version.files) within(dest, f.path);
+  if (existsSync(dest) && (await lstat(dest)).isSymbolicLink()) {
+    throw new Error(`${dest} is a link: install into a real folder`);
+  }
+  const walked = existsSync(dest) ? await walk(dest, { skipHidden: false }) : { files: [], links: [], hidden: [] };
+  if (walked.links.length) {
+    throw new Error(`${dest} holds links (${walked.links.join(", ")}): remove them, nothing was written`);
+  }
+  const present = walked.files;
+  const manifest = await readManifest(dest);
+  const known = Object.fromEntries(
+    Object.entries(manifest?.files ?? {}).filter(([p, h]) => isValidPath(p) && typeof h === "string")
+  );
+  const edited = [];
+  const untracked = [];
+  for (const path of present) {
+    const content = await readFile(join(dest, ...path.split("/")), "utf8");
+    if (Object.hasOwn(known, path)) {
+      if (sha256(content) !== known[path]) edited.push(path);
+    } else if (!incoming.has(path) || sha256(content) !== incoming.get(path).sha256) {
+      if (incoming.has(path) || !manifest) edited.push(path);
+      else untracked.push(path);
+    }
+  }
+  const blocking = edited.filter((p) => incoming.has(p) || !manifest);
+  if (blocking.length && !overwrite) throw new SkillInstallRefused(dest, blocking);
+  const written = [];
+  for (const f of version.files) {
+    const full = within(dest, f.path);
+    await mkdir(dirname(full), { recursive: true });
+    await writeFile(full, f.content, "utf8");
+    written.push(f.path);
+  }
+  const removed = [];
+  const keptEdited = [];
+  for (const path of Object.keys(known)) {
+    if (incoming.has(path) || !present.includes(path)) continue;
+    if (edited.includes(path)) {
+      keptEdited.push(path);
+      continue;
+    }
+    await rm(within(dest, path));
+    removed.push(path);
+  }
+  const next = {
+    name: version.name,
+    version: version.version,
+    installedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    files: Object.fromEntries(version.files.map((f) => [f.path, f.sha256]))
+  };
+  await writeFile(join(dest, MANIFEST_FILE), JSON.stringify(next, null, 2) + "\n", "utf8");
+  return {
+    dest,
+    version: version.version,
+    written,
+    removed,
+    keptUntracked: untracked.filter((p) => !incoming.has(p)),
+    keptEdited
+  };
+}
+function fenceFor(text2) {
+  const longest = Math.max(0, ...(text2.match(/`+/g) ?? []).map((r) => r.length));
+  return "`".repeat(Math.max(3, longest + 1));
+}
+function describeInstall(name, r) {
+  const lines = [
+    `Installed ${name} version ${r.version} into ${r.dest} (${r.written.length} file(s)).`
+  ];
+  if (r.removed.length) lines.push(`Removed (no longer in the skill): ${r.removed.join(", ")}`);
+  if (r.keptEdited.length) {
+    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.");
+  return lines.join("\n");
+}
+
+// src/tools/skills.ts
+var SKILLS = "/v1/standards/skills";
+function expandHome(path) {
+  return path.replace(/^~(?=$|[\\/])/, homedir2());
+}
+function text(t) {
+  return { content: [{ type: "text", text: t }] };
+}
+function registerSkillTools(server, apiClient, { localFiles }) {
+  const fileSchema = z.object({
+    path: z.string().describe('Path inside the skill folder, forward slashes, e.g. "references/guide.md"'),
+    content: z.string().describe("The file's full text, exactly as it is")
+  });
+  server.registerTool(
+    "publish_skill",
+    {
+      title: "Publish Skill",
+      description: localFiles ? "Publish a Claude Code skill folder (SKILL.md plus its references and scripts) to SystemDox so it can be installed on any computer. Pass `directory` (e.g. ~/.claude/skills/<name>): the server reads the files itself, byte for byte. Publishing a name again makes a new version. Never retype the files into `files` when the folder is on this computer." : "Publish a Claude Code skill (SKILL.md plus its references and scripts) to SystemDox so it can be installed on any computer. Pass every file of the folder in `files`, exactly as it is. Publishing a name again makes a new version.",
+      inputSchema: {
+        ...localFiles ? {
+          directory: z.string().optional().describe("The skill folder on this computer, holding SKILL.md at its root")
+        } : {},
+        files: z.array(fileSchema).optional().describe(localFiles ? "Only when there is no folder to read" : "Every file of the skill folder"),
+        name: z.string().optional().describe("The skill's name; defaults to SKILL.md's frontmatter name and must match it"),
+        spaceId: z.string().optional().describe("Space for a NEW skill (default: your default space)")
+      },
+      annotations: { readOnlyHint: false }
+    },
+    async (args) => {
+      let files;
+      let name;
+      let skipped = [];
+      if (localFiles && args.directory) {
+        ({ name, files, skipped } = await readSkillDirectory(expandHome(args.directory)));
+      } else if (args.files?.length) {
+        files = args.files;
+        const entry = files.find((f) => f.path === ENTRY_FILE);
+        name = entry ? frontmatterName(entry.content) : void 0;
+      } else {
+        throw new Error(localFiles ? "Pass `directory` (or `files`)." : "Pass `files`.");
+      }
+      name = args.name ?? name;
+      if (!name) throw new Error(`${ENTRY_FILE} has no frontmatter name; pass \`name\`.`);
+      const saved = await apiClient.post(
+        `${SKILLS}/${encodeURIComponent(name)}/versions`,
+        { files, ...args.spaceId ? { spaceId: args.spaceId } : {} }
+      );
+      apiClient.invalidateCache(SKILLS);
+      return text(
+        `Published **${saved.name}** version ${saved.version} (${saved.fileCount} file(s), ${saved.totalBytes} bytes).
+Install it anywhere with: npx -y @systemdox/mcp-server install-skill ${saved.name}` + (skipped.length ? `
+Left out (hidden files are never part of a skill): ${skipped.join(", ")}` : "")
+      );
+    }
+  );
+  server.registerTool(
+    "list_skills",
+    {
+      title: "List Skills",
+      description: "List the Claude Code skills published to SystemDox that you can install: name, description, latest version. Use install_skill to install one.",
+      inputSchema: {},
+      annotations: { readOnlyHint: true }
+    },
+    async () => {
+      const { skills } = await apiClient.get(SKILLS);
+      if (!skills.length) {
+        return text(
+          `No skills published yet. Publish one with publish_skill; they appear at ${configLink("/docs/skills", await workspaceBase(apiClient))}`
+        );
+      }
+      return text(
+        `${skills.length} skill(s):
+
+` + skills.map((s) => `- **${s.name}** (version ${s.latestVersion}, updated ${s.updatedAt.slice(0, 10)}): ${s.description}`).join("\n")
+      );
+    }
+  );
+  server.registerTool(
+    "install_skill",
+    {
+      title: "Install Skill",
+      description: localFiles ? "Install a skill published to SystemDox onto this computer (default ~/.claude/skills/<name>/). Refuses, naming the files, when a file there was edited since it was installed, unless overwrite is true. Never runs anything." : "Fetch a skill published to SystemDox so you can install it: returns every file and the folder to write them into (default ~/.claude/skills/<name>/). Write each file exactly, then the manifest it shows.",
+      inputSchema: {
+        name: z.string().describe("The skill's name"),
+        version: z.number().int().positive().optional().describe("A version number (default: the latest)"),
+        target: z.string().optional().describe("Folder to install into, e.g. a repo's .claude/skills/<name>"),
+        ...localFiles ? { overwrite: z.boolean().optional().describe("Replace files edited since they were installed") } : {}
+      },
+      annotations: { readOnlyHint: !localFiles }
+    },
+    async (args) => {
+      const version = await apiClient.getFresh(
+        `${SKILLS}/${encodeURIComponent(args.name)}/versions/${args.version ?? "latest"}`
+      );
+      if (localFiles) {
+        const dest2 = args.target ? expandHome(args.target) : defaultSkillDir(version.name);
+        if (basename(resolve2(dest2)) !== version.name) {
+          throw new Error(`target must be a folder named ${version.name} (e.g. .claude/skills/${version.name}); got ${dest2}`);
+        }
+        const result = await installSkill(version, dest2, { overwrite: args.overwrite });
+        return text(describeInstall(version.name, result));
+      }
+      const dest = args.target ?? `~/.claude/skills/${version.name}`;
+      const manifest = {
+        name: version.name,
+        version: version.version,
+        installedAt: "<now, ISO 8601>",
+        files: Object.fromEntries(version.files.map((f) => [f.path, f.sha256]))
+      };
+      const body = version.files.map((f) => {
+        const fence = fenceFor(f.content);
+        return `### ${f.path}
+
+${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.
+
+### ${MANIFEST_FILE}
+
+\`\`\`json
+${JSON.stringify(manifest, null, 2)}
+\`\`\`
+
+${body}`
+      );
+    }
+  );
+}
+export {
+  registerSkillTools
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@systemdox/mcp-server",
-  "version": "0.1.42",
+  "version": "0.1.43",
   "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",