@thehammer/danx-dashboard-mcp 0.1.166 → 0.1.170

package/README.md

@@ -1,8 +1,8 @@
 # @thehammer/danx-dashboard-mcp
 
-Stdio MCP server wrapping danxbot's dashboard `/api/issues/*` normalized DB-backed HTTP routes. Replaces the legacy "agents Edit/Write `.yml` files directly" pattern from before DX-704 / DX-811.
+Stdio MCP server fronting danxbot's dashboard HTTP API. Since DX-3465 it exposes three generic tools (`danxbot_api`, `danxbot_api_list`, `danxbot_api_spec` — see "Tool surface" below) that reach any route the caller's credential may reach, plus a handful of dedicated tools for agent-specific operations (`plan_connect`, `danxbot_complete`, Slack/template-app callbacks, …) — there is no per-operation tool any more.
 
-Each tool is a thin envelope over one HTTP route — Zod-validated at the MCP boundary, fetch under the hood, server response passed back to the agent verbatim. Refusal envelopes (`{error, ...extra}` with `failed_gate`, `non_terminal_phases`, `offending_keys`, etc.) come through as `{ok: false, status, body}` so the agent can pick the right next action without guessing. 5xx and network failures throw.
+`danxbot_api` is Zod-validated at the MCP boundary, fetches under the hood, and passes the server response back to the agent verbatim. Refusal envelopes (`{error, ...extra}` with `failed_gate`, `non_terminal_phases`, `offending_keys`, etc.) come through as `{ok: false, status, body}` so the agent can pick the right next action without guessing. 5xx and network failures throw.
 
 ## Env vars (required, fail-loud at boot)
 
@@ -24,7 +24,8 @@ All exposed as `mcp__danx-dashboard__<name>` once wired through the workspace `m
 | `danxbot_api` | `{method, path, query?, body?}` — calls any dashboard route the caller's credential may reach (card/plan CRUD, comments, dependencies, problems/solutions, quality gates, retro, triage, transitions, …). Returns `{ok, status, body}`; `body` carries the route's own response, or its structured error verbatim when `ok:false`. |
 | `danxbot_api_list` | No args. Lists the routes this caller's credential may reach, one line each (`{method, path, summary, permission}`) — call this first when you don't know the route for what you need to do. |
 | `danxbot_api_spec` | `{endpoints}` (comma-joined `METHOD /path` list, required, min 1). Returns the exact OpenAPI contract for those routes — call this when you know the route but not its exact request/response shape. |
-| `resource_fields` | `GET /api/resources/:resource/fields` — what an opt-in field TREE may name for one resource: `{resource, description, always, hashes, fields, relations}`. Install-global, no `board`. `resource: "issue"` is the root; a relation's own `resource` in the response is what to call this again with, one level deeper. |
+
+There is no dedicated `resource_fields` tool (removed DX-3465 — it was a thin wrapper `danxbot_api` already reaches with no agent-specific behavior earning it its own tool). What an opt-in field TREE may name for one resource (`{resource, description, always, hashes, fields, relations}`) is `danxbot_api({method:"GET", path:"/api/resources/<resource>/fields"})` — install-global, no `board`; `resource: "issue"` is the root, and a relation's own `resource` in the response is what to call this again with, one level deeper.
 
 A dedicated tool survives only for something about the agent itself, never a card/plan operation: `plan_connect` (binds the session to a plan; the event-bridge hook keys on it) and the per-dispatch worker callbacks (`danxbot_complete`, `danxbot_slack_reply`, `danxbot_slack_post_update`, `load_template_app`/`save_template_app`, `quality_gate_complete`, `link_thread_to_issue`, `attach_file`, the `slack_recovery_*` trio, `danxbot_set_evaluator_summary`) — see `src/lifecycle.ts`. The live list is always `tool-defs.json` in this package, regenerated by `npm run gen-tool-defs` — read it rather than trusting a list copied into prose.
 

package/dist/http-client.js

@@ -102,16 +102,19 @@ export class DashboardHttpClient {
             for (const [k, v] of Object.entries(extraQuery)) {
                 if (v === undefined || v === null)
                     continue;
-                // DX-3465 (code-quality gate finding, at 275f82c0d) — a field TREE
-                // (`fields`, and any other tree-shaped route param) arrives here as a
-                // real object/array, not a string; `String(v)` on either produces
-                // the useless literal "[object Object]" (objects) or a comma-joined
-                // list that drops all nesting (arrays). JSON-encode both so the
-                // server's own `fields=` query-string parser (which expects exactly
-                // this shape — see `src/dashboard/...` field-tree route handling)
-                // receives what it can actually parse; a plain scalar still
-                // stringifies the same way it always did.
-                params.set(k, typeof v === "object" ? JSON.stringify(v) : String(v));
+                // DX-3465 — a field TREE (`fields`, a plain object) is the only
+                // query param the server parses as JSON
+                // (`src/resources/field-tree.ts`); every LIST-valued param it has
+                // (`ids` on `GET /api/issues/batch`, `status` on the boards list,
+                // `endpoints` on `GET /api/openapi`) splits on commas instead, never
+                // JSON. Arrays are `typeof "object"` too, so the array check must
+                // come BEFORE the plain-object branch. A plain scalar stringifies
+                // as before.
+                params.set(k, Array.isArray(v)
+                    ? v.map((item) => String(item)).join(",")
+                    : typeof v === "object"
+                        ? JSON.stringify(v)
+                        : String(v));
             }
         }
         return `${base}${basePath}${cleanPath}?${params.toString()}`;

package/dist/index.js

@@ -84,6 +84,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import { DashboardHttpClient } from "./http-client.js";
 import { planConnect, danxbotApi, danxbotApiList, danxbotApiSpec, attachFile, DANXBOT_API_METHODS, } from "./handlers.js";
+import { queryValueSchema } from "./types.js";
 import { registerLifecycleTools, applyLifecycleVisibility, readLifecycleUrlsFromEnv, } from "./lifecycle.js";
 function readEnvOrDie(name) {
     const v = process.env[name];
@@ -337,24 +338,16 @@ strictTool("danxbot_api", "Call any dashboard API route your credential may reac
         .min(1)
         .startsWith("/api/")
         .describe('Full path starting with "/api/" — never a route template.'),
-    // DX-3465 (code-quality gate finding, at 275f82c0d) — a query value may
-    // be a field TREE (a plain object or array, e.g.
-    // `{"description":true,"comments":{"limit":20}}`), not just a scalar —
-    // SERVER_INSTRUCTIONS below says "ALWAYS pass `fields` … a field tree"
-    // and the OpenAPI spec agrees (`fields`'s schema is `{type:"object"}`),
-    // so the schema here must accept what those two tell the caller to
-    // send. `DashboardHttpClient#buildUrl` JSON-encodes an object/array
-    // value into the query string; a scalar serializes as before.
-    query: z
-        .record(z.union([
-        z.string(),
-        z.number(),
-        z.boolean(),
-        z.null(),
-        z.record(z.unknown()),
-        z.array(z.unknown()),
-    ]))
-        .optional(),
+    // DX-3465 — a query value may be a scalar, a field TREE (a plain
+    // object, e.g. `{"description":true,"comments":{"limit":20}}` — see
+    // SERVER_INSTRUCTIONS below and the OpenAPI spec's `fields` schema), or
+    // an array of scalars (e.g. `ids` on the batch-get route).
+    // `DashboardHttpClient#buildUrl` JSON-encodes a plain object but
+    // comma-joins an array, matching the two shapes the server actually
+    // parses (a JSON field tree vs. a comma-separated list param) — so array
+    // elements are restricted to scalars, the only thing a comma-join can
+    // represent losslessly.
+    query: queryValueSchema.optional(),
     body: z.unknown().optional(),
     ...boardField,
 }, async (args) => jsonResult(await danxbotApi(client, args)));
@@ -420,7 +413,7 @@ strictTool("attach_file", "Attach a LOCAL file to a card: `card_id` + `path` (an
 // no existing plan for an id to name yet.
 strictTool("plan_connect", 
 // DX-2735: trimmed with the problem tools to stay inside the work-profile budget.
-"Connect THIS session to a plan. ONE CALL IS ENOUGH TO START: the reply carries `{session, movedFrom, browserInstruction, briefing, listenerHealth}` — `browserInstruction` is a server-built action to take NOW: it names the plan's URL and tells you to open it (in-app browser if you have one, else default), keep that tab open for the whole session without navigating it away, and use a different tab for your own browsing — the operator's tab for following and talking to you. Returned on every connect, including a re-connect, so it doubles as the post-context-loss reminder. `briefing` is every goal/rule/caveat (ref+body), every architecture section (id+title), the plan's own ref/name/status, a first page of open cards (id/type/status/title/openProblemCount/assignedAgent) with a `morePagesHint` when more exist, and the closed-card count — usually replacing the plan read + card batch-read a fresh session used to need. A session is on AT MOST ONE plan: connecting elsewhere MOVES it, and `movedFrom: {id, name} | null` says which plan it left (null = no plan, or already this one). Binds only your OWN session, resolved from the session id this server forwards; afterwards every plan WRITE tool acts on this plan and takes no plan id. `listenerHealth` reports the event bridge's state — `null` (no session), or `{attached, state: \"unattached\"|\"credential_mismatch\"|\"healthy\", nextStep}` naming a concrete fix per unhealthy state (same shape the plan list/get routes report). Once healthy, every comment, answer, problem added and block/unblock on this plan's cards reaches the session unpolled, relayed by the plugin's event bridge as a line like `[DX-8 \"Title\" repo:board] newms87 answered \"<statement>\": chose \"Pause E2E\"`. Pass `title` (call `get_session({session_id:\"self\"})` first and forward its `title` verbatim) so the dashboard shows the same name Claude does — this server cannot read it itself. The response's `reminders[]` (when present) carries the mantra — read and follow it.", {
+"Connect THIS session to a plan. ONE CALL IS ENOUGH TO START: the reply carries `{session, movedFrom, browserInstruction, briefing, listenerHealth}` — `browserInstruction` is a server-built action to take NOW: it names the plan's URL and tells you to open it (in-app browser if you have one, else default), keep that tab open for the whole session without navigating it away, and use a different tab for your own browsing — the operator's tab for following and talking to you. Returned on every connect, including a re-connect, so it doubles as the post-context-loss reminder. `briefing` is every goal/rule/caveat (ref+body), every architecture section (id+title), the plan's own ref/name/status, a first page of open cards (id/type/status/title/openProblemCount/assignedAgent) with a `morePagesHint` when more exist, and the closed-card count — usually replacing the plan read + card batch-read a fresh session used to need. A session is on AT MOST ONE plan: connecting elsewhere MOVES it, and `movedFrom: {id, name} | null` says which plan it left (null = no plan, or already this one). Binds only your OWN session, resolved from the session id this server forwards; afterwards a `danxbot_api` call to a `/api/plans/mine/...` route (there is no dedicated plan-write tool) acts on this plan and takes no plan id. `listenerHealth` reports the event bridge's state — `null` (no session), or `{attached, state: \"unattached\"|\"credential_mismatch\"|\"healthy\", nextStep}` naming a concrete fix per unhealthy state (same shape the plan list/get routes report). Once healthy, every comment, answer, problem added and block/unblock on this plan's cards reaches the session unpolled, relayed by the plugin's event bridge as a line like `[DX-8 \"Title\" repo:board] newms87 answered \"<statement>\": chose \"Pause E2E\"`. Pass `title` (call `get_session({session_id:\"self\"})` first and forward its `title` verbatim) so the dashboard shows the same name Claude does — this server cannot read it itself. The response's `reminders[]` (when present) carries the mantra — read and follow it.", {
     plan_id: z.number().int().positive().describe("The plan id, from the plans list (`danxbot_api` `GET /api/plans`)."),
     title: z
         .string()

package/dist/types.js

@@ -1 +1,16 @@
-export {};
+import { z } from "zod";
+/**
+ * The zod schema for `danxbot_api`'s `query` argument, matching the
+ * `QueryValue` type above — a scalar, a field-tree object, or an array
+ * whose elements are themselves scalars (never objects; a comma-join
+ * cannot represent one losslessly). Exported so it can be exercised
+ * directly in tests without going through the MCP tool-call machinery.
+ */
+export const queryValueSchema = z.record(z.union([
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.null(),
+    z.record(z.unknown()),
+    z.array(z.union([z.string(), z.number(), z.boolean()])),
+]));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehammer/danx-dashboard-mcp",
-  "version": "0.1.166",
+  "version": "0.1.170",
   "description": "Stdio MCP server fronting danxbot's dashboard API for agents (operator sessions and dispatched workers alike): the generic danxbot_api/danxbot_api_list/danxbot_api_spec tools reach any route the caller's credential may call, plus dedicated agent-specific tools (plan_connect, danxbot_complete, and other per-dispatch lifecycle callbacks) (DX-3465, PLN-11 R-25).",
   "license": "MIT",
   "type": "module",