@systemdox/mcp-server 0.1.14 → 0.1.16

package/dist/index.js

@@ -216,6 +216,22 @@ function legacyToolDescription(canonical, description) {
   return `DEPRECATED \u2014 use \`${canonical}\` instead. This name still works and will not be removed before ${LEGACY_TOOL_REMOVAL_EARLIEST}. ${description}`;
 }
 
+// src/lib/config-links.ts
+async function workspaceBase(apiClient2) {
+  try {
+    const access = await apiClient2.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/tools/get-guardrails.ts
 var DESCRIPTION = "Retrieve SystemDox checks (banned patterns, required patterns, coding rules). Filter by language, category, or file path to get only relevant checks.";
 var inputSchema = () => ({
@@ -249,13 +265,9 @@ function registerGetGuardrails(server2, apiClient2) {
       );
     }
     if (filtered.length === 0) {
+      const text2 = guardrails.length === 0 ? `No checks found. Add checks at ${configLink("/docs/guardrails", await workspaceBase(apiClient2))}` : `No checks found${lang ? ` for language "${lang}"` : ""}${category ? ` in category "${category}"` : ""}.`;
       return {
-        content: [
-          {
-            type: "text",
-            text: `No checks found${lang ? ` for language "${lang}"` : ""}${category ? ` in category "${category}"` : ""}.`
-          }
-        ]
+        content: [{ type: "text", text: text2 }]
       };
     }
     const text = filtered.map(
@@ -510,7 +522,7 @@ function registerGetTechStack(server2, apiClient2) {
           content: [
             {
               type: "text",
-              text: "No tech stack entries configured."
+              text: `No tech stack entries configured. Add your stack at ${configLink("/docs/tech-stack", await workspaceBase(apiClient2))}`
             }
           ]
         };
@@ -596,11 +608,21 @@ ${adrs}`);
 
 ${specs}`);
       }
+      if (sections.length === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `No planning context available. Connect repositories at ${configLink("/settings/github", await workspaceBase(apiClient2))}`
+            }
+          ]
+        };
+      }
       return {
         content: [
           {
             type: "text",
-            text: sections.join("\n\n") || "No planning context available."
+            text: sections.join("\n\n")
           }
         ]
       };
@@ -608,8 +630,193 @@ ${specs}`);
   );
 }
 
-// src/tools/get-context.ts
+// src/tools/get-plan-board.ts
 import { z as z5 } from "zod";
+var API_ITEM_PAGE = 100;
+var DEFAULT_LIMIT = 50;
+var BUCKET_LABELS = {
+  inProgress: "In Progress",
+  todo: "Todo",
+  done: "Done"
+};
+var BUCKET_ORDER = ["inProgress", "todo", "done"];
+var STATUS_ARG_TO_BUCKET = {
+  todo: "todo",
+  in_progress: "inProgress",
+  done: "done"
+};
+function bucketOf(item) {
+  const status = (item.fields?.Status ?? "").trim().toLowerCase();
+  if (status) {
+    if (status.includes("done") || status.includes("ship") || status.includes("complete")) {
+      return "done";
+    }
+    if (status.includes("progress") || status.includes("doing") || status.includes("review")) {
+      return "inProgress";
+    }
+    return "todo";
+  }
+  return item.state === "CLOSED" ? "done" : "todo";
+}
+function formatBoards(boards) {
+  const lines = boards.map((b) => {
+    const c = b.statusCounts ?? { todo: 0, inProgress: 0, done: 0 };
+    return `- **${b.title}** \u2014 board #${b.number} \xB7 ${b.itemCount} item(s) (todo ${c.todo} \xB7 in progress ${c.inProgress} \xB7 done ${c.done})` + (b.description ? `
+  ${b.description}` : "") + `
+  ${b.url}`;
+  });
+  return lines.join("\n");
+}
+function formatItem(item) {
+  const meta = [];
+  if (item.labels.length > 0) meta.push(`labels: ${item.labels.join(", ")}`);
+  if (item.assignees.length > 0)
+    meta.push(`assignees: ${item.assignees.join(", ")}`);
+  const epic = item.fields?.Epic;
+  if (epic) meta.push(`epic: ${epic}`);
+  return `- #${item.number} ${item.title}${item.repo ? ` \u2014 ${item.repo}` : ""}` + (meta.length > 0 ? `
+  ${meta.join(" \xB7 ")}` : "") + (item.url ? `
+  ${item.url}` : "");
+}
+function registerGetPlanBoard(server2, apiClient2) {
+  server2.registerTool(
+    "get_plan_board",
+    {
+      title: "Get Plan Board",
+      description: "Read the GitHub Projects boards connected to this workspace. With no arguments, lists the open boards with their item counts by status. With project_number, lists that board's issues grouped by status (In Progress / Todo / Done), each with issue number, title, repo, labels, assignees and URL \u2014 so you can see what is planned or in flight and pick up the right issue. Read-only: this tool cannot create, move, or close board items.",
+      inputSchema: {
+        project_number: z5.number().int().positive().optional().describe(
+          "Board number (the N in github.com/orgs/{org}/projects/N). Omit to list the open boards."
+        ),
+        status: z5.enum(["todo", "in_progress", "done"]).optional().describe(
+          "With project_number, return only the items in this status group"
+        ),
+        limit: z5.number().int().positive().max(200).optional().describe(
+          `Max items to list (default ${DEFAULT_LIMIT}). Group headings always show the true totals.`
+        )
+      }
+    },
+    async ({ project_number, status, limit }) => {
+      if (project_number === void 0) {
+        const boards = await apiClient2.get(
+          "/v1/planning/projects"
+        );
+        if (boards.length === 0) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `No project boards found. Connect a GitHub organisation and create a board at ${configLink("/plan", await workspaceBase(apiClient2))}`
+              }
+            ]
+          };
+        }
+        const open = boards.filter((b) => !b.closed);
+        if (open.length === 0) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `No open project boards (${boards.length} closed). Reopen one, or create a board at ${configLink("/plan", await workspaceBase(apiClient2))}`
+              }
+            ]
+          };
+        }
+        const closedNote = boards.length > open.length ? `
+
+_${boards.length - open.length} closed board(s) not listed._` : "";
+        return {
+          content: [
+            {
+              type: "text",
+              text: `${open.length} open project board(s):
+
+${formatBoards(open)}` + closedNote + `
+
+Call get_plan_board with project_number to list a board's issues.`
+            }
+          ]
+        };
+      }
+      const response = await apiClient2.get(
+        `/v1/planning/projects/${project_number}/items`
+      );
+      const allItems = response.items ?? [];
+      const boardName = response.projectTitle ? `**${response.projectTitle}** \u2014 board #${project_number}` : `Board #${project_number}`;
+      if (allItems.length === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `${boardName} has no issues, or it is not visible to this workspace's GitHub connection. Check the board at ${configLink("/plan", await workspaceBase(apiClient2))}`
+            }
+          ]
+        };
+      }
+      const grouped = {
+        inProgress: [],
+        todo: [],
+        done: []
+      };
+      for (const item of allItems) grouped[bucketOf(item)].push(item);
+      const wanted = status ? [STATUS_ARG_TO_BUCKET[status]] : BUCKET_ORDER;
+      const shown = wanted.reduce((n, b) => n + grouped[b].length, 0);
+      if (shown === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `${boardName}: no items with status "${status}" (of ${allItems.length} item(s) on the board).`
+            }
+          ]
+        };
+      }
+      const cap = limit ?? DEFAULT_LIMIT;
+      let budget = cap;
+      const sections = [];
+      let rendered = 0;
+      for (const b of wanted) {
+        const items = grouped[b];
+        if (items.length === 0) continue;
+        const slice = items.slice(0, Math.max(budget, 0));
+        budget -= slice.length;
+        rendered += slice.length;
+        const omitted = items.length - slice.length;
+        sections.push(
+          `### ${BUCKET_LABELS[b]} (${items.length})
+` + (slice.length > 0 ? slice.map(formatItem).join("\n") : "_(not listed \u2014 item limit reached)_") + (omitted > 0 && slice.length > 0 ? `
+_\u2026${omitted} more not listed._` : "")
+        );
+      }
+      const notes = [];
+      if (rendered < shown) {
+        notes.push(
+          `_Listing ${rendered} of ${shown} matching item(s) \u2014 raise limit (max 200) or filter by status to see the rest._`
+        );
+      }
+      if (allItems.length >= API_ITEM_PAGE) {
+        notes.push(
+          `_The API reads the board's first ${API_ITEM_PAGE} items; a larger board may have more._`
+        );
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: `${boardName} \u2014 ${allItems.length} item(s)
+
+` + sections.join("\n\n") + (notes.length > 0 ? `
+
+${notes.join("\n")}` : "")
+          }
+        ]
+      };
+    }
+  );
+}
+
+// src/tools/get-context.ts
+import { z as z6 } from "zod";
 
 // src/lib/scoring.ts
 var WEIGHT_PATH = 0.4;
@@ -1176,13 +1383,13 @@ function registerGetContext(server2, apiClient2) {
       title: "Get Context",
       description: "Intelligent context aggregator: fetches checks, specs, docs, and tech stack, ranks them by relevance to your current task, and returns the full text of the highest-ranked items within a token budget \u2014 each with the ID needed to fetch the rest. Use this instead of calling individual tools when you want curated, relevant context.",
       inputSchema: {
-        task_description: z5.string().describe(
+        task_description: z6.string().describe(
           "What you're working on (e.g., 'add a new REST endpoint for user preferences')"
         ),
-        file_paths: z5.array(z5.string()).optional().describe(
+        file_paths: z6.array(z6.string()).optional().describe(
           "File paths being edited \u2014 used for language/category detection"
         ),
-        max_tokens: z5.number().optional().describe("Maximum token budget for the response (default: 4000)")
+        max_tokens: z6.number().optional().describe("Maximum token budget for the response (default: 4000)")
       }
     },
     async ({ task_description, file_paths, max_tokens }) => {
@@ -1199,7 +1406,7 @@ function registerGetContext(server2, apiClient2) {
 }
 
 // src/tools/create-guardrail.ts
-import { z as z6 } from "zod";
+import { z as z7 } from "zod";
 var DESCRIPTION2 = "Create a new check in SystemDox. Use this when you discover a pattern that should be enforced (banned pattern, required pattern, coding rule).";
 var CATEGORIES = [
   "imports",
@@ -1212,13 +1419,13 @@ var CATEGORIES = [
   "data-access"
 ];
 var inputSchema2 = () => ({
-  title: z6.string().describe("Short title for the check"),
-  description: z6.string().describe("Detailed description of what the check enforces and why"),
-  severity: z6.enum(["critical", "high", "medium", "low"]).describe("Severity level"),
-  category: z6.enum(CATEGORIES).optional().describe("Category (defaults to conventions)"),
-  pattern: z6.string().optional().describe("Bad code pattern that should be avoided"),
-  fix: z6.string().optional().describe("Correct code pattern to use instead"),
-  fitness_test: z6.string().optional().describe("Shell command to detect violations in CI")
+  title: z7.string().describe("Short title for the check"),
+  description: z7.string().describe("Detailed description of what the check enforces and why"),
+  severity: z7.enum(["critical", "high", "medium", "low"]).describe("Severity level"),
+  category: z7.enum(CATEGORIES).optional().describe("Category (defaults to conventions)"),
+  pattern: z7.string().optional().describe("Bad code pattern that should be avoided"),
+  fix: z7.string().optional().describe("Correct code pattern to use instead"),
+  fitness_test: z7.string().optional().describe("Shell command to detect violations in CI")
 });
 function registerCreateGuardrail(server2, apiClient2) {
   const handler = async ({
@@ -1284,7 +1491,7 @@ function registerCreateGuardrail(server2, apiClient2) {
 }
 
 // src/tools/update-spec.ts
-import { z as z7 } from "zod";
+import { z as z8 } from "zod";
 function registerUpdateSpec(server2, apiClient2) {
   server2.registerTool(
     "update_spec",
@@ -1292,12 +1499,12 @@ function registerUpdateSpec(server2, apiClient2) {
       title: "Update Spec",
       description: "Update an existing SystemDox spec's proposal, tasks, or requirements. Only draft specs can be modified \u2014 published specs must be versioned first.",
       inputSchema: {
-        spec_id: z7.string().describe("ID of the spec to update"),
-        section: z7.enum(["proposal", "tasks", "requirements"]).describe("Which section to update"),
-        content: z7.string().describe(
+        spec_id: z8.string().describe("ID of the spec to update"),
+        section: z8.enum(["proposal", "tasks", "requirements"]).describe("Which section to update"),
+        content: z8.string().describe(
           "New markdown content for the section. For requirements, provide the full requirement content."
         ),
-        requirement_name: z7.string().optional().describe(
+        requirement_name: z8.string().optional().describe(
           "Name of the requirement (required when section is 'requirements')"
         )
       },
@@ -1347,7 +1554,7 @@ function registerUpdateSpec(server2, apiClient2) {
 }
 
 // src/tools/report-decision.ts
-import { z as z8 } from "zod";
+import { z as z9 } from "zod";
 function registerReportDecision(server2, apiClient2) {
   server2.registerTool(
     "report_decision",
@@ -1355,11 +1562,11 @@ function registerReportDecision(server2, apiClient2) {
       title: "Report Decision",
       description: "Record an architecture decision made during development. Creates a draft ADR in SystemDox for human review.",
       inputSchema: {
-        title: z8.string().describe("Decision title (e.g., 'Use WebSocket for real-time updates')"),
-        context: z8.string().describe("What prompted this decision \u2014 the problem or constraint"),
-        decision: z8.string().describe("What was decided and why"),
-        consequences: z8.string().describe("What this decision means going forward \u2014 trade-offs, follow-up work"),
-        related_files: z8.array(z8.string()).optional().describe("File paths related to this decision")
+        title: z9.string().describe("Decision title (e.g., 'Use WebSocket for real-time updates')"),
+        context: z9.string().describe("What prompted this decision \u2014 the problem or constraint"),
+        decision: z9.string().describe("What was decided and why"),
+        consequences: z9.string().describe("What this decision means going forward \u2014 trade-offs, follow-up work"),
+        related_files: z9.array(z9.string()).optional().describe("File paths related to this decision")
       },
       annotations: {
         readOnlyHint: false
@@ -1410,7 +1617,7 @@ Status: draft \u2014 review in SystemDox before publishing.`
 }
 
 // src/tools/get-project-rules.ts
-import { z as z9 } from "zod";
+import { z as z10 } from "zod";
 var CATEGORY_LABELS = {
   deployment: "Deployment",
   architecture: "Architecture",
@@ -1426,7 +1633,7 @@ function registerGetProjectRules(server2, apiClient2) {
       title: "Get Project Rules",
       description: "Retrieve project rules defined in SystemDox Standards. These are team-defined principles covering deployment, architecture, security, testing, and process. Filter by category to get only relevant rules.",
       inputSchema: {
-        category: z9.enum(["deployment", "architecture", "security", "testing", "process", "other"]).optional().describe("Filter by rule category")
+        category: z10.enum(["deployment", "architecture", "security", "testing", "process", "other"]).optional().describe("Filter by rule category")
       }
     },
     async ({ category }) => {
@@ -1440,13 +1647,9 @@ function registerGetProjectRules(server2, apiClient2) {
         );
       }
       if (filtered.length === 0) {
+        const text2 = rules.length === 0 ? `No project rules found. Add rules at ${configLink("/docs/rules", await workspaceBase(apiClient2))}` : `No project rules found${category ? ` in category "${category}"` : ""}.`;
         return {
-          content: [
-            {
-              type: "text",
-              text: `No project rules found${category ? ` in category "${category}"` : ""}.`
-            }
-          ]
+          content: [{ type: "text", text: text2 }]
         };
       }
       const grouped = /* @__PURE__ */ new Map();
@@ -1482,7 +1685,7 @@ function registerGetProjectRules(server2, apiClient2) {
 }
 
 // src/tools/create-project-rule.ts
-import { z as z10 } from "zod";
+import { z as z11 } from "zod";
 function registerCreateProjectRule(server2, apiClient2) {
   server2.registerTool(
     "create_project_rule",
@@ -1490,10 +1693,10 @@ function registerCreateProjectRule(server2, apiClient2) {
       title: "Create Project Rule",
       description: "Create a new project rule in SystemDox Standards. Use this when you discover a team principle or convention that should be enforced across the project.",
       inputSchema: {
-        text: z10.string().describe(
+        text: z11.string().describe(
           "The rule statement \u2014 one enforceable principle per rule (e.g. 'All deployments MUST go through GitHub Actions workflows')"
         ),
-        category: z10.enum(["deployment", "architecture", "security", "testing", "process", "other"]).describe("Rule category")
+        category: z11.enum(["deployment", "architecture", "security", "testing", "process", "other"]).describe("Rule category")
       },
       annotations: {
         readOnlyHint: false
@@ -1535,7 +1738,7 @@ function registerGetPromptTemplates(server2, apiClient2) {
           content: [
             {
               type: "text",
-              text: "No prompt templates found."
+              text: `No prompt templates found. Add templates at ${configLink("/docs/prompts", await workspaceBase(apiClient2))}`
             }
           ]
         };
@@ -1564,7 +1767,7 @@ ${text}`
 }
 
 // src/tools/create-prompt-template.ts
-import { z as z11 } from "zod";
+import { z as z12 } from "zod";
 function registerCreatePromptTemplate(server2, apiClient2) {
   server2.registerTool(
     "create_prompt_template",
@@ -1572,9 +1775,9 @@ function registerCreatePromptTemplate(server2, apiClient2) {
       title: "Create Prompt Template",
       description: "Create a new reusable prompt template in SystemDox Standards. Use this to store preconfigured prompts for common AI tasks like code reviews, documentation generation, or analysis frameworks.",
       inputSchema: {
-        name: z11.string().describe("Short name for the template"),
-        description: z11.string().optional().describe("Brief description of when to use this template"),
-        prompt: z11.string().describe("The full prompt text that Gen AI will use when generating content")
+        name: z12.string().describe("Short name for the template"),
+        description: z12.string().optional().describe("Brief description of when to use this template"),
+        prompt: z12.string().describe("The full prompt text that Gen AI will use when generating content")
       },
       annotations: {
         readOnlyHint: false
@@ -1613,6 +1816,7 @@ function createServer(apiClient2) {
   registerGetDocs(server2, apiClient2);
   registerGetTechStack(server2, apiClient2);
   registerGetPlanningContext(server2, apiClient2);
+  registerGetPlanBoard(server2, apiClient2);
   registerGetContext(server2, apiClient2);
   registerGetProjectRules(server2, apiClient2);
   registerGetPromptTemplates(server2, apiClient2);

package/dist/lib/config-links.d.ts

@@ -0,0 +1,18 @@
+import type { SystemDoxApiClient } from "./api-client.js";
+/**
+ * The tenant's workspace base URL (https://{slug}.systemdox.com), or null
+ * when it can't be resolved. The slug is the first label of the portal host
+ * that GET /v1/docs/portal-access reports — the API builds that host as
+ * `{slug}.{DOCS_DOMAIN}`, so the first label is the slug whichever docs
+ * domain is live. The GET goes through the api client's response cache, so
+ * repeated empty states don't re-fetch.
+ */
+export declare function workspaceBase(apiClient: SystemDoxApiClient): Promise<string | null>;
+/**
+ * Where to add missing configuration: a full URL when the workspace base is
+ * known, the in-app path otherwise.
+ *
+ * Mirrored by apps/app/src/pages/ai/mcpPreview.ts — keep the output
+ * byte-identical when either side changes.
+ */
+export declare function configLink(path: string, base: string | null): string;

package/dist/lib/config-links.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+
+// 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`;
+}
+export {
+  configLink,
+  workspaceBase
+};

package/dist/tools/get-plan-board.d.ts

@@ -0,0 +1,27 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { SystemDoxApiClient } from "../lib/api-client.js";
+interface BoardItem {
+    id: string;
+    number: number;
+    title: string;
+    state: string;
+    url: string;
+    repo: string;
+    labels: string[];
+    assignees: string[];
+    fields: Record<string, string>;
+}
+type Bucket = "todo" | "inProgress" | "done";
+/**
+ * Bucket one board item by its Status column.
+ *
+ * Boards name their columns differently, so match loosely — the same
+ * done/ship/complete and progress/doing/review matching the backend uses for
+ * the board-level counts (planning_api `_status_counts`). Where that helper
+ * treats a *missing* Status as todo, this falls back to the issue's own
+ * open/closed state, so a closed issue with no Status is never presented to an
+ * agent as available work.
+ */
+export declare function bucketOf(item: Pick<BoardItem, "state" | "fields">): Bucket;
+export declare function registerGetPlanBoard(server: McpServer, apiClient: SystemDoxApiClient): void;
+export {};