@thehammer/danx-dashboard-mcp 0.1.60 → 0.1.62

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` | Returns hydrated card + ancestor chain |
+| `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}` |
@@ -33,6 +33,10 @@ All exposed as `mcp__danx-dashboard__<name>` once wired through the workspace `m
 | `issue_requires_human` | `POST/DELETE /api/issues/:id/requires-human` | Set replaces step rows atomically; clear soft-deletes them. A successful set also returns `solutions_reminder: {solution_count, instruction}` |
 | `issue_retro` | `PUT /api/issues/:id/retro` | Requires terminal card; replace semantics |
 
+## `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` (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
 
 `plan_connect` connects the session to a plan AND returns `listener: {command, persistent: true, instruction}`. The agent arms `command` with Claude Code's Monitor tool (`persistent: true`); every line the command prints becomes a notification that wakes the session.

package/dist/handlers.js

@@ -49,11 +49,46 @@ 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;
+/**
+ * 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. 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(",");
     }
+    if (args.ids !== undefined) {
+        if (args.ids.length === 0) {
+            throw new Error("issue_get: ids must be a non-empty array");
+        }
+        query.ids = args.ids.join(",");
+        // DX-2727 — the batch route resolves globally, exactly like the
+        // single-id path (see its own doc comment): no `board` is forwarded.
+        return client.request({ method: "GET", path: "/batch", query });
+    }
+    if (args.id === undefined) {
+        throw new Error("issue_get: pass exactly one of id or ids");
+    }
     return client.request({
         method: "GET",
         path: `/${encodeURIComponent(args.id)}`,
@@ -704,21 +739,49 @@ 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 });
 }
 /**
- * One plan, entire — its cards, the boards they cover, its goals + rules +
- * caveats, its architecture sections, and the sessions working on it. ONE
- * call rather than five, which is what keeps this tool surface small enough
- * to be worth an agent's context.
+ * One plan — its cheap scalars by default, or opt into its cards, its goals
+ * + rules + caveats, its architecture sections, and the sessions working on
+ * it via `fields` (DX-2727). One call rather than several, which is what
+ * keeps this tool surface small enough to be worth an agent's context even
+ * once every part of a plan is opt-in rather than always-on.
  */
 export async function planGet(client, args = {}) {
+    const query = {};
+    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`,
         basePath: PLANS_BASE_PATH,
+        query,
     });
 }
 function readIssuedTicket(body) {

package/dist/index.js

@@ -12,7 +12,7 @@
  * through the workspace `mcp.template.json`):
  *
  *   - issue_list             GET    /api/issues
- *   - issue_get              GET    /api/issues/:id
+ *   - issue_get              GET    /api/issues/:id | /api/issues/batch (DX-2727 ids[] batch)
  *   - issue_create           POST   /api/issues
  *   - issue_edit             PATCH  /api/issues/:id/edit
  *   - issue_transition       POST   /api/issues/:id/transition
@@ -33,7 +33,7 @@
  *   - brief_get_page   GET    /api/brief/page (DX-2083 / DX-2484)
  *   - brief_set_page   PUT    /api/brief/page (DX-2083 / DX-2484)
  *   - plan_list              GET    /api/plans (DX-2683)
- *   - plan_get               GET    /api/plans/:id/full | /api/plans/mine
+ *   - plan_get               GET    /api/plans/:id/full | /api/plans/mine (DX-2727: bare = scalars only, fields= opts in)
  *   - plan_create            POST   /api/plans
  *   - plan_connect           POST   /api/plan-sessions/me/plan
  *   - plan_add_record        POST   /api/plans/mine/records
@@ -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, 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];
@@ -307,8 +307,14 @@ server.tool("issue_list", "List issues for the dispatch's board by default via G
     ...boardField,
 }, async (args) => jsonResult(await issueList(client, args)));
 // ---------------- issue_get ----------------
-server.tool("issue_get", "Fetch a single issue via GET /api/issues/:id. Board-scoped; defaults to the dispatch's board. Issue ids are globally unique, so this resolves from any dispatch regardless of `board`. 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: 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. 404 envelope on unknown id.", {
-    id: z.string().min(1),
+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 100 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 (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()
@@ -643,13 +649,30 @@ 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 one plan WHOLE via GET /api/plans (DX-2683) — its member cards (with the boards they cover), its goals, rules and caveats, its architecture sections, the sessions working on it, and your own session state. One call, not five. 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. Returns `{plan, cards, boards, records: {goal, rule, caveat} (each `[{id, ref, body, context, contentHash}]` — `context` is markdown detail or null), architecture: {sections: [{id, planId, contentHash, title, content, sortOrder, createdAt, updatedAt}]}, sessions, session, sessionListenerAttached}` — `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..1000, default 200) pick the page, 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()
         .positive()
         .optional()
         .describe("A plan id from `plan_list`. Omit to read the plan this session is connected to."),
+    fields: z
+        .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(1000)
+        .optional()
+        .describe("How many cards one page holds, 1..1000 (default 200). 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.60",
+  "version": "0.1.62",
   "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",