@thehammer/danx-dashboard-mcp 0.1.31 → 0.1.32

package/dist/handlers.js

@@ -24,45 +24,40 @@
 import { readFile } from "node:fs/promises";
 import { basename, extname, isAbsolute } from "node:path";
 import { resolvePriority } from "./priority.js";
+/**
+ * `filter`/`fields`/`sort` are JSON/CSV-encoded onto the query string (the
+ * route parses `?filter=<JSON>`, `?fields=a,b`, `?sort=<JSON>` — see
+ * `src/issues/read/reader.ts#parseEnvelope`); each is omitted entirely when
+ * empty so the wire carries no `{}`/`[]` noise. `board` stays a flat
+ * top-level param, resolved by the HTTP client exactly as before.
+ */
 export async function issueList(client, args) {
-    // status_derived is display-only on the server but the route accepts
-    // it as a projection filter — passthrough verbatim. parent_id=null is
-    // the legitimate "root cards only" filter; the server reader treats
-    // the literal string "null" identically.
     const query = {};
-    if (args.type !== undefined)
-        query.type = args.type;
-    if (args.parent_id !== undefined) {
-        query.parent_id = args.parent_id === null ? "null" : args.parent_id;
+    if (args.filter !== undefined && Object.keys(args.filter).length > 0) {
+        query.filter = JSON.stringify(args.filter);
+    }
+    if (args.fields !== undefined && args.fields.length > 0) {
+        query.fields = args.fields.join(",");
     }
-    if (args.dispatchable_derived !== undefined) {
-        query.dispatchable_derived = args.dispatchable_derived;
+    if (args.sort !== undefined && args.sort.length > 0) {
+        query.sort = JSON.stringify(args.sort);
     }
-    if (args.assigned_agent !== undefined)
-        query.assigned_agent = args.assigned_agent;
-    if (args.include_closed !== undefined)
-        query.include_closed = args.include_closed;
-    if (args.status_derived !== undefined)
-        query.status_derived = args.status_derived;
-    if (args.q !== undefined)
-        query.q = args.q;
     if (args.limit !== undefined)
         query.limit = args.limit;
     if (args.offset !== undefined)
         query.offset = args.offset;
-    // DX-1163 — the agent surface is lean by default: opt the route into the
-    // `IssueListRowLeanV2` projection (id/type/title/status/parent_id/
-    // assigned_agent/children-ids/priority). The SPA omits this and keeps the
-    // rich board row; `issue_get` still returns the full card body.
-    query.lean = true;
     // DX-1171 — board-only: forward the qualified board id, no repo.
     return client.request({ method: "GET", path: "", query, board: args.board });
 }
-// ---------------- issue_get ----------------
 export async function issueGet(client, args) {
+    const query = {};
+    if (args.fields !== undefined && args.fields.length > 0) {
+        query.fields = args.fields.join(",");
+    }
     return client.request({
         method: "GET",
         path: `/${encodeURIComponent(args.id)}`,
+        query,
         board: args.board,
     });
 }

package/dist/index.js

@@ -127,6 +127,36 @@ const EFFORT_VALUES = [
 ];
 const ISSUE_TYPES = ["Epic", "Bug", "Feature", "Story", "Chore"];
 const NON_EPIC_TYPES = ["Bug", "Feature", "Story", "Chore"];
+// DX-935 / DX-937 — field-group taxonomy for the nested read envelope,
+// hand-copied from `src/issues/read/field-groups.ts` (LIST_GROUPS / GET_GROUPS
+// — this package cannot import server source). Drift surfaces at runtime as a
+// server 400, not silently.
+const LIST_FIELD_GROUPS = [
+    "description",
+    "ac",
+    "comments",
+    "retro",
+    "dependencies",
+    "triage",
+    "requires_human",
+    "assignment",
+    "quality_gates",
+    "children",
+    "effort",
+];
+const GET_FIELD_GROUPS = [
+    ...LIST_FIELD_GROUPS,
+    "mirrors",
+    "code_review_items",
+];
+const SORT_ORDERS = ["asc", "desc"];
+const sortField = z
+    .array(z.object({
+    column: z.string().min(1),
+    order: z.enum(SORT_ORDERS),
+}))
+    .optional()
+    .describe("Multi-column sort — ordered list of {column, order}. Absent → the server's default order (priority desc, repo_name asc, with a numeric-id tiebreaker always appended).");
 // DX-1290 — the uniform 4-state checklist-item status. Terminal = passing|cancelled.
 const CHECKLIST_ITEM_STATUSES = [
     "incomplete",
@@ -162,21 +192,37 @@ const boardField = {
         .describe("Target another board by its qualified id `<repo>:<slug>` (e.g. `platform:the-supply-operations-hub`); omit to use this dispatch's board. Unknown board → 404."),
 };
 // ---------------- issue_list ----------------
-server.tool("issue_list", "List issues for the dispatch's board by default via GET /api/issues. Board-scoped; defaults to the dispatch's board. Pass `board` (a qualified id `<repo>:<slug>`) to list another board instead (unknown board → 404). Filters: q (free-text search matched case-insensitively over title + description — use this to find cards by keyword), type, parent_id (string id, null for root-only), dispatchable_derived (boolean — server-computed pickup-ready gate), assigned_agent, include_closed (default false — excludes completed_at/cancelled_at). Returns ALL matching cards (no row cap unless you pass limit). Response body shape: {issues: Issue[]} — LEAN agent rows (DX-1163): each row carries ONLY {id, type, title, status, parent_id, assigned_agent, children (ids), priority}. UI-only board fields (children_detail, counts, triage_ice_total, blocked_descendants, conflict_on, child_assignments, requires_human_child_count, latest_work_dispatch, primary_attachment) and the `description` body are NOT included — call issue_get for the full card. Server-side numeric-suffix ordering so DX-10 follows DX-9. Use this instead of grepping .danxbot/issues/ — the DB-backed route is the source of truth post-DX-704.", {
-    q: z.string().optional(),
-    status_derived: z.string().optional(),
-    type: z.enum(ISSUE_TYPES).optional(),
-    parent_id: z.string().nullable().optional(),
-    dispatchable_derived: z.boolean().optional(),
-    assigned_agent: z.string().optional(),
-    include_closed: z.boolean().optional(),
+server.tool("issue_list", "List issues for the dispatch's board by default via GET /api/issues. Board-scoped; defaults to the dispatch's board. Pass `board` (a qualified id `<repo>:<slug>`) to list another board instead (unknown board → 404). Nested envelope (DX-935 / DX-937 — hard-cut, no flat params): `filter` — the OLD flat filters, now nested (type, parent_id, dispatchable_derived, status_derived[], self_dispatchable_derived, assigned_agent, include_closed, include_deleted, and `q` — free-text over id+title+description, the former standalone `q` param now lives at `filter.q`). `fields` — opt-in named field-GROUPS (description, ac, comments, retro, dependencies, triage, requires_human, assignment, quality_gates, children, effort); THE DEFAULT RESPONSE (no `fields`) IS MINIMAL — only cheap scalar columns (id, type, title, status, parent_id, priority, created_at, updated_at, assigned_agent), zero joins. Point any heavy read (full description, comments[], retro, ac items, dependency edges, triage history, quality-gate rows, children ids) at the matching `fields` entry rather than assuming it's already on the row. `sort` — ordered [{column, order}] (id|priority|repo_name|title|type|status_derived|triage_ice_total|created_at|updated_at); absent → default order (priority desc, repo_name asc) with an always-appended numeric-id tiebreaker (DX-10 follows DX-9). `limit`/`offset` — optional paging (no cap by default). Use issue_get for a single fully-detailed card.", {
+    filter: z
+        .object({
+        q: z.string().optional(),
+        type: z.enum(ISSUE_TYPES).optional(),
+        parent_id: z.string().nullable().optional(),
+        dispatchable_derived: z.boolean().optional(),
+        status_derived: z.array(z.string()).optional(),
+        self_dispatchable_derived: z.boolean().optional(),
+        assigned_agent: z.string().optional(),
+        include_closed: z.boolean().optional(),
+        include_deleted: z.boolean().optional(),
+    })
+        .optional()
+        .describe("Nested list filters (DX-935) — the hard-cut replacement for the old flat top-level params, including the former standalone `q` (now `filter.q`). Omit entirely for no filtering."),
+    fields: z
+        .array(z.enum(LIST_FIELD_GROUPS))
+        .optional()
+        .describe("Opt-in field-GROUPS to add to the minimal default row: description, 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(),
     offset: z.number().int().nonnegative().optional(),
     ...boardField,
 }, async (args) => jsonResult(await issueList(client, args)));
 // ---------------- issue_get ----------------
-server.tool("issue_get", 'Fetch a single hydrated 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`. Returns the full card (every joined child collection: ac [the 2-state facade onto the default "Acceptance Criteria" checklist] + checklists [DX-1290: the full named-checklist model — each {name, items:[{label, detail, status: incomplete|failing|passing|cancelled}]}], comments, dependencies, requires_human steps, retro action items + commits, triage history, quality_gates — DX-1177: one row per registered quality gate {gate, required, status pending|pass|fail, completed_at, message}; a required PRE gate not yet `pass` pre-empts the work dispatch with the gate reviewer, and `issue_transition complete` refuses while a required POST gate row != pass) plus the ancestor chain walked via parent_id. 404 envelope on unknown id.', {
+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); no joined collections. Pass `fields` to opt into named field-GROUPS: description (full description body), 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),
+    fields: z
+        .array(z.enum(GET_FIELD_GROUPS))
+        .optional()
+        .describe("Opt-in field-GROUPS to add to the minimal default row: description, ac, comments, retro, dependencies, triage, requires_human, assignment, quality_gates, children, mirrors, code_review_items. Absent/empty = minimal scalars only."),
     ...boardField,
 }, async (args) => jsonResult(await issueGet(client, args)));
 // ---------------- issue_create ----------------

package/package.json

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