@systemdox/mcp-server 0.1.47 → 0.1.49

package/dist/sync-memory.js

@@ -650,6 +650,27 @@ async function readCredentials() {
   return readJson(credentialsPath(), {});
 }
 var run = promisify(execFile);
+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.");
+}
 function apiUrlFrom(env = process.env) {
   return requireHttpsApiUrl(env.SYSTEMDOX_API_URL || API_URL_DEFAULT);
 }
@@ -1055,17 +1076,6 @@ async function upload(client, ws, project, plan, team, report) {
   }
   await send();
 }
-async function keyFromEnvironment(env) {
-  if (env.SYSTEMDOX_API_KEY) return env.SYSTEMDOX_API_KEY;
-  const entries2 = Object.entries(await readCredentials()).filter(([, v]) => typeof v?.apiKey === "string" && v.apiKey);
-  if (entries2.length === 1) return entries2[0][1].apiKey;
-  if (entries2.length > 1) {
-    throw new SyncFailed(
-      `~/.claude/systemdox/credentials.json holds keys for ${entries2.map(([w]) => w).join(", ")}: set SYSTEMDOX_API_KEY to the key of the workspace to sync.`
-    );
-  }
-  throw new SyncFailed("No SystemDox key. Set SYSTEMDOX_API_KEY, or run npx -y @systemdox/mcp-server setup, then run this again.");
-}
 async function syncMemory(opts) {
   const { client, out } = opts;
   const now = opts.now?.() ?? /* @__PURE__ */ new Date();
@@ -1201,7 +1211,7 @@ async function runSyncMemory(argv, io, env = process.env) {
     args = parseSyncMemoryArgs(argv);
     if (!client) {
       const apiUrl = apiUrlFrom(env);
-      const apiKey = await keyFromEnvironment(env);
+      const apiKey = await localApiKey(env);
       client = new SystemDoxApiClient({ apiKey, apiUrl, cacheTtlMs: 0, defaultOrg: void 0 });
     }
   } catch (e) {

package/dist/tools/get-change.d.ts

@@ -0,0 +1,134 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { SystemDoxApiClient } from "../lib/api-client.js";
+/**
+ * get_change (ADR-218, specs/changes/change-page/contract.md §5.1): one change
+ * as SystemDox last synced it, in one read of GET /v1/changes/{owner}/{repo}/{slug}
+ * (openapi.yaml, operationId getChange). The answer is Markdown — the title,
+ * key and size; the parts with their states and pull requests; the decision;
+ * the contract files; every feature file with its scenarios as
+ * `id · state · title`; the plan; the release pull requests — then the Change
+ * object whole in a fenced JSON block, and last the brief's verdict. A build
+ * session calls it first and stops when the brief is not passed (the
+ * *Implement story* prompt template's first step).
+ */
+/** ADR-218 §2.3.2's five words, read from GitHub, never written by SystemDox. */
+export type State = "not yet" | "waiting for your review" | "passed" | "being built" | "done";
+export interface PullRequest {
+    number: number;
+    title: string;
+    state: "open" | "merged";
+    base: string;
+    repo: string;
+    openedAt: string;
+    mergedAt: string | null;
+    url: string;
+    approvingReview: {
+        by: string;
+        at: string;
+    } | null;
+}
+export interface TrackedFile {
+    path: string;
+    docId: string;
+    pullRequest: PullRequest | null;
+    /** The file's last commit belongs to no pull request; it counts as merged. */
+    direct: boolean;
+}
+export interface ScenarioCounts {
+    proposed: number;
+    built: number;
+    defect: number;
+    unbuilt: number;
+    open: number;
+    untagged: number;
+    total: number;
+}
+export interface Scenario {
+    id: string;
+    title: string;
+    /** The state tag without `@`; empty when untagged. */
+    state: "proposed" | "built" | "defect" | "unbuilt" | "open" | "";
+    steps: string[];
+}
+export interface FeatureFile extends TrackedFile {
+    title: string;
+    runner: "pytest-bdd" | "vitest" | "node:test" | "";
+    scenarios: Scenario[];
+    counts: ScenarioCounts;
+}
+export interface Board {
+    number: number;
+    title: string;
+    url: string;
+    items: {
+        todo: number;
+        inProgress: number;
+        done: number;
+        truncated: boolean;
+    };
+}
+export interface Change {
+    key: string;
+    owner: string;
+    repo: string;
+    slug: string;
+    title: string;
+    size: "small" | "ordinary" | "foundational";
+    archived: boolean;
+    /** `decision` is null when the change has no decision (a small change). */
+    states: {
+        decision: State | null;
+        contract: State;
+        behaviour: State;
+        plan: State;
+        release: State;
+    };
+    counts: ScenarioCounts;
+    waitingForReview: PullRequest[];
+    lastActivity: string;
+    syncedAt: string;
+    proposal: TrackedFile;
+    decision: {
+        adr: string;
+        title: string;
+        status: string;
+        docId: string;
+        pullRequest: PullRequest | null;
+    } | null;
+    contract: {
+        files: TrackedFile[];
+        operations: {
+            method: string;
+            path: string;
+            operationId: string;
+            summary: string;
+        }[];
+        channels: {
+            name: string;
+            address: string;
+            messages: string[];
+        }[];
+    };
+    behaviour: {
+        files: FeatureFile[];
+        counts: ScenarioCounts;
+    };
+    plan: {
+        file: TrackedFile | null;
+        draftId: string | null;
+        board: Board | null;
+    };
+    release: {
+        prs: PullRequest[];
+    };
+}
+/**
+ * The answer's last line (contract.md §5.1): "The brief is passed", or "The
+ * brief is not passed: <part> is <state>", naming each part that waits in the
+ * page's order. A change without a decision (`states.decision` null) is not
+ * held up by one.
+ */
+export declare function briefVerdict(states: Change["states"]): string;
+/** The answer of contract.md §5.1, its verdict on the last line. */
+export declare function formatChange(change: Change): string;
+export declare function registerGetChange(server: McpServer, apiClient: Pick<SystemDoxApiClient, "getFresh">): void;

package/dist/tools/get-change.js

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+
+// src/tools/get-change.ts
+import { z } from "zod";
+var GITHUB_NAME = "[A-Za-z0-9][A-Za-z0-9._-]{0,99}";
+var REPO_RE = new RegExp(`^${GITHUB_NAME}/${GITHUB_NAME}$`);
+var SLUG_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+var SLUG_MAX = 64;
+var PARTS = ["decision", "contract", "behaviour", "plan", "release"];
+var BRIEF = ["decision", "contract", "behaviour", "plan"];
+var PAST_REVIEW = /* @__PURE__ */ new Set(["passed", "being built", "done"]);
+function briefVerdict(states) {
+  const waiting = BRIEF.filter(
+    (part) => !(part === "decision" && states.decision === null) && !PAST_REVIEW.has(String(states[part]))
+  ).map((part) => `${part} is ${states[part] ?? "unknown"}`);
+  return waiting.length === 0 ? "The brief is passed" : `The brief is not passed: ${waiting.join(", ")}`;
+}
+function prLink(pr) {
+  return `[${pr.repo}#${pr.number}](${pr.url}) ${pr.state}`;
+}
+function fileSource(file) {
+  if (file.pullRequest) return prLink(file.pullRequest);
+  return file.direct ? "committed directly" : "\u2014";
+}
+function partPullRequests(change, part) {
+  const files = part === "contract" ? change.contract.files : part === "behaviour" ? change.behaviour.files : part === "plan" ? [change.plan.file] : [];
+  const prs = part === "decision" ? [change.decision?.pullRequest ?? null] : part === "release" ? change.release.prs : files.map((file) => file?.pullRequest ?? null);
+  const unique = /* @__PURE__ */ new Map();
+  for (const pr of prs) {
+    if (pr && !unique.has(`${pr.repo}#${pr.number}`)) unique.set(`${pr.repo}#${pr.number}`, pr);
+  }
+  return [...unique.values()].sort((a, b) => Number(b.state === "open") - Number(a.state === "open"));
+}
+function countsLine(counts) {
+  const tags = ["proposed", "built", "defect", "unbuilt", "open", "untagged"].filter((tag) => counts[tag] > 0).map((tag) => `${counts[tag]} ${tag}`);
+  return `${counts.total} scenario(s)` + (tags.length > 0 ? `: ${tags.join(", ")}` : "");
+}
+function partsTable(change) {
+  const rows = PARTS.filter((part) => !(part === "decision" && change.states.decision === null)).map((part) => {
+    const prs = partPullRequests(change, part);
+    return `| ${part} | ${change.states[part]} | ${prs.length > 0 ? prs.map(prLink).join(", ") : "\u2014"} |`;
+  });
+  return ["| Part | State | Pull request |", "|---|---|---|", ...rows].join("\n");
+}
+function decisionSection(change) {
+  const decision = change.decision;
+  if (decision === null) return "## Decision\n\nNone: the proposal names no ADR (a small change).";
+  const status = decision.status || "no record in a connected repository";
+  return `## Decision
+
+${decision.adr} \xB7 ${status}${decision.title ? ` \u2014 ${decision.title}` : ""}`;
+}
+function contractSection(change) {
+  const files = change.contract.files;
+  return "## Contract\n\n" + (files.length > 0 ? files.map((file) => `- ${file.path} \u2014 ${fileSource(file)}`).join("\n") : "No contract file yet (openapi.yaml, asyncapi.yaml or contract.md).");
+}
+function behaviourSection(change) {
+  const { files, counts } = change.behaviour;
+  if (files.length === 0) {
+    return `## Behaviour
+
+No feature file names this change. A feature file joins it when its path or its first ten lines name \`${change.slug}\`${change.decision ? ` or ${change.decision.adr}` : ""}.`;
+  }
+  const blocks = files.map(
+    (file) => [
+      `### ${file.path}`,
+      "",
+      [file.title, file.runner ? `runner ${file.runner}` : "", fileSource(file), countsLine(file.counts)].filter(Boolean).join(" \xB7 "),
+      "",
+      ...file.scenarios.map((s) => `- ${s.id || "(no id)"} \xB7 ${s.state || "untagged"} \xB7 ${s.title}`)
+    ].join("\n")
+  );
+  return ["## Behaviour", countsLine(counts), ...blocks].join("\n\n");
+}
+function planSection(change) {
+  const { file, draftId, board } = change.plan;
+  const boardLine = board ? `[#${board.number} ${board.title}](${board.url}) \u2014 todo ${board.items.todo} \xB7 in progress ${board.items.inProgress} \xB7 done ${board.items.done}` + (board.items.truncated ? " (counted over its first 500 items)" : "") : "none";
+  return [
+    "## Plan",
+    "",
+    `- plan.md: ${file ? `${file.path} \u2014 ${fileSource(file)}` : "none"}`,
+    `- Draft: ${draftId ?? "none"}`,
+    `- Board: ${boardLine}`
+  ].join("\n");
+}
+function releaseSection(change) {
+  const lines = change.release.prs.map(
+    (pr) => `- ${prLink(pr)} \xB7 ${pr.title} \xB7 ` + (pr.approvingReview ? `approved by ${pr.approvingReview.by} at ${pr.approvingReview.at}` : "no approving review on its head yet")
+  );
+  return `## Release
+
+${lines.length > 0 ? lines.join("\n") : "No release pull request is open."}`;
+}
+function formatChange(change) {
+  const header = `# ${change.title}
+
+\`${change.key}\` \xB7 size: ${change.size}` + (change.archived ? " \xB7 archived: read-only, done" : "") + ` \xB7 synced ${change.syncedAt}`;
+  return [
+    header,
+    partsTable(change),
+    decisionSection(change),
+    contractSection(change),
+    behaviourSection(change),
+    planSection(change),
+    releaseSection(change),
+    // Compact: a change's every scenario with its steps rides in this block.
+    "```json\n" + JSON.stringify(change) + "\n```",
+    briefVerdict(change.states)
+  ].join("\n\n");
+}
+function registerGetChange(server, apiClient) {
+  server.registerTool(
+    "get_change",
+    {
+      title: "Get Change",
+      description: `Read one change (a specs/changes/<slug>/ folder of a connected repository) as SystemDox last synced it from GitHub: the state of each part of its brief (decision, contract, behaviour, plan) and of its release, each with its pull request; the decision's ADR and status; the contract files; every feature file that names the change, with its scenarios as id \xB7 state \xB7 title; the plan (plan.md, the draft, the board); the release pull requests; and the Change object as JSON. The last line says "The brief is passed" or "The brief is not passed: <part> is <state>". Call it before building a story, and stop if the brief is not passed or the story's scenarios are not proposed. Read-only.`,
+      inputSchema: {
+        repo: z.string().regex(REPO_RE, "the repository as owner/name, e.g. acme/booking-api").describe("The repository that holds the change, as owner/name"),
+        slug: z.string().max(SLUG_MAX).regex(SLUG_RE, "a change folder's name: lower-case words joined by -, e.g. customer-reminders").describe("The change's folder name: specs/changes/<slug>/")
+      },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ repo, slug }) => {
+      const [owner, name] = repo.split("/");
+      let change;
+      try {
+        change = await apiClient.getFresh(
+          `/v1/changes/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/${encodeURIComponent(slug)}`
+        );
+      } catch (err) {
+        if (err.status === 404) {
+          return {
+            content: [{ type: "text", text: `No such change ${repo}/${slug}` }],
+            isError: true
+          };
+        }
+        throw err;
+      }
+      return { content: [{ type: "text", text: formatChange(change) }] };
+    }
+  );
+}
+export {
+  briefVerdict,
+  formatChange,
+  registerGetChange
+};

package/dist/tools/skills.js

@@ -291,7 +291,7 @@ Left out (hidden files are never part of a skill): ${skipped.join(", ")}` : "")
       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))}`
+          `No skills published yet. Publish one with publish_skill; they appear at ${configLink("/docs/team-setup/skills", await workspaceBase(apiClient))}`
         );
       }
       return text(

package/package.json

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