@thehammer/danx-dashboard-mcp 0.1.24 → 0.1.26

package/dist/handlers.test.js

@@ -0,0 +1,51 @@
+import { describe, it, expect } from "vitest";
+import { DashboardHttpClient } from "./http-client.js";
+import { issueList, issueTransition } from "./handlers.js";
+/**
+ * `issue_list` query-param forwarding. A fake `fetch` captures the built
+ * URL so each filter is asserted at the wire, through the real client's
+ * URL builder (`?repo=` always stamped, extra query merged after).
+ */
+function clientCapturing() {
+    const urls = [];
+    const fetchImpl = (async (url) => {
+        urls.push(url);
+        return new Response(JSON.stringify({ issues: [] }), { status: 200 });
+    });
+    const client = new DashboardHttpClient({ baseUrl: "http://localhost:5555", repo: "danxbot", token: "t" }, fetchImpl);
+    return { client, urls };
+}
+describe("issueList — query forwarding", () => {
+    it("forwards q as the server-side search needle", async () => {
+        const { client, urls } = clientCapturing();
+        await issueList(client, { q: "retire" });
+        expect(urls[0]).toContain("q=retire");
+    });
+    it("omits q when not provided", async () => {
+        const { client, urls } = clientCapturing();
+        await issueList(client, { include_closed: true });
+        expect(urls[0]).not.toContain("q=");
+        expect(urls[0]).toContain("include_closed=true");
+    });
+});
+describe("issueTransition — body forwarding", () => {
+    function clientCapturingBody() {
+        const bodies = [];
+        const fetchImpl = (async (_url, init) => {
+            bodies.push(JSON.parse(String(init?.body ?? "{}")));
+            return new Response(JSON.stringify({ issue: {} }), { status: 200 });
+        });
+        const client = new DashboardHttpClient({ baseUrl: "http://localhost:5555", repo: "danxbot", token: "t" }, fetchImpl);
+        return { client, bodies };
+    }
+    it("forwards manual: true on pickup (DX-946 operator self-pickup)", async () => {
+        const { client, bodies } = clientCapturingBody();
+        await issueTransition(client, { id: "DX-1", action: "pickup", manual: true });
+        expect(bodies[0]).toEqual({ action: "pickup", manual: true });
+    });
+    it("omits manual when not provided", async () => {
+        const { client, bodies } = clientCapturingBody();
+        await issueTransition(client, { id: "DX-1", action: "pickup" });
+        expect(bodies[0]).toEqual({ action: "pickup" });
+    });
+});

package/dist/index.js

@@ -48,6 +48,7 @@
  * agent reads `body.error` + structured fields to decide next action.
  * 5xx and network failures throw — never silently swallowed.
  */
+import { pathToFileURL } from "node:url";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
@@ -73,22 +74,34 @@ function readEnvOptional(name) {
     const v = process.env[name];
     return typeof v === "string" && v !== "" ? v : undefined;
 }
-// Compose the dispatch's qualified board id (`<repo>:<slug>`) from the
-// two env halves the worker injects. DANXBOT_BOARD_NAME already carries
-// the board SLUG at the spawn site (src/dispatch/core.ts sets it from
-// `board.slug`), so a plain join yields the canonical id — no transform.
-// Both halves are fail-loud required (Core Principle 1 — no fallback).
-const config = {
-    baseUrl: readEnvOrDie("DANXBOT_DASHBOARD_URL"),
-    token: readEnvOrDie("DANXBOT_DISPATCH_TOKEN"),
-    board: `${readEnvOrDie("DANX_REPO_NAME")}:${readEnvOrDie("DANXBOT_BOARD_NAME")}`,
-    // DX-1398 — OPTIONAL cross-process trace context. Present → stamped on every
-    // outbound call so the agent's card writes chain under the launch; absent
-    // (untraced dispatch) → omitted, and the dashboard mints a fresh root.
-    traceparent: readEnvOptional("DANXBOT_TRACEPARENT"),
-};
-const client = new DashboardHttpClient(config);
-const server = new McpServer({
+// The dispatch config + HTTP client are LATE-BOUND (assigned by `boot()` at
+// entrypoint, below). Tool registration happens at module import and the
+// callbacks close over these `let` bindings, reading them at CALL time — so the
+// module can be IMPORTED without env (the DX-1606 tool-defs generator + its
+// drift test introspect `server`'s tool schemas without spawning a dispatch),
+// while a real run still fails loud on missing env via `boot()`.
+let config;
+let client;
+/**
+ * Compose the dispatch's qualified board id (`<repo>:<slug>`) from the two env
+ * halves the worker injects and build the HTTP client. DANXBOT_BOARD_NAME
+ * already carries the board SLUG at the spawn site (src/dispatch/core.ts sets it
+ * from `board.slug`), so a plain join yields the canonical id — no transform.
+ * Both halves are fail-loud required (Core Principle 1 — no fallback).
+ */
+function boot() {
+    config = {
+        baseUrl: readEnvOrDie("DANXBOT_DASHBOARD_URL"),
+        token: readEnvOrDie("DANXBOT_DISPATCH_TOKEN"),
+        board: `${readEnvOrDie("DANX_REPO_NAME")}:${readEnvOrDie("DANXBOT_BOARD_NAME")}`,
+        // DX-1398 — OPTIONAL cross-process trace context. Present → stamped on every
+        // outbound call so the agent's card writes chain under the launch; absent
+        // (untraced dispatch) → omitted, and the dashboard mints a fresh root.
+        traceparent: readEnvOptional("DANXBOT_TRACEPARENT"),
+    };
+    client = new DashboardHttpClient(config);
+}
+export const server = new McpServer({
     name: "danx-dashboard-mcp",
     version: "0.1.0",
 });
@@ -321,7 +334,7 @@ server.tool("issue_quality_gate", "Toggle a single card's per-card quality-gate
     ...boardField,
 }, async (args) => jsonResult(await issueQualityGate(client, args)));
 // ---------------- issue_retro ----------------
-server.tool("issue_retro", "Replace the retro block via PUT /api/issues/:id/retro. Body: {good, bad, action_item_ids[], commits[]}. REFUSES 409 unless the card is terminal (completed_at OR cancelled_at) — retro ships when work concludes. Replace semantics: good/bad upsert; action_item_ids[] + commits[] soft-delete prior live rows and insert with fresh ordinals. action_item_ids[] entries MUST match <PREFIX>-N. commits[] entries take {sha, subject?}.", {
+server.tool("issue_retro", "Replace the retro block via PUT /api/issues/:id/retro. Body: {good, bad, action_item_ids[], commits[], tests[]}. REFUSES 409 unless the card is terminal (completed_at OR cancelled_at) — retro ships when work concludes. Replace semantics: good/bad upsert; action_item_ids[] + commits[] + tests[] soft-delete prior live rows and insert with fresh ordinals. action_item_ids[] entries MUST match <PREFIX>-N. commits[] entries take {sha, subject?}. tests[] (DX-1646) is REQUIRED (empty array allowed — the \"ran no tests\" case): one row per test GROUP that ran (a whole suite/class — name the group, do NOT list individual unit tests) or per individual e2e test (kind:'e2e', listed explicitly since they are few + expensive). Each row: {name, kind:'group'|'e2e', num_tests, num_passing_tests, duration_ms} required; num_assertions + num_passing_assertions NULLABLE (vitest surfaces no assertion totals — pass null or omit).", {
     id: z.string().min(1),
     good: z.string(),
     bad: z.string(),
@@ -330,6 +343,20 @@ server.tool("issue_retro", "Replace the retro block via PUT /api/issues/:id/retr
         sha: z.string().min(1),
         subject: z.string().optional(),
     })),
+    tests: z.array(z.object({
+        name: z.string().min(1),
+        kind: z.enum(["group", "e2e"]),
+        num_tests: z.number().int().nonnegative(),
+        num_assertions: z.number().int().nonnegative().nullable().optional(),
+        num_passing_tests: z.number().int().nonnegative(),
+        num_passing_assertions: z
+            .number()
+            .int()
+            .nonnegative()
+            .nullable()
+            .optional(),
+        duration_ms: z.number().int().nonnegative(),
+    })),
     ...boardField,
 }, async (args) => jsonResult(await issueRetro(client, args)));
 // ---------------- issue_attach ----------------
@@ -347,11 +374,20 @@ server.tool("issue_attach", "Attach a LOCAL file to an issue card via POST /api/
 }, async (args) => jsonResult(await issueAttach(client, args)));
 // ---------------- main ----------------
 async function main() {
+    boot();
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error(`danx-dashboard-mcp running on stdio (dashboard=${config.baseUrl}, board=${config.board})`);
 }
-main().catch((err) => {
-    console.error(`[danx-dashboard-mcp] fatal: ${err.message}`);
-    process.exit(1);
-});
+// Boot the stdio server ONLY when run as the entrypoint (the published bin).
+// Importing this module (the tool-defs generator + its drift test) registers
+// the tools on `server` without reading env or attaching stdin — so the
+// schemas can be introspected without spawning a dispatch.
+const isEntrypoint = typeof process.argv[1] === "string" &&
+    import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isEntrypoint) {
+    main().catch((err) => {
+        console.error(`[danx-dashboard-mcp] fatal: ${err.message}`);
+        process.exit(1);
+    });
+}

package/dist/tool-defs.js

@@ -0,0 +1,58 @@
+/**
+ * DX-1606 — expose THIS MCP server's tool DEFINITIONS as plain JSON Schema, so
+ * the danxbot service can count the injected-context token cost of each tool.
+ *
+ * The server registers tools via `server.tool(name, description, zodShape, …)`
+ * (in `index.ts`); the zod shapes are converted to JSON Schema by the MCP SDK
+ * when it answers `tools/list`. Rather than re-declare the schemas (drift), this
+ * module drives the SAME `tools/list` the live agent receives by linking an
+ * in-memory client to the already-registered `server` — so the emitted defs are
+ * byte-identical to what the agent's context is charged for.
+ *
+ * The danxbot service can NOT take a zod / MCP-SDK runtime dependency (and the
+ * Docker image does not install this package's node_modules), so the service
+ * reads the COMMITTED `tool-defs.json` produced by `generateToolDefsJson()`
+ * below — plain data, no runtime deps. `gen-tool-defs.ts` writes that file and
+ * `tool-defs.test.ts` asserts it is in sync (fail-loud on drift).
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { server } from "./index.js";
+/** The server id the danx-dashboard catalog mcp-server artifact is keyed by. */
+export const DANX_DASHBOARD_SERVER_ID = "danx-dashboard";
+/**
+ * Introspect `server`'s registered tools via an in-memory `tools/list` — the
+ * exact `{name, description, inputSchema}` the agent's context receives — and
+ * map them to the API's `{name, description, input_schema}` shape, sorted by
+ * name for a stable committed artifact.
+ */
+export async function generateToolDefs() {
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    const client = new Client({ name: "tool-defs-introspect", version: "0.0.0" });
+    await Promise.all([
+        server.connect(serverTransport),
+        client.connect(clientTransport),
+    ]);
+    try {
+        const { tools } = await client.listTools();
+        return tools
+            .map((t) => ({
+            name: t.name,
+            description: t.description ?? "",
+            input_schema: t.inputSchema,
+        }))
+            .sort((a, b) => a.name.localeCompare(b.name));
+    }
+    finally {
+        await client.close();
+        await server.close();
+    }
+}
+/** The full `tool-defs.json` payload (server id + the introspected defs). */
+export async function generateToolDefsFile() {
+    return { server: DANX_DASHBOARD_SERVER_ID, tools: await generateToolDefs() };
+}
+/** Deterministic 2-space JSON the committed file + the drift test compare. */
+export function serializeToolDefsFile(file) {
+    return JSON.stringify(file, null, 2) + "\n";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehammer/danx-dashboard-mcp",
-  "version": "0.1.24",
+  "version": "0.1.26",
   "description": "Stdio MCP server wrapping danxbot's dashboard /api/issues/* normalized DB-backed HTTP routes for dispatched agents (DX-704 Phase 2).",
   "license": "MIT",
   "type": "module",
@@ -24,6 +24,7 @@
     "build": "tsc -p tsconfig.json && node -e \"require('fs').chmodSync('dist/index.js', 0o755)\"",
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts",
+    "gen-tool-defs": "tsx scripts/gen-tool-defs.ts",
     "test": "vitest run",
     "test:watch": "vitest"
   },