@thehammer/danx-dashboard-mcp 0.1.192 → 0.1.194

package/README.md

@@ -21,7 +21,7 @@ All exposed as `mcp__danx-dashboard__<name>` once wired through the workspace `m
 
 | Tool | Purpose |
 |---|---|
-| `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` | `{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`. While this session is plan-connected, the dashboard's own reminders for it (today: `plan_list.listener_unattached`, attached by the server to `GET /api/plans` when the event listener is unattached past the startup grace, DX-3997) are relayed into the body's `reminders[]`; the MCP carries no reminder text or state of its own and re-reads at most every 30s. |
 | `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. |
 

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/index.js

@@ -79,12 +79,14 @@ import { ACTIVITY_SUBCOMMAND, runActivityCommand } from "./activity.js";
 import { EVENT_TEXT_SUBCOMMAND, runEventTextCommand } from "./event-text.js";
 import { resolveDeclaredCredential } from "./credential.js";
 import { recordSessionConnectionAfterConnect } from "./session-connection.js";
+import { createListenerReminder, isPlanConnectedOnThisMachine, } from "./listener-reminder.js";
 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 { 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];
@@ -113,6 +115,8 @@ function readEnvOptional(name) {
 // while a real run still fails loud on missing env via `boot()`.
 let config;
 let client;
+// DX-3997 — late-bound with `client`; see `listener-reminder.ts`.
+let listenerReminder;
 /**
  * DX-2862 — what this server would tell the session's plan event bridge about
  * how to reach the dashboard AS THIS SERVER: the URL, where the credential came
@@ -146,6 +150,14 @@ function boot() {
         fingerprint: credential.fingerprint,
     };
     client = new DashboardHttpClient(config);
+    const dashboardClient = client;
+    listenerReminder = createListenerReminder({
+        sessionId: config.session?.id,
+        fetchHealth: () => dashboardClient.request({ method: "GET", basePath: "", path: "/api/plans", query: { limit: 1 } }),
+        isPlanConnected: isPlanConnectedOnThisMachine,
+        now: Date.now,
+        logLine: (line) => console.error(line),
+    });
     // DX-3465 (PLN-11 R-25) — the lifecycle tool set's per-tool visibility is
     // per-dispatch, not static: a tool whose callback URL wasn't injected for
     // THIS dispatch must not even be advertised (mirrors the old standalone
@@ -227,6 +239,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
@@ -328,10 +341,14 @@ const boardField = {
 strictTool("danxbot_api", "Call any dashboard API route your credential may reach. `method` + `path` (a FULL path, e.g. " +
     '"/api/issues/DX-1/transition" — substitute real ids yourself, never a route template with `:id` in it) + ' +
     "optional `query`/`body`. The response is the route's JSON body verbatim, `reminders[]` included when the " +
-    "route attaches one. `board` overrides this dispatch's configured board for a board-scoped route only " +
+    "route attaches one — a plan-connected session whose event listener the dashboard reports unattached also gets " +
+    "the dashboard's own `plan_list.listener_unattached` reminder relayed there (DX-3997). `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()
@@ -359,7 +376,10 @@ strictTool("danxbot_api", "Call any dashboard API route your credential may reac
     // instead of reaching the dashboard malformed.
     body: bodyValueSchema.optional(),
     ...boardField,
-}, async (args) => jsonResult(await danxbotApi(client, args)));
+}, 
+// DX-3997 — the result rides back verbatim, plus the dashboard's own `reminders[]` entries
+// for this plan-connected session (the server decides; `listener-reminder.ts` only relays).
+async (args) => jsonResult(await listenerReminder.apply(await danxbotApi(client, args))));
 // ---------------- danxbot_api_list (DX-3465 A5, PLN-11 R-25) ----------------
 strictTool("danxbot_api_list", "Lists the dashboard API routes your credential may call right now — `[{method, path, summary, permission}]`, " +
     "one line each, in the route TEMPLATE form `danxbot_api_spec` also expects (e.g. " +
@@ -436,6 +456,8 @@ strictTool("plan_connect",
 // whose credential the stream must be minted with.
 async (args) => {
     const result = await planConnect(client, args);
+    // DX-3997 — a (re)connect restarts the bridge; the next `danxbot_api` must re-read health.
+    listenerReminder.invalidate();
     return jsonResult({
         ...result,
         ...recordSessionConnectionAfterConnect(result, {

package/dist/listener-reminder.js

@@ -0,0 +1,119 @@
+import { readSessionConnection } from "./session-connection.js";
+/** DX-3997 — how long one health read serves every response; per server process. */
+export const HEALTH_CACHE_WINDOW_MS = 30_000;
+function isReminder(value) {
+    const r = value;
+    return typeof r === "object" && r !== null && typeof r.key === "string" && typeof r.text === "string";
+}
+/** The reminders the health response carries, or a thrown Error naming why it cannot be read. */
+function readReminders(result) {
+    if (!result.ok)
+        throw new Error(`GET /api/plans answered ${result.status}`);
+    const body = result.body;
+    if (typeof body !== "object" || body === null || Array.isArray(body)) {
+        throw new Error("GET /api/plans did not answer a JSON object");
+    }
+    const reminders = body.reminders;
+    if (reminders === undefined)
+        return [];
+    if (!Array.isArray(reminders) || !reminders.every(isReminder)) {
+        throw new Error("GET /api/plans carried a `reminders` field that is not an array of {key, text} strings");
+    }
+    return reminders.map(({ key, text }) => ({ key, text }));
+}
+export function createListenerReminder(deps) {
+    let cached = null;
+    let inFlight = null;
+    // Bumped by `invalidate()`: a read that started under an older value must not refill the cache.
+    let generation = 0;
+    let failureLogged = false;
+    let shapeLogged = false;
+    const logFailure = (reason) => {
+        if (failureLogged)
+            return;
+        failureLogged = true;
+        deps.logLine(`[danx-dashboard-mcp] plan listener health check failed (${reason}); nothing relayed`);
+    };
+    async function read() {
+        try {
+            const reminders = readReminders(await deps.fetchHealth());
+            failureLogged = false;
+            return reminders;
+        }
+        catch (err) {
+            logFailure(err.message);
+            return [];
+        }
+    }
+    async function remindersNow() {
+        if (cached !== null && deps.now() - cached.at < HEALTH_CACHE_WINDOW_MS)
+            return cached.reminders;
+        // One read serves every caller that arrives while it is outstanding.
+        if (inFlight !== null)
+            return inFlight;
+        const startedUnder = generation;
+        const started = read()
+            .then((reminders) => {
+            if (generation === startedUnder)
+                cached = { reminders, at: deps.now() };
+            return reminders;
+        })
+            .finally(() => {
+            if (inFlight === started)
+                inFlight = null;
+        });
+        inFlight = started;
+        return started;
+    }
+    return {
+        async apply(result) {
+            const sessionId = deps.sessionId;
+            if (sessionId === undefined || sessionId === "")
+                return result;
+            const body = result.body;
+            // Never wrap or alter a body that is not a JSON object.
+            if (typeof body !== "object" || body === null || Array.isArray(body))
+                return result;
+            // Read per call (a file read): a connect made after this process started takes effect on
+            // the next call, and an unconnected session costs zero health reads.
+            let connected;
+            try {
+                connected = deps.isPlanConnected(sessionId);
+            }
+            catch (err) {
+                logFailure(err.message);
+                return result;
+            }
+            if (!connected)
+                return result;
+            const existing = body.reminders;
+            if (existing !== undefined && !Array.isArray(existing)) {
+                if (!shapeLogged) {
+                    shapeLogged = true;
+                    deps.logLine("[danx-dashboard-mcp] listener reminder not relayed: the response's own `reminders` is not an array");
+                }
+                return result;
+            }
+            const relayed = await remindersNow();
+            const present = new Set((existing ?? []).map((r) => (isReminder(r) ? r.key : null)));
+            const fresh = relayed.filter((r) => {
+                if (present.has(r.key))
+                    return false;
+                present.add(r.key);
+                return true;
+            });
+            if (fresh.length === 0)
+                return result;
+            return { ...result, body: { ...body, reminders: [...(existing ?? []), ...fresh] } };
+        },
+        invalidate() {
+            generation += 1;
+            cached = null;
+            inFlight = null;
+        },
+    };
+}
+/** The production wiring: the real local record. */
+export function isPlanConnectedOnThisMachine(sessionId) {
+    return readSessionConnection(sessionId) !== null;
+}

package/package.json

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