@thehammer/danx-dashboard-mcp 0.1.61 → 0.1.63

package/README.md

@@ -22,7 +22,7 @@ All exposed as `mcp__danx-dashboard__<name>` once wired through the workspace `m
 | Tool | HTTP | Notes |
 |---|---|---|
 | `issue_list` | `GET /api/issues` | filters: `type`, `parent_id` (null → root-only), `dispatchable_derived`, `assigned_agent`, `include_closed`, `limit`, `offset` |
-| `issue_get` | `GET /api/issues/:id` or `GET /api/issues/batch` | Pass `id` for one card, or `ids[]` (DX-2727) to resolve many across boards in ONE call — global, no board scope, per-id `not_found` rather than a whole-call 404. Minimal scalars by default; `fields` opts in |
+| `issue_get` | `GET /api/issues/:id` or `GET /api/issues/batch` | Pass `id` for one card, or `ids[]` (DX-2727, at most 100) to resolve many across boards in ONE call — global, so `ids` with `board` throws; per-id `not_found` rather than a whole-call 404. Minimal scalars by default; `fields` opts in |
 | `issue_create` | `POST /api/issues` | Epic REQUIRES non-empty `phase_children[]` (atomic insert). `title` = short domain-naming label; `summary` = 1–3 plain-language sentences, always shown; `description` = the collapsed "Context" body. Root and every phase child take their own `summary` |
 | `issue_edit` | `PATCH /api/issues/:id/edit` | Prose + structured keys (`title`, `summary` (null clears), `description`, `ac`, `checklists`, `effort_level`, `parent_id`, `priority`, `list_id`); semantic keys refused with 400 + pointer to dedicated handler. `priority` (DX-1532) takes a tier word (`low`/`high`/…) or a number in `[0,6)` — the ONLY way to set the numeric column the Trello label + dashboard badge read; never set priority via description prose |
 | `issue_transition` | `POST /api/issues/:id/transition` | Actions: ready, pickup, rollback_pickup, complete, cancel, block, unblock, archive, reopen. A successful `block` also returns `solutions_reminder: {solution_count, instruction}` |
@@ -35,7 +35,7 @@ All exposed as `mcp__danx-dashboard__<name>` once wired through the workspace `m
 
 ## `plan_get` — cheap by default, opt-in for the rest (DX-2727)
 
-A bare `plan_get` (no `fields`) returns only the plan's cheap scalars — `plan`, `boards`, `cardCount`, `bucketCounts`, `session`, `sessionListenerAttached` — plus `available_field_groups` naming what else exists. Pass `fields` to opt into `cards` (capped at 200 members, with `cards_total` reporting the true count so a truncation is never silent), `records` (every goal/rule/caveat) or `records:goal` / `records:rule` / `records:caveat` (just one kind), `architecture`, and `sessions`. A `plan_get` made only to grab a hash before a one-line edit no longer pays for the architecture document or every member card.
+A bare `plan_get` (no `fields`) returns only the plan's cheap scalars — `plan`, `boards`, `cardCount`, `bucketCounts`, `session`, `sessionListenerAttached` — plus `available_field_groups` naming what else exists. Pass `fields` to opt into `cards` (paged: `cards_offset`, default 0, and `cards_limit`, 1..1000, default 200, pick the page; the response carries `cards_total` and `cards_offset`, so page with `cards_offset` while `cards_offset + cards.length < cards_total` — either paging arg without `cards` in `fields` is a 400), `records` (every goal/rule/caveat) or `records:goal` / `records:rule` / `records:caveat` (just one kind), `architecture`, and `sessions`. A `plan_get` made only to grab a hash before a one-line edit no longer pays for the architecture document or every member card.
 
 ## `listen` — a working session's event listener
 

package/dist/handlers.js

@@ -49,19 +49,43 @@ export async function issueList(client, args) {
     // DX-1171 — board-only: forward the qualified board id, no repo.
     return client.request({ method: "GET", path: "", query, board: args.board });
 }
+// ---------------- issue_get ----------------
+/**
+ * The most distinct ids one batch `issue_get` may name — mirrors the server's
+ * `src/issues/list-page.ts#ISSUE_BATCH_GET_MAX` (the batch route 400s above it);
+ * `__tests__/handlers.test.ts` asserts the two agree.
+ */
+export const ISSUE_BATCH_GET_MAX = 100;
+/**
+ * The largest page any paged list read accepts (`issue_list`'s `limit`,
+ * `plan_get`'s `cards_limit`) — mirrors the server's
+ * `src/issues/list-page.ts#MAX_LIMIT` (it 400s above it);
+ * `__tests__/handlers.test.ts` asserts the two agree.
+ */
+export const LIST_PAGE_MAX_LIMIT = 1000;
+/**
+ * `plan_get`'s `cards_limit` when omitted — mirrors the server's
+ * `src/issues/list-page.ts#PLAN_GET_CARDS_DEFAULT_LIMIT`;
+ * `__tests__/handlers.test.ts` asserts the two agree.
+ */
+export const PLAN_GET_CARDS_DEFAULT_LIMIT = 200;
 /**
  * Fetch one card via `GET /api/issues/:id`, or many via
  * `GET /api/issues/batch?ids=...` (DX-2727) — a real batch read that keeps
  * the single-id route's global, cross-board resolution rather than routing
  * through `issue_list` (board-scoped per call, and its filter has no `id`
  * property). Exactly one of `id` / `ids` must be given; the batch form
- * reports a per-id `not_found` list rather than failing the whole call, and
- * ignores `board` — the same no-scope contract the single-id form already has.
+ * reports a per-id `not_found` list rather than failing the whole call. The
+ * batch form is a global read with no board scope, so `ids` together with
+ * `board` is REFUSED here rather than `board` being silently dropped.
  */
 export async function issueGet(client, args) {
     if (args.id !== undefined && args.ids !== undefined) {
         throw new Error("issue_get: pass exactly one of id or ids, not both");
     }
+    if (args.ids !== undefined && args.board !== undefined) {
+        throw new Error("issue_get: board does not apply to the ids batch form — it resolves every id globally; drop board");
+    }
     const query = {};
     if (args.fields !== undefined && args.fields.length > 0) {
         query.fields = args.fields.join(",");
@@ -728,6 +752,24 @@ export async function issueAttach(client, args, deps = {}) {
 /* ── Plans: what a connected session may read and add to (DX-2683) ────────── */
 const PLANS_BASE_PATH = "/api/plans";
 const PLAN_SESSIONS_BASE_PATH = "/api/plan-sessions";
+/**
+ * DX-2727 — the plan_get field-group taxonomy: the ONE copy in this package
+ * (the `plan_get` zod enum in `index.ts` reads this const, and the type is
+ * derived from it). The published package cannot import server source at
+ * runtime, so it stays a literal; `__tests__/handlers.test.ts` imports the
+ * server's `src/issues/plan-field-groups.ts#PLAN_FIELD_GROUPS` and asserts
+ * the two are equal, so drift fails a test rather than a live call.
+ * `records` is the union of every kind; `records:<kind>` narrows to one.
+ */
+export const PLAN_FIELD_GROUPS = [
+    "cards",
+    "records",
+    "records:goal",
+    "records:rule",
+    "records:caveat",
+    "architecture",
+    "sessions",
+];
 /** Every plan, plus which one THIS session is connected to. */
 export async function planList(client) {
     return client.request({ method: "GET", path: "", basePath: PLANS_BASE_PATH });
@@ -744,6 +786,10 @@ export async function planGet(client, args = {}) {
     if (args.fields !== undefined && args.fields.length > 0) {
         query.fields = args.fields.join(",");
     }
+    if (args.cards_offset !== undefined)
+        query.cards_offset = args.cards_offset;
+    if (args.cards_limit !== undefined)
+        query.cards_limit = args.cards_limit;
     return client.request({
         method: "GET",
         path: args.plan_id === undefined ? "/mine" : `/${args.plan_id}/full`,

package/dist/index.js

@@ -88,7 +88,7 @@ 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 { issueAttach, issueChecklist, issueComment, issueCreate, issueDependency, issueEdit, issueGet, issueList, issueQualityGate, issueQualityGateVerdict, issueRequiresHuman, issueRetro, issueSolution, issueTransition, issueTriage, briefGetPage, briefList, briefSetPage, planAddArchitectureSection, planAddCard, planAddRecord, planConnect, planCreate, planDeleteArchitectureSection, planDeleteRecord, planGet, planGetArchitectureSection, planGetRecord, planList, planRemoveCard, planRename, planReorderArchitectureSection, planUpdateArchitectureSection, planUpdateRecord, repoKnowledgeGet, repoKnowledgeSet, } from "./handlers.js";
+import { issueAttach, issueChecklist, issueComment, issueCreate, issueDependency, issueEdit, issueGet, issueList, issueQualityGate, issueQualityGateVerdict, issueRequiresHuman, issueRetro, issueSolution, issueTransition, issueTriage, briefGetPage, briefList, briefSetPage, planAddArchitectureSection, planAddCard, planAddRecord, planConnect, planCreate, planDeleteArchitectureSection, planDeleteRecord, planGet, PLAN_FIELD_GROUPS, ISSUE_BATCH_GET_MAX, LIST_PAGE_MAX_LIMIT, PLAN_GET_CARDS_DEFAULT_LIMIT, planGetArchitectureSection, planGetRecord, planList, planRemoveCard, planRename, planReorderArchitectureSection, planUpdateArchitectureSection, planUpdateRecord, repoKnowledgeGet, repoKnowledgeSet, } from "./handlers.js";
 import { PRIORITY_TIER_WORDS } from "./priority.js";
 function readEnvOrDie(name) {
     const v = process.env[name];
@@ -231,18 +231,6 @@ const GET_FIELD_GROUPS = [
     "mirrors",
     "code_review_items",
 ];
-// DX-2727 — `plan_get`'s field-group taxonomy, hand-copied from
-// `src/issues/plan-field-groups.ts` (this package cannot import server
-// source). `records` is every kind; `records:<kind>` narrows to just one.
-const PLAN_FIELD_GROUPS = [
-    "cards",
-    "records",
-    "records:goal",
-    "records:rule",
-    "records:caveat",
-    "architecture",
-    "sessions",
-];
 const SORT_ORDERS = ["asc", "desc"];
 const sortField = z
     .array(z.object({
@@ -314,18 +302,19 @@ server.tool("issue_list", "List issues for the dispatch's board by default via G
         .optional()
         .describe("Opt-in field-GROUPS to add to the minimal default row: description (description + summary), solutions (solutions_count), ac, comments, retro, dependencies, triage, requires_human, assignment, quality_gates, children, effort. Absent/empty = minimal scalars only — no joins."),
     sort: sortField,
-    limit: z.number().int().positive().max(1000).optional(),
+    limit: z.number().int().positive().max(LIST_PAGE_MAX_LIMIT).optional(),
     offset: z.number().int().nonnegative().optional(),
     ...boardField,
 }, async (args) => jsonResult(await issueList(client, args)));
 // ---------------- issue_get ----------------
-server.tool("issue_get", "Fetch one card via GET /api/issues/:id, or MANY via GET /api/issues/batch?ids=... (DX-2727) — pass exactly one of `id` (single) or `ids` (batch, an array). Board-scoped for the single form; defaults to the dispatch's board. Issue ids are globally unique, so BOTH forms resolve from any dispatch regardless of `board` (the batch form ignores `board` entirely — it is a global, cross-board read). DEFAULT RESPONSE IS MINIMAL (DX-935 / DX-937) — only cheap scalar columns (id, type, title, status, parent_id, priority, created_at, updated_at, assigned_agent, content_hash — DX-2741, the card's optimistic-concurrency token; pass it back as `content_hash` on an `issue_edit` touching title/description/checklists); no joined collections. Pass `fields` to opt into named field-GROUPS, applied per card in the batch form too: description (full description body + the plain-language summary), solutions (the card's live candidate solutions, each with its content_hash, + every operator answer in decisions[]), ac (acceptance-criteria + checklists model), comments (comments[]), retro (retro good/bad/action_items/commits), dependencies (waiting_on/conflict_on/blocked gate state), triage (triage history + ICE), requires_human (the requires_human gate + steps), assignment (dispatch/assigned_agent/lifecycle timestamps), quality_gates (DX-1177 — one row per registered gate {gate, required, status pending|pass|fail, completed_at, message}; a required PRE gate not yet `pass` pre-empts the work dispatch, and `issue_transition complete` refuses while a required POST gate row != pass), children (child id list + rollups), mirrors (external mirror sync state), code_review_items (code-review findings). Point any heavy read at the matching `fields` entry rather than assuming it's already on the row. Single form: 404 envelope on unknown id. Batch form: returns `{issues: [...found cards...], not_found: [...ids that didn't resolve...]}` — an unknown or soft-deleted id never fails the whole call, it just lands in `not_found` alongside every card that DID resolve.", {
+server.tool("issue_get", "Fetch one card via GET /api/issues/:id, or MANY via GET /api/issues/batch?ids=... (DX-2727) — pass exactly one of `id` (single) or `ids` (batch, an array). Board-scoped for the single form; defaults to the dispatch's board. Issue ids are globally unique, so BOTH forms resolve from any dispatch regardless of `board`; the batch form is a global, cross-board read and REFUSES `board` (passing `ids` with `board` throws). The batch form takes at most " + ISSUE_BATCH_GET_MAX + " ids per call — split a larger set. DEFAULT RESPONSE IS MINIMAL (DX-935 / DX-937) — only cheap scalar columns (id, type, title, status, parent_id, priority, created_at, updated_at, assigned_agent, content_hash — DX-2741, the card's optimistic-concurrency token; pass it back as `content_hash` on an `issue_edit` touching title/description/checklists); no joined collections. Pass `fields` to opt into named field-GROUPS, applied per card in the batch form too: description (full description body + the plain-language summary), solutions (the card's live candidate solutions, each with its content_hash, + every operator answer in decisions[]), ac (acceptance-criteria + checklists model), comments (comments[]), retro (retro good/bad/action_items/commits), dependencies (waiting_on/conflict_on/blocked gate state), triage (triage history + ICE), requires_human (the requires_human gate + steps), assignment (dispatch/assigned_agent/lifecycle timestamps), quality_gates (DX-1177 — one row per registered gate {gate, required, status pending|pass|fail, completed_at, message}; a required PRE gate not yet `pass` pre-empts the work dispatch, and `issue_transition complete` refuses while a required POST gate row != pass), children (child id list + rollups), mirrors (external mirror sync state), code_review_items (code-review findings). Point any heavy read at the matching `fields` entry rather than assuming it's already on the row. Single form: 404 envelope on unknown id. Batch form: returns `{issues: [...found cards...], not_found: [...ids that didn't resolve...]}` — an unknown or soft-deleted id never fails the whole call, it just lands in `not_found` alongside every card that DID resolve.", {
     id: z.string().min(1).optional().describe("A single card id. Mutually exclusive with `ids`."),
     ids: z
         .array(z.string().min(1))
         .min(1)
+        .max(ISSUE_BATCH_GET_MAX)
         .optional()
-        .describe("Batch form (DX-2727): every requested id, resolved globally in ONE call. Mutually exclusive with `id`. Reports not_found per id rather than failing the whole call."),
+        .describe(`Batch form (DX-2727): every requested id (at most ${ISSUE_BATCH_GET_MAX}), resolved globally in ONE call. Mutually exclusive with \`id\`, and never combined with \`board\` (the batch is global; passing both throws). Reports not_found per id rather than failing the whole call.`),
     fields: z
         .array(z.enum(GET_FIELD_GROUPS))
         .optional()
@@ -660,7 +649,7 @@ server.tool("brief_set_page", 'Write one Brief page via PUT /api/brief/page?slug
 // 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.
 server.tool("plan_list", "List every plan via GET /api/plans (DX-2683), 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, and its cards may come from any repository. Returns `{ok, status, body: {plans: [{id, name, createdAt, cardCount, boards}], session, sessionListenerAttached}}`. `session` is your own registration — `{sessionId, title, planId, planName, firstSeenAt, lastActiveAt}` — or `null` if this process is not running inside a Claude Code session. A `planId` of null means you are connected to no plan: read any plan with `plan_get`, then `plan_connect` to the one you are working on (or ask the operator to connect you from the Plans list). `sessionListenerAttached` says whether your event listener is running: `false` while connected to a plan means you will NOT hear about its cards — call `plan_connect` again and arm the Monitor it returns. NOTE this is NOT the board Brief (`brief_list`), which is a different feature entirely.", {}, async () => jsonResult(await planList(client)));
-server.tool("plan_get", "Read a plan via GET /api/plans (DX-2683). Pass `plan_id` to read ANY plan (browsing another plan is useful and changes nothing); OMIT it to read the plan this session is connected to. Omitting it while connected to no plan fails loud with `{error: \"session_not_connected\"}` — connect first. A BARE call (no `fields`) returns ONLY the plan's cheap scalars: `{plan, boards, cardCount, bucketCounts, session, sessionListenerAttached, available_field_groups}` — no member cards, no goals/rules/caveats, no architecture body. Pass `fields` to opt into the rest, one call at a time: `cards` (every member card, capped at 200 with `cards_total` reporting the true count so a truncation is never silent), `records` (every goal+rule+caveat, keyed by kind) or `records:goal` / `records:rule` / `records:caveat` (just that one kind — cheaper than the full union), `architecture` (`{sections: [{id, planId, contentHash, title, content, sortOrder, createdAt, updatedAt}]}`), `sessions` (every session connected to the plan). `session`/`sessionListenerAttached` (your own connection state) and `available_field_groups` ride EVERY response, gated or not. `sessionListenerAttached: false` while connected means your event listener is not running; call `plan_connect` again and arm the Monitor it returns. ALWAYS `plan_get`/`plan_get_architecture_section` immediately before `plan_update_architecture_section`/`plan_delete_architecture_section` and pass the returned `contentHash` back as `base_hash`.", {
+server.tool("plan_get", "Read a plan via GET /api/plans (DX-2683). Pass `plan_id` to read ANY plan (browsing another plan is useful and changes nothing); OMIT it to read the plan this session is connected to. Omitting it while connected to no plan fails loud with `{error: \"session_not_connected\"}` — connect first. A BARE call (no `fields`) returns ONLY the plan's cheap scalars: `{plan, boards, cardCount, bucketCounts, session, sessionListenerAttached, available_field_groups}` — no member cards, no goals/rules/caveats, no architecture body. Pass `fields` to opt into the rest, one call at a time: `cards` (member cards, PAGED: `cards_offset` (default 0) and `cards_limit` (1.." + LIST_PAGE_MAX_LIMIT + ", default " + PLAN_GET_CARDS_DEFAULT_LIMIT + ") pick the page, in card-reference order (board prefix, then card number — stable while cards are edited, so pages never repeat or skip a card unless the plan's membership changes between reads), and the response carries `cards_total` and `cards_offset` — page with cards_offset while cards_offset + cards.length < cards_total; either paging arg without `fields: [\"cards\"]` is a 400), `records` (every goal+rule+caveat, keyed by kind) or `records:goal` / `records:rule` / `records:caveat` (just that one kind — cheaper than the full union), `architecture` (`{sections: [{id, planId, contentHash, title, content, sortOrder, createdAt, updatedAt}]}`), `sessions` (every session connected to the plan). `session`/`sessionListenerAttached` (your own connection state) and `available_field_groups` ride EVERY response, gated or not. `sessionListenerAttached: false` while connected means your event listener is not running; call `plan_connect` again and arm the Monitor it returns. ALWAYS `plan_get`/`plan_get_architecture_section` immediately before `plan_update_architecture_section`/`plan_delete_architecture_section` and pass the returned `contentHash` back as `base_hash`.", {
     plan_id: z
         .number()
         .int()
@@ -671,6 +660,19 @@ server.tool("plan_get", "Read a plan via GET /api/plans (DX-2683). Pass `plan_id
         .array(z.enum(PLAN_FIELD_GROUPS))
         .optional()
         .describe("Opt-in field-GROUPS: cards, records (every kind) or records:goal/records:rule/records:caveat (one kind), architecture, sessions. Absent/empty = cheap scalars only (plan, boards, cardCount, bucketCounts) plus session state."),
+    cards_offset: z
+        .number()
+        .int()
+        .nonnegative()
+        .optional()
+        .describe("Where the `cards` page starts (default 0). Requires `fields` to include `cards`. Page with cards_offset while cards_offset + cards.length < cards_total."),
+    cards_limit: z
+        .number()
+        .int()
+        .positive()
+        .max(LIST_PAGE_MAX_LIMIT)
+        .optional()
+        .describe("How many cards one page holds, 1.." + LIST_PAGE_MAX_LIMIT + " (default " + PLAN_GET_CARDS_DEFAULT_LIMIT + "). Requires `fields` to include `cards`."),
 }, async (args) => jsonResult(await planGet(client, args)));
 server.tool("plan_create", "Create a new, empty plan via POST /api/plans (DX-2531). GLOBAL — a plan is not board-scoped, and this call adds no cards, no records, and no architecture sections; it does NOT connect any session to the new plan (call `plan_connect` separately, exactly as adding a card to a plan is its own separate step). Returns `{ok, status, body: {plan: {id, name, createdAt}}}`. Use the returned `plan.id` with `plan_connect` to start working on it, or with `plan_get({plan_id})` to browse it.", {
     name: z.string().min(1).describe("The plan's name — shown in the Plans list."),

package/package.json

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