@thehammer/danx-dashboard-mcp 0.1.104 → 0.1.108

package/dist/handlers.js

@@ -1383,3 +1383,136 @@ export async function failureCategoryUpdate(client, args) {
         body: patch,
     });
 }
+// ---------------- dispatch_transcript_search (DX-3221) ----------------
+/**
+ * DX-3221 — search or tail ANOTHER dispatch's stored JSONL transcript
+ * without ever touching the filesystem. Wraps the existing durable
+ * `GET /api/dispatches/:id/logs` route (DX-1682, reading the `dispatch_logs`
+ * sink every worker already streams its raw JSONL lines into per DX-1484 —
+ * no dashboard-side change needed, that data is already captured today for
+ * every worker dispatch).
+ *
+ * Why this exists instead of a filesystem path: CLAUDE.md Core Principle 5
+ * makes the worktree boundary binary (inside allow, outside reject, no
+ * per-card opt-in) — a Grep/Glob tool pointed at `~/.claude/projects/`, or a
+ * worktree-guard carve-out for that path, both widen that boundary the same
+ * way a Bash `grep` would. This tool needs no such carve-out: it is an
+ * ordinary HTTP call authenticated the same way every other
+ * `mcp__danx-dashboard__*` tool already is, so worktree-guard never enters
+ * the picture and CP5 stays untouched.
+ *
+ * Why this ALSO fixes the underlying complaint `Read` can't: `Read`
+ * paginates by LINE, and a persisted JSONL entry can itself be one giant
+ * line (a large MCP tool-result payload, escaped-newline JSON) that exceeds
+ * the 25000-token cap with no way to sub-page inside it (`offset`/`limit`
+ * are line-granular). This handler does the string/regex search ITSELF,
+ * server-side of the model (inside this Node process), and only ever hands
+ * back a bounded excerpt around a match — never the whole line — so a
+ * single oversized line is no longer un-searchable.
+ */
+const DISPATCHES_BASE_PATH = "/api/dispatches";
+/** Tail lines returned when no `pattern` is given. */
+const DEFAULT_TAIL_LINES = 20;
+/** Hard ceiling on `tail` — keeps a mistaken huge request bounded. */
+const MAX_TAIL_LINES = 200;
+/** Characters of context returned around (or up to, for tail) each line. */
+const DEFAULT_CONTEXT_CHARS = 1000;
+/** Hard ceiling on `contextChars` — this is what keeps a single giant line from blowing the model's context the way `Read` does today. */
+const MAX_CONTEXT_CHARS = 4000;
+/** Matches returned before search stops scanning further lines. */
+const DEFAULT_MAX_MATCHES = 10;
+/** Hard ceiling on `maxMatches`. */
+const MAX_MATCHES_CEILING = 50;
+function clampPositiveInt(value, fallback, ceiling) {
+    const n = value ?? fallback;
+    if (!Number.isFinite(n) || n <= 0)
+        return fallback;
+    return Math.min(Math.floor(n), ceiling);
+}
+/**
+ * `GET /api/dispatches/:id/logs` (DX-1682) → search or tail, in-process.
+ * Proxies the SAME durable sink `handleGetDispatchLogs` already serves —
+ * this tool adds no new dashboard route, only client-side windowing.
+ */
+export async function dispatchTranscriptSearch(client, args) {
+    const hasPattern = args.pattern !== undefined && args.pattern !== "";
+    // Validate the regex BEFORE the network call — a malformed `pattern` is a
+    // caller input error, not a reason to spend an HTTP round-trip first.
+    let re = null;
+    if (hasPattern) {
+        try {
+            re = new RegExp(args.pattern, "gi");
+        }
+        catch (err) {
+            return {
+                ok: false,
+                status: 400,
+                body: {
+                    error: `dispatch_transcript_search: invalid \`pattern\` regex: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            };
+        }
+    }
+    const logsResult = await client.request({
+        method: "GET",
+        path: `/${encodeURIComponent(args.dispatchId)}/logs`,
+        basePath: DISPATCHES_BASE_PATH,
+    });
+    if (!logsResult.ok) {
+        return logsResult;
+    }
+    const body = logsResult.body;
+    const lines = body?.lines ?? [];
+    const contextChars = clampPositiveInt(args.contextChars, DEFAULT_CONTEXT_CHARS, MAX_CONTEXT_CHARS);
+    if (re) {
+        const maxMatches = clampPositiveInt(args.maxMatches, DEFAULT_MAX_MATCHES, MAX_MATCHES_CEILING);
+        const results = [];
+        for (const { ordinal, line } of lines) {
+            re.lastIndex = 0;
+            const match = re.exec(line);
+            if (!match)
+                continue;
+            const half = Math.floor(contextChars / 2);
+            const start = Math.max(0, match.index - half);
+            const end = Math.min(line.length, match.index + match[0].length + half);
+            const truncated = start > 0 || end < line.length;
+            results.push({
+                ordinal,
+                excerpt: `${start > 0 ? "…" : ""}${line.slice(start, end)}${end < line.length ? "…" : ""}`,
+                truncated,
+            });
+            if (results.length >= maxMatches)
+                break;
+        }
+        return {
+            ok: true,
+            status: 200,
+            body: {
+                dispatch_id: args.dispatchId,
+                pattern: args.pattern,
+                total_lines: lines.length,
+                matched_lines: results.length,
+                results,
+            },
+        };
+    }
+    const tail = clampPositiveInt(args.tail, DEFAULT_TAIL_LINES, MAX_TAIL_LINES);
+    const results = lines.slice(-tail).map(({ ordinal, line }) => {
+        const truncated = line.length > contextChars;
+        return {
+            ordinal,
+            excerpt: truncated ? `${line.slice(0, contextChars)}…` : line,
+            truncated,
+        };
+    });
+    return {
+        ok: true,
+        status: 200,
+        body: {
+            dispatch_id: args.dispatchId,
+            total_lines: lines.length,
+            returned_lines: results.length,
+            results,
+        },
+    };
+}

package/dist/index.js

@@ -52,6 +52,7 @@
  *   - failure_category_list     GET    /api/failure-categories (DX-2791/DX-2792, board-less)
  *   - failure_category_create   POST   /api/failure-categories (DX-2791/DX-2792, board-less)
  *   - failure_category_update   PATCH  /api/failure-categories/:id (DX-2791/DX-2792, board-less)
+ *   - dispatch_transcript_search  GET  /api/dispatches/:id/logs (DX-3221 — search/tail, no new route)
  *
  * DX-2683 — THE PLAN TOOLS ARE SESSION-BOUND, and asymmetrically so. Reads
  * may name any plan; WRITES take no plan id at all and act on the plan this
@@ -101,7 +102,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, 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, } 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, } from "./handlers.js";
 import { PRIORITY_TIER_WORDS } from "./priority.js";
 function readEnvOrDie(name) {
     const v = process.env[name];
@@ -278,7 +279,7 @@ const sortField = z
     order: z.enum(SORT_ORDERS),
 }))
     .optional()
-    .describe("Multi-column sort — ordered list of {column, order}. Absent → the server's default order (priority desc, repo_name asc, with a numeric-id tiebreaker always appended).");
+    .describe("Multi-column sort — ordered list of {column, order}. Absent → the server's default order (priority desc (higher priority=most urgent first), repo_name asc, with a numeric-id tiebreaker always appended).");
 // DX-1290 — the uniform checklist-item status, extended DX-2653 with
 // `deferred` (a named real-world/post-deploy check still outstanding).
 // Terminal = passing|cancelled|deferred.
@@ -325,7 +326,7 @@ const DESCRIPTION_DESCRIBE = 'The full body ("Context"): evidence, examples, tec
 server.tool("issue_list", 
 // DX-2735: trimmed to pay for the problem tools inside the work-profile
 // injected-surface budget — same facts, no repeated prose.
-"List cards via GET /api/issues. Board-scoped; see `board`. `filter`: type, parent_id, dispatchable_derived, status_derived[], self_dispatchable_derived, assigned_agent, include_closed, include_deleted, q (free text over id+title+description). THE DEFAULT ROW IS MINIMAL — scalars only (id, type, title, status, parent_id, priority, created_at, updated_at, assigned_agent, content_hash), no joins; opt into heavy data with `fields` groups: description (+ summary), problems (open_problem_count — a card needs a human exactly when this is > 0), ac, comments, retro, dependencies, triage, assignment, quality_gates, children, effort. `sort`: [{column, order}] over id|priority|repo_name|title|type|status_derived|triage_ice_total|created_at|updated_at; default priority desc, repo_name asc, numeric-id tiebreaker. `limit`/`offset` page (uncapped by default). issue_get reads one card in full.", {
+"List cards via GET /api/issues. Board-scoped; see `board`. `filter`: type, parent_id, dispatchable_derived, status_derived[], self_dispatchable_derived, assigned_agent, include_closed, include_deleted, q (free text over id+title+description). THE DEFAULT ROW IS MINIMAL — scalars only (id, type, title, status, parent_id, priority, created_at, updated_at, assigned_agent, content_hash), no joins; opt into heavy data with `fields` groups: description (+ summary), problems (open_problem_count — a card needs a human exactly when this is > 0), ac, comments, retro, dependencies, triage, assignment, quality_gates, children, effort. `sort`: [{column, order}] over id|priority|repo_name|title|type|status_derived|triage_ice_total|created_at|updated_at; default priority desc (highest priority=most urgent first), repo_name asc, numeric-id tiebreaker. `limit`/`offset` page (uncapped by default). DX-3113 — `include_closed` defaults to FALSE: a bare call silently excludes every Done/Cancelled card (leaf AND container alike). The response always carries `total` (the full count matching every filter except limit/offset — compare against `issues.length` to tell an exhausted list from a truncated one) and, whenever `include_closed` was not explicitly `true`, `closed_excluded` (how many additional terminal cards the default withheld — re-call with `include_closed: true` to see them). issue_get reads one card in full.", {
     filter: z
         .object({
         q: z.string().optional(),
@@ -421,7 +422,7 @@ server.tool("issue_create", '`plan` is REQUIRED on every create (DX-3006): pass
     ...boardField,
 }, async (args) => jsonResult(await issueCreate(client, args, config.board)));
 // ---------------- issue_edit ----------------
-server.tool("issue_edit", 'Patch a card via PATCH /api/issues/:id/edit. ALLOWED keys: title, summary, description, ac, checklists, effort_level, parent_id, priority, list_id, triage_enabled, type, content_hash. Any other key (lifecycle, triage, dependencies, retro, blocked) is refused 400 with offending_keys[] naming the right tool: issue_transition / issue_triage / issue_comment / issue_dependency / issue_problem / issue_retro. `type`: Story/Bug/Chore = eligible for autonomous pickup; Task or a container (Epic/Feature) removes that eligibility — how a planning item becomes work. `priority` (a tier word or a number) is the ONLY way to set priority; a "Priority:" line in the description does nothing. CHECKLISTS: each item has one status `incomplete|failing|passing|cancelled|deferred`; `deferred` (work done, a real-world/post-deploy check outstanding) REQUIRES `detail`, and a `📡`-prefixed item can never be `passing`. `ac` edits the default "Acceptance Criteria" checklist (items matched by check_item_id, else exact title); `checklists` REPLACES every named checklist with full status control (`{name, items:[{label, detail?, status}]}`). Send `ac` OR `checklists`, not both (400). `list_id` pins the card to a list by id or display NAME; its type must match the card\'s current derived status (400 otherwise — e.g. ready the card first before pinning it to a `ready`-type list); null clears the pin. `content_hash` (DX-2741) is the card\'s optimistic-concurrency token — REQUIRED whenever the edit touches `title` / `description` / `checklists` (NOT `ac`, which keeps its own check_item_id/title diffing): missing → 400, stale → 409 `stale_issue_content` carrying `currentHash` + `currentTitle` + `currentDescription`. Read it off `issue_get`/`issue_list`\'s `content_hash` scalar (present even minimal); on 409, re-`issue_get` and retry with the fresh hash — never blindly.', {
+server.tool("issue_edit", 'Patch a card via PATCH /api/issues/:id/edit. ALLOWED keys: title, summary, description, ac, checklists, effort_level, parent_id, priority, list_id, triage_enabled, type, content_hash. Any other key (lifecycle, triage, dependencies, retro, blocked) is refused 400 with offending_keys[] naming the right tool: issue_transition / issue_triage / issue_comment / issue_dependency / issue_problem / issue_retro. `type`: Story/Bug/Chore = eligible for autonomous pickup; Task or a container (Epic/Feature) removes that eligibility — how a planning item becomes work. `priority` (tier word: "lowest"–"critical", or number 0–6; higher = more urgent, prefer tier word) is the ONLY way to set priority; a "Priority:" line does nothing. CHECKLISTS: each item has one status `incomplete|failing|passing|cancelled|deferred`; `deferred` (work done, a real-world/post-deploy check outstanding) REQUIRES `detail`, and a `📡`-prefixed item can never be `passing`. `ac` edits the default "Acceptance Criteria" checklist (items matched by check_item_id, else exact title); `checklists` REPLACES every named checklist with full status control (`{name, items:[{label, detail?, status}]}`). Send `ac` OR `checklists`, not both (400). `list_id` pins the card to a list by id or display NAME; its type must match the card\'s current derived status (400 otherwise — e.g. ready the card first before pinning it to a `ready`-type list); null clears the pin. `content_hash` (DX-2741) is the card\'s optimistic-concurrency token — REQUIRED whenever the edit touches `title` / `description` / `checklists` (NOT `ac`, which keeps its own check_item_id/title diffing): missing → 400, stale → 409 `stale_issue_content` carrying `currentHash` + `currentTitle` + `currentDescription`. Read it off `issue_get`/`issue_list`\'s `content_hash` scalar (present even minimal); on 409, re-`issue_get` and retry with the fresh hash — never blindly.', {
     id: z.string().min(1),
     title: z.string().min(1).optional().describe(TITLE_DESCRIBE),
     summary: z
@@ -469,7 +470,7 @@ server.tool("issue_edit", 'Patch a card via PATCH /api/issues/:id/edit. ALLOWED
     priority: z
         .union([z.enum(PRIORITY_TIER_WORDS), z.number()])
         .optional()
-        .describe('A tier word ("lowest"…"critical", resolved to the tier midpoint) or a number in [0,6). The only way to set priority.'),
+        .describe('A tier word ("lowest"=0–1…"critical"=5–6; higher number = more urgent, prefer tier word) or number in [0,6); higher numbers are more urgent. The only way to set priority.'),
     list_id: z.string().min(1).nullable().optional(),
     triage_enabled: z
         .boolean()
@@ -938,6 +939,14 @@ server.tool("failure_category_update", "Patch an existing failure category via P
     ignoreReason: z.string().nullable().optional(),
     expectedRate: expectedRateField,
 }, async (args) => jsonResult(await failureCategoryUpdate(client, args)));
+// ---------------- dispatch_transcript_search (DX-3221) ----------------
+server.tool("dispatch_transcript_search", "Search or tail ANOTHER dispatch's stored JSONL session transcript via the existing durable GET /api/dispatches/:id/logs sink (DX-1682/DX-1484) — every worker dispatch's raw transcript lines are already captured there today, so this adds no new server route, only in-process search/windowing. Use this instead of trying to Read a session transcript file directly: it needs no filesystem access to `~/.claude/projects/` (an ordinary authenticated HTTP call, so it never touches worktree-guard or CLAUDE.md Core Principle 5's worktree boundary), and it fixes what Read structurally cannot — Read paginates by LINE, and one persisted JSONL entry can itself be a single line far past Read's 25000-token cap with no way to sub-page inside it; this tool does the string/regex search itself and only ever returns a bounded excerpt AROUND a match, never the whole line. With `pattern`: returns up to `maxMatches` matching lines (case-insensitive regex), each as a windowed excerpt of up to `contextChars` characters centered on the first match. Without `pattern`: returns the most recent `tail` lines instead, each capped at `contextChars` characters (a `truncated: true` flag marks a capped excerpt either way — never a caller-visible error the way an oversized Read would throw). `dispatchId` is a real `dispatches.id` — exactly the ids a failure-repair card's own body already lists under \"dispatches that hit it\".", {
+    dispatchId: z.string().min(1).describe("The dispatch id whose transcript to search — from a failure-repair card's own body, or any other dispatch id you already have."),
+    pattern: z.string().min(1).optional().describe("Case-insensitive regex tested against each raw JSONL line. Omit to get a tail read of the most recent lines instead."),
+    tail: z.number().int().positive().optional().describe("Only used when `pattern` is omitted. How many of the most recent lines to return. Defaults to 20, capped at 200."),
+    contextChars: z.number().int().positive().optional().describe("Characters of context per returned line/match. Defaults to 1000, capped at 4000 — this cap is what keeps even a single oversized line searchable instead of erroring the way Read does."),
+    maxMatches: z.number().int().positive().optional().describe("Only used with `pattern`. Stop after this many matching lines. Defaults to 10, capped at 50."),
+}, async (args) => jsonResult(await dispatchTranscriptSearch(client, args)));
 // ---------------- main ----------------
 async function main() {
     boot();

package/package.json

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