@systemdox/mcp-server 0.1.14 → 0.1.16

package/README.md

@@ -45,7 +45,8 @@ HTTP. Point any HTTP-capable MCP client at it — nothing to install or update.
   which suits serverless hosting. There is no long-lived SSE stream.
 - **Scope** — the key is the boundary. A key bound to a single space (a
   "department" key) sees only that space's context; org-wide planner endpoints
-  (`get_planning_context`) are barred to it and answer `403`. Give each
+  (`get_planning_context`, `get_plan_board`) are barred to it and answer `403`.
+  Give each
   department's repo its own key via `${SYSTEMDOX_API_KEY}`, and an agent in one
   department never sees another's checks, specs, or docs.
 
@@ -89,7 +90,7 @@ npx @systemdox/mcp-server setup
 ## Tools
 
 Read: `get_checks`, `get_specs`, `get_docs`, `get_tech_stack`,
-`get_planning_context`, `get_context`, `get_project_rules`,
+`get_planning_context`, `get_plan_board`, `get_context`, `get_project_rules`,
 `get_prompt_templates`. Write: `create_check`, `update_spec`,
 `report_decision`, `create_project_rule`, `create_prompt_template`. Write tools
 require an API key with `editor`+ role.

package/dist/cli.js

@@ -246,6 +246,27 @@ var init_deprecation = __esm({
   }
 });
 
+// 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`;
+}
+var init_config_links = __esm({
+  "src/lib/config-links.ts"() {
+    "use strict";
+  }
+});
+
 // src/tools/get-guardrails.ts
 import { z } from "zod";
 function registerGetGuardrails(server2, apiClient2) {
@@ -268,13 +289,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(
@@ -331,6 +348,7 @@ var init_get_guardrails = __esm({
     "use strict";
     init_language();
     init_deprecation();
+    init_config_links();
     DESCRIPTION = "Retrieve SystemDox checks (banned patterns, required patterns, coding rules). Filter by language, category, or file path to get only relevant checks.";
     inputSchema = () => ({
       language: z.string().optional().describe(
@@ -559,7 +577,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))}`
             }
           ]
         };
@@ -593,6 +611,7 @@ ${sections}`
 var init_get_tech_stack = __esm({
   "src/tools/get-tech-stack.ts"() {
     "use strict";
+    init_config_links();
   }
 });
 
@@ -650,11 +669,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")
           }
         ]
       };
@@ -664,6 +693,199 @@ ${specs}`);
 var init_get_planning_context = __esm({
   "src/tools/get-planning-context.ts"() {
     "use strict";
+    init_config_links();
+  }
+});
+
+// src/tools/get-plan-board.ts
+import { z as z5 } from "zod";
+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")}` : "")
+          }
+        ]
+      };
+    }
+  );
+}
+var API_ITEM_PAGE, DEFAULT_LIMIT, BUCKET_LABELS, BUCKET_ORDER, STATUS_ARG_TO_BUCKET;
+var init_get_plan_board = __esm({
+  "src/tools/get-plan-board.ts"() {
+    "use strict";
+    init_config_links();
+    API_ITEM_PAGE = 100;
+    DEFAULT_LIMIT = 50;
+    BUCKET_LABELS = {
+      inProgress: "In Progress",
+      todo: "Todo",
+      done: "Done"
+    };
+    BUCKET_ORDER = ["inProgress", "todo", "done"];
+    STATUS_ARG_TO_BUCKET = {
+      todo: "todo",
+      in_progress: "inProgress",
+      done: "done"
+    };
   }
 });
 
@@ -1240,7 +1462,7 @@ var init_context_builder = __esm({
 });
 
 // src/tools/get-context.ts
-import { z as z5 } from "zod";
+import { z as z6 } from "zod";
 function registerGetContext(server2, apiClient2) {
   server2.registerTool(
     "get_context",
@@ -1248,13 +1470,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 }) => {
@@ -1277,7 +1499,7 @@ var init_get_context = __esm({
 });
 
 // src/tools/create-guardrail.ts
-import { z as z6 } from "zod";
+import { z as z7 } from "zod";
 function registerCreateGuardrail(server2, apiClient2) {
   const handler = async ({
     title,
@@ -1357,19 +1579,19 @@ var init_create_guardrail = __esm({
       "data-access"
     ];
     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")
     });
   }
 });
 
 // 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",
@@ -1377,12 +1599,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')"
         )
       },
@@ -1437,7 +1659,7 @@ var init_update_spec = __esm({
 });
 
 // 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",
@@ -1445,11 +1667,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
@@ -1505,7 +1727,7 @@ var init_report_decision = __esm({
 });
 
 // src/tools/get-project-rules.ts
-import { z as z9 } from "zod";
+import { z as z10 } from "zod";
 function registerGetProjectRules(server2, apiClient2) {
   server2.registerTool(
     "get_project_rules",
@@ -1513,7 +1735,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 }) => {
@@ -1527,13 +1749,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();
@@ -1571,6 +1789,7 @@ var CATEGORY_LABELS;
 var init_get_project_rules = __esm({
   "src/tools/get-project-rules.ts"() {
     "use strict";
+    init_config_links();
     CATEGORY_LABELS = {
       deployment: "Deployment",
       architecture: "Architecture",
@@ -1583,7 +1802,7 @@ var init_get_project_rules = __esm({
 });
 
 // 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",
@@ -1591,10 +1810,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
@@ -1641,7 +1860,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))}`
             }
           ]
         };
@@ -1671,11 +1890,12 @@ ${text}`
 var init_get_prompt_templates = __esm({
   "src/tools/get-prompt-templates.ts"() {
     "use strict";
+    init_config_links();
   }
 });
 
 // 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",
@@ -1683,9 +1903,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
@@ -1730,6 +1950,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);
@@ -1748,6 +1969,7 @@ var init_server = __esm({
     init_get_docs();
     init_get_tech_stack();
     init_get_planning_context();
+    init_get_plan_board();
     init_get_context();
     init_create_guardrail();
     init_update_spec();
@@ -1935,7 +2157,7 @@ async function setup() {
     console.log(`  Configured: ${target.name}`);
   }
   console.log(
-    "\n  Done! Restart your AI coding tool to activate the SystemDox MCP server.\n  The server provides 13 tools: get_context, get_checks,\n  get_project_rules, get_prompt_templates, get_specs, get_docs,\n  get_tech_stack, get_planning_context, create_check,\n  create_project_rule, create_prompt_template, update_spec,\n  report_decision.\n\n  get_guardrails and create_guardrail remain registered as deprecated\n  aliases of get_checks and create_check \u2014 existing configs keep working.\n"
+    "\n  Done! Restart your AI coding tool to activate the SystemDox MCP server.\n  The server provides 14 tools: get_context, get_checks,\n  get_project_rules, get_prompt_templates, get_specs, get_docs,\n  get_tech_stack, get_planning_context, get_plan_board, create_check,\n  create_project_rule, create_prompt_template, update_spec,\n  report_decision.\n\n  get_guardrails and create_guardrail remain registered as deprecated\n  aliases of get_checks and create_check \u2014 existing configs keep working.\n"
   );
 }
 var args = process.argv.slice(2);