@bli-cockpit/mcp 0.1.29 → 0.1.30

package/README.md

@@ -34,7 +34,7 @@ about what an agent can reach.
 
 <!-- BEGIN GENERATED verb census — `npm run mcp:readme` -->
 
-**81 of 84 Tower verbs have an MCP twin.**
+**83 of 86 Tower verbs have an MCP twin.**
 Each tool goes through the SAME door its CLI verb calls, with the same
 collector device token — never a second route and never a service-role
 reader. `src/verb-census.test.ts` fails when a verb is in none of the
@@ -97,6 +97,7 @@ three tables below.
 | `cockpit notes list` | `notes_list` | `GET /api/notes/library` |
 | `cockpit notes move` | `notes_move` | `POST /api/notes/move` |
 | `cockpit notes paste` | `notes_paste` | `POST /api/notes/upload (text)` |
+| `cockpit notes place` | `notes_place` | `POST /api/notes/place` |
 | `cockpit notes share` | `notes_share` | `POST /api/notes/share` |
 | `cockpit notes shelf` | `notes_shelf` | `GET /api/notes/shelf` |
 | `cockpit notes shelves` | `notes_shelves` | `GET /api/notes/library` |
@@ -111,17 +112,18 @@ three tables below.
 | `cockpit scout start` | `scout_start` | `POST /api/cockpit/scout (start)` |
 | `cockpit scout undo` | `scout_undo` | `POST /api/cockpit/scout (undo_dismiss)` |
 | `cockpit search` | `tower_search` | `GET /api/search` |
-| `cockpit settings delete` | `settings_delete` | `DELETE /api/settings/env-blobs` |
-| `cockpit settings list` | `settings_list` | `GET /api/settings/env-blobs` |
-| `cockpit settings set` | `settings_set` | `POST /api/settings/{jarvis-model,switches,model-routing,env-blobs} + PUT /api/settings/cli-floor` |
-| `cockpit settings show` | `settings_show` | `GET /api/settings/* + /api/team/members` |
+| `cockpit settings env delete` | `settings_delete` | `DELETE /api/settings/env-blobs` |
+| `cockpit settings env list` | `settings_list` | `GET /api/settings/env-blobs` |
+| `cockpit settings switches set` | `settings_set` | `POST /api/settings/{jarvis-model,switches,model-routing,env-blobs} + PUT /api/settings/cli-floor` |
+| `cockpit settings` | `settings_show` | `GET /api/settings/* + /api/team/members` |
 | `cockpit slack coverage` | `slack_coverage` | `GET /api/ops/slack/coverage` |
 | `cockpit slack read` | `slack_read` | `POST /api/ops/slack/read` |
-| `cockpit team device-list` | `team_device_list` | `GET /api/team/devices` |
-| `cockpit team device-revoke` | `team_device_revoke` | `POST /api/ambient/devices/[deviceId]/revoke` |
+| `cockpit team device list` | `team_device_list` | `GET /api/team/devices` |
+| `cockpit team device revoke` | `team_device_revoke` | `POST /api/ambient/devices/[deviceId]/revoke` |
 | `cockpit team invite` | `team_invite` | `POST /api/team/invite` |
 | `cockpit team members` | `team_members` | `GET /api/team/members` |
 | `cockpit team role` | `team_role` | `PATCH /api/team/members/[userId]/role` |
+| `cockpit usage people` | `usage_people` | `GET /api/usage/people` |
 | `cockpit workbook` | `workbook_read` | `GET /api/cockpit/workbook` |
 
 ### Owed a twin

package/dist/notes-write-tools.js

@@ -199,6 +199,31 @@ export function registerNotesWriteTools(server, deps) {
             ? textResult(text, { ok: true, shelf: body.shelf ?? null })
             : errorResult(text);
     }));
+    register("notes_place", {
+        title: "Say which shelf a Tower meeting note belongs on",
+        description: "Answers where one note files itself and WHY, from the meeting series it is part of, who was in the room "
+            + "and its own name — no model call. Read-only unless `apply: true`, which files it there. It never "
+            + "overrules a shelf a person typed: a note that already has one comes back as `already_shelved`.",
+        inputSchema: {
+            note_id: z.string().min(1).max(200).describe("A note id."),
+            apply: z.boolean().optional().describe("Actually put it there. Default: only say where."),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const response = await callAgentDoor(session, deps.fetchImpl, "POST", "/api/notes/place", { note_id: String(args.note_id ?? ""), apply: args.apply === true }, WRITE_DEADLINE_MS);
+        if (!response.ok)
+            return errorResult(doorFailureText("notes_place", response));
+        const body = response.body;
+        const text = [body.headline ?? "Tower answered without a sentence.", ...(body.lines ?? [])].join("\n");
+        return body.ok === true
+            ? textResult(text, {
+                ok: true,
+                shelf: body.shelf ?? null,
+                suggested_shelf: body.suggestedShelf ?? null,
+                decided_by: body.decidedBy ?? null,
+                applied: body.applied === true,
+            })
+            : errorResult(text);
+    }));
 }
 /** Share and unshare are one door and one body; only the boolean differs. */
 async function shareCall(deps, session, args, share) {

package/dist/readme-census.js

@@ -11,12 +11,17 @@
  * and returns a string. No file writing here — that is the script's job, so
  * this can be asserted without touching a disk.
  */
-import { AWAITING_TWIN, MCP_TWINS, TERMINAL_ONLY, towerVerbs } from "./verb-census.js";
+import { AWAITING_TWIN, MCP_TWINS, TERMINAL_ONLY, towerVerbs, typedSpelling } from "./verb-census.js";
 export const CENSUS_BEGIN = "<!-- BEGIN GENERATED verb census — `npm run mcp:readme` -->";
 export const CENSUS_END = "<!-- END GENERATED verb census -->";
-/** `cockpit docs read` → `` `cockpit docs read` ``; `jarvis --trace` keeps its flag. */
+/**
+ * `cockpit docs read` → `` `cockpit docs read` ``; `jarvis --trace` keeps its
+ * flag. A census key whose grammar differs from the typed command is rendered
+ * as the command (`settings show` → `cockpit settings`), because this column is
+ * headed "CLI verb" and a reader takes it literally (BLI-4048).
+ */
 function spell(verb) {
-    return `\`cockpit ${verb}\``;
+    return `\`cockpit ${typedSpelling(verb)}\``;
 }
 export function renderCensusMarkdown() {
     // Every verb the collector's own tables name, plus the one hand-entered mode

package/dist/server.js

@@ -23,6 +23,7 @@ import { registerSettingsTools } from "./settings-tools.js";
 import { registerSettingsWriteTools } from "./settings-write-tools.js";
 import { registerTeamWriteTools } from "./team-write-tools.js";
 import { registerWorkTools } from "./work-tools.js";
+import { registerUsageTools } from "./usage-tools.js";
 export const PACKAGE_NAME = "@bli-cockpit/mcp";
 export const PACKAGE_VERSION = "0.1.4";
 // ---- input schemas (Zod raw shapes) -----------------------------------------
@@ -390,6 +391,7 @@ export function createServer(deps) {
     // the docs/msg tools above, for the same reason: a coding session should
     // file and move a Tower issue the way it files and moves a Linear one.
     registerWorkTools(server, { fetchImpl: deps.fetchImpl });
+    registerUsageTools(server, { fetchImpl: deps.fetchImpl });
     // BLI-3708: the mailboxes a person attached. Reads, a send and a sync over
     // the same /api/mail/** doors `cockpit mail` calls; `add-imap` deliberately
     // has no twin (see mail-tools.ts's header — a credential is not a tool

package/dist/usage-tools.d.ts

@@ -0,0 +1,4 @@
+import { type ToolDeps } from "./tool-result.js";
+export declare function registerUsageTools(server: {
+    registerTool: (...args: never[]) => unknown;
+}, deps: ToolDeps): void;

package/dist/usage-tools.js

@@ -0,0 +1,21 @@
+import { z } from "zod";
+import { callAgentDoor } from "./agent-door.js";
+import { doorFailureText, errorResult, registrarFor, textResult, withSession } from "./tool-result.js";
+export function registerUsageTools(server, deps) {
+    registrarFor(server)("usage_people", {
+        title: "Read usage by person",
+        description: "Per-person Claude Code and Codex token usage, list-price equivalent, and extraction coverage.",
+        inputSchema: { since: z.string().optional().describe("30d or an ISO timestamp."), until: z.string().optional(), include_automated: z.boolean().optional() },
+    }, async (args) => withSession(deps, async (session) => {
+        const query = new URLSearchParams({ since: String(args.since ?? "30d") });
+        if (args.until)
+            query.set("until", String(args.until));
+        if (args.include_automated)
+            query.set("include_automated", "1");
+        const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/usage/people?${query}`);
+        if (!response.ok)
+            return errorResult(doorFailureText("usage_people", response));
+        const coverage = response.body.coverage;
+        return textResult(`${coverage?.sessions_extracted ?? 0} of ${coverage?.sessions_observed ?? 0} sessions extracted.`, response.body);
+    }));
+}

package/dist/verb-census.d.ts

@@ -67,6 +67,30 @@ export interface McpTwin {
 }
 /** A CLI verb and the MCP tool that does the same thing, over the same door. */
 export declare const MCP_TWINS: Record<string, McpTwin>;
+/**
+ * Census key → what a person actually types. (BLI-4048)
+ *
+ * The keys above are derived MECHANICALLY from each noun's `action` union, and
+ * for two nouns that union is not the grammar. `settings`'s positional is a
+ * SECTION (`personal|switches|models|env|cli-floor`) and the `action` is what
+ * the parser decides afterwards; `team`'s `device-list` is one action word
+ * spelled as two typed words, `team device list`. So `cockpit settings show`
+ * and `cockpit team device-list` were rendered into the README's "CLI verb"
+ * column and into `cli-caller-identity.md`, and the CLI refused all six.
+ *
+ * This is the display layer and nothing else: the keys, the twin rule and the
+ * suite are untouched. Every spelling here is proven typable —
+ * `scripts/doc-doors.test.mjs` runs the rendered table through the collector's
+ * own parser, so a wrong entry fails the build rather than misleading a
+ * stranger. Where one tool serves several sections (`settings_set` writes any
+ * of them) the spelling names ONE of them and the door column names the rest.
+ *
+ * A verb whose key is already typable is absent from here on purpose; the
+ * shorter this map is, the closer the census keys are to the product.
+ */
+export declare const TYPED_SPELLING: Record<string, string>;
+/** How a census key is written when a person is being told to type it. */
+export declare function typedSpelling(verb: string): string;
 /** Verbs that can never have an MCP twin, and why. A claim, not a backlog. */
 export declare const TERMINAL_ONLY: Record<string, string>;
 /**

package/dist/verb-census.js

@@ -209,6 +209,7 @@ export function memoryMcpToolNames() {
 }
 /** A CLI verb and the MCP tool that does the same thing, over the same door. */
 export const MCP_TWINS = {
+    "usage people": { tool: "usage_people", door: "GET /api/usage/people" },
     "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]" },
@@ -259,6 +260,7 @@ export const MCP_TWINS = {
     "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" },
+    "notes place": { tool: "notes_place", door: "POST /api/notes/place" },
     "memory log": { tool: "memory_experience", door: "POST /api/memory/experience" },
     // BLI-4047: the memory STORE at a terminal. The twins live on the second
     // server, `bli-memory`, over the same four doors these CLI verbs call.
@@ -302,6 +304,39 @@ export const MCP_TWINS = {
     // header of this file).
     "jarvis --trace": { tool: "jarvis_trace", door: "GET /api/ops/trace/[id]" },
 };
+/**
+ * Census key → what a person actually types. (BLI-4048)
+ *
+ * The keys above are derived MECHANICALLY from each noun's `action` union, and
+ * for two nouns that union is not the grammar. `settings`'s positional is a
+ * SECTION (`personal|switches|models|env|cli-floor`) and the `action` is what
+ * the parser decides afterwards; `team`'s `device-list` is one action word
+ * spelled as two typed words, `team device list`. So `cockpit settings show`
+ * and `cockpit team device-list` were rendered into the README's "CLI verb"
+ * column and into `cli-caller-identity.md`, and the CLI refused all six.
+ *
+ * This is the display layer and nothing else: the keys, the twin rule and the
+ * suite are untouched. Every spelling here is proven typable —
+ * `scripts/doc-doors.test.mjs` runs the rendered table through the collector's
+ * own parser, so a wrong entry fails the build rather than misleading a
+ * stranger. Where one tool serves several sections (`settings_set` writes any
+ * of them) the spelling names ONE of them and the door column names the rest.
+ *
+ * A verb whose key is already typable is absent from here on purpose; the
+ * shorter this map is, the closer the census keys are to the product.
+ */
+export const TYPED_SPELLING = {
+    "settings show": "settings",
+    "settings list": "settings env list",
+    "settings set": "settings switches set",
+    "settings delete": "settings env delete",
+    "team device-list": "team device list",
+    "team device-revoke": "team device revoke",
+};
+/** How a census key is written when a person is being told to type it. */
+export function typedSpelling(verb) {
+    return TYPED_SPELLING[verb] ?? verb;
+}
 /** Verbs that can never have an MCP twin, and why. A claim, not a backlog. */
 export const TERMINAL_ONLY = {
     "mail add-imap": "carries a Google app password. The CLI reads it from STDIN precisely so it never lands in an argument list; an MCP tool argument travels through a model's context window and whatever transcript store sits behind it, so attaching a mailbox stays a thing a person does at a terminal (BLI-3708)",

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@bli-cockpit/mcp",
-  "version": "0.1.29",
+  "version": "0.1.30",
   "private": false,
-  "description": "bli-tower \u2014 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).",
+  "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"
@@ -30,7 +30,7 @@
     "readme": "npm run build && node scripts/write-readme-census.mjs"
   },
   "dependencies": {
-    "@bli-cockpit/telemetry-core": "0.1.42",
+    "@bli-cockpit/telemetry-core": "0.1.43",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.3.6"
   },