@systemdox/mcp-server 0.1.14 → 0.1.16

package/dist/http.js

@@ -200,6 +200,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(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/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 = () => ({
@@ -233,13 +249,9 @@ function registerGetGuardrails(server, apiClient) {
       );
     }
     if (filtered.length === 0) {
+      const text2 = guardrails.length === 0 ? `No checks found. Add checks at ${configLink("/docs/guardrails", await workspaceBase(apiClient))}` : `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(
@@ -494,7 +506,7 @@ function registerGetTechStack(server, apiClient) {
           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(apiClient))}`
             }
           ]
         };
@@ -580,11 +592,21 @@ ${adrs}`);
 
 ${specs}`);
       }
+      if (sections.length === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `No planning context available. Connect repositories at ${configLink("/settings/github", await workspaceBase(apiClient))}`
+            }
+          ]
+        };
+      }
       return {
         content: [
           {
             type: "text",
-            text: sections.join("\n\n") || "No planning context available."
+            text: sections.join("\n\n")
           }
         ]
       };
@@ -592,8 +614,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(server, apiClient) {
+  server.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 apiClient.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(apiClient))}`
+              }
+            ]
+          };
+        }
+        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(apiClient))}`
+              }
+            ]
+          };
+        }
+        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 apiClient.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(apiClient))}`
+            }
+          ]
+        };
+      }
+      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;
@@ -1160,13 +1367,13 @@ function registerGetContext(server, apiClient) {
       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 }) => {
@@ -1183,7 +1390,7 @@ function registerGetContext(server, apiClient) {
 }
 
 // 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",
@@ -1196,13 +1403,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(server, apiClient) {
   const handler2 = async ({
@@ -1268,7 +1475,7 @@ function registerCreateGuardrail(server, apiClient) {
 }
 
 // src/tools/update-spec.ts
-import { z as z7 } from "zod";
+import { z as z8 } from "zod";
 function registerUpdateSpec(server, apiClient) {
   server.registerTool(
     "update_spec",
@@ -1276,12 +1483,12 @@ function registerUpdateSpec(server, apiClient) {
       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')"
         )
       },
@@ -1331,7 +1538,7 @@ function registerUpdateSpec(server, apiClient) {
 }
 
 // src/tools/report-decision.ts
-import { z as z8 } from "zod";
+import { z as z9 } from "zod";
 function registerReportDecision(server, apiClient) {
   server.registerTool(
     "report_decision",
@@ -1339,11 +1546,11 @@ function registerReportDecision(server, apiClient) {
       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
@@ -1394,7 +1601,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",
@@ -1410,7 +1617,7 @@ function registerGetProjectRules(server, apiClient) {
       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 }) => {
@@ -1424,13 +1631,9 @@ function registerGetProjectRules(server, apiClient) {
         );
       }
       if (filtered.length === 0) {
+        const text2 = rules.length === 0 ? `No project rules found. Add rules at ${configLink("/docs/rules", await workspaceBase(apiClient))}` : `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();
@@ -1466,7 +1669,7 @@ function registerGetProjectRules(server, apiClient) {
 }
 
 // src/tools/create-project-rule.ts
-import { z as z10 } from "zod";
+import { z as z11 } from "zod";
 function registerCreateProjectRule(server, apiClient) {
   server.registerTool(
     "create_project_rule",
@@ -1474,10 +1677,10 @@ function registerCreateProjectRule(server, apiClient) {
       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
@@ -1519,7 +1722,7 @@ function registerGetPromptTemplates(server, apiClient) {
           content: [
             {
               type: "text",
-              text: "No prompt templates found."
+              text: `No prompt templates found. Add templates at ${configLink("/docs/prompts", await workspaceBase(apiClient))}`
             }
           ]
         };
@@ -1548,7 +1751,7 @@ ${text}`
 }
 
 // src/tools/create-prompt-template.ts
-import { z as z11 } from "zod";
+import { z as z12 } from "zod";
 function registerCreatePromptTemplate(server, apiClient) {
   server.registerTool(
     "create_prompt_template",
@@ -1556,9 +1759,9 @@ function registerCreatePromptTemplate(server, apiClient) {
       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
@@ -1597,6 +1800,7 @@ function createServer(apiClient) {
   registerGetDocs(server, apiClient);
   registerGetTechStack(server, apiClient);
   registerGetPlanningContext(server, apiClient);
+  registerGetPlanBoard(server, apiClient);
   registerGetContext(server, apiClient);
   registerGetProjectRules(server, apiClient);
   registerGetPromptTemplates(server, apiClient);