@thehammer/danx-dashboard-mcp 0.1.82 → 0.1.83

package/dist/handlers.js

@@ -844,6 +844,7 @@ export const PLAN_FIELD_GROUPS = [
     "records:caveat",
     "architecture",
     "sessions",
+    "notes",
 ];
 /**
  * DX-2834 — the plan-status taxonomy, mirroring `PLAN_FIELD_GROUPS` just
@@ -1147,6 +1148,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];
@@ -793,6 +793,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/package.json

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