@thehammer/danx-dashboard-mcp 0.1.149 → 0.1.150

package/README.md

@@ -22,7 +22,8 @@ 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, 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_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` (DX-3426) opts in via a recursive field TREE — `{"description": true, "problems": {"solutions": true}, "comments": {"limit": 10}}` — not a flat group list; a cursor-paged relation (today only `comments`) takes its page args (`limit`/`before`) inside its own nested object, so paging now works on the batch form too. See `resource_fields` |
+| `resource_fields` | `GET /api/resources/:resource/fields` | DX-3426 — what an `issue_get`-style field tree may name for one resource: `{resource, description, always, hashes, fields, relations}`. Install-global, no `board`. `resource: "issue"` is the root; a relation's own `resource` in the response is what to call this again with, one level deeper |
 | `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. `block` is a dispatch hold only — it never marks the card as needing a human; use `issue_problem` add for that |

package/dist/entrypoint.test.js

@@ -0,0 +1,43 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { mkdtempSync, writeFileSync, symlinkSync, rmSync, realpathSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { isEntrypointModule } from "./entrypoint.js";
+describe("isEntrypointModule (DX-1647)", () => {
+    let dir;
+    let real;
+    let link;
+    beforeAll(() => {
+        dir = mkdtempSync(join(tmpdir(), "entrypoint-test-"));
+        real = join(dir, "index.js");
+        writeFileSync(real, "// stub entry\n");
+        link = join(dir, "danx-dashboard-mcp"); // mimics node_modules/.bin symlink
+        symlinkSync(real, link);
+    });
+    afterAll(() => {
+        rmSync(dir, { recursive: true, force: true });
+    });
+    // import.meta.url always reports the module REALPATH — model that here.
+    const moduleUrl = () => pathToFileURL(realpathSync(real)).href;
+    it("true when argv[1] is the real file (direct `node index.js`)", () => {
+        expect(isEntrypointModule(moduleUrl(), real)).toBe(true);
+    });
+    it("true when argv[1] is a SYMLINK to the file (npx / global bin) — the fleet regression", () => {
+        // The symlink path !== the realpath, but the entrypoint MUST still be
+        // detected, or npx imports the module and exits without booting the server.
+        expect(link).not.toBe(realpathSync(link));
+        expect(isEntrypointModule(moduleUrl(), link)).toBe(true);
+    });
+    it("false when argv[1] is undefined (module imported, not run as bin)", () => {
+        expect(isEntrypointModule(moduleUrl(), undefined)).toBe(false);
+    });
+    it("false when argv[1] is an empty string", () => {
+        expect(isEntrypointModule(moduleUrl(), "")).toBe(false);
+    });
+    it("false when argv[1] points at a different real file", () => {
+        const other = join(dir, "other.js");
+        writeFileSync(other, "// other\n");
+        expect(isEntrypointModule(moduleUrl(), other)).toBe(false);
+    });
+});

package/dist/field-tree.js

@@ -0,0 +1,35 @@
+/**
+ * DX-3426 — the shared recursive FIELD-TREE shape.
+ *
+ * The dashboard's single-card and batch card reads (`issue_get` today;
+ * `issue_list` / `plan_get` in later cards, per DX-3426's own follow-up scope)
+ * take a nested JSON tree instead of a flat field-GROUP list: each key names a
+ * field or relation of the resource at that level, and each value is either
+ * `true` (the field, or a relation's child with its default fields), a
+ * non-negative integer (a cursor-paged relation's own page ARGUMENT — e.g.
+ * `{"comments": {"limit": 10, "before": 812}}`, where `limit`/`before` are
+ * themselves plain integer values inside the nested object), or another
+ * field tree (a relation's child with a NAMED field selection). Example:
+ *
+ *   {"description": true, "ac": true, "problems": {"solutions": {"steps": true}, "decisions": true}, "comments": {"limit": 10}}
+ *
+ * One schema, one module — every tool that accepts a field tree imports THIS
+ * export rather than redeclaring the shape, so the recursion is defined once
+ * and every caller's JSON Schema serializes the same way. `z.lazy` is
+ * required because the schema refers to itself; `zod-to-json-schema` (the
+ * MCP SDK's own zod v3 → JSON Schema converter, see
+ * `@modelcontextprotocol/sdk`'s `zod-json-schema-compat.ts`) resolves that
+ * self-reference to a local `$ref` rather than unrolling it infinitely —
+ * verified directly against the listed tool schema in
+ * `__tests__/tool-defs.test.ts`, not assumed from reading the library's
+ * source. `issue_solution`'s pre-existing `steps` field (DX-3310) is the
+ * same `z.lazy` self-reference pattern already shipping on this server.
+ */
+import { z } from "zod";
+/**
+ * The shared schema. A record whose values are `true`, a non-negative
+ * integer, or the same schema recursively — generic on purpose (no
+ * issue-specific field names baked in here) so `issue_list` / `plan_get` can
+ * reuse it unchanged in their own later cards.
+ */
+export const fieldTreeSchema = z.lazy(() => z.record(z.union([z.literal(true), z.number().int().nonnegative(), fieldTreeSchema])));

package/dist/handlers.js

@@ -95,16 +95,15 @@ export async function issueGet(client, args) {
     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");
     }
-    // DX-3321 — comments paging is a SINGLE-id-route feature
-    // (`GET /api/issues/:id?comments_limit=&comments_offset=`); the batch
-    // route has no per-card paging at all. Refuse rather than silently drop,
-    // same as the `ids` + `board` refusal just above.
-    if (args.ids !== undefined && (args.comments_limit !== undefined || args.comments_offset !== undefined)) {
-        throw new Error("issue_get: comments_limit/comments_offset do not apply to the ids batch form — it has no per-card comment paging; drop them or use the single-id form");
-    }
     const query = {};
-    if (args.fields !== undefined && args.fields.length > 0) {
-        query.fields = args.fields.join(",");
+    // DX-3426 — the tree travels as ONE JSON-encoded query param (mirrors how
+    // `issue_list`'s `filter`/`sort` envelopes already ride the wire above),
+    // rather than the old CSV-of-group-names. Sent on both the single and
+    // batch forms — comment paging (or any other relation argument) now lives
+    // INSIDE the tree, so there is nothing left for the old ids+comments_*
+    // refusal to guard against.
+    if (args.fields !== undefined && Object.keys(args.fields).length > 0) {
+        query.fields = JSON.stringify(args.fields);
     }
     if (args.ids !== undefined) {
         if (args.ids.length === 0) {
@@ -118,10 +117,6 @@ export async function issueGet(client, args) {
     if (args.id === undefined) {
         throw new Error("issue_get: pass exactly one of id or ids");
     }
-    if (args.comments_limit !== undefined)
-        query.comments_limit = args.comments_limit;
-    if (args.comments_offset !== undefined)
-        query.comments_offset = args.comments_offset;
     return client.request({
         method: "GET",
         path: `/${encodeURIComponent(args.id)}`,
@@ -1723,3 +1718,20 @@ export async function dispatchTranscriptSearch(client, args) {
         },
     };
 }
+// ---------------- resource_fields (DX-3426) ----------------
+const RESOURCES_BASE_PATH = "/api/resources";
+/**
+ * `GET /api/resources/:resource/fields` — what a field TREE (`issue_get`'s
+ * `fields`, and any later tool built on the same shape) may name for ONE
+ * resource: `{resource, description, always, hashes, fields, relations}`.
+ * Install-global (no `board` — mirrors `failure_category_list`'s own
+ * board-less rationale just above: nothing server-side would read one).
+ * Unknown resource → 404 `unknown_resource`.
+ */
+export async function resourceFields(client, args) {
+    return client.request({
+        method: "GET",
+        path: `/${encodeURIComponent(args.resource)}/fields`,
+        basePath: RESOURCES_BASE_PATH,
+    });
+}

package/dist/index.js

@@ -12,7 +12,11 @@
  * through the workspace `mcp.template.json`):
  *
  *   - issue_list             GET    /api/issues
- *   - issue_get              GET    /api/issues/:id | /api/issues/batch (DX-2727 ids[] batch)
+ *   - issue_get              GET    /api/issues/:id | /api/issues/batch (DX-2727 ids[] batch;
+ *                            DX-3426 `fields` is a recursive field TREE, not a flat group list —
+ *                            see `resource_fields` below and `./field-tree.ts`)
+ *   - resource_fields        GET    /api/resources/:resource/fields (DX-3426 — what `fields` may
+ *                            name for a resource; install-global, no `board`)
  *   - issue_create           POST   /api/issues
  *   - issue_edit             PATCH  /api/issues/:id/edit
  *   - issue_transition       POST   /api/issues/:id/transition
@@ -106,8 +110,9 @@ 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, issueProblem, issueQualityGate, issueQualityGateVerdict, issueRetireBranch, issueRetro, issueSolution, issueTransition, issueTriage, briefGetPage, briefList, briefSetPage, failureCategoryCreate, failureCategoryList, failureCategoryUpdate, dispatchTranscriptSearch, planAddArchitectureSection, planAddCard, planAddNote, planAddRecord, planConnect, planCreate, planDeleteArchitectureSection, planDeleteNote, planDeleteRecord, planGet, PLAN_FIELD_GROUPS, PLAN_EVENT_KINDS, PLAN_EVENT_ORIGINS, PLAN_STATUSES, ISSUE_BATCH_GET_MAX, LIST_PAGE_MAX_LIMIT, PLAN_GET_CARDS_DEFAULT_LIMIT, PLAN_GET_EVENTS_DEFAULT_LIMIT, PLAN_GET_EVENTS_MAX_LIMIT, planGetArchitectureSection, planGetRecord, planList, planRemoveCard, planRename, planReorderArchitectureSection, planUpdateArchitectureSection, planUpdateNote, planUpdateRecord, repoKnowledgeGet, repoKnowledgeSet, qualityGateInstruction, } from "./handlers.js";
+import { issueAttach, issueChecklist, issueComment, issueCreate, issueDependency, issueEdit, issueGet, issueList, issueProblem, issueQualityGate, issueQualityGateVerdict, issueRetireBranch, issueRetro, issueSolution, issueTransition, issueTriage, briefGetPage, briefList, briefSetPage, failureCategoryCreate, failureCategoryList, failureCategoryUpdate, dispatchTranscriptSearch, planAddArchitectureSection, planAddCard, planAddNote, planAddRecord, planConnect, planCreate, planDeleteArchitectureSection, planDeleteNote, planDeleteRecord, planGet, PLAN_FIELD_GROUPS, PLAN_EVENT_KINDS, PLAN_EVENT_ORIGINS, PLAN_STATUSES, ISSUE_BATCH_GET_MAX, LIST_PAGE_MAX_LIMIT, PLAN_GET_CARDS_DEFAULT_LIMIT, PLAN_GET_EVENTS_DEFAULT_LIMIT, PLAN_GET_EVENTS_MAX_LIMIT, planGetArchitectureSection, planGetRecord, planList, planRemoveCard, planRename, planReorderArchitectureSection, planUpdateArchitectureSection, planUpdateNote, planUpdateRecord, repoKnowledgeGet, repoKnowledgeSet, qualityGateInstruction, resourceFields, } from "./handlers.js";
 import { PRIORITY_TIER_WORDS } from "./priority.js";
+import { fieldTreeSchema } from "./field-tree.js";
 function readEnvOrDie(name) {
     const v = process.env[name];
     if (typeof v !== "string" || v === "") {
@@ -272,10 +277,11 @@ const EFFORT_VALUES = [
 // still be CREATED through this MCP.
 const ISSUE_TYPES = ["Epic", "Bug", "Feature", "Story", "Chore", "Task"];
 const NON_EPIC_TYPES = ["Bug", "Feature", "Story", "Chore", "Task"];
-// 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.
+// DX-935 / DX-937 — field-group taxonomy for the LIST read envelope,
+// hand-copied from `src/issues/read/field-groups.ts` (`LIST_GROUPS` — this
+// package cannot import server source). Drift surfaces at runtime as a server
+// 400, not silently. DX-3426 moved `issue_get` to the field tree
+// (`field-tree.ts`); DX-3427 moves the list the same way and deletes this.
 const LIST_FIELD_GROUPS = [
     "description",
     // DX-2735: replaced the flat "solutions" group (hard cut, no alias).
@@ -290,13 +296,6 @@ const LIST_FIELD_GROUPS = [
     "children",
     "effort",
 ];
-const GET_FIELD_GROUPS = [
-    ...LIST_FIELD_GROUPS,
-    "mirrors",
-    "code_review_items",
-    // DX-2835 — every plan this card is on ({id, ref, name}[]), detail only.
-    "plans",
-];
 const SORT_ORDERS = ["asc", "desc"];
 const sortField = z
     .array(z.object({
@@ -393,33 +392,27 @@ strictTool("issue_list",
 }, async (args) => jsonResult(await issueList(client, args)));
 // ---------------- issue_get ----------------
 strictTool("issue_get", 
-// DX-2735: trimmed to pay for the problem tools inside the work-profile
-// injected-surface budget — same facts, no repeated prose.
-"Fetch one card (`id`) or many (`ids`, at most " + ISSUE_BATCH_GET_MAX + " — split larger sets); pass exactly one. Ids are globally unique, so both resolve from any board; the batch form is global and throws with `board`. THE DEFAULT ROW IS MINIMAL — scalars only (id, type, title, status, parent_id, priority, created_at, updated_at, assigned_agent, content_hash: the concurrency token issue_edit needs for title/description/checklists). `fields` opts into groups, per card in a batch too: description (body + summary), problems (live problems in order, each {id, statement, content_hash, open} with its solutions[] and decisions[] — a card needs a human exactly when open_problem_count > 0), ac (acceptance criteria + checklists), comments (paged via `comments_limit`/`comments_offset` — see their own field descriptions, single-id form only), retro, dependencies (waiting_on/conflict_on/blocked), triage (history + ICE), assignment (dispatch, assigned_agent, lifecycle timestamps), quality_gates (one row per gate {gate, required, status pending|pass|fail, completed_at, message}; a required PRE gate not `pass` pre-empts the work dispatch, and complete refuses while a required POST gate is not `pass`), children (ids + rollups), mirrors (external sync state), code_review_items, plans (every plan this card is on, `{id, ref, name}[]` via `plan_cards` — `ref` is the plan's `PLN-<id>`). Within a `comments` page, comments are ordered CHRONOLOGICALLY (oldest first) — only the requested WINDOW is anchored at the newest end, not the array itself; naming `comments_limit`/`comments_offset` alongside `ids` (the batch form) is refused. Single form: unknown id → 404. Batch form: `{issues: [...], not_found: [...ids]}` — an unknown or deleted id never fails the call.", {
+// DX-3426: field GROUPS replaced by a recursive field TREE (see
+// `./field-tree.ts`) — comment paging now lives INSIDE the tree (a
+// cursor-paged relation, today only `comments`, takes `limit`/`before` in
+// its own nested object) instead of top-level `comments_limit`/
+// `comments_offset`, which is also why the old "ids + comments_* refused"
+// rule is gone: paging is per-relation now, so it works on the batch form
+// too. Kept compact — call `resource_fields({resource:"issue"})` for the
+// full, current list of what `fields` may name, rather than enumerating it
+// here (it would drift the moment a field/relation is added or removed).
+"Fetch one card (`id`) or many (`ids`, at most " + ISSUE_BATCH_GET_MAX + " — split larger sets); pass exactly one. Ids are globally unique, so both resolve from any board; the batch form is global and throws with `board`. THE DEFAULT ROW IS THE ALWAYS-ON FIELDS ONLY — identity, lifecycle stamps, derived status/list/blocked, assigned_agent, and content_hash (the concurrency token issue_edit needs for title/description/checklists); every child hash is likewise always returned. `fields` opts into more, per card in a batch too: a JSON object tree — each key names a field or relation, each value is `true` (that field, or a relation's child with its default fields), a nested object (a relation's child with named fields), or on the cursor-paged `comments` relation the nested object may also carry `limit`/`before` (comment id) to page — e.g. `{\"description\": true, \"problems\": {\"solutions\": {\"steps\": true}}, \"comments\": {\"limit\": 10}}`; a paged response also carries `comments_page: {limit, total, next_cursor}` (`next_cursor` → pass back as `before` for the next older page, null = none). Call `resource_fields({resource:\"issue\"})` for exactly what may be requested (every field/relation name, each relation's own child resource, and its paging shape if any) — never guess a name. Unknown field/relation → 400 `unknown_field`; bad shape → 400 `invalid_fields`; bad `limit`/`before` → 400 `invalid_field_argument`; a field you lack permission for → 403 `forbidden_field`. Single form: unknown id → 404. Batch form: `{issues: [...], not_found: [...ids]}` — an unknown or deleted id never fails the call.", {
     id: z.string().min(1).optional(),
     ids: z.array(z.string().min(1)).min(1).max(ISSUE_BATCH_GET_MAX).optional(),
-    fields: z
-        .array(z.enum(GET_FIELD_GROUPS))
-        .optional()
-        .describe("Field groups to add; absent = minimal scalars."),
-    comments_limit: z
-        .number()
-        .int()
-        .positive()
-        .optional()
-        .describe("Single-id form only. How many comments the page holds (server default 20), the window anchored at the " +
-        "NEWEST comment. An out-of-range value (server max 200) is refused by the server with its own 400, " +
-        "never silently clamped here. Requires `fields:[\"comments\"]`."),
-    comments_offset: z
-        .number()
-        .int()
-        .nonnegative()
+    fields: fieldTreeSchema
         .optional()
-        .describe("Single-id form only. Skip this many of the newest comments before the page starts (default 0) — page " +
-        "forward while comments_offset + comments.length < comments_total to reach older comments. Requires " +
-        "`fields` to include `comments`."),
+        .describe("A field tree (see tool description); absent/empty = minimal scalars. `resource_fields({resource:\"issue\"})` names every valid key."),
     ...boardField,
 }, async (args) => jsonResult(await issueGet(client, args)));
+// ---------------- resource_fields ----------------
+strictTool("resource_fields", "DX-3426: what a field TREE (`issue_get`'s `fields`, and any later tool that takes one) may name for one resource — `{resource, description, always: string[], hashes: string[], fields: [{name, description}], relations: [{name, description, resource, paging?: {default_limit, max_limit, page_field}}]}`. `always`/`hashes` ride every response regardless of `fields` (never request them). A relation's `resource` names what to call this same tool with next, to go one level deeper. Install-global, not board-scoped. `resource: \"issue\"` is the root; unknown resource → 404 `unknown_resource`.", {
+    resource: z.string().min(1).describe('Resource name, e.g. "issue", or a relation\'s own `resource` from a prior call.'),
+}, async (args) => jsonResult(await resourceFields(client, args)));
 // ---------------- issue_create ----------------
 strictTool("issue_create", '`plan` is REQUIRED on every create — no default, no inference; see its own field description for the two values and the refusal. This replaces the plan_add_card follow-up at creation time; plan_add_card remains for putting an EXISTING card on a plan. ' +
     'Create a card. Board-scoped; see `board`. type=Epic REQUIRES non-empty phase_children[] (epic and phases inserted in one transaction; children get the epic as parent); other types refuse phase_children[] (400). Status starts at Review. `list_id` places the card straight into a column — a board_lists id or the list\'s display NAME (case-insensitive, emoji-tolerant): a `ready`-type queue lands it in ToDo, a `completed` list in Done, with no follow-up transition. Not valid on Epic; unknown name/id → 400. `quality_gates` adds gates beyond the board\'s type defaults (see its own field description); add one later with `issue_quality_gate`. ALWAYS pass `triage_enabled` explicitly on the root card and every phase child (see its own field description).', {

package/package.json

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