@bli-cockpit/mcp 0.1.2 → 0.1.4

package/dist/tool-result.js

@@ -0,0 +1,105 @@
+/**
+ * What every agent-door tool on this server needs, written once (BLI-3756).
+ *
+ * `docs-msg-tools.ts` and `work-tools.ts` each carried their own copy of these
+ * four helpers. Batch 1 of the MCP twin build added five more surfaces, and
+ * seven copies of "what does a refused door say?" is seven places for the
+ * answer to drift — so the copies became this module and nothing else decides
+ * how a tool names a refusal.
+ *
+ * The one rule worth stating out loud: **a refusal keeps the DOOR's own
+ * words.** The reason label and the sentence are both computed on the server,
+ * where the outcome is known, and relayed here verbatim. A second wording in
+ * this package would be a second thing to keep in step, and the agent reading
+ * it would have no way to tell which one was true.
+ */
+import { z } from "zod";
+import { loadAgentDoorSession } from "./agent-door-session.js";
+export function textResult(text, structured) {
+    return { content: [{ type: "text", text }], ...(structured ? { structuredContent: structured } : {}) };
+}
+export function errorResult(text) {
+    return { isError: true, content: [{ type: "text", text }] };
+}
+/**
+ * The session is loaded fresh per call (a cheap file read) rather than once at
+ * server startup: this package still serves the legacy event-stream tools on a
+ * machine with no collector pairing at all, so a missing session must fail the
+ * ONE call that needed it, by name, and never the whole process.
+ */
+export async function withSession(deps, run) {
+    const loadSession = deps.loadSession ?? loadAgentDoorSession;
+    const loaded = loadSession();
+    if (!loaded.ok) {
+        return errorResult(`This machine is not paired with Tower (${loaded.reason}). ${loaded.message}`);
+    }
+    return run(loaded.session);
+}
+/**
+ * The door's own reason label and its own sentence.
+ *
+ * Two answer shapes are read because two exist on the server and both are
+ * deliberate: the ingest-style routes answer `{reason, message}`, while every
+ * `/api/notes/**` door answers in the shape the BROWSER renders — a `headline`
+ * plus `lines` — because the page and the terminal read the same body
+ * (`commands/notes-door.ts` says why). Reading both here rather than
+ * rephrasing either keeps one meaning per field.
+ */
+export function doorFailureText(door, response) {
+    if (response.transportError) {
+        return `Tower could not be reached for ${door} (${response.transportError}). Nothing was read or written.`;
+    }
+    return `Tower refused ${door} (${doorReason(response.body)}): ${doorSentence(response.body, response.status)}`;
+}
+/** The label a script should branch on. `unknown_error` only when the door named none. */
+export function doorReason(body) {
+    for (const key of ["reason", "error", "code"]) {
+        const value = body[key];
+        if (typeof value === "string" && value.trim() !== "")
+            return value;
+    }
+    return "unknown_error";
+}
+function doorSentence(body, status) {
+    const headline = typeof body["headline"] === "string" ? body["headline"] : null;
+    const message = typeof body["message"] === "string" ? body["message"] : null;
+    const lines = Array.isArray(body["lines"])
+        ? body["lines"].filter((line) => typeof line === "string")
+        : [];
+    const said = [headline ?? message, ...lines].filter(Boolean);
+    return said.length > 0 ? said.join(" ") : `Tower answered ${status}.`;
+}
+/** The one cast, so no tool family repeats it. */
+export function registrarFor(server) {
+    return server.registerTool.bind(server);
+}
+/** `?a=1&b=2`, or "" when nothing was asked for. Never a bare `?`. */
+export function queryString(params) {
+    const rendered = params.toString();
+    return rendered === "" ? "" : `?${rendered}`;
+}
+// ─────────────────────────────────────────────────────────────────────────
+// Deliberate acts (BLI-3756 batch 2)
+// ─────────────────────────────────────────────────────────────────────────
+/**
+ * The `--yes` of this surface.
+ *
+ * `cockpit` refuses a share, a revoke, a role change or a delete that nobody
+ * confirmed: `--yes`, or a person at a keyboard, and nothing else
+ * (`commands/settings.ts` `confirmDestructive`). An MCP client has no
+ * keyboard, so the only half that survives is the explicit flag — and it must
+ * survive, or the surface a model reaches would be the one surface where a
+ * revoke needs no second thought. The reason label is the CLI's own,
+ * `confirmation_required`, so a script branching on it reads the same word
+ * from either door.
+ */
+export const CONFIRM_INPUT = z
+    .boolean()
+    .optional()
+    .describe("Must be true. This act is deliberate and is refused without it — the same rule as the CLI's --yes.");
+/** `null` when the caller confirmed; the refusal itself when they did not. */
+export function unconfirmed(args, sentence) {
+    if (args.confirm === true)
+        return null;
+    return errorResult(`Refused (confirmation_required): ${sentence} Nothing was changed.`);
+}

package/dist/verb-census.d.ts

@@ -39,3 +39,25 @@ export interface TowerVerb {
 export declare function towerNouns(): string[];
 /** Every Tower verb a person may type today. */
 export declare function towerVerbs(): TowerVerb[];
+export interface McpTwin {
+    /** The MCP tool name. Must actually be registered — the suite checks. */
+    tool: string;
+    /** The API door it goes through: the SAME one the CLI verb calls. */
+    door: string;
+}
+/** A CLI verb and the MCP tool that does the same thing, over the same door. */
+export declare const MCP_TWINS: Record<string, McpTwin>;
+/** Verbs that can never have an MCP twin, and why. A claim, not a backlog. */
+export declare const TERMINAL_ONLY: Record<string, string>;
+/**
+ * Verbs owed a twin, with who owes it. This list should only ever shrink.
+ *
+ * **It is empty, and that is the point** (BLI-3756, batch 2, 2026-09-05).
+ * Every `cockpit <noun> <verb>` that talks to Tower now has an MCP tool over
+ * the same door — reads in batch 1, writes in batch 2 — so BLI-3706's rule
+ * holds without an exception: a Tower surface an agent cannot reach is as good
+ * as dead, and there is no surface left in that state. A new entry here is a
+ * new debt, not a normal state; it needs a ticket in its reason and it must
+ * come back out.
+ */
+export declare const AWAITING_TWIN: Record<string, string>;

package/dist/verb-census.js

@@ -63,13 +63,34 @@ function actionAliases() {
  * The `LocalCommand` variants, split the way the union is written: one chunk
  * per `  | {` at the top level of the type.
  */
+/**
+ * The `LocalCommand` union, wherever it currently lives.
+ *
+ * It moved from `local-args.ts` to `local-command-shapes.ts` in BLI-3728, when
+ * `local-args.ts` crossed the 700-line readability ceiling and was split into
+ * "which parser does this argv go to" (there) and "what does a parsed command
+ * look like" (the sibling). Both files are read rather than one, because a
+ * census that silently finds fewer verbs than exist is worse than no census —
+ * this function throwing when it can find the union in NEITHER file is the
+ * whole point, and hardcoding one filename is how it would stop throwing while
+ * being wrong.
+ */
 function commandVariants() {
-    const source = readFileSync(join(COLLECTOR_COMMANDS_DIR, "local-args.ts"), "utf8");
-    const start = source.indexOf("export type LocalCommand =");
-    if (start < 0)
-        throw new Error("LocalCommand union not found in local-args.ts");
-    const end = source.indexOf("\nexport ", start + 10);
-    return source.slice(start, end < 0 ? undefined : end).split(/\n\s{2}\|\s/);
+    for (const file of ["local-command-shapes.ts", "local-args.ts"]) {
+        let source;
+        try {
+            source = readFileSync(join(COLLECTOR_COMMANDS_DIR, file), "utf8");
+        }
+        catch {
+            continue;
+        }
+        const start = source.indexOf("export type LocalCommand =");
+        if (start < 0)
+            continue;
+        const end = source.indexOf("\nexport ", start + 10);
+        return source.slice(start, end < 0 ? undefined : end).split(/\n\s{2}\|\s/);
+    }
+    throw new Error("LocalCommand union not found in local-command-shapes.ts or local-args.ts");
 }
 /** Every Tower verb a person may type today. */
 export function towerVerbs() {
@@ -106,3 +127,84 @@ export function towerVerbs() {
     }
     return verbs.sort((a, b) => a.spelling.localeCompare(b.spelling));
 }
+/** A CLI verb and the MCP tool that does the same thing, over the same door. */
+export const MCP_TWINS = {
+    "docs list": { tool: "docs_list", door: "GET /api/docs/documents" },
+    "docs tree": { tool: "docs_tree", door: "GET /api/docs/tree" },
+    "docs read": { tool: "docs_read", door: "GET /api/docs/documents/[id]" },
+    "docs create": { tool: "docs_create", door: "POST /api/docs/documents" },
+    "docs update": { tool: "docs_update", door: "PATCH /api/docs/documents/[id]" },
+    "msg channels": { tool: "msg_channels", door: "GET /api/msg/channels" },
+    "msg create": { tool: "msg_create_channel", door: "POST /api/msg/channels" },
+    "msg dm": { tool: "msg_dm", door: "POST /api/msg/channels (dm)" },
+    "msg read": { tool: "msg_read", door: "GET /api/msg/channels/[id]/messages" },
+    "msg thread": { tool: "msg_thread", door: "GET /api/msg/channels/[id]/messages?thread_parent_id=" },
+    "msg send": { tool: "msg_send", door: "POST /api/msg/channels/[id]/messages" },
+    "issue list": { tool: "work_list_issues", door: "GET /api/work/issues" },
+    "issue show": { tool: "work_get_issue", door: "GET /api/work/issues/[id]" },
+    "issue create": { tool: "work_create_issue", door: "POST /api/work/issues" },
+    "issue update": { tool: "work_update_issue", door: "PATCH /api/work/issues/[id]" },
+    "issue move": { tool: "work_move_issue", door: "POST /api/work/issues/[id]/state" },
+    "issue comment": { tool: "work_comment_issue", door: "POST /api/work/issues/[id]/comments" },
+    "issue history": { tool: "work_issue_history", door: "GET /api/work/issues/[id]/history" },
+    "project list": { tool: "work_list_projects", door: "GET /api/work/projects" },
+    "brief read": { tool: "brief_read", door: "GET /api/jarvis/brief" },
+    "brief history": { tool: "brief_history", door: "GET /api/jarvis/brief?history=1" },
+    "brief status": { tool: "brief_status", door: "GET /api/ops/brief-status" },
+    "brief rewrite": { tool: "brief_rewrite", door: "POST /api/jarvis/recompile" },
+    correct: { tool: "brief_correct", door: "POST /api/jarvis/corrections" },
+    "notes list": { tool: "notes_list", door: "GET /api/notes/library" },
+    "notes show": { tool: "notes_show", door: "GET /api/notes/library/[id]" },
+    "notes shelf": { tool: "notes_shelf", door: "GET /api/notes/shelf" },
+    "notes shelves": { tool: "notes_shelves", door: "GET /api/notes/library" },
+    "notes upload": { tool: "notes_upload", door: "POST /api/notes/upload" },
+    "notes paste": { tool: "notes_paste", door: "POST /api/notes/upload (text)" },
+    "notes share": { tool: "notes_share", door: "POST /api/notes/share" },
+    "notes unshare": { tool: "notes_unshare", door: "POST /api/notes/share (share=false)" },
+    "notes move": { tool: "notes_move", door: "POST /api/notes/move" },
+    "ops status": { tool: "ops_status", door: "GET /api/ops/status" },
+    "ops recompile": { tool: "ops_recompile", door: "POST /api/ops/recompile" },
+    "slack coverage": { tool: "slack_coverage", door: "GET /api/ops/slack/coverage" },
+    "slack read": { tool: "slack_read", door: "POST /api/ops/slack/read" },
+    "settings show": { tool: "settings_show", door: "GET /api/settings/* + /api/team/members" },
+    "settings list": { tool: "settings_list", door: "GET /api/settings/env-blobs" },
+    "settings set": { tool: "settings_set", door: "POST /api/settings/{jarvis-model,switches,model-routing,env-blobs} + PUT /api/settings/cli-floor" },
+    "settings delete": { tool: "settings_delete", door: "DELETE /api/settings/env-blobs" },
+    "team members": { tool: "team_members", door: "GET /api/team/members" },
+    "team device-list": { tool: "team_device_list", door: "GET /api/team/devices" },
+    "team invite": { tool: "team_invite", door: "POST /api/team/invite" },
+    "team role": { tool: "team_role", door: "PATCH /api/team/members/[userId]/role" },
+    "team device-revoke": { tool: "team_device_revoke", door: "POST /api/ambient/devices/[deviceId]/revoke" },
+    "model show": { tool: "model_show", door: "GET /api/settings/jarvis-model" },
+    "model set": { tool: "model_set", door: "POST /api/settings/jarvis-model" },
+    "scout board": { tool: "scout_board", door: "GET /api/cockpit/scout" },
+    "scout start": { tool: "scout_start", door: "POST /api/cockpit/scout (start)" },
+    "scout dismiss": { tool: "scout_dismiss", door: "POST /api/cockpit/scout (dismiss)" },
+    "scout undo": { tool: "scout_undo", door: "POST /api/cockpit/scout (undo_dismiss)" },
+    workbook: { tool: "workbook_read", door: "GET /api/cockpit/workbook" },
+    // BLI-3728: one search over documents, messages, issues, meeting notes and
+    // memory. `cockpit search` takes no action word — the whole verb is the noun
+    // — so it is keyed on the noun alone, the same way `jarvis` and `workbook`
+    // are.
+    search: { tool: "tower_search", door: "GET /api/search" },
+    jarvis: { tool: "jarvis_ask", door: "POST /api/jarvis/cli" },
+    // Entered by hand: a mode flag, not an `action` the parser names (see the
+    // header of this file).
+    "jarvis --trace": { tool: "jarvis_trace", door: "GET /api/ops/trace/[id]" },
+};
+/** Verbs that can never have an MCP twin, and why. A claim, not a backlog. */
+export const TERMINAL_ONLY = {
+    "brief edit": "opens the person's own $EDITOR on this machine and files what they changed; an agent has no editor to open (commands/editor.ts)",
+};
+/**
+ * Verbs owed a twin, with who owes it. This list should only ever shrink.
+ *
+ * **It is empty, and that is the point** (BLI-3756, batch 2, 2026-09-05).
+ * Every `cockpit <noun> <verb>` that talks to Tower now has an MCP tool over
+ * the same door — reads in batch 1, writes in batch 2 — so BLI-3706's rule
+ * holds without an exception: a Tower surface an agent cannot reach is as good
+ * as dead, and there is no surface left in that state. A new entry here is a
+ * new debt, not a normal state; it needs a ticket in its reason and it must
+ * come back out.
+ */
+export const AWAITING_TWIN = {};

package/dist/work-tools.d.ts

@@ -14,13 +14,8 @@
  * per call, so a machine with no `cockpit login` pairing still serves this
  * server's other tools and only a `work_` call fails, by name.
  */
-import { loadAgentDoorSession } from "./agent-door-session.js";
-import { type FetchImpl } from "./agent-door.js";
-export interface WorkDeps {
-    fetchImpl: FetchImpl;
-    /** Injectable for tests; defaults to reading `~/.config/bli-cockpit/session.json`. */
-    loadSession?: typeof loadAgentDoorSession;
-}
+import { type ToolDeps } from "./tool-result.js";
+export type WorkDeps = ToolDeps;
 /** The closed state vocabulary, verbatim from `lib/work/api-doors.ts` `WORK_ISSUE_STATES`. */
 export declare const WORK_ISSUE_STATES: readonly ["backlog", "todo", "in_progress", "in_review", "done", "canceled"];
 export declare function registerWorkTools(server: {

package/dist/work-tools.js

@@ -15,8 +15,8 @@
  * server's other tools and only a `work_` call fails, by name.
  */
 import { z } from "zod";
-import { loadAgentDoorSession } from "./agent-door-session.js";
 import { callAgentDoor } from "./agent-door.js";
+import { doorFailureText, errorResult, registrarFor, textResult, withSession, } from "./tool-result.js";
 /** The closed state vocabulary, verbatim from `lib/work/api-doors.ts` `WORK_ISSUE_STATES`. */
 export const WORK_ISSUE_STATES = [
     "backlog",
@@ -26,30 +26,17 @@ export const WORK_ISSUE_STATES = [
     "done",
     "canceled",
 ];
-function textResult(text, structured) {
-    return { content: [{ type: "text", text }], ...(structured ? { structuredContent: structured } : {}) };
-}
-function errorResult(text) {
-    return { isError: true, content: [{ type: "text", text }] };
-}
-async function withSession(deps, run) {
-    const loadSession = deps.loadSession ?? loadAgentDoorSession;
-    const loaded = loadSession();
-    if (!loaded.ok)
-        return errorResult(`This machine is not paired with Tower (${loaded.reason}). ${loaded.message}`);
-    return run(loaded.session);
-}
-function doorFailureText(door, response) {
-    if (response.transportError) {
-        return `Tower could not be reached for ${door} (${response.transportError}). Nothing was read or written.`;
+/**
+ * A row the Linear import could not give state names to says which it is.
+ * Printing "(none) -> (none)" is honest and useless; naming the gap keeps
+ * nobody reading a real gap as a broken tool (`commands/issue.ts` says the
+ * same thing in the same words).
+ */
+function historyChange(row) {
+    if (row.from_value === null && row.to_value === null) {
+        return `(no state names recorded — imported from ${row.source ?? "elsewhere"})`;
     }
-    const reason = typeof response.body.reason === "string"
-        ? response.body.reason
-        : typeof response.body.error === "string"
-            ? response.body.error
-            : "unknown_error";
-    const message = typeof response.body.message === "string" ? response.body.message : `Tower answered ${response.status}.`;
-    return `Tower refused ${door} (${reason}): ${message}`;
+    return `${row.from_value ?? "(none)"} -> ${row.to_value ?? "(none)"}`;
 }
 /** A project id from a project NAME or a uuid — exact after case-folding, never fuzzy. */
 async function resolveProjectId(deps, session, ref) {
@@ -67,7 +54,7 @@ const ISSUE_REF = z
     .max(200)
     .describe("A BLI-#### identifier (e.g. BLI-3654) or an issue's uuid. Both work.");
 export function registerWorkTools(server, deps) {
-    const register = server.registerTool.bind(server);
+    const register = registrarFor(server);
     register("work_list_issues", {
         title: "List Tower issues",
         description: "Issues you may see, most recently updated first. Filter by state, assignee (\"me\", \"unassigned\", or a uuid) "
@@ -219,6 +206,29 @@ export function registerWorkTools(server, deps) {
         const comment = response.body.comment;
         return textResult(`Commented on ${ref} (${comment?.id ?? "?"}).`, { comment });
     }));
+    register("work_issue_history", {
+        title: "Read a Tower issue's history",
+        description: "Every recorded change to one issue — state moves, assignee changes — newest first, with who made it and "
+            + "when. History rows are never rewritten; a row imported without state names says so rather than showing "
+            + "\"(none) -> (none)\".",
+        inputSchema: {
+            id: ISSUE_REF,
+            limit: z.number().int().min(1).max(500).optional(),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const ref = String(args.id ?? "");
+        const query = typeof args.limit === "number" ? `?limit=${args.limit}` : "";
+        const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/work/issues/${encodeURIComponent(ref)}/history${query}`);
+        if (!response.ok)
+            return errorResult(doorFailureText("work_issue_history", response));
+        const history = (Array.isArray(response.body.history) ? response.body.history : []);
+        const lines = history
+            .map((row) => `${row.occurred_at ?? "?"}  ${(row.change_type ?? "?").padEnd(9)}  ${historyChange(row)}  `
+            + `${row.actor_name ?? ""}`)
+            .map((line) => line.trimEnd())
+            .join("\n");
+        return textResult(`${history.length} change(s) on ${ref}.${lines ? `\n${lines}` : ""}`, { history });
+    }));
     register("work_list_projects", {
         title: "List Tower projects",
         description: "The projects issues are filed under. Use a project's name with work_list_issues or work_create_issue.",

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@bli-cockpit/mcp",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "private": false,
-  "description": "bli-tower — an MCP server over BLI Cockpit's agent doors: JARVIS (jarvis_*), documents (docs_*), channels (msg_*), issues (work_*), plus the legacy event-stream tools (emit_event, get_ticket_timeline, get_active_tickets).",
+  "description": "bli-tower — an MCP server over BLI Cockpit's agent doors: JARVIS (jarvis_*), documents (docs_*), channels (msg_*), issues (work_*), the daily page (brief_*), meeting notes (notes_*), the ops board (ops_status/slack_*), settings/team/model, Scout and the workbook, plus the legacy event-stream tools (emit_event, get_ticket_timeline, get_active_tickets).",
   "type": "module",
   "bin": {
     "bli-cockpit-mcp": "./dist/index.js"
@@ -25,10 +25,11 @@
     "typecheck": "tsc --noEmit",
     "pretest": "node ../../scripts/build-workspace-dep.mjs @bli-cockpit/telemetry-core",
     "test": "vitest run",
-    "start": "node dist/index.js"
+    "start": "node dist/index.js",
+    "readme": "npm run build && node scripts/write-readme-census.mjs"
   },
   "dependencies": {
-    "@bli-cockpit/telemetry-core": "0.1.28",
+    "@bli-cockpit/telemetry-core": "0.1.29",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.3.6"
   },