@thehammer/danx-dashboard-mcp 0.1.119 → 0.1.121

package/dist/handlers.js

@@ -96,6 +96,13 @@ 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(",");
@@ -112,6 +119,10 @@ 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)}`,
@@ -668,12 +679,13 @@ export async function issueProblem(client, args) {
     }
 }
 /**
- * One problem's candidate solutions via
- * `/api/issues/:id/problems/:pid/solutions[/:sid]` (DX-2735), action-dispatched
- * like `issue_checklist`. A missing required arg for the chosen action throws at
- * this boundary (no round-trip); the server's refusal envelopes
- * (`stale_solution` with the current row, a second recommendation on the same
- * problem, editing a chosen option, a solution id from another problem → 404)
+ * One problem's candidate solutions, AND (DX-3310) one solution's individual
+ * procedure steps, via `/api/issues/:id/problems/:pid/solutions[/:sid][/steps[/:stepId]]`
+ * — action-dispatched like `issue_checklist`. A missing required arg for the
+ * chosen action throws at this boundary (no round-trip); the server's
+ * refusal envelopes (`stale_solution`/`stale_step` with the current row, a
+ * second recommendation on the same problem, editing a chosen option, a
+ * solution/step id from the wrong scope → 404, nesting past depth 3 → 400)
  * pass through verbatim.
  *
  * There is deliberately NO answer action, on this tool or any other. Answering
@@ -697,11 +709,22 @@ export async function issueSolution(client, args) {
         case "add": {
             // DX-2735: the POST carries the CHECKED title, not a re-read of args.title.
             const title = need.string(args.title, "title");
+            // DX-3310 — omitted `steps` on add means "no steps", not "leave
+            // untouched" (there is nothing yet to leave untouched on a brand new
+            // solution) — sent through only when the caller actually supplied it,
+            // so an existing add-only caller that never heard of `steps` keeps
+            // creating exactly what it always created.
+            if (args.steps !== undefined)
+                content.steps = args.steps;
             return client.request({ method: "POST", path: base, body: { ...content, title }, board });
         }
         case "edit": {
             const solutionId = need.id(args.solution_id, "solution_id");
             const baseHash = need.string(args.base_hash, "base_hash");
+            // DX-3310 — omitted keeps the stored steps untouched; an explicit
+            // (including empty) array replaces them via the server's diff.
+            if (args.steps !== undefined)
+                content.steps = args.steps;
             return client.request({
                 method: "PATCH",
                 path: `${base}/${solutionId}`,
@@ -719,6 +742,42 @@ export async function issueSolution(client, args) {
                 board,
             });
         }
+        // DX-3310 (AC 35250) — granular single-step CUD, so changing one step
+        // never requires resending the whole `steps` tree.
+        case "add_step": {
+            const solutionId = need.id(args.solution_id, "solution_id");
+            const title = need.string(args.title, "title");
+            const body = { title };
+            if (args.description !== undefined)
+                body.description = args.description;
+            if (args.parent_step_id !== undefined)
+                body.parent_step_id = args.parent_step_id;
+            if (args.position !== undefined)
+                body.position = args.position;
+            return client.request({ method: "POST", path: `${base}/${solutionId}/steps`, body, board });
+        }
+        case "edit_step": {
+            const solutionId = need.id(args.solution_id, "solution_id");
+            const stepId = need.id(args.step_id, "step_id");
+            const baseHash = need.string(args.base_hash, "base_hash");
+            const body = { base_hash: baseHash };
+            if (args.title !== undefined)
+                body.title = args.title;
+            if (args.description !== undefined)
+                body.description = args.description;
+            return client.request({ method: "PATCH", path: `${base}/${solutionId}/steps/${stepId}`, body, board });
+        }
+        case "remove_step": {
+            const solutionId = need.id(args.solution_id, "solution_id");
+            const stepId = need.id(args.step_id, "step_id");
+            const baseHash = need.string(args.base_hash, "base_hash");
+            return client.request({
+                method: "DELETE",
+                path: `${base}/${solutionId}/steps/${stepId}`,
+                body: { base_hash: baseHash },
+                board,
+            });
+        }
     }
 }
 /**

package/dist/index.js

@@ -20,7 +20,7 @@
  *   - issue_comment          POST/PATCH/DELETE /api/issues/:id/comments[/:cid]
  *   - issue_checklist        POST/PATCH/DELETE /api/issues/:id/checklists[/:cid[/items[/:iid]]]
  *   - issue_problem          GET/POST/PATCH/DELETE /api/issues/:id/problems[/:pid] (DX-2735)
- *   - issue_solution         POST/PATCH/DELETE /api/issues/:id/problems/:pid/solutions[/:sid] (DX-2735)
+ *   - issue_solution         POST/PATCH/DELETE /api/issues/:id/problems/:pid/solutions[/:sid][/steps[/:stepId]] (DX-2735, steps DX-3310)
  *   - issue_dependency       POST/DELETE /api/issues/:id/dependencies[/:did]
  *   - issue_retire_branch    POST   /api/issues/:id/card-branch-retire (DX-2845)
  *   - issue_quality_gate     POST   /api/issues/:id/quality-gates/:gate
@@ -384,13 +384,29 @@ strictTool("issue_list",
 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 (GET /api/issues/:id, `id`) or many (GET /api/issues/batch, `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, 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>`). Single form: unknown id → 404. Batch form: `{issues: [...], not_found: [...ids]}` — an unknown or deleted id never fails the call.", {
+"Fetch one card (GET /api/issues/:id, `id`) or many (GET /api/issues/batch, `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 (see `comments_limit`/`comments_offset` below), 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>`). The `comments` group returns a PAGE ANCHORED AT THE NEWEST COMMENT: `comments_offset` counts back from the newest comment (offset 0 = the most recent comments_limit comments), and `comments_total` is the card's real total comment count, so `comments_offset + comments.length < comments_total` means older comments remain — page forward with `comments_offset` to reach them; a long-running card's decisive history (what was tried, measured, rejected or reverted) often lives past the first page. WITHIN a page, comments are ordered CHRONOLOGICALLY (oldest first, newest last) — the same order every other comment read in this API uses; only the WINDOW you request is anchored at the newest end, not the array itself. `comments_limit`/`comments_offset` apply to the SINGLE-id form only (no per-card paging in the batch form — naming either alongside `ids` is refused). 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` to include `comments`."),
+    comments_offset: z
+        .number()
+        .int()
+        .nonnegative()
+        .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`."),
     ...boardField,
 }, async (args) => jsonResult(await issueGet(client, args)));
 // ---------------- issue_create ----------------
@@ -610,7 +626,7 @@ const SOLUTION_FIELDS = {
     con: z.string().optional(),
     recommended: z.boolean().optional(),
 };
-strictTool("issue_problem", "A card's PROBLEMS via /api/issues/:id/problems[/:pid]: one statement the operator must resolve (a question, or a flaw in the plan) OR an action only a person can carry out, each with its own solutions/answers — one problem per question. OPEN = not yet answered; the card needs a human exactly while open_problem_count > 0 — there is no separate flag to set, adding a problem IS putting the card in front of a human. list → live problems in order, each {id, statement, context, type, summary, content_hash, open, solutions[], decisions[]}; add {statement, context?, type?, summary?, solutions?} → problem_id + solution_ids in one transaction (zero solutions is valid: the operator answers free-form) plus `problems_reminder: {open_problem_count, instruction}` naming each open problem's solution count; edit :pid {base_hash, statement, context?, summary?}; remove :pid {base_hash} — always allowed, even as the card's last open problem (DX-2830: removing it just means the card no longer needs a human). A stale base_hash → 409 `stale_problem` with currentHash + currentProblem: merge, then retry. No answer action — the operator answers in the dashboard. DX-2942 — `statement` is capped at 200 characters (a 400 names the actual length otherwise): write it as ONE plain sentence (a question for a question, the deed itself for an action), and put any investigation detail in `context` (markdown, no cap) instead of running it on. Good: statement \"Which cache should we use?\", context \"Redis fits the read-heavy path; see benchmark in #123. Memcached is simpler ops but no persistence.\" Bad: statement \"We looked at Redis vs Memcached, ran benchmarks showing Redis 3x faster on reads, but Memcached has simpler ops and we're not sure persistence matters here since the cache is fully rebuildable from Postgres...\" (too long, refused — move it to context). Every problem is also a `type`, with a `summary` distinct from `context`: read BOTH fields' own descriptions below before your first `add` — together they teach which type this is, and the three-field split (`statement` / `summary` / `context`) an action actually needs.", {
+strictTool("issue_problem", "A card's PROBLEMS via /api/issues/:id/problems[/:pid]: one statement the operator must resolve (a question, or a flaw in the plan) OR an action only a person can carry out, each with its own solutions/answers — one problem per question. OPEN = not yet answered; the card needs a human exactly while open_problem_count > 0 — there is no separate flag to set, adding a problem IS putting the card in front of a human. list → live problems in order, each {id, statement, context, type, summary, content_hash, open, solutions[], decisions[]}; add {statement, context?, type?, summary?, solutions?} → problem_id + solution_ids in one transaction (zero solutions is valid: the operator answers free-form) plus `problems_reminder: {open_problem_count, instruction}` naming each open problem's solution count; edit :pid {base_hash, statement, context?, summary?}; remove :pid {base_hash} — always allowed, even as the card's last open problem (removing it just means the card no longer needs a human). A stale base_hash → 409 `stale_problem` with currentHash + currentProblem: merge, then retry. No answer action — the operator answers in the dashboard. `statement` is capped at 200 characters (a 400 names the actual length otherwise): write it as ONE plain sentence (a question for a question, the deed itself for an action), and put any investigation detail in `context` (markdown, no cap) instead of running it on. Good: statement \"Which cache should we use?\", context \"Redis fits the read-heavy path; see benchmark in #123. Memcached is simpler ops but no persistence.\" Bad: statement \"We looked at Redis vs Memcached, ran benchmarks showing Redis 3x faster on reads, but Memcached has simpler ops and we're not sure persistence matters here since the cache is fully rebuildable from Postgres...\" (too long, refused — move it to context). Every problem is also a `type`, with a `summary` distinct from `context`: read BOTH fields' own descriptions below before your first `add` — together they teach which type this is, and the three-field split (`statement` / `summary` / `context`) an action actually needs.", {
     id: z.string().min(1),
     action: z.enum(["list", "add", "edit", "remove"]),
     problem_id: z.number().int().positive().optional().describe("edit/remove"),
@@ -643,10 +659,8 @@ strictTool("issue_problem", "A card's PROBLEMS via /api/issues/:id/problems[/:pi
         "WHY THE ACTION IS NEEDED AND WHY YOU CANNOT DO IT YOURSELF — that sentence is what tells the operator this " +
         "is not you being lazy (an add with no summary is refused 400); context is whatever additional detail the " +
         "person needs to carry it out; solutions[] are the possible ROUTES a person could take (e.g. \"rotate by " +
-        "hand in the console\" vs \"run the provisioning script\" vs \"ask the vendor\") — each will carry its own " +
-        "ordered steps to completion once the operator picks one (a later release; for now, describe the route in " +
-        "the solution's body). Omitted defaults to \"question\" (today's behavior) — but that default exists for " +
-        "the caller who has never heard of this field, not as permission to skip the choice: decide deliberately " +
+        "hand in the console\" vs \"run the provisioning script\" vs \"ask the vendor\"), each carrying its own " +
+        "steps to completion once the operator picks one. Omitted defaults to \"question\" — decide deliberately " +
         "every time."),
     summary: z
         .string()
@@ -664,15 +678,61 @@ strictTool("issue_problem", "A card's PROBLEMS via /api/issues/:id/problems[/:pi
         .describe("add only; fields as issue_solution add"),
     ...boardField,
 }, async (args) => jsonResult(await issueProblem(client, args)));
-// ---------------- issue_solution ----------------
-strictTool("issue_solution", "One problem's options via /api/issues/:id/problems/:pid/solutions[/:sid]; `problem_id` is REQUIRED (from issue_problem list/add; another problem's solution id → 404). add {title, body?, pro?, con?, recommended?}: title names the option, body is its markdown detail, pro/con the case for and against; edit :sid {base_hash, ...only the changed fields}; remove :sid {base_hash}. A stale base_hash → 409 `stale_solution` with currentHash + currentSolution: merge, then retry. At most ONE live recommended per problem: a second → 409 naming `recommended_solution_id`. A chosen option cannot be edited (409 — add a new one) but can be removed.", {
+const STEP_INPUT = z.lazy(() => z
+    .object({
+    id: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("present → this node IS an existing step (matched on this id); absent → new, or matched by (parent, ordinal, title)"),
+    title: z.string().min(1),
+    description: z.string().nullable().optional().describe("markdown detail, or null/omitted for none"),
+    steps: z.array(STEP_INPUT).optional().describe("this step's own children, nested — refused past 3 levels total"),
+})
+    .strict());
+strictTool("issue_solution", "One problem's options via /api/issues/:id/problems/:pid/solutions[/:sid], AND (DX-3310) one solution's individual " +
+    "procedure steps via .../solutions/:sid/steps[/:stepId]; `problem_id` is REQUIRED (from issue_problem list/add; " +
+    "another problem's solution id → 404). add {title, body?, pro?, con?, recommended?, steps?}: title names the " +
+    "option/route, body is its markdown detail, pro/con the case for and against, `steps` is its WHOLE procedure " +
+    "authored in one call — an ordered array of {title, description?, steps?}, nestable to 3 levels (a 4th is refused " +
+    "400 naming the offending step and the limit); edit :sid {base_hash, ...only the changed fields, steps?}: `steps` " +
+    "omitted leaves the stored procedure untouched, an explicit array (including []) DIFFS against it — send back an " +
+    "existing step's `id` (read from the card) to keep it (even while retitling/reordering it) and omit `id` for a " +
+    "genuinely new step; any existing step you don't include gets removed. NEVER resend the whole tree just to fix " +
+    "one word — see add_step/edit_step/remove_step below. remove :sid {base_hash}. A stale base_hash → 409 " +
+    "`stale_solution` with currentHash + currentSolution: merge, then retry. At most ONE live recommended per " +
+    "problem: a second → 409 naming `recommended_solution_id`. A chosen option cannot be edited (409 — add a new " +
+    "one) but can be removed.\n\n" +
+    "Granular single-step actions — change ONE step without resending the tree: add_step {solution_id, title, " +
+    "description?, parent_step_id?, position?} — parent_step_id omitted/null = top-level; position is 1-indexed " +
+    "among the parent's current live children, omitted = append; nesting past depth 3 → 400. edit_step " +
+    "{solution_id, step_id, base_hash, title?, description?} — never moves a step (no parent_step_id/position here). " +
+    "remove_step {solution_id, step_id, base_hash} — soft-deletes it AND its own live children. A stale base_hash on " +
+    "a step → 409 `stale_step` with currentHash + currentStep (carrying its real derived `label`).", {
     id: z.string().min(1),
-    action: z.enum(["add", "edit", "remove"]),
+    action: z.enum(["add", "edit", "remove", "add_step", "edit_step", "remove_step"]),
     problem_id: z.number().int().positive(),
-    solution_id: z.number().int().positive().optional().describe("edit/remove"),
-    base_hash: z.string().min(1).optional().describe("content_hash last read; edit/remove"),
-    title: z.string().min(1).optional().describe("add"),
+    solution_id: z.number().int().positive().optional().describe("edit/remove/add_step/edit_step/remove_step"),
+    base_hash: z.string().min(1).optional().describe("content_hash last read; edit/remove/edit_step/remove_step"),
+    title: z.string().min(1).optional().describe("add; also add_step/edit_step"),
     ...SOLUTION_FIELDS,
+    steps: z.array(STEP_INPUT).optional().describe("add/edit only — see this tool's own description"),
+    description: z.string().nullable().optional().describe("add_step/edit_step; markdown detail, or null/omitted for none"),
+    step_id: z.number().int().positive().optional().describe("edit_step/remove_step"),
+    parent_step_id: z
+        .number()
+        .int()
+        .positive()
+        .nullable()
+        .optional()
+        .describe("add_step only; omitted/null = top-level step"),
+    position: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("add_step only; 1-indexed among the parent's current live children, omitted = append"),
     ...boardField,
 }, async (args) => jsonResult(await issueSolution(client, args)));
 // ---------------- issue_dependency ----------------

package/package.json

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