@thehammer/danx-dashboard-mcp 0.1.159 → 0.1.162

package/dist/http-client.js

@@ -1,6 +1,10 @@
+import { assertVersionFloorSatisfied, MCP_MIN_VERSION_HEADER } from "./version-floor.js";
 export class DashboardHttpClient {
     config;
     fetchImpl;
+    // DX-3597 — true once this instance has made ONE request, regardless of
+    // outcome. Drives the "first call OR any 4xx" version-floor check below.
+    hasCheckedVersionFloor = false;
     constructor(config, fetchImpl = fetch) {
         this.config = config;
         this.fetchImpl = fetchImpl;
@@ -50,6 +54,18 @@ export class DashboardHttpClient {
         catch (err) {
             throw new Error(`[danx-dashboard-mcp] network failure on ${args.method} ${url}: ${err instanceof Error ? err.message : String(err)}`);
         }
+        // DX-3597 — proactive on the first call this instance ever makes
+        // (regardless of outcome: a stale client can otherwise look fine for a
+        // while on routes whose shape didn't change), and on every subsequent
+        // 4xx (a response that might otherwise read as an ordinary caller
+        // error when it's really "you're running an old MCP"). Throws
+        // McpOutdatedError instead of returning below when this package is
+        // behind the floor — see version-floor.ts's own doc.
+        const isFirstCall = !this.hasCheckedVersionFloor;
+        this.hasCheckedVersionFloor = true;
+        if (isFirstCall || (res.status >= 400 && res.status < 500)) {
+            assertVersionFloorSatisfied(res.headers.get(MCP_MIN_VERSION_HEADER));
+        }
         const text = await res.text();
         let parsed = null;
         if (text !== "") {

package/dist/index.js

@@ -879,7 +879,7 @@ strictTool("issue_attach", "Attach a LOCAL file to an issue card: `id` (the card
 // plan id — and it can only ever bind the caller's own session. `plan_create`
 // also takes no plan id, but for a different reason: it MAKES a plan rather
 // than acting on one, so there is no existing plan for an id to name yet.
-strictTool("plan_list", "List every plan, and learn which plan THIS session is connected to. Plans are GLOBAL, not board-scoped — a plan is a named, dated set of cards an operator assembled by hand, from any repo. Returns `{plans: [{id, ref, name, createdAt, cardCount, boards, status, signedOffAt, signedOffBy, autoSignOff}], session, sessionListenerAttached}` — `ref` is the plan's short reference (`PLN-<id>`), cite it rather than the bare id. `status` is computed fresh on every read, never stored — except the sign-off pair itself: `awaiting-session` (no live session — a session row isn't released just because a session ended), `planning` (no cards, or only Review/Backlog/terminal ones with ≥1 not Done/Cancelled), `building` (a live session AND ≥1 card ToDo/In Progress or stuck-but-active — Blocked/Needs Help), `awaiting-sign-off` (≥1 card, all Done/Cancelled, but nobody has signed the plan off yet — DX-3519), `complete` (≥1 card, all Done/Cancelled, AND signed off — wins even with no session). `signedOffAt`/`signedOffBy` are `null` until a human (`signedOffBy` = their identity) or the `autoSignOff` toggle (`signedOffBy: 'auto'`) signs the plan off; sign-off itself is a human-only write, not exposed through this MCP surface — direct the operator to the dashboard's plan page. Pass `status` to filter. `session` is your own registration (`{sessionId, title, planId, planName, firstSeenAt, lastActiveAt}`) or null outside a Claude Code session; `planId: null` means connected to no plan — `plan_get` to browse, `plan_connect` to bind. `sessionListenerAttached` says whether your event stream is attached (the plugin's plan bridge); false for a few seconds right after connect is normal, false after that means events aren't reaching you — tell the operator.", {
+strictTool("plan_list", "List every plan, and learn which plan THIS session is connected to. Plans are GLOBAL, not board-scoped — a plan is a named, dated set of cards an operator assembled by hand, from any repo. Returns `{plans: [{id, ref, name, createdAt, cardCount, boards, status, signedOffAt, signedOffBy, autoSignOff}], session, sessionListenerAttached}` — `ref` is the plan's short reference (`PLAN-<id>`), cite it rather than the bare id. `status` is computed fresh on every read, never stored — except the sign-off pair itself: `awaiting-session` (no live session — a session row isn't released just because a session ended), `planning` (no cards, or only Review/Backlog/terminal ones with ≥1 not Done/Cancelled), `building` (a live session AND ≥1 card ToDo/In Progress or stuck-but-active — Blocked/Needs Help), `awaiting-sign-off` (≥1 card, all Done/Cancelled, but nobody has signed the plan off yet — DX-3519), `complete` (≥1 card, all Done/Cancelled, AND signed off — wins even with no session). `signedOffAt`/`signedOffBy` are `null` until a human (`signedOffBy` = their identity) or the `autoSignOff` toggle (`signedOffBy: 'auto'`) signs the plan off; sign-off itself is a human-only write, not exposed through this MCP surface — direct the operator to the dashboard's plan page. Pass `status` to filter. `session` is your own registration (`{sessionId, title, planId, planName, firstSeenAt, lastActiveAt}`) or null outside a Claude Code session; `planId: null` means connected to no plan — `plan_get` to browse, `plan_connect` to bind. `sessionListenerAttached` says whether your event stream is attached (the plugin's plan bridge); false for a few seconds right after connect is normal, false after that means events aren't reaching you — tell the operator.", {
     status: z
         .enum(PLAN_STATUSES)
         .optional()
@@ -891,7 +891,7 @@ strictTool("plan_get",
 // TREE against the plan resource — the SAME `fieldTreeSchema` `issue_get`/
 // `issue_list` already take (`./field-tree.ts`). Every former query param
 // now lives INSIDE the tree as a relation argument.
-"Read a plan. Pass `plan_id` to read ANY plan; OMIT to read the plan this session is connected to — omitting while connected to none fails loud `{error: \"session_not_connected\"}`, connect first. A BARE call (no `fields`) returns ONLY the plan's cheap scalars: `{id, ref, name, created_at, signed_off_at, signed_off_by, auto_sign_off, boards, card_count, bucket_counts, status, session, sessionListenerAttached}` — no cards, records, or architecture body. `ref` is the plan's short reference (`PLN-<id>`) — cite that, not the bare id. `status` is computed fresh on every read, never stored — see `plan_list` for the four values and what each means. Pass a `fields` tree to opt into: `cards` (member cards — the ISSUE resource itself, so any of `issue_get`'s own fields/relations may be nested under it, e.g. `{\"cards\": {\"title\": true, \"status\": true}}`; cursor-paged via `{\"limit\": N, \"before\": \"<cursor>\"}`, response carries a sibling `cards_page: {limit, total, next_cursor}`), `records` (every goal+rule+caveat) or `{\"records\": {\"kind\": \"goal\"}}` / `{\"kind\": [\"goal\",\"rule\"]}` (narrow to one or more kinds, cheaper), `architecture_sections` (`[{id, plan_id, content_hash, title, content, sort_order, created_at, updated_at}]`), `sessions` (every session connected to the plan), `notes` (the latest milestone-timeline page), `events` (the plan's durable event ledger — every human action and bridge message; cursor-paged via `{\"limit\": N, \"before\": \"<cursor>\"}` plus the filter args `{\"kinds\": [...], \"origin\": \"...\", \"writer\": \"...\"}`; response carries `events` rows plus a sibling `events_page: {limit, total, next_cursor}`; `next_cursor` null on the last page; an event on a card whose board you cannot read is left out, plan-level events are always visible). Call `resource_fields({resource:\"plan\"})` for the full, current list of what a tree may name — never guess a name; unknown → 400 `unknown_field`. `session`/`sessionListenerAttached` ride every response regardless (not part of the tree — they describe YOUR session, not the plan). `sessionListenerAttached` is `false` for a few seconds right after `plan_connect` while the plugin's event bridge starts; still `false` after that while connected means the plan's card events are not reaching you — tell the operator. ALWAYS `plan_get`/`plan_get_architecture_section` immediately before `plan_update_architecture_section`/`plan_delete_architecture_section` and pass the returned `content_hash`/`contentHash` back as `base_hash`.", {
+"Read a plan. Pass `plan_id` to read ANY plan; OMIT to read the plan this session is connected to — omitting while connected to none fails loud `{error: \"session_not_connected\"}`, connect first. A BARE call (no `fields`) returns ONLY the plan's cheap scalars: `{id, ref, name, created_at, signed_off_at, signed_off_by, auto_sign_off, boards, card_count, bucket_counts, status, session, sessionListenerAttached}` — no cards, records, or architecture body. `ref` is the plan's short reference (`PLAN-<id>`) — cite that, not the bare id. `status` is computed fresh on every read, never stored — see `plan_list` for the four values and what each means. Pass a `fields` tree to opt into: `cards` (member cards — the ISSUE resource itself, so any of `issue_get`'s own fields/relations may be nested under it, e.g. `{\"cards\": {\"title\": true, \"status\": true}}`; cursor-paged via `{\"limit\": N, \"before\": \"<cursor>\"}`, response carries a sibling `cards_page: {limit, total, next_cursor}`), `records` (every goal+rule+caveat) or `{\"records\": {\"kind\": \"goal\"}}` / `{\"kind\": [\"goal\",\"rule\"]}` (narrow to one or more kinds, cheaper), `architecture_sections` (`[{id, plan_id, content_hash, title, content, sort_order, created_at, updated_at}]`), `sessions` (every session connected to the plan), `notes` (the latest milestone-timeline page), `events` (the plan's durable event ledger — every human action and bridge message; cursor-paged via `{\"limit\": N, \"before\": \"<cursor>\"}` plus the filter args `{\"kinds\": [...], \"origin\": \"...\", \"writer\": \"...\"}`; response carries `events` rows plus a sibling `events_page: {limit, total, next_cursor}`; `next_cursor` null on the last page; an event on a card whose board you cannot read is left out, plan-level events are always visible). Call `resource_fields({resource:\"plan\"})` for the full, current list of what a tree may name — never guess a name; unknown → 400 `unknown_field`. `session`/`sessionListenerAttached` ride every response regardless (not part of the tree — they describe YOUR session, not the plan). `sessionListenerAttached` is `false` for a few seconds right after `plan_connect` while the plugin's event bridge starts; still `false` after that while connected means the plan's card events are not reaching you — tell the operator. ALWAYS `plan_get`/`plan_get_architecture_section` immediately before `plan_update_architecture_section`/`plan_delete_architecture_section` and pass the returned `content_hash`/`contentHash` back as `base_hash`.", {
     plan_id: z
         .number()
         .int()
@@ -902,7 +902,7 @@ strictTool("plan_get",
         .optional()
         .describe("A field tree (see tool description); absent/empty = cheap scalars only. `resource_fields({resource:\"plan\"})` names every valid key."),
 }, async (args) => jsonResult(await planGet(client, args)));
-strictTool("plan_create", "Create a new, empty plan. Global — not board-scoped. Adds no cards, records, or architecture sections, and does not connect any session (call `plan_connect` separately). Returns `{plan: {id, ref, name, createdAt}}` — `ref` is the short reference (`PLN-<id>`). Use `plan.id` with `plan_connect` to start working on it, or `plan_get({plan_id})` to browse.", {
+strictTool("plan_create", "Create a new, empty plan. Global — not board-scoped. Adds no cards, records, or architecture sections, and does not connect any session (call `plan_connect` separately). Returns `{plan: {id, ref, name, createdAt}}` — `ref` is the short reference (`PLAN-<id>`). Use `plan.id` with `plan_connect` to start working on it, or `plan_get({plan_id})` to browse.", {
     name: z.string().min(1).describe("The plan's name — shown in the Plans list."),
 }, async (args) => jsonResult(await planCreate(client, args)));
 strictTool("plan_connect", 

package/dist/version-floor.js

@@ -0,0 +1,128 @@
+/**
+ * DX-3597 — this package's half of the MCP-version-floor guard whose
+ * server-side half shipped in DX-3525 (`src/mcp-contract.ts`,
+ * `src/dashboard/serve-request.ts`, `src/resources/field-tree.ts`, all in
+ * the main danxbot repo — this package cannot import them, see below).
+ *
+ * The dashboard stamps `X-Danx-Mcp-Min-Version` on every routed `/api/*`
+ * response with its currently-advertised floor (`MIN_MCP_VERSION` in
+ * `src/mcp-contract.ts` — DX-3597 made that floor track the version where
+ * an MCP-exposed contract last changed, not "whatever's currently
+ * published"; see that file's module doc for the full decision).
+ *
+ * `DashboardHttpClient.request()` (`./http-client.ts`) reads this header on
+ * the FIRST call this process makes (regardless of outcome — a proactive
+ * check, since a stale client can otherwise appear to work for a while on
+ * routes whose shape didn't change) and on every subsequent 4xx (a response
+ * that might otherwise read as an ordinary caller error, when it's really
+ * "you're running an old MCP"). When this package's own version is behind
+ * the advertised floor, it throws `McpOutdatedError` instead of returning
+ * the ordinary envelope — the same "throw rather than fabricate/silently
+ * pass through" contract `http-client.ts` already applies to a 5xx/network
+ * failure (see that file's own doc): an outdated MCP is exactly that class
+ * of failure, nothing the calling tool can meaningfully work around.
+ *
+ * Everything here is duplicated, not imported, from the server's
+ * `src/mcp-contract.ts` — this package is an INDEPENDENTLY PUBLISHED npm
+ * artifact (DX-2103) and cannot depend on the danxbot service's own `src/`
+ * tree. Keep the header name, the package name, and the version-compare
+ * behavior in agreement with that file by hand when either changes.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/** Must match `MCP_MIN_VERSION_HEADER` in danxbot's `src/mcp-contract.ts` verbatim. */
+export const MCP_MIN_VERSION_HEADER = "X-Danx-Mcp-Min-Version";
+/** Must match `MCP_PACKAGE_NAME` in danxbot's `src/mcp-contract.ts` verbatim. */
+export const MCP_PACKAGE_NAME = "@thehammer/danx-dashboard-mcp";
+/**
+ * Numeric-dotted version compare (major.minor.patch, ...) — mirrors
+ * `compareMcpVersions` in danxbot's `src/mcp-contract.ts` behavior
+ * byte-for-byte (duplicated, not imported — see module doc). Both sides of
+ * this contract have only ever used plain numeric dotted versions, so this
+ * throws rather than silently falling back to a lexical compare, which
+ * would misorder "0.1.9" vs "0.1.10".
+ */
+export function compareMcpVersions(a, b) {
+    const parse = (v) => {
+        if (!/^\d+(\.\d+)*$/.test(v)) {
+            throw new Error(`[danx-dashboard-mcp] "${v}" is not a plain numeric dotted version (major.minor.patch)`);
+        }
+        return v.split(".").map(Number);
+    };
+    const pa = parse(a);
+    const pb = parse(b);
+    const len = Math.max(pa.length, pb.length);
+    for (let i = 0; i < len; i++) {
+        const da = pa[i] ?? 0;
+        const db = pb[i] ?? 0;
+        if (da !== db)
+            return da - db;
+    }
+    return 0;
+}
+let cachedOwnVersion;
+/**
+ * Reads this package's OWN version from its `package.json` — always present
+ * next to `dist/` (or `src/`, under `npm run dev`'s `tsx`) at runtime even
+ * though `files: ["dist","README.md"]` excludes it from the tarball
+ * MANIFEST: npm always includes `package.json` in what it publishes and
+ * what it installs, regardless of `files` (the same guarantee `README` /
+ * `LICENSE` / the `main` entry get) — this reads the copy npm actually
+ * installed next to this module, not danxbot's own source tree. Both
+ * `dist/version-floor.js` and `src/version-floor.ts` sit exactly one
+ * directory below the package root, so `../package.json` resolves
+ * correctly under both the published (dist) and dev (`tsx src/index.ts`)
+ * shapes. Memoized — the version cannot change mid-process.
+ */
+export function readOwnVersion() {
+    if (cachedOwnVersion !== undefined)
+        return cachedOwnVersion;
+    const here = dirname(fileURLToPath(import.meta.url));
+    const pkgJsonPath = join(here, "..", "package.json");
+    const raw = readFileSync(pkgJsonPath, "utf8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.version !== "string") {
+        throw new Error(`[danx-dashboard-mcp] could not read this package's own version from ${pkgJsonPath}`);
+    }
+    cachedOwnVersion = parsed.version;
+    return cachedOwnVersion;
+}
+/** Test-only escape hatch — real callers never need to override the memoized read. */
+export function __resetOwnVersionCacheForTests() {
+    cachedOwnVersion = undefined;
+}
+/**
+ * Thrown by `assertVersionFloorSatisfied` when this package is running
+ * behind the server's advertised floor. Carries structured `have`/`need`
+ * fields (not just a prose message) so a caller that wants to branch on
+ * "is this specifically an outdated-MCP failure" can check `error.code`
+ * rather than pattern-match the message text.
+ */
+export class McpOutdatedError extends Error {
+    code = "mcp_outdated";
+    have;
+    need;
+    constructor(have, need) {
+        super(`[danx-dashboard-mcp] mcp_outdated: this MCP is running ${MCP_PACKAGE_NAME}@${have}, but the dashboard ` +
+            `requires >= ${need}. Restart your Claude Code session to pick up the published update.`);
+        this.name = "McpOutdatedError";
+        this.have = have;
+        this.need = need;
+    }
+}
+/**
+ * Compares this package's own version against the floor a response header
+ * advertised. No-ops (returns) when compatible, or when `headerValue` is
+ * `null`/empty (an old-enough server, or a test stub, that never stamped
+ * one — nothing to compare against). Throws `McpOutdatedError` when this
+ * package is behind.
+ */
+export function assertVersionFloorSatisfied(headerValue) {
+    if (!headerValue)
+        return;
+    const have = readOwnVersion();
+    if (compareMcpVersions(have, headerValue) < 0) {
+        throw new McpOutdatedError(have, headerValue);
+    }
+}

package/package.json

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