@thehammer/danx-dashboard-mcp 0.1.190 → 0.1.193

package/README.md

@@ -9,7 +9,7 @@ Stdio MCP server fronting danxbot's dashboard HTTP API. Since DX-3465 it exposes
 | Var | Purpose |
 |---|---|
 | `DANXBOT_DASHBOARD_URL` | Dashboard base, e.g. `http://danxbot-dashboard:5555` (inside compose) or `http://localhost:5555` (host) |
-| `DANXBOT_DASHBOARD_TOKEN_FILE` **or** `DANXBOT_DISPATCH_TOKEN` | The credential, declared exactly one of two ways (DX-2862, `src/credential.ts`). A FILE holding the bearer (a leading `~` is the user's home) — how an interactive operator session declares one, since its `.mcp.json` is git-tracked and can never carry the token itself. Or the bearer VERBATIM — how a dispatch declares one, substituted from its overlay. A declared file is AUTHORITATIVE and its failure is FATAL: an inherited `DANXBOT_DISPATCH_TOKEN` is never consulted instead, because on an operator machine that value routinely names a different (local-dev) dashboard, which answers healthily and empty. The same resolver serves the `bridge` subcommand below, so a session's tools and its event stream can never sign in as two different identities |
+| `DANXBOT_DASHBOARD_TOKEN_FILE` **or** `DANX_DASHBOARD_CREDENTIAL` | The credential, declared exactly one of two ways (DX-2862, `src/credential.ts`). A FILE holding the bearer (a leading `~` is the user's home) — how an interactive operator session declares one, since its `.mcp.json` is git-tracked and can never carry the token itself. Or the bearer VERBATIM — how a dispatch declares one, substituted from its overlay. A declared file is AUTHORITATIVE and its failure is FATAL: an inherited `DANX_DASHBOARD_CREDENTIAL` is never consulted instead, because on an operator machine that value routinely names a different (local-dev) dashboard, which answers healthily and empty. The same resolver serves the `bridge` subcommand below, so a session's tools and its event stream can never sign in as two different identities |
 | `DANX_REPO_NAME` | Repo half of the qualified board id |
 | `DANXBOT_BOARD_NAME` | Board-slug half of the qualified board id (the dispatch injects `board.slug` here) |
 
@@ -39,7 +39,7 @@ A program runs this, not an agent: the danxbot Claude Code plugin's plan event b
 CLAUDE_CODE_SESSION_ID=<session> npx -y @thehammer/danx-dashboard-mcp@<version> bridge [--resume-ids <id>,<id>,...]
 ```
 
-- **Credential — the session's own, never the ambient one (DX-2862).** The session id is the only thing `bridge` takes from its environment; `--resume-ids` is the only argument and holds no secret. Everything else comes from the connection record this session's own danx-dashboard MCP server wrote on `plan_connect` (`src/session-connection.ts`): the dashboard URL, the credential's SOURCE, and its FINGERPRINT. `bridge` resolves that source through the same resolver the server used and refuses to run unless the result fingerprints identically — `credential_mismatch`. Before that fix it used whatever `DANXBOT_DISPATCH_TOKEN` the session's environment held, and on a machine where that differed from the server's credential the dashboard admitted the stream and dropped every event, with nothing logged anywhere.
+- **Credential — the session's own, never the ambient one (DX-2862).** The session id is the only thing `bridge` takes from its environment; `--resume-ids` is the only argument and holds no secret. Everything else comes from the connection record this session's own danx-dashboard MCP server wrote on `plan_connect` (`src/session-connection.ts`): the dashboard URL, the credential's SOURCE, and its FINGERPRINT. `bridge` resolves that source through the same resolver the server used and refuses to run unless the result fingerprints identically — `credential_mismatch`. Before that fix it used whatever `DANX_DASHBOARD_CREDENTIAL` the session's environment held, and on a machine where that differed from the server's credential the dashboard admitted the stream and dropped every event, with nothing logged anywhere.
 - **No client-side reach check (DX-2920).** `bridge` used to prove board reach itself, before ever opening the stream (`GET /api/plans/mine?fields=cards` + a per-board `GET /api/issues/:id/problems`). That check is DELETED. The dashboard briefly enforced the identical requirement server-side (DX-2863: refusing a mint or stream admission with `403 issuer_cannot_read_plan_boards`, and ending a live stream `{"reason":"scope_narrowed","boards":[…]}`), but DX-3468 removed that mechanism too — DX-3409 made every credential team-bound, so a plan session's issuer and every board its connected plan covers are always in the same team, and the check could never fire any more. `bridge` no longer independently verifies board reach at all, client- or server-side. Once a ticket is minted, `bridge` emits, once, `{"type":"ready"}` — no `boards` field, since reach is no longer proven client-side.
 - **Ticket.** `bridge` mints the session's listener ticket (`POST /api/plan-sessions/me/stream-ticket`, 10 s timeout) and keeps it in the process. A ticket authorizes reading that one session's event stream and nothing else, and is only issued while the session is connected to a plan. Minting a new one ends the previous listener.
 - **Output — JSON Lines.** One `{"type":"event","id":<id|null>,"text":"…"}` per event on the connected plan's cards, where `text` is `[DX-8 "Title" repo:board] newms87 answered "Which rollout order?": chose "Pause E2E" — note: "only this week"`, `… answered "…": "<free-form answer>"`, `… commented: "…"`, `… opened a problem: "…"`, `… blocked the card: "…"`, or `… unblocked the card`. An event it cannot read still produces one, with a `could not read event` text. Nothing for keep-alives, reconnects or re-mints. The session's own writes are never echoed back to it.

package/dist/bridge.js

@@ -283,7 +283,7 @@ export class BridgeStartError extends Error {
 /**
  * The session's connection, as its own MCP server recorded it — and the proof
  * that this process holds the SAME credential that server does. Never falls back
- * to an ambient `DANXBOT_DISPATCH_TOKEN`: that fallback is precisely DX-2862.
+ * to an ambient env credential: that fallback is precisely DX-2862.
  */
 const INSTANCE_ID_ENV = "DANX_BRIDGE_INSTANCE_ID";
 /**

package/dist/credential.js

@@ -6,7 +6,7 @@
  * and `danx-dashboard-mcp bridge` (the session's event stream, run by the
  * danxbot plugin's plan event bridge). Before this module they resolved their
  * credential independently — the server through danxbot's operator launcher,
- * which read a token file, and the bridge from whatever `DANXBOT_DISPATCH_TOKEN`
+ * which read a token file, and the bridge from whatever credential variable
  * happened to be in the session's environment. On a machine where those two
  * differ (DX-2862: `ffe9f8a882f0…` in the environment, `6f9bc6e94b83…` in
  * `~/.config/danxbot/dashboard-token-gpt`) the session's tools worked, the
@@ -21,15 +21,15 @@
  *     home). The file's trimmed contents are the credential. This is how an
  *     interactive operator session declares one, because its `.mcp.json` is
  *     git-tracked and can never carry the bearer itself.
- *   - `DANXBOT_DISPATCH_TOKEN` — the credential verbatim. This is how a
+ *   - `DANX_DASHBOARD_CREDENTIAL` — the credential verbatim. This is how a
  *     DISPATCH declares one: the worker substitutes it into the materialized
  *     `.mcp.json` from the dispatch overlay.
  *
  * A DECLARED FILE IS AUTHORITATIVE, AND ITS FAILURE IS FATAL. When the file
- * variable is set, `DANXBOT_DISPATCH_TOKEN` is never consulted — not even when
+ * variable is set, `DANX_DASHBOARD_CREDENTIAL` is never consulted — not even when
  * the file is missing or empty. That is the DX-2483 rule, moved here from the
  * launcher it used to live in: an operator machine routinely carries an
- * inherited `DANXBOT_DISPATCH_TOKEN` naming the LOCAL dev dashboard, which
+ * inherited env credential naming the LOCAL dev dashboard, which
  * answers healthily and empty for a board it does not carry, so preferring it
  * after a failed file read would turn a loud, fixable error into exactly the
  * silent wrong-dashboard answer this whole module exists to prevent.
@@ -39,7 +39,7 @@ import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { isAbsolute, join, resolve } from "node:path";
 export const CREDENTIAL_FILE_ENV = "DANXBOT_DASHBOARD_TOKEN_FILE";
-export const CREDENTIAL_TOKEN_ENV = "DANXBOT_DISPATCH_TOKEN";
+export const CREDENTIAL_TOKEN_ENV = "DANX_DASHBOARD_CREDENTIAL";
 /**
  * A credential that cannot be resolved. Carries the remedy beside the reason,
  * because both of this module's callers report failures to a human who is not

package/dist/danxbot-api-examples.js

@@ -0,0 +1,59 @@
+/**
+ * DX-3923 — correct first calls for the routes every card session uses,
+ * rendered into the `danxbot_api` tool description (index.ts). The DX-3678
+ * grading run found the same avoidable 4xx in session after session (a card
+ * read's `fields` sent as a comma string, `fields.parent`, top-level list
+ * filters, a card edit sent to `PATCH /api/issues/:id`, a comment keyed
+ * `body`, retro `tests[].kind: "unit"`, the AC-tick route hunted through a
+ * 36 KB `danxbot_api_list`) because nothing an agent
+ * reads before its first call showed the right shape. The tool description
+ * is the one surface every profile and every operator session carries.
+ *
+ * Kept as data, not prose, so danxbot's own tests can check each example
+ * against the live server contract (route table, resource fields, body
+ * schemas) and fail when one drifts — this package cannot import the
+ * server's constants itself (it is published on its own).
+ */
+export const DANXBOT_API_EXAMPLES = {
+    cardRead: {
+        method: "GET",
+        path: "/api/issues/<id>",
+        query: { fields: { description: true, ac: true, comments: true, checklists: true, parent_title: true } },
+    },
+    cardList: {
+        method: "GET",
+        path: "/api/issues",
+        query: { filter: { status_derived: "ToDo", q: "<text>" } },
+    },
+    cardEdit: {
+        method: "PATCH",
+        path: "/api/issues/<id>/edit",
+        body: { description: "<markdown>", content_hash: "<content_hash from your read>" },
+    },
+    comment: {
+        method: "POST",
+        path: "/api/issues/<id>/comments",
+        body: { text: "<markdown>" },
+    },
+    acTick: {
+        method: "PATCH",
+        path: "/api/issues/<id>/checklists/<checklists[].id>/items/<items[].id>",
+        body: { status: "passing" },
+    },
+};
+/** The retro route's accepted `tests[].kind` values. */
+export const RETRO_TEST_KIND_EXAMPLES = ["group", "e2e"];
+function render(example) {
+    const { method, path, query, body } = example;
+    return JSON.stringify({ method, path, ...(query ? { query } : {}), ...(body ? { body } : {}) });
+}
+/** The description sentence `danxbot_api` carries. */
+export function danxbotApiExamplesText() {
+    const e = DANXBOT_API_EXAMPLES;
+    return (`Correct first calls: card read ${render(e.cardRead)} (\`fields\` is an object, never a comma string); ` +
+        `card list ${render(e.cardList)} (filters only inside \`filter\`); ` +
+        `card edit ${render(e.cardEdit)}; ` +
+        `comment ${render(e.comment)}; ` +
+        `AC tick ${render(e.acTick)}; ` +
+        `retro \`tests[].kind\` is ${RETRO_TEST_KIND_EXAMPLES.map((k) => `"${k}"`).join(" or ")}.`);
+}

package/dist/handlers.js

@@ -81,7 +81,7 @@ export function isDanxbotApiMethod(value) {
  *
  * The credential lives inside `client` (resolved once at boot — the
  * operator's declared token file for a session, the per-dispatch
- * `DANXBOT_DISPATCH_TOKEN` for a worker) and never appears in this
+ * `DANX_DASHBOARD_CREDENTIAL` for a worker) and never appears in this
  * function's arguments or return value — nothing in `DanxbotApiArgs` can
  * carry one. The session id (`x-danx-session-id`) rides every call the SAME
  * way it already does for every other tool on this server

package/dist/index.js

@@ -55,8 +55,8 @@
  *                           session, whose `.mcp.json` is git-tracked and so
  *                           can never carry one); authoritative when set, and
  *                           its failure is fatal — an inherited
- *                           DANXBOT_DISPATCH_TOKEN is never consulted instead
- *     DANXBOT_DISPATCH_TOKEN  the bearer verbatim (a dispatch, substituted into
+ *                           DANX_DASHBOARD_CREDENTIAL is never consulted instead
+ *     DANX_DASHBOARD_CREDENTIAL  the bearer verbatim (a dispatch, substituted into
  *                           the materialized `.mcp.json` from its overlay)
  *   DANX_REPO_NAME          repo half of the qualified board id
  *   DANXBOT_BOARD_NAME      board-slug half of the qualified board id
@@ -85,6 +85,7 @@ import { z } from "zod";
 import { DashboardHttpClient } from "./http-client.js";
 import { planConnect, danxbotApi, danxbotApiList, danxbotApiSpec, attachFile, DANXBOT_API_METHODS, } from "./handlers.js";
 import { bodyValueSchema, queryValueSchema } from "./types.js";
+import { danxbotApiExamplesText } from "./danxbot-api-examples.js";
 import { registerLifecycleTools, applyLifecycleVisibility, readLifecycleUrlsFromEnv, } from "./lifecycle.js";
 function readEnvOrDie(name) {
     const v = process.env[name];
@@ -227,6 +228,7 @@ same four verbs:
   - create POST <collection>            — the resource's own required fields; a 400 names any missing/invalid one.
   - update PATCH/PUT <collection>/:id   — send only the fields you are changing; most resources require the
                                            concurrency token below when the edit touches contested text fields.
+                                           A card is the exception: PATCH /api/issues/<id>/edit.
   - delete DELETE <collection>/:id      — usually a soft-delete; the resource's own docs say so.
 Don't know the route for what you need to do? Call \`danxbot_api_list()\` — it lists exactly the routes your
 credential may call, one line each. Then call \`danxbot_api_spec({endpoints: ["METHOD /path/template"]})\` for the
@@ -331,7 +333,10 @@ strictTool("danxbot_api", "Call any dashboard API route your credential may reac
     "route attaches one. `board` overrides this dispatch's configured board for a board-scoped route only " +
     "(ignored by a route that isn't board-scoped). See this server's own instructions (shown once, at connect) " +
     "for the shared resource shape, the stale-hash rule, and how to read a refusal — don't know the route? call " +
-    "`danxbot_api_list` first; unsure of its exact shape? call `danxbot_api_spec` first.", {
+    "`danxbot_api_list` first; unsure of its exact shape? call `danxbot_api_spec` first. " +
+    // DX-3923 — the shapes agents guessed wrong most often, shown before the
+    // first call instead of learned from a 4xx.
+    danxbotApiExamplesText(), {
     method: z.enum(DANXBOT_API_METHODS),
     path: z
         .string()
@@ -466,7 +471,7 @@ async function main() {
 // the dashboard URL, credential source, and credential itself come from the
 // session-connection record this server's own `plan_connect` wrote
 // (`session-connection.ts`), never from the bridge's own environment
-// (DX-2862: a bridge trusting its own ambient `DANXBOT_DISPATCH_TOKEN` is the
+// (DX-2862: a bridge trusting its own ambient env credential is the
 // exact bug this repo fixed).
 //
 // Any OTHER argument is refused rather than ignored, so a typo cannot

package/dist/session-connection.js

@@ -6,7 +6,7 @@
  * in the SESSION's environment — not in the MCP server's, which is the only
  * place the server's `.mcp.json` env block exists. So the bridge cannot see
  * what the server was configured with, and before this it simply used its own
- * ambient `DANXBOT_DISPATCH_TOKEN`. When that was a different credential from
+ * ambient env credential. When that was a different credential from
  * the server's, every event was dropped silently (the card's incident).
  *
  * WHAT IS WRITTEN, AND WHAT IS NOT. On a successful `plan_connect` the server

package/package.json

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