@thehammer/danx-dashboard-mcp 0.1.30 → 0.1.31

package/README.md

@@ -26,9 +26,9 @@ All exposed as `mcp__danx_dashboard__<name>` once wired through the workspace `m
 | `issue_create` | `POST /api/issues` | Epic REQUIRES non-empty `phase_children[]` (atomic insert) |
 | `issue_edit` | `PATCH /api/issues/:id/edit` | Prose + structured keys (`title`, `description`, `ac`, `checklists`, `effort_level`, `parent_id`, `priority`, `list_id`); semantic keys refused with 400 + pointer to dedicated handler. `priority` (DX-1532) takes a tier word (`low`/`high`/…) or a number in `[0,6)` — the ONLY way to set the numeric column the Trello label + dashboard badge read; never set priority via description prose |
 | `issue_transition` | `POST /api/issues/:id/transition` | Actions: ready, pickup, rollback_pickup, complete, cancel, block, unblock, archive, reopen |
-| `issue_triage` | `POST /api/issues/:id/triage` | Verdicts: approve, cancel, keep, defer (with optional ICE + ttl_seconds). None of these are a cross-card ordering gate — a card held at Review via `keep` can still be readied independent of a sibling; use `issue_dependency` to sequence cards |
+| `issue_triage` | `POST /api/issues/:id/triage` | Verdicts: approve, cancel, keep, defer (with optional ICE + ttl_seconds) |
 | `issue_comment` | `POST/PATCH/DELETE /api/issues/:id/comments[/:cid]` | Author server-stamped, soft-delete preserved |
-| `issue_dependency` | `POST/DELETE /api/issues/:id/dependencies[/:did]` | `depends_on` cycle-checked; remove hardcodes `reason: "recorded_in_error"`. The only mechanism the dispatch picker enforces to sequence one card after another — status alone is not a substitute |
+| `issue_dependency` | `POST/DELETE /api/issues/:id/dependencies[/:did]` | `depends_on` cycle-checked; remove hardcodes `reason: "recorded_in_error"` |
 | `issue_requires_human` | `POST/DELETE /api/issues/:id/requires-human` | Set replaces step rows atomically; clear soft-deletes them |
 | `issue_retro` | `PUT /api/issues/:id/retro` | Requires terminal card; replace semantics |
 

package/dist/handlers.js

@@ -66,6 +66,40 @@ export async function issueGet(client, args) {
         board: args.board,
     });
 }
+// ---------------- repo_knowledge_get / repo_knowledge_set ----------------
+const REPO_KNOWLEDGE_BASE_PATH = "/api/repo-knowledge";
+/**
+ * Fetch the board's working-knowledge doc via GET /api/repo-knowledge
+ * (DX-1128, Story 2). Mirrors `issueGet` — a bare board-scoped GET, no id
+ * (the doc is 1-per-board). Board resolves the same way every other tool's
+ * `board` arg does: per-call override, else the dispatch's env-derived board.
+ */
+export async function repoKnowledgeGet(client, args = {}) {
+    return client.request({
+        method: "GET",
+        path: "",
+        basePath: REPO_KNOWLEDGE_BASE_PATH,
+        board: args.board,
+    });
+}
+/**
+ * Write the board's working-knowledge doc via PUT /api/repo-knowledge
+ * (DX-1128, Story 2). Mirrors `issueEdit`'s shape (a PATCH-like body write)
+ * but targets the repo-knowledge route family, not `/api/issues`. The
+ * server's optimistic-concurrency guard rejects a stale `base_hash` — the
+ * refusal envelope (`{ok: false, body: {error, currentHash}}`) passes
+ * through verbatim so the caller can re-get, re-merge, and retry.
+ */
+export async function repoKnowledgeSet(client, args) {
+    const { board, ...body } = args;
+    return client.request({
+        method: "PUT",
+        path: "",
+        basePath: REPO_KNOWLEDGE_BASE_PATH,
+        body,
+        board,
+    });
+}
 export async function issueCreate(client, args, defaultBoard) {
     // Resolve the target board ONCE: per-call `args.board` override (a
     // qualified `<repo>:<slug>` id) wins, else the dispatch's env-derived

package/dist/http-client.js

@@ -6,7 +6,7 @@ export class DashboardHttpClient {
         this.fetchImpl = fetchImpl;
     }
     async request(args) {
-        const url = this.buildUrl(args.path, args.query, args.board);
+        const url = this.buildUrl(args.path, args.query, args.board, args.basePath);
         const headers = {
             Authorization: `Bearer ${this.config.token}`,
             Accept: "application/json",
@@ -54,7 +54,7 @@ export class DashboardHttpClient {
         }
         return { ok: false, status: res.status, body: parsed };
     }
-    buildUrl(path, extraQuery, boardOverride) {
+    buildUrl(path, extraQuery, boardOverride, basePath = "/api/issues") {
         const base = this.config.baseUrl.replace(/\/+$/, "");
         const [rawPath, existingQs] = path.split("?", 2);
         let cleanPath;
@@ -73,6 +73,6 @@ export class DashboardHttpClient {
                 params.set(k, String(v));
             }
         }
-        return `${base}/api/issues${cleanPath}?${params.toString()}`;
+        return `${base}${basePath}${cleanPath}?${params.toString()}`;
     }
 }

package/dist/index.js

@@ -24,6 +24,8 @@
  *   - issue_quality_gate     POST   /api/issues/:id/quality-gates/:gate
  *   - issue_retro            PUT    /api/issues/:id/retro
  *   - issue_attach           POST   /api/issues/:id/attachments (reads a local file)
+ *   - repo_knowledge_get     GET    /api/repo-knowledge
+ *   - repo_knowledge_set     PUT    /api/repo-knowledge (DX-1128, Story 2)
  *
  * BOARD-ONLY (DX-1171): board is the first-level concept; repo is
  * DERIVED from board server-side, never passed. The package composes the
@@ -53,7 +55,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { DashboardHttpClient } from "./http-client.js";
-import { issueAttach, issueChecklist, issueComment, issueCreate, issueDependency, issueEdit, issueGet, issueList, issueQualityGate, issueRequiresHuman, issueRetro, issueTransition, issueTriage, } from "./handlers.js";
+import { issueAttach, issueChecklist, issueComment, issueCreate, issueDependency, issueEdit, issueGet, issueList, issueQualityGate, issueRequiresHuman, issueRetro, issueTransition, issueTriage, repoKnowledgeGet, repoKnowledgeSet, } from "./handlers.js";
 import { PRIORITY_TIER_WORDS } from "./priority.js";
 function readEnvOrDie(name) {
     const v = process.env[name];
@@ -260,7 +262,7 @@ server.tool("issue_transition", "Stamp a lifecycle transition via POST /api/issu
     ...boardField,
 }, async (args) => jsonResult(await issueTransition(client, args)));
 // ---------------- issue_triage ----------------
-server.tool("issue_triage", "Record a triage verdict via POST /api/issues/:id/triage. Verdicts: approve (stamps ready_at — moves to ToDo, clears triage TTL), cancel (stamps cancelled_at — terminal), keep (refreshes triage_expires_at by ttl_seconds — defaults 7 days, card stays at Review), defer (stamps archived_at, clears ready_at — parks to Backlog). ICE components optional but recorded when present (total = i*c*e). Reason is REQUIRED non-empty. REFUSES 409 on terminal cards. None of these verdicts create a cross-card ordering gate — a card left at Review (via keep) is invisible to the plan-dependency gate's live-partner comparison and can be readied independent of any sibling's status. To sequence one card after another, use issue_dependency (kind: depends_on) — that is the only mechanism the dispatch picker actually enforces regardless of status.", {
+server.tool("issue_triage", "Record a triage verdict via POST /api/issues/:id/triage. Verdicts: approve (stamps ready_at — moves to ToDo, clears triage TTL), cancel (stamps cancelled_at — terminal), keep (refreshes triage_expires_at by ttl_seconds — defaults 7 days, card stays at Review), defer (stamps archived_at, clears ready_at — parks to Backlog). ICE components optional but recorded when present (total = i+c+e). Reason is REQUIRED non-empty. REFUSES 409 on terminal cards.", {
     id: z.string().min(1),
     verdict: z.enum(TRIAGE_VERDICTS),
     reason: z.string().min(1),
@@ -308,7 +310,7 @@ server.tool("issue_checklist", "Targeted checklist CUD via /api/issues/:id/check
     ...boardField,
 }, async (args) => jsonResult(await issueChecklist(client, args)));
 // ---------------- issue_dependency ----------------
-server.tool("issue_dependency", 'Dependency CRUD via /api/issues/:id/dependencies[/:did]. action=add → POST {kind, target_id, reason} where kind ∈ {depends_on, conflict_on}. depends_on adds are CYCLE-CHECKED (BFS from target back to source — 409 if loop). Idempotent: re-adding a live triple returns the existing id. Self-loops refuse 409. action=remove → DELETE /:did. The server REQUIRES the literal reason="recorded_in_error" on removal (encodes "removal means NOT related, never satisfied") — this MCP boundary hardcodes it, so callers do not pass reason on remove. This is the ONLY mechanism the dispatch picker enforces to sequence one card after another — leaving a card at a Review/held status (e.g. an issue_triage "keep" verdict) is NOT a substitute and provides no cross-card ordering protection.', {
+server.tool("issue_dependency", 'Dependency CRUD via /api/issues/:id/dependencies[/:did]. action=add → POST {kind, target_id, reason} where kind ∈ {depends_on, conflict_on}. depends_on adds are CYCLE-CHECKED (BFS from target back to source — 409 if loop). Idempotent: re-adding a live triple returns the existing id. Self-loops refuse 409. action=remove → DELETE /:did. The server REQUIRES the literal reason="recorded_in_error" on removal (encodes "removal means NOT related, never satisfied") — this MCP boundary hardcodes it, so callers do not pass reason on remove.', {
     id: z.string().min(1),
     action: z.enum(["add", "remove"]),
     kind: z.enum(["depends_on", "conflict_on"]).optional(),
@@ -379,6 +381,19 @@ server.tool("issue_attach", "Attach a LOCAL file to an issue card via POST /api/
         .describe("Absolute path to a local file on the dispatch's shared filesystem (must start with `/`)."),
     ...boardField,
 }, async (args) => jsonResult(await issueAttach(client, args)));
+// ---------------- repo_knowledge_get ----------------
+server.tool("repo_knowledge_get", "Fetch the board's working-knowledge markdown doc via GET /api/repo-knowledge (DX-1128, Story 2). Board-scoped; defaults to the dispatch's board. Pass `board` (a qualified id `<repo>:<slug>`) to read another board's doc. Returns `{ok, status, body: {content, contentHash, updatedAt, updatedBy, boardId}}` — an unset doc reads as the empty view (`content: \"\"`, `contentHash: \"\"`), NOT a 404. Ground exploratory answers in `content`; before `repo_knowledge_set`, ALWAYS `repo_knowledge_get` immediately first and pass its `contentHash` back as `base_hash` — the server's optimistic-concurrency guard rejects a stale write.", {
+    ...boardField,
+}, async (args) => jsonResult(await repoKnowledgeGet(client, args)));
+// ---------------- repo_knowledge_set ----------------
+server.tool("repo_knowledge_set", 'Write the board\'s working-knowledge markdown doc via PUT /api/repo-knowledge (DX-1128, Story 2). Board-scoped; defaults to the dispatch\'s board. `base_hash` MUST be the `contentHash` from the immediately-prior `repo_knowledge_get` call ("" for the true first write, when the board has no doc yet) — the server compares it against the CURRENT hash and, on mismatch, fails loud with `{ok: false, body: {error: "stale_repo_knowledge", currentHash}}` rather than silently overwriting a concurrent write. On that refusal: re-`repo_knowledge_get`, re-merge your insight into the fresh content, and retry `repo_knowledge_set` with the new hash. On success, persists to the DB, publishes `repo-knowledge:updated` over SSE (live in the dashboard editor), and returns the new view.', {
+    content: z.string(),
+    base_hash: z
+        .string()
+        .optional()
+        .describe('The contentHash last read via repo_knowledge_get ("" for a true first write). Omitted also normalizes to "" server-side, so it only succeeds against an empty/absent doc — always get immediately before set.'),
+    ...boardField,
+}, async (args) => jsonResult(await repoKnowledgeSet(client, args)));
 // ---------------- main ----------------
 async function main() {
     boot();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehammer/danx-dashboard-mcp",
-  "version": "0.1.30",
+  "version": "0.1.31",
   "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",

package/dist/handlers.test.js

@@ -1,51 +0,0 @@
-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" });
-    });
-});