@thehammer/danx-dashboard-mcp 0.1.2 → 0.1.3

package/README.md

@@ -10,7 +10,7 @@ Each tool is a thin envelope over one HTTP route — Zod-validated at the MCP bo
 |---|---|
 | `DANXBOT_DASHBOARD_URL` | Dashboard base, e.g. `http://danxbot-dashboard:5555` (inside compose) or `http://localhost:5555` (host) |
 | `DANXBOT_DISPATCH_TOKEN` | Per-dispatch bearer — server validates via `requireUser`/dispatch-token checks |
-| `DANX_REPO_NAME` | Repo scope appended as `?repo=<name>` to every URL |
+| `DANX_REPO_NAME` | Default repo scope appended as `?repo=<name>`; each tool's optional `repo` arg overrides it per-call for cross-repo reads/writes (unknown repo → 404) |
 
 ## Tool surface
 

package/dist/handlers.js

@@ -22,17 +22,24 @@ export async function issueList(client, args) {
         query.limit = args.limit;
     if (args.offset !== undefined)
         query.offset = args.offset;
-    return client.request({ method: "GET", path: "", query });
+    return client.request({ method: "GET", path: "", query, repo: args.repo });
 }
 // ---------------- issue_get ----------------
 export async function issueGet(client, args) {
-    return client.request({ method: "GET", path: `/${encodeURIComponent(args.id)}` });
+    return client.request({
+        method: "GET",
+        path: `/${encodeURIComponent(args.id)}`,
+        repo: args.repo,
+    });
 }
-export async function issueCreate(client, args, repo) {
-    // `repo` lives in BOTH the query string (via http-client) AND the
-    // body (server requires it inside the JSON envelope per
+export async function issueCreate(client, args, defaultRepo) {
+    // Resolve the target repo ONCE: per-call `args.repo` override (target
+    // another registered repo) wins, else the dispatch's `DANX_REPO_NAME`.
+    // `repo` lives in BOTH the query string (via http-client) AND the body
+    // (server requires it inside the JSON envelope per
     // `write/create.ts::validate`). Sending only one fails-loud — the
-    // duplication is intentional.
+    // duplication is intentional. The dashboard 404s an unknown repo.
+    const repo = args.repo ?? defaultRepo;
     const body = {
         repo,
         type: args.type,
@@ -47,10 +54,13 @@ export async function issueCreate(client, args, repo) {
         body.effort_level = args.effort_level;
     if (args.phase_children !== undefined)
         body.phase_children = args.phase_children;
-    return client.request({ method: "POST", path: "", body });
+    return client.request({ method: "POST", path: "", body, repo });
 }
 export async function issueEdit(client, args) {
-    const { id, ...rest } = args;
+    // `repo` is a transport concern (query), NOT a patch field — pull it
+    // out of `rest` so it never leaks into the `/edit` body (the server
+    // 400s on non-allowlisted keys).
+    const { id, repo, ...rest } = args;
     // Strip undefined so we don't send `{title: undefined}` — JSON.stringify
     // drops them anyway but explicit is clearer.
     const body = {};
@@ -62,26 +72,30 @@ export async function issueEdit(client, args) {
         method: "PATCH",
         path: `/${encodeURIComponent(id)}/edit`,
         body,
+        repo,
     });
 }
 export async function issueTransition(client, args) {
-    const { id, ...body } = args;
+    const { id, repo, ...body } = args;
     return client.request({
         method: "POST",
         path: `/${encodeURIComponent(id)}/transition`,
         body,
+        repo,
     });
 }
 export async function issueTriage(client, args) {
-    const { id, ...body } = args;
+    const { id, repo, ...body } = args;
     return client.request({
         method: "POST",
         path: `/${encodeURIComponent(id)}/triage`,
         body,
+        repo,
     });
 }
 export async function issueComment(client, args) {
     const idEnc = encodeURIComponent(args.id);
+    const repo = args.repo;
     if (args.action === "add") {
         if (typeof args.text !== "string") {
             throw new Error("issue_comment action=add requires text");
@@ -90,6 +104,7 @@ export async function issueComment(client, args) {
             method: "POST",
             path: `/${idEnc}/comments`,
             body: { text: args.text },
+            repo,
         });
     }
     if (args.action === "edit") {
@@ -103,6 +118,7 @@ export async function issueComment(client, args) {
             method: "PATCH",
             path: `/${idEnc}/comments/${args.comment_id}`,
             body: { text: args.text },
+            repo,
         });
     }
     // delete
@@ -112,10 +128,12 @@ export async function issueComment(client, args) {
     return client.request({
         method: "DELETE",
         path: `/${idEnc}/comments/${args.comment_id}`,
+        repo,
     });
 }
 export async function issueDependency(client, args) {
     const idEnc = encodeURIComponent(args.id);
+    const repo = args.repo;
     if (args.action === "add") {
         if (args.kind === undefined) {
             throw new Error("issue_dependency action=add requires kind");
@@ -131,6 +149,7 @@ export async function issueDependency(client, args) {
                 target_id: args.target_id,
                 reason: args.reason ?? "",
             },
+            repo,
         });
     }
     // remove
@@ -145,10 +164,12 @@ export async function issueDependency(client, args) {
         // agent that types the wrong reason gets a refusal here at MCP
         // arg-validation, not a confusing 400 envelope.
         body: { reason: "recorded_in_error" },
+        repo,
     });
 }
 export async function issueRequiresHuman(client, args) {
     const idEnc = encodeURIComponent(args.id);
+    const repo = args.repo;
     if (args.set) {
         if (typeof args.reason !== "string") {
             throw new Error("issue_requires_human set=true requires reason");
@@ -160,18 +181,21 @@ export async function issueRequiresHuman(client, args) {
             method: "POST",
             path: `/${idEnc}/requires-human`,
             body: { reason: args.reason, steps: args.steps },
+            repo,
         });
     }
     return client.request({
         method: "DELETE",
         path: `/${idEnc}/requires-human`,
+        repo,
     });
 }
 export async function issueRetro(client, args) {
-    const { id, ...body } = args;
+    const { id, repo, ...body } = args;
     return client.request({
         method: "PUT",
         path: `/${encodeURIComponent(id)}/retro`,
         body,
+        repo,
     });
 }

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);
+        const url = this.buildUrl(args.path, args.query, args.repo);
         const headers = {
             Authorization: `Bearer ${this.config.token}`,
             Accept: "application/json",
@@ -47,7 +47,7 @@ export class DashboardHttpClient {
         }
         return { ok: false, status: res.status, body: parsed };
     }
-    buildUrl(path, extraQuery) {
+    buildUrl(path, extraQuery, repoOverride) {
         const base = this.config.baseUrl.replace(/\/+$/, "");
         const [rawPath, existingQs] = path.split("?", 2);
         let cleanPath;
@@ -58,7 +58,7 @@ export class DashboardHttpClient {
             cleanPath = rawPath.startsWith("/") ? rawPath : `/${rawPath}`;
         }
         const params = new URLSearchParams(existingQs ?? "");
-        params.set("repo", this.config.repo);
+        params.set("repo", repoOverride ?? this.config.repo);
         if (extraQuery) {
             for (const [k, v] of Object.entries(extraQuery)) {
                 if (v === undefined || v === null)

package/dist/index.js

@@ -25,7 +25,9 @@
  * Env at boot (validated fail-loud — missing → process.exit(1)):
  *   DANXBOT_DASHBOARD_URL   dashboard base (e.g. http://danxbot-dashboard:5555)
  *   DANXBOT_DISPATCH_TOKEN  per-dispatch bearer
- *   DANX_REPO_NAME          repo scope, appended as ?repo=<name> on every call
+ *   DANX_REPO_NAME          default repo scope, appended as ?repo=<name>;
+ *                           each tool's optional `repo` arg overrides it
+ *                           per-call for cross-repo reads/writes
  *
  * Envelope contract: every tool returns the dashboard's response body
  * verbatim wrapped as `{ok, status, body}`. Refusals (4xx with the v2
@@ -88,8 +90,20 @@ const TRANSITION_ACTIONS = [
     "reopen",
 ];
 const TRIAGE_VERDICTS = ["approve", "cancel", "keep", "defer"];
+// Optional per-call repo override shared by every tool. Omitted → the
+// server binding's DANX_REPO_NAME is used; provided → that registered
+// repo is targeted instead (the dashboard 404s an unknown repo). Spread
+// into each tool's Zod input object so cross-repo work is reachable from
+// any dispatch without rebinding the MCP server.
+const repoField = {
+    repo: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Target another registered repo; omit to use this dispatch's repo. Unknown repo → 404."),
+};
 // ---------------- issue_list ----------------
-server.tool("issue_list", "List issues for the current repo via GET /api/v2/issues. Filters: type, parent_id (string id, null for root-only), dispatchable_derived (boolean — server-computed pickup-ready gate), assigned_agent, include_closed (default false — excludes completed_at/cancelled_at). Response body shape: {issues: IssueV2[]}. Server-side numeric-suffix ordering so DX-10 follows DX-9. Use this instead of grepping .danxbot/issues/ — the DB-backed route is the source of truth post-DX-704.", {
+server.tool("issue_list", "List issues for the dispatch's repo by default via GET /api/v2/issues. Pass `repo` to list another registered repo instead (unknown repo → 404). Filters: type, parent_id (string id, null for root-only), dispatchable_derived (boolean — server-computed pickup-ready gate), assigned_agent, include_closed (default false — excludes completed_at/cancelled_at). Response body shape: {issues: IssueV2[]}. Server-side numeric-suffix ordering so DX-10 follows DX-9. Use this instead of grepping .danxbot/issues/ — the DB-backed route is the source of truth post-DX-704.", {
     status_derived: z.string().optional(),
     type: z.enum(ISSUE_TYPES).optional(),
     parent_id: z.string().nullable().optional(),
@@ -98,13 +112,15 @@ server.tool("issue_list", "List issues for the current repo via GET /api/v2/issu
     include_closed: z.boolean().optional(),
     limit: z.number().int().positive().max(1000).optional(),
     offset: z.number().int().nonnegative().optional(),
+    ...repoField,
 }, async (args) => jsonResult(await issueList(client, args)));
 // ---------------- issue_get ----------------
-server.tool("issue_get", "Fetch a single hydrated issue via GET /api/v2/issues/:id. Returns the full card (every joined child collection: ac, comments, dependencies, requires_human steps, retro action items + commits, triage history) plus the ancestor chain walked via parent_id. 404 envelope on unknown id.", {
+server.tool("issue_get", "Fetch a single hydrated issue via GET /api/v2/issues/:id. Issue ids are globally unique across repos, so this resolves from any dispatch regardless of `repo`. Returns the full card (every joined child collection: ac, comments, dependencies, requires_human steps, retro action items + commits, triage history) plus the ancestor chain walked via parent_id. 404 envelope on unknown id.", {
     id: z.string().min(1),
-}, async ({ id }) => jsonResult(await issueGet(client, { id })));
+    ...repoField,
+}, async (args) => jsonResult(await issueGet(client, args)));
 // ---------------- issue_create ----------------
-server.tool("issue_create", "Create a fresh card via POST /api/v2/issues. 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.", {
+server.tool("issue_create", "Create a fresh card via POST /api/v2/issues. Defaults to the dispatch's repo; pass `repo` to create the card in another registered repo (forwarded into body.repo + ?repo=; unknown repo → 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.", {
     type: z.enum(ISSUE_TYPES),
     title: z.string().min(1),
     description: z.string(),
@@ -120,6 +136,7 @@ server.tool("issue_create", "Create a fresh card via POST /api/v2/issues. INVARI
         effort_level: z.enum(EFFORT_VALUES).nullable().optional(),
     }))
         .optional(),
+    ...repoField,
 }, async (args) => jsonResult(await issueCreate(client, args, config.repo)));
 // ---------------- issue_edit ----------------
 server.tool("issue_edit", "Patch prose fields only via PATCH /api/v2/issues/:id/edit. ALLOWED keys: title, description, ac, effort_level, parent_id. ANY OTHER KEY (lifecycle timestamps, triage state, dependencies, retro, requires_human, blocked/dispatch gates) returns 400 with offending_keys[] and a pointer to the dedicated semantic handler — use issue_transition / issue_triage / issue_comment / issue_dependency / issue_requires_human / issue_retro instead. AC replacement is wholesale soft-delete + reinsert with fresh ordinals; check_item_id linkage survives via title match.", {
@@ -134,6 +151,7 @@ server.tool("issue_edit", "Patch prose fields only via PATCH /api/v2/issues/:id/
         .optional(),
     effort_level: z.enum(EFFORT_VALUES).nullable().optional(),
     parent_id: z.string().nullable().optional(),
+    ...repoField,
 }, async (args) => jsonResult(await issueEdit(client, args)));
 // ---------------- issue_transition ----------------
 server.tool("issue_transition", "Stamp a lifecycle transition via POST /api/v2/issues/:id/transition. **THIS IS THE ONLY WAY TO MOVE A CARD'S LIFECYCLE STATE** — DX-835 separated card lifecycle (this tool) from dispatch finalization (`mcp__danxbot__danxbot_complete`). The worker no longer infers card moves from `danxbot_complete.status`; agents that want the card to move MUST call this tool BEFORE calling `danxbot_complete`. Actions: ready (Review→ToDo), pickup (ToDo→In Progress — server checks every dispatch gate: ready_at, blocked_at, requires_human_reason, depends_on partners terminal, conflict_on partners idle; refuses 409 with failed_gate naming the cause), rollback_pickup, **complete** (stamps completed_at — moves card to Done; this is YOUR explicit decision, not a side effect of danxbot_complete; REFUSES 409 on Epic if any phase child non-terminal — see non_terminal_phases[]), cancel (stamps cancelled_at — terminal), **block** (requires non-empty reason — stamps blocked_at + blocked_reason + clears dispatch; USE THIS when the CARD itself cannot proceed without human intervention; distinct from env-fault dispatch failures which use `danxbot_complete({status:'failed'})`), unblock, archive (parks to Backlog, clears ready_at), reopen (terminal→active, clears completed_at/cancelled_at/archived_at). Terminal cards refuse every action except reopen. Ladder timestamps preserved — forward stamps never clear earlier ones (CLAUDE.md Core Principle 2).", {
@@ -142,6 +160,7 @@ server.tool("issue_transition", "Stamp a lifecycle transition via POST /api/v2/i
     reason: z.string().optional(),
     summary: z.string().optional(),
     dispatch_id: z.string().min(1).optional(),
+    ...repoField,
 }, async (args) => jsonResult(await issueTransition(client, args)));
 // ---------------- issue_triage ----------------
 server.tool("issue_triage", "Record a triage verdict via POST /api/v2/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.", {
@@ -156,6 +175,7 @@ server.tool("issue_triage", "Record a triage verdict via POST /api/v2/issues/:id
     })
         .optional(),
     ttl_seconds: z.number().positive().optional(),
+    ...repoField,
 }, async (args) => jsonResult(await issueTriage(client, args)));
 // ---------------- issue_comment ----------------
 server.tool("issue_comment", "Comment CRUD via /api/v2/issues/:id/comments[/:cid]. action=add → POST {text} (server stamps author from bearer + auto-incrementing ordinal); action=edit → PATCH /:cid {text}; action=delete → DELETE /:cid (soft-delete, audit trail preserved — comments are NEVER hard-deleted). Client-supplied author is IGNORED (server-stamped to prevent impersonation).", {
@@ -163,6 +183,7 @@ server.tool("issue_comment", "Comment CRUD via /api/v2/issues/:id/comments[/:cid
     action: z.enum(["add", "edit", "delete"]),
     comment_id: z.number().int().positive().optional(),
     text: z.string().min(1).optional(),
+    ...repoField,
 }, async (args) => jsonResult(await issueComment(client, args)));
 // ---------------- issue_dependency ----------------
 server.tool("issue_dependency", "Dependency CRUD via /api/v2/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.", {
@@ -172,6 +193,7 @@ server.tool("issue_dependency", "Dependency CRUD via /api/v2/issues/:id/dependen
     target_id: z.string().min(1).optional(),
     reason: z.string().optional(),
     dependency_id: z.number().int().positive().optional(),
+    ...repoField,
 }, async (args) => jsonResult(await issueDependency(client, args)));
 // ---------------- issue_requires_human ----------------
 server.tool("issue_requires_human", "Set or clear the requires_human dispatch gate via /api/v2/issues/:id/requires-human. set=true → POST {reason, steps[]} — sets requires_human_reason (the dispatch gate per DX-704 — poller refuses pickup while non-null), set_by from bearer, set_at NOW(), REPLACES the step rows (prior soft-deleted, fresh ordinals). set=false → DELETE — clears the columns and soft-deletes every live step. Terminal cards refuse 409 on set.", {
@@ -179,6 +201,7 @@ server.tool("issue_requires_human", "Set or clear the requires_human dispatch ga
     set: z.boolean(),
     reason: z.string().optional(),
     steps: z.array(z.string().min(1)).optional(),
+    ...repoField,
 }, async (args) => jsonResult(await issueRequiresHuman(client, args)));
 // ---------------- issue_retro ----------------
 server.tool("issue_retro", "Replace the retro block via PUT /api/v2/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?}.", {
@@ -190,6 +213,7 @@ server.tool("issue_retro", "Replace the retro block via PUT /api/v2/issues/:id/r
         sha: z.string().min(1),
         subject: z.string().optional(),
     })),
+    ...repoField,
 }, async (args) => jsonResult(await issueRetro(client, args)));
 // ---------------- main ----------------
 async function main() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehammer/danx-dashboard-mcp",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Stdio MCP server wrapping danxbot's dashboard /api/v2/issues/* normalized DB-backed HTTP routes for dispatched agents (DX-704 Phase 2).",
   "license": "MIT",
   "type": "module",