@thehammer/danx-dashboard-mcp 0.1.82 → 0.1.84

package/dist/handlers.js

@@ -392,7 +392,11 @@ export async function issueComment(client, args) {
         return client.request({
             method: "POST",
             path: `/${idEnc}/comments`,
-            body: { text, ...(args.metadata !== undefined ? { metadata: args.metadata } : {}) },
+            body: {
+                text,
+                ...(args.metadata !== undefined ? { metadata: args.metadata } : {}),
+                ...(args.problem_id !== undefined ? { problem_id: args.problem_id } : {}),
+            },
             board,
         });
     }
@@ -844,6 +848,7 @@ export const PLAN_FIELD_GROUPS = [
     "records:caveat",
     "architecture",
     "sessions",
+    "notes",
 ];
 /**
  * DX-2834 — the plan-status taxonomy, mirroring `PLAN_FIELD_GROUPS` just
@@ -1147,6 +1152,85 @@ export async function planDeleteRecord(client, args) {
         body: { content_hash: args.content_hash },
     });
 }
+/**
+ * Write a milestone note to a plan, via `POST /api/plans/:plan_id/notes`.
+ * TAKES AN EXPLICIT `plan_id`, unlike `plan_add_record`/`plan_add_architecture_section`
+ * — mirrors `plan_add_card`'s sibling `plan_remove_card`/`plan_rename`: a
+ * dispatched worker has no plan connection when it finishes a card, and a
+ * card can sit on several plans, so the writer names which one the note
+ * belongs to. A note is a MILESTONE, not a log — write one when a card (or a
+ * related group of cards) finishes, an important decision lands, or a
+ * goal/rule/caveat/architecture section changes meaningfully; routine step
+ * progress stays a card comment. Links resolve on read into what they point
+ * at (a card's title, a record's ref + body, a section's title) — an unknown
+ * card id, an unparseable or foreign record ref, or an unknown or foreign
+ * section id is refused 400 naming exactly which one. A card link does NOT
+ * require the card to be a member of this plan; a record/section link MUST
+ * belong to THIS plan. `author` is stamped server-side from your identity,
+ * never sent by you. Unknown plan → 404. Returns the new note plus the
+ * plan's latest notes page.
+ */
+export async function planAddNote(client, args) {
+    return client.request({
+        method: "POST",
+        path: `/${args.plan_id}/notes`,
+        basePath: PLANS_BASE_PATH,
+        body: {
+            title: args.title,
+            body: args.body,
+            ...(args.card_ids === undefined ? {} : { card_ids: args.card_ids }),
+            ...(args.record_refs === undefined ? {} : { record_refs: args.record_refs }),
+            ...(args.section_ids === undefined ? {} : { section_ids: args.section_ids }),
+        },
+    });
+}
+/**
+ * Edit a plan note, via `PATCH /api/plans/:plan_id/notes/:note_id`.
+ * `content_hash` MUST be the note's `contentHash` from your last read; on a
+ * mismatch nothing is written and you get `{error: "stale_plan_note",
+ * currentHash, currentTitle, currentBody, currentLinks}` — merge into those
+ * and retry with `content_hash: currentHash`, never blindly. `title`/`body`
+ * are each optional and keep their stored value when omitted. The LINK
+ * fields are all-or-nothing as a GROUP: omit all three to keep the stored
+ * link set untouched; send ANY one of them to REPLACE THE WHOLE SET (never a
+ * per-link add/remove — the set is the unit of change). The hash covers
+ * title, body AND the link set, so a stale read of any of the three is
+ * refused. TAKES AN EXPLICIT `plan_id`, same reason as `plan_add_note`.
+ * Unknown plan or note id → 404. Returns the edited note plus the plan's
+ * latest notes page.
+ */
+export async function planUpdateNote(client, args) {
+    return client.request({
+        method: "PATCH",
+        path: `/${args.plan_id}/notes/${args.note_id}`,
+        basePath: PLANS_BASE_PATH,
+        body: {
+            content_hash: args.content_hash,
+            ...(args.title === undefined ? {} : { title: args.title }),
+            ...(args.body === undefined ? {} : { body: args.body }),
+            ...(args.card_ids === undefined ? {} : { card_ids: args.card_ids }),
+            ...(args.record_refs === undefined ? {} : { record_refs: args.record_refs }),
+            ...(args.section_ids === undefined ? {} : { section_ids: args.section_ids }),
+        },
+    });
+}
+/**
+ * Soft-delete a plan note, via `DELETE /api/plans/:plan_id/notes/:note_id`.
+ * `content_hash` MUST be the note's `contentHash` from your last read; a
+ * stale hash deletes nothing and returns the same `{error:
+ * "stale_plan_note", currentHash, currentTitle, currentBody, currentLinks}`
+ * shape `plan_update_note` uses. TAKES AN EXPLICIT `plan_id`, same reason as
+ * `plan_add_note`. Unknown plan, unknown note, or an already-deleted note →
+ * 404. Returns the plan's remaining latest notes page.
+ */
+export async function planDeleteNote(client, args) {
+    return client.request({
+        method: "DELETE",
+        path: `/${args.plan_id}/notes/${args.note_id}`,
+        basePath: PLANS_BASE_PATH,
+        body: { content_hash: args.content_hash },
+    });
+}
 // ---------------- failure_category_list / _create / _update (DX-2792) ----------------
 /**
  * DX-2792 (Failure evaluation 3/4) — wraps `src/dashboard/failure-categories-routes.ts`,

package/dist/index.js

@@ -101,7 +101,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, issueProblem, issueQualityGate, issueQualityGateVerdict, issueRetireBranch, issueRetro, issueSolution, issueTransition, issueTriage, briefGetPage, briefList, briefSetPage, failureCategoryCreate, failureCategoryList, failureCategoryUpdate, planAddArchitectureSection, planAddCard, planAddRecord, planConnect, planCreate, planDeleteArchitectureSection, planDeleteRecord, planGet, PLAN_FIELD_GROUPS, PLAN_STATUSES, ISSUE_BATCH_GET_MAX, LIST_PAGE_MAX_LIMIT, PLAN_GET_CARDS_DEFAULT_LIMIT, planGetArchitectureSection, planGetRecord, planList, planRemoveCard, planRename, planReorderArchitectureSection, planUpdateArchitectureSection, planUpdateRecord, repoKnowledgeGet, repoKnowledgeSet, } 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, planAddArchitectureSection, planAddCard, planAddNote, planAddRecord, planConnect, planCreate, planDeleteArchitectureSection, planDeleteNote, planDeleteRecord, planGet, PLAN_FIELD_GROUPS, PLAN_STATUSES, ISSUE_BATCH_GET_MAX, LIST_PAGE_MAX_LIMIT, PLAN_GET_CARDS_DEFAULT_LIMIT, planGetArchitectureSection, planGetRecord, planList, planRemoveCard, planRename, planReorderArchitectureSection, planUpdateArchitectureSection, planUpdateNote, planUpdateRecord, repoKnowledgeGet, repoKnowledgeSet, } from "./handlers.js";
 import { PRIORITY_TIER_WORDS } from "./priority.js";
 function readEnvOrDie(name) {
     const v = process.env[name];
@@ -504,12 +504,13 @@ server.tool("issue_triage", "Record a triage confidence score via POST /api/issu
     ...boardField,
 }, async (args) => jsonResult(await issueTriage(client, args)));
 // ---------------- issue_comment ----------------
-server.tool("issue_comment", "Comment CRUD via /api/issues/:id/comments[/:cid]. action=add → POST {text, metadata?} (server stamps author from bearer + auto-incrementing ordinal); action=edit → PATCH /:cid {text}; action=delete → DELETE /:cid (soft-delete, audit trail preserved — comments are NEVER hard-deleted). Client-supplied author is IGNORED (server-stamped to prevent impersonation). `metadata` (DX-2157, action=add only) is an OPTIONAL opaque JSON object a calling app attaches to the comment — e.g. a generated `{sql, explanation}` packet its own UI renders specially. danxbot stores + returns it verbatim and enforces NO shape on its contents; omit for a plain markdown-only comment (unaffected either way).", {
+server.tool("issue_comment", "Comment CRUD via /api/issues/:id/comments[/:cid]. action=add → POST {text, metadata?, problem_id?} (server stamps author from bearer + auto-incrementing ordinal); action=edit → PATCH /:cid {text}; action=delete → DELETE /:cid (soft-delete, audit trail preserved — comments are NEVER hard-deleted). Client-supplied author is IGNORED (server-stamped to prevent impersonation). `metadata` (DX-2157, action=add only) is an OPTIONAL opaque JSON object a calling app attaches to the comment — e.g. a generated `{sql, explanation}` packet its own UI renders specially. danxbot stores + returns it verbatim and enforces NO shape on its contents; omit for a plain markdown-only comment (unaffected either way). `problem_id` (DX-2906, action=add only) OPTIONALLY threads the comment as a follow-up question under one of this SAME card's problems (from `issue_problem` list/add) WITHOUT answering it — commenting never changes open_problem_count, blocked, or records a decision; use issue_problem's answer route for that. An unknown id, another card's id, or a removed problem's id all 404 naming the problem id — an ANSWERED (but not removed) problem still accepts a follow-up comment, since the thread continues after a decision.", {
     id: z.string().min(1),
     action: z.enum(["add", "edit", "delete"]),
     comment_id: z.number().int().positive().optional(),
     text: z.string().min(1).optional(),
     metadata: z.record(z.unknown()).optional(),
+    problem_id: z.number().int().positive().optional().describe("action=add only — thread this comment as a follow-up under a LIVE problem of this same card, without answering it"),
     ...boardField,
 }, async (args) => jsonResult(await issueComment(client, args)));
 // ---------------- issue_checklist ----------------
@@ -793,6 +794,32 @@ server.tool("plan_delete_record", 'Soft-delete a goal/rule/caveat of your connec
     record_id: z.number().int().positive().describe("The record id to delete."),
     content_hash: z.string().describe("The record's `contentHash` from your last read. Required."),
 }, async (args) => jsonResult(await planDeleteRecord(client, args)));
+server.tool("plan_add_note", "Write a milestone note to a plan's timeline, via POST /api/plans/:plan_id/notes (DX-2915). A note is a MILESTONE, not a log — write one for a card (or related group of cards) finishing, an important decision, or a meaningful goal/rule/caveat/architecture-section change; routine step progress stays a card comment, never a note. Terse tone: `title` at most 60 characters, `body` (the wrap-up) at most 250 (both 400 if too long, naming the limit and actual length). Links resolve on read into what they point at (a card's title, a record's ref+body, a section's title): an unknown card, an unparseable or foreign record ref, or an unknown or foreign section id is refused 400 naming exactly which one. A card link does NOT require the card to be a member of this plan; a record/section link MUST belong to THIS plan. `author` is stamped from your identity server-side — there is no field for it. TAKES AN EXPLICIT `plan_id` (like `plan_remove_card`/`plan_rename`), so a dispatched worker with no plan connection can still write. Unknown plan → 404. Returns the new note plus the plan's latest notes page.", {
+    plan_id: z.number().int().positive().describe("The plan id, from `plan_list`."),
+    title: z.string().min(1).describe("At most 60 characters."),
+    body: z.string().min(1).describe("The wrap-up, at most 250 characters."),
+    card_ids: z.array(z.string().min(1)).optional().describe("Card ids this note concerns, e.g. `[\"DX-2894\"]`."),
+    record_refs: z
+        .array(z.string().min(1))
+        .optional()
+        .describe("Goal/rule/caveat references this note announces, e.g. `[\"G-1\", \"R-3\", \"CAV-2\"]`."),
+    section_ids: z.array(z.number().int().positive()).optional().describe("Architecture section ids this note announces."),
+}, async (args) => jsonResult(await planAddNote(client, args)));
+server.tool("plan_update_note", 'Edit a plan note, via PATCH /api/plans/:plan_id/notes/:note_id (DX-2915). `content_hash` MUST be the note\'s `contentHash` from your last read; a mismatch writes NOTHING and returns `{error: "stale_plan_note", currentHash, currentTitle, currentBody, currentLinks}` — merge into those and retry with `content_hash: currentHash`, never blindly. `title`/`body` are each optional and keep their stored value when omitted. The link fields (`card_ids`/`record_refs`/`section_ids`) are all-or-nothing AS A GROUP: omit all three to leave the stored link set untouched; send ANY one of them to REPLACE THE WHOLE SET — there is no per-link add/remove. The hash covers title, body AND the link set. TAKES AN EXPLICIT `plan_id`, same reason as `plan_add_note`. Unknown plan or note id → 404. Returns the edited note plus the plan\'s latest notes page.', {
+    plan_id: z.number().int().positive().describe("The plan id, from `plan_list`."),
+    note_id: z.number().int().positive().describe("The note id to edit."),
+    content_hash: z.string().describe("The note's `contentHash` from your last read. Required."),
+    title: z.string().min(1).optional().describe("New title, at most 60 characters. Omit to keep the stored title."),
+    body: z.string().min(1).optional().describe("New wrap-up, at most 250 characters. Omit to keep the stored body."),
+    card_ids: z.array(z.string().min(1)).optional().describe("REPLACES the whole link set when sent (with record_refs/section_ids)."),
+    record_refs: z.array(z.string().min(1)).optional().describe("REPLACES the whole link set when sent (with card_ids/section_ids)."),
+    section_ids: z.array(z.number().int().positive()).optional().describe("REPLACES the whole link set when sent (with card_ids/record_refs)."),
+}, async (args) => jsonResult(await planUpdateNote(client, args)));
+server.tool("plan_delete_note", 'Soft-delete a plan note, via DELETE /api/plans/:plan_id/notes/:note_id (DX-2915). `content_hash` must be the note\'s `contentHash` from your last read; a stale hash deletes nothing and returns `{error: "stale_plan_note", currentHash, currentTitle, currentBody, currentLinks}` — the same shape `plan_update_note` uses. TAKES AN EXPLICIT `plan_id`, same reason as `plan_add_note`. Unknown plan, unknown note, or an already-deleted note → 404. Returns the plan\'s remaining latest notes page.', {
+    plan_id: z.number().int().positive().describe("The plan id, from `plan_list`."),
+    note_id: z.number().int().positive().describe("The note id to delete."),
+    content_hash: z.string().describe("The note's `contentHash` from your last read. Required."),
+}, async (args) => jsonResult(await planDeleteNote(client, args)));
 server.tool("plan_add_card", "Add an existing card to the plan this session is connected to, via POST /api/plans/mine/cards (DX-2683). The card may live on ANY board — that is what a plan is for. Idempotent: re-adding a card already on the plan is a no-op, not an error, and a card may sit in several plans at once. This adds MEMBERSHIP only; it never edits the card. TAKES NO PLAN ID: the plan is resolved from your connected session. Not connected → `{error: \"session_not_connected\"}`. Unknown card → 404. Returns the plan's full member list.", {
     card_id: z.string().min(1).describe("An existing card id, e.g. `DX-2683`."),
 }, async (args) => jsonResult(await planAddCard(client, args)));

package/dist/listen.js

@@ -92,8 +92,18 @@ export function invalidEventReason(value) {
     if (!isRecord(d))
         return "detail is not an object";
     switch (value.kind) {
-        case "comment_added":
-            return isCappedText(d.excerpt) ? null : "detail.excerpt is not capped text";
+        case "comment_added": {
+            if (!isCappedText(d.excerpt))
+                return "detail.excerpt is not capped text";
+            // DX-2906 — `problem` is OPTIONAL (only present when the comment named
+            // one); absent is valid, but a present-and-malformed one is not.
+            if (d.problem === undefined)
+                return null;
+            const problem = d.problem;
+            return isRecord(problem) && typeof problem.id === "number" && isCappedText(problem.statement)
+                ? null
+                : "detail.problem is not {id, statement}";
+        }
         case "solution_answered": {
             const problem = d.problem;
             if (!isRecord(problem) || typeof problem.id !== "number" || !isCappedText(problem.statement)) {
@@ -122,8 +132,16 @@ export function invalidEventReason(value) {
 function describe(event) {
     const d = event.detail;
     switch (event.kind) {
-        case "comment_added":
-            return `${event.actor} commented: ${quoted(d.excerpt)}`;
+        case "comment_added": {
+            // DX-2906 — a comment naming a problem (a follow-up question, without
+            // answering it) relays distinctly from a plain comment, so an agent
+            // listening to the stream can tell which of its open problems just
+            // got a reply.
+            const problem = d.problem;
+            if (problem === undefined)
+                return `${event.actor} commented: ${quoted(d.excerpt)}`;
+            return `${event.actor} commented on problem ${quoted(problem.statement)}: ${quoted(d.excerpt)}`;
+        }
         case "solution_answered": {
             // DX-2735: every answer answers ONE problem on a card that may carry several,
             // so the line names the problem — otherwise the agent cannot tell which of its

package/package.json

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