@thehammer/danx-dashboard-mcp 0.1.23 → 0.1.25

package/dist/handlers.js

@@ -89,8 +89,8 @@ export async function issueCreate(client, args, defaultBoard) {
         body.effort_level = args.effort_level;
     if (args.list_id !== undefined)
         body.list_id = args.list_id;
-    if (args.required_gates !== undefined)
-        body.required_gates = args.required_gates;
+    if (args.gate_decisions !== undefined)
+        body.gate_decisions = args.gate_decisions;
     if (args.phase_children !== undefined)
         body.phase_children = args.phase_children;
     return client.request({ method: "POST", path: "", body, board });
@@ -346,7 +346,7 @@ export async function issueRequiresHuman(client, args) {
  * POST /api/issues/:id/quality-gates/:gate {required} — the same write the
  * dashboard drawer's Quality Gates tab performs (DX-1181). This is the ONLY
  * post-create path to mark a gate required/not — `issue_create` carries
- * `required_gates[]` at birth, and `issue_edit` rejects gate keys; without
+ * `gate_decisions` at birth, and `issue_edit` rejects gate keys; without
  * this tool an agent that created a card cannot turn a gate on afterward.
  *
  * `gate` is a registry name (`plan-dependency` | `plan-architecture` |

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",
 });
@@ -165,7 +178,7 @@ server.tool("issue_get", 'Fetch a single hydrated issue via GET /api/issues/:id.
     ...boardField,
 }, async (args) => jsonResult(await issueGet(client, args)));
 // ---------------- issue_create ----------------
-server.tool("issue_create", 'Create a fresh card via POST /api/issues. Board-scoped; defaults to the dispatch\'s board. Pass `board` (a qualified id `<repo>:<slug>`) to create the card on another board (forwarded into body.board + ?board=; unknown board → 404). INVARIANT: type=Epic REQUIRES non-empty phase_children[] (epic-with-phases atomicity per DX-575) and the route atomically inserts the epic + every phase in ONE transaction. Non-Epic types REFUSE phase_children[] with 400. Status defaults to Review (no lifecycle timestamps stamped on create). parent_id optional. ac items take {title}; phase children inherit the new epic\'s id as parent_id. Optional list_id PLACES the card directly into a column in ONE call. **Pass EITHER a board_lists id OR the list\'s display NAME (case-insensitive, emoji-tolerant — e.g. a queue name like "⚙️ Fulfillment Queue" or just "Fulfillment Queue") — the server resolves a name to its id.** The card lands DIRECTLY in that column with the matching lifecycle stamped automatically — a `ready`-type queue → ToDo, a `completed` list → Done, etc. **You do NOT need a separate issue_transition(ready) + issue_edit(list_id) afterward — just pass the queue name here and the card is created already in that column.** Omit list_id for the default (Review). NOT valid on type=Epic (Epic status derives from children) → 400. Unknown name/id → 400. Optional required_gates[] flags which quality gates (dependency, architecture, tdd, code) are REQUIRED on this card so they run pre-dispatch (only when the board also has that gate enabled); unknown gate name → 400.', {
+server.tool("issue_create", 'Create a fresh card via POST /api/issues. Board-scoped; defaults to the dispatch\'s board. Pass `board` (a qualified id `<repo>:<slug>`) to create the card on another board (forwarded into body.board + ?board=; unknown board → 404). INVARIANT: type=Epic REQUIRES non-empty phase_children[] (epic-with-phases atomicity per DX-575) and the route atomically inserts the epic + every phase in ONE transaction. Non-Epic types REFUSE phase_children[] with 400. Status defaults to Review (no lifecycle timestamps stamped on create). parent_id optional. ac items take {title}; phase children inherit the new epic\'s id as parent_id. Optional list_id PLACES the card directly into a column in ONE call. **Pass EITHER a board_lists id OR the list\'s display NAME (case-insensitive, emoji-tolerant — e.g. a queue name like "⚙️ Fulfillment Queue" or just "Fulfillment Queue") — the server resolves a name to its id.** The card lands DIRECTLY in that column with the matching lifecycle stamped automatically — a `ready`-type queue → ToDo, a `completed` list → Done, etc. **You do NOT need a separate issue_transition(ready) + issue_edit(list_id) afterward — just pass the queue name here and the card is created already in that column.** Omit list_id for the default (Review). NOT valid on type=Epic (Epic status derives from children) → 400. Unknown name/id → 400. **gate_decisions is REQUIRED whenever the board has any OPTIONAL quality gate for the card\'s type** (DX-1594): supply one `{gate, enabled, note}` per board-optional gate. The create FAILS CLOSED — a missing decision returns 400 `{error, required_gate_decisions:[...]}` enumerating exactly which gates to answer, so just retry with a decision for each listed gate. `required`/`disabled` board gates take no decision; a board with no optional gates needs no gate_decisions at all.', {
     type: z.enum(ISSUE_TYPES),
     title: z.string().min(1),
     description: z.string(),
@@ -173,10 +186,14 @@ server.tool("issue_create", 'Create a fresh card via POST /api/issues. Board-sco
     ac: z.array(z.object({ title: z.string().min(1) })).optional(),
     effort_level: z.enum(EFFORT_VALUES).nullable().optional(),
     list_id: z.string().min(1).nullable().optional(),
-    required_gates: z
-        .array(z.string().min(1))
+    gate_decisions: z
+        .array(z.object({
+        gate: z.string().min(1),
+        enabled: z.boolean(),
+        note: z.string(),
+    }))
         .optional()
-        .describe('Optional array of quality-gate names to mark REQUIRED on this card (e.g. ["architecture","tdd"]). Board requirement is TRI-STATE per gate (`board_quality_gate_settings.default_state`), NOT binary: `required` runs always; `optional` runs WHEN flagged on the card (per-card opt-in — `optional` is ENABLED, not off); `disabled` never runs (flag inert). So flagging makes the gate run unless the board state is `disabled`. Use this when you (the creating agent) judge the card needs that pre-dispatch review gate; omit for cards that don\'t. Known gates: dependency, architecture, tdd, code. The operator can also toggle these per-card later in the issue drawer.'),
+        .describe('REQUIRED fail-closed quality-gate decisions (DX-1594 — replaces required_gates). One {gate, enabled, note} per board-OPTIONAL gate of the card\'s type: `enabled` answers whether the gate runs on this card, `note` records the rationale (persisted as the decision rationale, distinct from the reviewer verdict). The board requirement is TRI-STATE per gate (`board_quality_gate_settings.default_state`): `required` runs always (NO decision — auto-on); `optional` REQUIRES a decision here (unanswered → the create 400s); `disabled` never runs (NO decision). Omit this only on a board with no optional gates; otherwise the 400 body\'s `required_gate_decisions` lists exactly which gates to answer — retry with {enabled, note} for each. A decision naming a non-optional gate is rejected 400.'),
     phase_children: z
         .array(z.object({
         type: z.enum(NON_EPIC_TYPES),
@@ -184,6 +201,14 @@ server.tool("issue_create", 'Create a fresh card via POST /api/issues. Board-sco
         description: z.string(),
         ac: z.array(z.object({ title: z.string().min(1) })).optional(),
         effort_level: z.enum(EFFORT_VALUES).nullable().optional(),
+        gate_decisions: z
+            .array(z.object({
+            gate: z.string().min(1),
+            enabled: z.boolean(),
+            note: z.string(),
+        }))
+            .optional()
+            .describe("Per-child fail-closed gate decisions — same shape + rule as the root gate_decisions, resolved against THIS child's own type. Required when the child's type has board-optional gates."),
     }))
         .optional(),
     ...boardField,
@@ -295,7 +320,7 @@ server.tool("issue_requires_human", "Set or clear the requires_human dispatch ga
     ...boardField,
 }, async (args) => jsonResult(await issueRequiresHuman(client, args)));
 // ---------------- issue_quality_gate ----------------
-server.tool("issue_quality_gate", "Toggle a single card's per-card quality-gate `required` flag via POST /api/issues/:id/quality-gates/:gate {required} — the SAME write the dashboard drawer's Quality Gates tab performs (DX-1181). This is the ONLY post-create way to mark a gate required/not-required: `issue_create` carries `required_gates[]` at birth, and `issue_edit` REJECTS gate keys (400 offending_keys) — without this tool a card created without a gate can never have it turned on by an agent. `gate` is a registry name: `plan-dependency` | `plan-architecture` | `plan-tdd` | `code-test-quality` | `code-architecture` | `code-quality` (the PRE/plan- gates run before the work dispatch; the POST/code- gates block issue_transition complete). Unknown gate → 400 (never a silent no-op); a card with no seeded row for a registered gate → 500 (canonical corruption). NOTE board requirement is TRI-STATE per gate (`board_quality_gate_settings.default_state`, the Agents-tab surface), NOT a binary on/off: `required` = gate always runs (this flag irrelevant); `optional` = gate runs WHEN this per-card flag is true (per-card opt-in — `optional` is ENABLED, NOT off); `disabled` = never runs (this flag inert). So flipping `required:true` here LAUNCHES the gate when the board state is `required` OR `optional`; it is inert ONLY when the board state is `disabled`. Do not read `optional` as off. (Source of truth: `isGateEffectivelyRequired` in `src/issues/quality-gates/read.ts`.) Returns the hydrated issue. Board-scoped; pass `board` (`<repo>:<slug>`) to target another board.", {
+server.tool("issue_quality_gate", "Toggle a single card's per-card quality-gate `required` flag via POST /api/issues/:id/quality-gates/:gate {required} — the SAME write the dashboard drawer's Quality Gates tab performs (DX-1181). This is the ONLY post-create way to mark a gate required/not-required: `issue_create` carries `gate_decisions` at birth, and `issue_edit` REJECTS gate keys (400 offending_keys) — without this tool a card created without a gate can never have it turned on by an agent. `gate` is a registry name: `plan-dependency` | `plan-architecture` | `plan-tdd` | `code-test-quality` | `code-architecture` | `code-quality` (the PRE/plan- gates run before the work dispatch; the POST/code- gates block issue_transition complete). Unknown gate → 400 (never a silent no-op); a card with no seeded row for a registered gate → 500 (canonical corruption). NOTE board requirement is TRI-STATE per gate (`board_quality_gate_settings.default_state`, the Agents-tab surface), NOT a binary on/off: `required` = gate always runs (this flag irrelevant); `optional` = gate runs WHEN this per-card flag is true (per-card opt-in — `optional` is ENABLED, NOT off); `disabled` = never runs (this flag inert). So flipping `required:true` here LAUNCHES the gate when the board state is `required` OR `optional`; it is inert ONLY when the board state is `disabled`. Do not read `optional` as off. (Source of truth: `isGateEffectivelyRequired` in `src/issues/quality-gates/read.ts`.) Returns the hydrated issue. Board-scoped; pass `board` (`<repo>:<slug>`) to target another board.", {
     id: z.string().min(1),
     gate: z.enum([
         "plan-dependency",
@@ -309,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(),
@@ -318,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 ----------------
@@ -335,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.23",
+  "version": "0.1.25",
   "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"
   },