@systemdox/mcp-server 0.1.14 → 0.1.16

package/dist/tools/get-plan-board.js

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+
+// src/tools/get-plan-board.ts
+import { z } from "zod";
+
+// 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-plan-board.ts
+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: z.number().int().positive().optional().describe(
+          "Board number (the N in github.com/orgs/{org}/projects/N). Omit to list the open boards."
+        ),
+        status: z.enum(["todo", "in_progress", "done"]).optional().describe(
+          "With project_number, return only the items in this status group"
+        ),
+        limit: z.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")}` : "")
+          }
+        ]
+      };
+    }
+  );
+}
+export {
+  bucketOf,
+  registerGetPlanBoard
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@systemdox/mcp-server",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "type": "module",
   "description": "MCP server that exposes SystemDox checks, specs, docs, and tech stack to AI coding tools",
   "main": "./dist/index.js",