@thehammer/danx-dashboard-mcp 0.1.192 → 0.1.193

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

@@ -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()

package/package.json

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