@thehammer/danx-dashboard-mcp 0.1.21 → 0.1.23

package/README.md

@@ -24,7 +24,7 @@ All exposed as `mcp__danx_dashboard__<name>` once wired through the workspace `m
 | `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_create` | `POST /api/issues` | Epic REQUIRES non-empty `phase_children[]` (atomic insert) |
-| `issue_edit` | `PATCH /api/issues/:id/edit` | Prose-only — semantic keys refused with 400 + pointer to dedicated handler |
+| `issue_edit` | `PATCH /api/issues/:id/edit` | Prose + structured keys (`title`, `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 |
 | `issue_triage` | `POST /api/issues/:id/triage` | Verdicts: approve, cancel, keep, defer (with optional ICE + ttl_seconds) |
 | `issue_comment` | `POST/PATCH/DELETE /api/issues/:id/comments[/:cid]` | Author server-stamped, soft-delete preserved |

package/dist/handlers.js

@@ -23,6 +23,7 @@
  */
 import { readFile } from "node:fs/promises";
 import { basename, extname, isAbsolute } from "node:path";
+import { resolvePriority } from "./priority.js";
 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
@@ -97,8 +98,9 @@ export async function issueCreate(client, args, defaultBoard) {
 export async function issueEdit(client, args) {
     // `board` is a transport concern (query), NOT a patch field — pull it
     // out of `rest` so it never leaks into the `/edit` body (the server
-    // 400s on non-allowlisted keys).
-    const { id, board, ...rest } = args;
+    // 400s on non-allowlisted keys). `priority` is pulled out separately so it
+    // can be resolved (tier word → numeric) before it reaches the body.
+    const { id, board, priority, ...rest } = args;
     // Strip undefined so we don't send `{title: undefined}` — JSON.stringify
     // drops them anyway but explicit is clearer.
     const body = {};
@@ -106,6 +108,12 @@ export async function issueEdit(client, args) {
         if (v !== undefined)
             body[k] = v;
     }
+    // DX-1532 — resolve a tier WORD to its numeric midpoint (inverse of
+    // priorityTier); a raw number passes through for the route to range-validate.
+    // Omitted (undefined) → never sent, so a prose-only edit is unchanged.
+    if (priority !== undefined) {
+        body.priority = resolvePriority(priority);
+    }
     return client.request({
         method: "PATCH",
         path: `/${encodeURIComponent(id)}/edit`,
@@ -343,9 +351,16 @@ export async function issueRequiresHuman(client, args) {
  *
  * `gate` is a registry name (`plan-dependency` | `plan-architecture` |
  * `plan-tdd` | `code-test-quality` | `code-architecture` | `code-quality`).
- * An unknown gate is a 400 from the server (never a silent no-op). The
- * board-level master switch is a separate surface — a gate only RUNS when
- * the board enables it AND the card marks it required.
+ * An unknown gate is a 400 from the server (never a silent no-op).
+ *
+ * Board requirement is TRI-STATE per gate, NOT a binary on/off
+ * (`board_quality_gate_settings.default_state`): `required` = always runs
+ * (this per-card flag is irrelevant); `optional` = ENABLED, runs WHEN this
+ * per-card flag is true (per-card opt-in — `optional` is NOT "off");
+ * `disabled` = never runs (this flag is inert). So flipping `required:true`
+ * here launches the gate when the board state is `required` OR `optional`;
+ * it is inert ONLY when the board state is `disabled`. Source of truth:
+ * `isGateEffectivelyRequired` in `src/issues/quality-gates/read.ts`.
  */
 export async function issueQualityGate(client, args) {
     return client.request({

package/dist/index.js

@@ -53,6 +53,7 @@ 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, issueRequiresHuman, issueRetro, issueTransition, issueTriage, } from "./handlers.js";
+import { PRIORITY_TIER_WORDS } from "./priority.js";
 function readEnvOrDie(name) {
     const v = process.env[name];
     if (typeof v !== "string" || v === "") {
@@ -175,7 +176,7 @@ server.tool("issue_create", 'Create a fresh card via POST /api/issues. Board-sco
     required_gates: z
         .array(z.string().min(1))
         .optional()
-        .describe('Optional array of quality-gate names to mark REQUIRED on this card (e.g. ["architecture","tdd"]). A gate only actually runs if the board has that gate ENABLED (master switch) AND it is required on the card. Use this when you (the creating agent) judge the card needs that pre-dispatch review gate; omit for cards that don\'t. Known gates: dependency, architecture, tdd, code. The operator can also toggle these per-card later in the issue drawer.'),
+        .describe('Optional array of quality-gate names to mark REQUIRED on this card (e.g. ["architecture","tdd"]). Board requirement is TRI-STATE per gate (`board_quality_gate_settings.default_state`), NOT binary: `required` runs always; `optional` runs WHEN flagged on the card (per-card opt-in — `optional` is ENABLED, not off); `disabled` never runs (flag inert). So flagging makes the gate run unless the board state is `disabled`. Use this when you (the creating agent) judge the card needs that pre-dispatch review gate; omit for cards that don\'t. Known gates: dependency, architecture, tdd, code. The operator can also toggle these per-card later in the issue drawer.'),
     phase_children: z
         .array(z.object({
         type: z.enum(NON_EPIC_TYPES),
@@ -188,7 +189,7 @@ server.tool("issue_create", 'Create a fresh card via POST /api/issues. Board-sco
     ...boardField,
 }, async (args) => jsonResult(await issueCreate(client, args, config.board)));
 // ---------------- issue_edit ----------------
-server.tool("issue_edit", 'Patch prose fields only via PATCH /api/issues/:id/edit. ALLOWED keys: title, description, ac, checklists, effort_level, parent_id, list_id. ANY OTHER KEY (lifecycle timestamps, triage state, dependencies, retro, requires_human, blocked/dispatch gates) returns 400 with offending_keys[] and a pointer to the dedicated semantic handler — use issue_transition / issue_triage / issue_comment / issue_dependency / issue_requires_human / issue_retro instead. CHECKLISTS (DX-1290): a card carries 0..N named checklists, each item ONE 4-state status `incomplete|failing|passing|cancelled` (terminal = passing|cancelled). `ac` is the 2-state CONVENIENCE onto the default "Acceptance Criteria" checklist (checked:true ↔ passing, false ↔ incomplete) — wholesale soft-delete + reinsert of that checklist\'s items. `checklists` is the GENERIC wholesale write path: it REPLACES every named checklist on the card with full 4-state control (each `{name, items:[{label, detail?, status}]}`) — use it to author named checklists like "Feature Tests". Send EITHER `ac` OR `checklists`, NOT both (400). list_id (DX-1192 / DX-1200) PINS the card to a specific board list. **Pass EITHER a board_lists id OR the list\'s display NAME (case-insensitive, e.g. a queue name like "⚙️ Fulfillment Queue") — the server resolves a name to its id.** Its type MUST match the card\'s CURRENT derived-status list-type (so to route a ToDo card into a `ready`-type queue, ready it first; mismatch / unknown name or id → 400); pass null to clear the pin (back to default-for-type).', {
+server.tool("issue_edit", 'Patch prose + structured fields via PATCH /api/issues/:id/edit. ALLOWED keys: title, description, ac, checklists, effort_level, parent_id, priority, list_id. ANY OTHER KEY (lifecycle timestamps, triage state, dependencies, retro, requires_human, blocked/dispatch gates) returns 400 with offending_keys[] and a pointer to the dedicated semantic handler — use issue_transition / issue_triage / issue_comment / issue_dependency / issue_requires_human / issue_retro instead. PRIORITY (DX-1532): set card priority via the `priority` key — a tier WORD ("lowest"/"low"/"medium"/"high"/"very_high"/"critical", resolved to the tier midpoint) OR a raw number in [0,6). This is the ONLY way to change priority: the numeric `issues.priority` column is what the Trello priority label AND the dashboard badge read — editing a "Priority: <x>" line in the DESCRIPTION changes nothing downstream (a silent false-positive). To honor a "set priority" request, write `priority` here, do NOT edit description prose. CHECKLISTS (DX-1290): a card carries 0..N named checklists, each item ONE 4-state status `incomplete|failing|passing|cancelled` (terminal = passing|cancelled). `ac` is the 2-state CONVENIENCE onto the default "Acceptance Criteria" checklist (checked:true ↔ passing, false ↔ incomplete) — wholesale soft-delete + reinsert of that checklist\'s items. `checklists` is the GENERIC wholesale write path: it REPLACES every named checklist on the card with full 4-state control (each `{name, items:[{label, detail?, status}]}`) — use it to author named checklists like "Feature Tests". Send EITHER `ac` OR `checklists`, NOT both (400). list_id (DX-1192 / DX-1200) PINS the card to a specific board list. **Pass EITHER a board_lists id OR the list\'s display NAME (case-insensitive, e.g. a queue name like "⚙️ Fulfillment Queue") — the server resolves a name to its id.** Its type MUST match the card\'s CURRENT derived-status list-type (so to route a ToDo card into a `ready`-type queue, ready it first; mismatch / unknown name or id → 400); pass null to clear the pin (back to default-for-type).', {
     id: z.string().min(1),
     title: z.string().min(1).optional(),
     description: z.string().optional(),
@@ -210,6 +211,10 @@ server.tool("issue_edit", 'Patch prose fields only via PATCH /api/issues/:id/edi
         .optional(),
     effort_level: z.enum(EFFORT_VALUES).nullable().optional(),
     parent_id: z.string().nullable().optional(),
+    priority: z
+        .union([z.enum(PRIORITY_TIER_WORDS), z.number()])
+        .optional()
+        .describe('Card priority (DX-1532). A tier WORD ("lowest"/"low"/"medium"/"high"/"very_high"/"critical") resolved to the tier midpoint, OR a raw number in [0,6). Writes the numeric `issues.priority` column the Trello label + dashboard badge read — set priority HERE, never via description prose (which no system reads for priority).'),
     list_id: z.string().min(1).nullable().optional(),
     ...boardField,
 }, async (args) => jsonResult(await issueEdit(client, args)));
@@ -290,7 +295,7 @@ server.tool("issue_requires_human", "Set or clear the requires_human dispatch ga
     ...boardField,
 }, async (args) => jsonResult(await issueRequiresHuman(client, args)));
 // ---------------- issue_quality_gate ----------------
-server.tool("issue_quality_gate", "Toggle a single card's per-card quality-gate `required` flag via POST /api/issues/:id/quality-gates/:gate {required} — the SAME write the dashboard drawer's Quality Gates tab performs (DX-1181). This is the ONLY post-create way to mark a gate required/not-required: `issue_create` carries `required_gates[]` at birth, and `issue_edit` REJECTS gate keys (400 offending_keys) — without this tool a card created without a gate can never have it turned on by an agent. `gate` is a registry name: `plan-dependency` | `plan-architecture` | `plan-tdd` | `code-test-quality` | `code-architecture` | `code-quality` (the PRE/plan- gates run before the work dispatch; the POST/code- gates block issue_transition complete). Unknown gate → 400 (never a silent no-op); a card with no seeded row for a registered gate → 500 (canonical corruption). NOTE the board-level master switch is separate (the Agents-tab `board_quality_gate_settings`): a gate only RUNS when the board enables it AND the card marks it required — flipping `required` here is necessary but not sufficient if the board has the gate disabled. Returns the hydrated issue. Board-scoped; pass `board` (`<repo>:<slug>`) to target another board.", {
+server.tool("issue_quality_gate", "Toggle a single card's per-card quality-gate `required` flag via POST /api/issues/:id/quality-gates/:gate {required} — the SAME write the dashboard drawer's Quality Gates tab performs (DX-1181). This is the ONLY post-create way to mark a gate required/not-required: `issue_create` carries `required_gates[]` at birth, and `issue_edit` REJECTS gate keys (400 offending_keys) — without this tool a card created without a gate can never have it turned on by an agent. `gate` is a registry name: `plan-dependency` | `plan-architecture` | `plan-tdd` | `code-test-quality` | `code-architecture` | `code-quality` (the PRE/plan- gates run before the work dispatch; the POST/code- gates block issue_transition complete). Unknown gate → 400 (never a silent no-op); a card with no seeded row for a registered gate → 500 (canonical corruption). NOTE board requirement is TRI-STATE per gate (`board_quality_gate_settings.default_state`, the Agents-tab surface), NOT a binary on/off: `required` = gate always runs (this flag irrelevant); `optional` = gate runs WHEN this per-card flag is true (per-card opt-in — `optional` is ENABLED, NOT off); `disabled` = never runs (this flag inert). So flipping `required:true` here LAUNCHES the gate when the board state is `required` OR `optional`; it is inert ONLY when the board state is `disabled`. Do not read `optional` as off. (Source of truth: `isGateEffectivelyRequired` in `src/issues/quality-gates/read.ts`.) Returns the hydrated issue. Board-scoped; pass `board` (`<repo>:<slug>`) to target another board.", {
     id: z.string().min(1),
     gate: z.enum([
         "plan-dependency",

package/dist/priority.js

@@ -0,0 +1,70 @@
+/**
+ * Tier-word → numeric priority resolution for the MCP `issue_edit` tool
+ * (DX-1532).
+ *
+ * Priority is a STRUCTURED numeric column `issues.priority` (float in `[0,6)`).
+ * Both the Trello "priority" label and the dashboard priority badge read it via
+ * `priorityTier(issue.priority)` — description PROSE ("Priority: Low") is read
+ * by neither. So an agent that "sets priority" by editing description text
+ * produces a silent false-positive: nothing downstream changes. The fix is to
+ * let the agent write the numeric column through `issue_edit`.
+ *
+ * Agents (and operators) speak in tier WORDS ("low" / "high"), so the tool
+ * accepts a tier word and resolves it to the tier's MIDPOINT here — the inverse
+ * of `src/issue-tracker/priority-tier.ts#priorityTier`. A raw numeric is passed
+ * through unchanged for the server route to range-validate (it 400s on
+ * out-of-`[0,6)`), so the MCP boundary never has to duplicate that bound.
+ *
+ * This package is a standalone published artifact and cannot import the
+ * backend's `priority-tier` module, so the midpoint table is duplicated here.
+ * Each value IS the `[min,max)` bucket midpoint by construction and equals the
+ * backend's `PRIORITY_TIERS.defaultValue`; `src/issue-tracker/priority-tier.test.ts`
+ * asserts `priorityTier(defaultValue) === key` on the canonical side, pinning
+ * the round-trip these midpoints rely on.
+ */
+/**
+ * The six priority tier words, low → high. A const tuple so it doubles as the
+ * `z.enum` source in `index.ts`.
+ */
+export const PRIORITY_TIER_WORDS = [
+    "lowest",
+    "low",
+    "medium",
+    "high",
+    "very_high",
+    "critical",
+];
+/**
+ * Tier word → bucket midpoint (inverse of `priorityTier`). Lands the numeric
+ * column squarely inside the requested tier so a later `priorityTier` read
+ * returns the same word.
+ */
+export const PRIORITY_TIER_MIDPOINTS = {
+    lowest: 0.5,
+    low: 1.5,
+    medium: 2.5,
+    high: 3.5,
+    very_high: 4.5,
+    critical: 5.5,
+};
+/**
+ * Resolve a priority input — a tier WORD or a raw numeric — to the numeric
+ * value the `PATCH /api/issues/:id/edit` route stores in `issues.priority`.
+ *
+ * - tier word → its bucket midpoint (`PRIORITY_TIER_MIDPOINTS`).
+ * - number → passed through unchanged; the server route range-validates it to
+ *   `[0,6)` and 400s otherwise (the MCP boundary deliberately does not
+ *   re-validate the bound — single source of truth on the route).
+ * - unknown string → throws here at the MCP boundary (no round-trip). The Zod
+ *   enum on the tool schema already rejects this for tool callers; the explicit
+ *   throw keeps the helper safe for any direct caller.
+ */
+export function resolvePriority(input) {
+    if (typeof input === "number")
+        return input;
+    const midpoint = PRIORITY_TIER_MIDPOINTS[input];
+    if (midpoint === undefined) {
+        throw new Error(`issue_edit: unknown priority tier word "${input}" (expected one of ${PRIORITY_TIER_WORDS.join(", ")} or a number in [0,6))`);
+    }
+    return midpoint;
+}

package/package.json

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

package/dist/handlers.test.js

@@ -1,51 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { DashboardHttpClient } from "./http-client.js";
-import { issueList, issueTransition } from "./handlers.js";
-/**
- * `issue_list` query-param forwarding. A fake `fetch` captures the built
- * URL so each filter is asserted at the wire, through the real client's
- * URL builder (`?repo=` always stamped, extra query merged after).
- */
-function clientCapturing() {
-    const urls = [];
-    const fetchImpl = (async (url) => {
-        urls.push(url);
-        return new Response(JSON.stringify({ issues: [] }), { status: 200 });
-    });
-    const client = new DashboardHttpClient({ baseUrl: "http://localhost:5555", repo: "danxbot", token: "t" }, fetchImpl);
-    return { client, urls };
-}
-describe("issueList — query forwarding", () => {
-    it("forwards q as the server-side search needle", async () => {
-        const { client, urls } = clientCapturing();
-        await issueList(client, { q: "retire" });
-        expect(urls[0]).toContain("q=retire");
-    });
-    it("omits q when not provided", async () => {
-        const { client, urls } = clientCapturing();
-        await issueList(client, { include_closed: true });
-        expect(urls[0]).not.toContain("q=");
-        expect(urls[0]).toContain("include_closed=true");
-    });
-});
-describe("issueTransition — body forwarding", () => {
-    function clientCapturingBody() {
-        const bodies = [];
-        const fetchImpl = (async (_url, init) => {
-            bodies.push(JSON.parse(String(init?.body ?? "{}")));
-            return new Response(JSON.stringify({ issue: {} }), { status: 200 });
-        });
-        const client = new DashboardHttpClient({ baseUrl: "http://localhost:5555", repo: "danxbot", token: "t" }, fetchImpl);
-        return { client, bodies };
-    }
-    it("forwards manual: true on pickup (DX-946 operator self-pickup)", async () => {
-        const { client, bodies } = clientCapturingBody();
-        await issueTransition(client, { id: "DX-1", action: "pickup", manual: true });
-        expect(bodies[0]).toEqual({ action: "pickup", manual: true });
-    });
-    it("omits manual when not provided", async () => {
-        const { client, bodies } = clientCapturingBody();
-        await issueTransition(client, { id: "DX-1", action: "pickup" });
-        expect(bodies[0]).toEqual({ action: "pickup" });
-    });
-});