@bli-cockpit/mcp 0.1.5 → 0.1.7

package/README.md

@@ -34,7 +34,7 @@ about what an agent can reach.
 
 <!-- BEGIN GENERATED verb census — `npm run mcp:readme` -->
 
-**56 of 57 Tower verbs have an MCP twin.**
+**64 of 66 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
@@ -61,6 +61,14 @@ three tables below.
 | `cockpit issue update` | `work_update_issue` | `PATCH /api/work/issues/[id]` |
 | `cockpit jarvis` | `jarvis_ask` | `POST /api/jarvis/cli` |
 | `cockpit jarvis --trace` | `jarvis_trace` | `GET /api/ops/trace/[id]` |
+| `cockpit mail accounts` | `mail_accounts` | `GET /api/mail/accounts` |
+| `cockpit mail attachment` | `mail_attachment` | `GET /api/mail/attachments/[id]?meta=1` |
+| `cockpit mail detach` | `mail_detach` | `DELETE /api/mail/accounts` |
+| `cockpit mail inbox` | `mail_inbox` | `GET /api/mail/inbox` |
+| `cockpit mail read` | `mail_read` | `GET /api/mail/threads/[id]` |
+| `cockpit mail search` | `mail_search` | `GET /api/mail/search` |
+| `cockpit mail send` | `mail_send` | `POST /api/mail/send` |
+| `cockpit mail sync` | `mail_sync` | `POST /api/mail/accounts/[id]/sync` |
 | `cockpit model set` | `model_set` | `POST /api/settings/jarvis-model` |
 | `cockpit model show` | `model_show` | `GET /api/settings/jarvis-model` |
 | `cockpit msg channels` | `msg_channels` | `GET /api/msg/channels` |
@@ -112,6 +120,7 @@ A claim about the verb's nature, not a backlog.
 | CLI verb | Why it can never have a twin |
 | --- | --- |
 | `cockpit 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) |
+| `cockpit 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) |
 
 <!-- END GENERATED verb census -->
 

package/dist/mail-tools.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `mail_*` MCP tools (BLI-3708) — the mailboxes a person attached, on the
+ * `bli-tower` server, over the same `/api/mail/**` doors `cockpit mail` and
+ * the browser call, authenticated with this machine's collector device token.
+ *
+ * The point, in one sentence: an agent working on somebody's behalf should be
+ * able to READ the mail that explains a ticket — the invoice, the vendor's
+ * reply, the bank notice — and send a reply, without a browser and without a
+ * second copy of anybody's credentials.
+ *
+ * TWO DELIBERATE ASYMMETRIES with the CLI, both recorded in `verb-census.ts`:
+ *
+ * - **`cockpit mail add-imap` has NO MCP twin.** It carries a Google app
+ *   password, and the CLI takes that on stdin precisely so it never lands in
+ *   an argument list. An MCP tool argument IS an argument list — it travels
+ *   through a model's context window and whatever transcript store sits behind
+ *   it. Attaching a mailbox stays a thing a person does at a terminal.
+ * - **`mail_attachment` answers METADATA, not bytes.** The CLI writes the file
+ *   to `--out <path>`; an MCP tool has nowhere to put ten megabytes but the
+ *   conversation. It returns the same `?meta=1` read the CLI uses to describe
+ *   a file before downloading it, and names the command that fetches it.
+ *
+ * Same session discipline as `work-tools.ts`: the session is loaded fresh per
+ * call, so a machine with no `cockpit login` pairing still serves this
+ * server's other tools and only a `mail_` call fails, by name.
+ */
+import { type ToolDeps } from "./tool-result.js";
+export type MailDeps = ToolDeps;
+export declare function registerMailTools(server: {
+    registerTool: (...args: never[]) => unknown;
+}, deps: MailDeps): void;

package/dist/mail-tools.js

@@ -0,0 +1,204 @@
+/**
+ * `mail_*` MCP tools (BLI-3708) — the mailboxes a person attached, on the
+ * `bli-tower` server, over the same `/api/mail/**` doors `cockpit mail` and
+ * the browser call, authenticated with this machine's collector device token.
+ *
+ * The point, in one sentence: an agent working on somebody's behalf should be
+ * able to READ the mail that explains a ticket — the invoice, the vendor's
+ * reply, the bank notice — and send a reply, without a browser and without a
+ * second copy of anybody's credentials.
+ *
+ * TWO DELIBERATE ASYMMETRIES with the CLI, both recorded in `verb-census.ts`:
+ *
+ * - **`cockpit mail add-imap` has NO MCP twin.** It carries a Google app
+ *   password, and the CLI takes that on stdin precisely so it never lands in
+ *   an argument list. An MCP tool argument IS an argument list — it travels
+ *   through a model's context window and whatever transcript store sits behind
+ *   it. Attaching a mailbox stays a thing a person does at a terminal.
+ * - **`mail_attachment` answers METADATA, not bytes.** The CLI writes the file
+ *   to `--out <path>`; an MCP tool has nowhere to put ten megabytes but the
+ *   conversation. It returns the same `?meta=1` read the CLI uses to describe
+ *   a file before downloading it, and names the command that fetches it.
+ *
+ * Same session discipline as `work-tools.ts`: the session is loaded fresh per
+ * call, so a machine with no `cockpit login` pairing still serves this
+ * server's other tools and only a `mail_` call fails, by name.
+ */
+import { z } from "zod";
+import { callAgentDoor } from "./agent-door.js";
+import { CONFIRM_INPUT, doorFailureText, errorResult, queryString, registrarFor, textResult, unconfirmed, withSession, } from "./tool-result.js";
+function messageLine(message) {
+    const from = message.from_address?.address ?? "(no sender)";
+    return `${message.is_unread ? "*" : " "} ${message.internal_date.slice(0, 16)}  ${from}  ${message.subject ?? "(no subject)"}  [thread ${message.thread_id ?? "?"}]`;
+}
+const ADDRESS = z.string().email().max(320);
+export function registerMailTools(server, deps) {
+    const register = registrarFor(server);
+    register("mail_accounts", {
+        title: "List attached mailboxes",
+        description: "Every mailbox attached to Tower that you may see — address, provider (gmail_oauth or imap), health and last sync. "
+            + "One person may have several; there is no default mailbox anywhere in this surface, so start here when you need an account id.",
+        inputSchema: {},
+    }, async () => withSession(deps, async (session) => {
+        const response = await callAgentDoor(session, deps.fetchImpl, "GET", "/api/mail/accounts");
+        if (!response.ok)
+            return errorResult(doorFailureText("mail_accounts", response));
+        const accounts = (Array.isArray(response.body.accounts) ? response.body.accounts : []);
+        const lines = accounts
+            .map((account) => `${account.address}  ${account.provider}  ${account.status}${account.status_reason ? ` (${account.status_reason})` : ""}  ${account.id}`)
+            .join("\n");
+        return textResult(accounts.length === 0
+            ? "No mailboxes are attached. A person attaches one with `cockpit mail add-imap` (personal) or the browser (work)."
+            : `${accounts.length} mailbox(es).\n${lines}`, { accounts });
+    }));
+    register("mail_inbox", {
+        title: "Read the unified inbox",
+        description: "Messages across every mailbox you may read, newest first. Never a body — call mail_read on a thread for that. "
+            + "`account_id` narrows to one mailbox; `unread` and `label` filter; `before` (an ISO instant) pages backwards.",
+        inputSchema: {
+            account_id: z.string().uuid().optional(),
+            unread: z.boolean().optional(),
+            label: z.string().min(1).max(100).optional(),
+            before: z.string().min(1).max(40).optional(),
+            limit: z.number().int().min(1).max(200).optional(),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const query = new URLSearchParams();
+        if (args.account_id)
+            query.set("account_id", String(args.account_id));
+        if (args.unread === true)
+            query.set("unread", "1");
+        if (args.label)
+            query.set("label", String(args.label));
+        if (args.before)
+            query.set("before", String(args.before));
+        if (args.limit)
+            query.set("limit", String(args.limit));
+        const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/mail/inbox${queryString(query)}`);
+        if (!response.ok)
+            return errorResult(doorFailureText("mail_inbox", response));
+        const messages = (Array.isArray(response.body.messages) ? response.body.messages : []);
+        return textResult(messages.length === 0
+            ? "No mail matches that."
+            : `${messages.length} message(s).\n${messages.map(messageLine).join("\n")}`, { messages, accounts: response.body.accounts ?? [] });
+    }));
+    register("mail_read", {
+        title: "Read one conversation",
+        description: "One thread with every message's text body, oldest first. Thread ids come from mail_inbox or mail_search. "
+            + "Read the thread before saying what somebody wrote — a snippet is the first 240 characters and nothing more.",
+        inputSchema: { thread_id: z.string().uuid() },
+    }, async (args) => withSession(deps, async (session) => {
+        const threadId = String(args.thread_id ?? "");
+        const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/mail/threads/${encodeURIComponent(threadId)}`);
+        if (!response.ok)
+            return errorResult(doorFailureText("mail_read", response));
+        const thread = response.body.thread;
+        const messages = (Array.isArray(response.body.messages) ? response.body.messages : []);
+        const rendered = messages
+            .map((message) => `--- ${message.internal_date} ${message.from_address?.address ?? "(no sender)"} [${message.id}]\n`
+            + (message.body_text ?? message.snippet ?? "(no text body — this message is HTML only)").trim())
+            .join("\n\n");
+        return textResult(`${thread?.subject ?? "(no subject)"} — ${thread?.account_address ?? "?"}, ${messages.length} message(s)\n\n${rendered}`, { thread, messages });
+    }));
+    register("mail_search", {
+        title: "Search your mail",
+        description: "Full text over the subject and plain-text body of every message you may read. Quoted phrases and OR work the way "
+            + "they do in a search box. Returns headers only; call mail_read on a hit's thread to read it.",
+        inputSchema: {
+            query: z.string().min(1).max(400),
+            account_id: z.string().uuid().optional(),
+            limit: z.number().int().min(1).max(200).optional(),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const query = new URLSearchParams({ q: String(args.query ?? "") });
+        if (args.account_id)
+            query.set("account_id", String(args.account_id));
+        if (args.limit)
+            query.set("limit", String(args.limit));
+        const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/mail/search${queryString(query)}`);
+        if (!response.ok)
+            return errorResult(doorFailureText("mail_search", response));
+        const matches = (Array.isArray(response.body.matches) ? response.body.matches : []);
+        return textResult(matches.length === 0
+            ? `Nothing in your mail matched "${String(args.query)}".`
+            : `${matches.length} match(es).\n${matches.map(messageLine).join("\n")}`, { matches });
+    }));
+    register("mail_send", {
+        title: "Send mail from one mailbox",
+        description: "Sends a message. `account_id` is REQUIRED and is the address it goes out from — with several mailboxes attached, "
+            + "that is never something to guess. `in_reply_to_message_id` (a message id from mail_read) threads the reply. "
+            + "This actually sends mail to real people: confirm must be true.",
+        inputSchema: {
+            account_id: z.string().uuid(),
+            to: z.array(ADDRESS).min(1).max(50),
+            cc: z.array(ADDRESS).max(50).optional(),
+            subject: z.string().max(998),
+            text: z.string().min(1).max(500_000),
+            in_reply_to_message_id: z.string().uuid().optional(),
+            confirm: CONFIRM_INPUT,
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const refusal = unconfirmed(args, "Sending mail reaches real people and cannot be recalled.");
+        if (refusal)
+            return refusal;
+        const response = await callAgentDoor(session, deps.fetchImpl, "POST", "/api/mail/send", {
+            account_id: args.account_id,
+            to: args.to.map((address) => ({ address })),
+            ...(Array.isArray(args.cc) && args.cc.length > 0
+                ? { cc: args.cc.map((address) => ({ address })) }
+                : {}),
+            subject: args.subject ?? "",
+            text: args.text,
+            ...(args.in_reply_to_message_id ? { in_reply_to_message_id: args.in_reply_to_message_id } : {}),
+        });
+        if (!response.ok)
+            return errorResult(doorFailureText("mail_send", response));
+        const sent = response.body.sent;
+        return textResult(`Sent from ${sent?.address ?? "that mailbox"} to ${args.to.join(", ")}${sent?.threaded ? " (as a reply)" : ""}.`, { sent });
+    }));
+    register("mail_attachment", {
+        title: "Describe an attachment",
+        description: "The filename, mime type and size of one attachment. Attachments are POINTERS in Tower — nothing is stored — and "
+            + "the bytes are not returned here: `cockpit mail attachment <id> --out <path>` downloads the file at a terminal.",
+        inputSchema: { attachment_id: z.string().uuid() },
+    }, async (args) => withSession(deps, async (session) => {
+        const id = String(args.attachment_id ?? "");
+        const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/mail/attachments/${encodeURIComponent(id)}?meta=1`);
+        if (!response.ok)
+            return errorResult(doorFailureText("mail_attachment", response));
+        const attachment = response.body.attachment;
+        return textResult(`${attachment?.filename ?? "(unnamed)"} — ${attachment?.mime_type ?? "unknown type"}, ${attachment?.size_bytes ?? "?"} bytes. `
+            + `Download it with: cockpit mail attachment ${id} --out <path>`, { attachment });
+    }));
+    register("mail_sync", {
+        title: "Read a mailbox now",
+        description: "Runs one sync pass on one mailbox instead of waiting for the 15-minute cron, and answers with what landed or the "
+            + "reason it did not (token_revoked, history_gap, auth_failed, quota…). Only the mailbox's OWNER may do this.",
+        inputSchema: { account_id: z.string().uuid() },
+    }, async (args) => withSession(deps, async (session) => {
+        const id = String(args.account_id ?? "");
+        const response = await callAgentDoor(session, deps.fetchImpl, "POST", `/api/mail/accounts/${encodeURIComponent(id)}/sync`);
+        if (!response.ok)
+            return errorResult(doorFailureText("mail_sync", response));
+        const run = response.body.run;
+        if (run?.reason && run.reason !== "ok") {
+            return errorResult(`That mailbox did not sync (${run.reason})${run.detail ? `: ${run.detail}` : ""}.`);
+        }
+        return textResult(`Synced: ${run?.messagesAdded ?? 0} new, ${run?.messagesUpdated ?? 0} updated.`, { run: run ?? {} });
+    }));
+    register("mail_detach", {
+        title: "Detach a mailbox",
+        description: "Removes a mailbox from Tower along with its stored mail and its credential. The mail itself is untouched at the "
+            + "provider — this unhooks Tower, it does not delete anybody's email. Irreversible here: confirm must be true.",
+        inputSchema: { account_id: z.string().uuid(), confirm: CONFIRM_INPUT },
+    }, async (args) => withSession(deps, async (session) => {
+        const refusal = unconfirmed(args, "Detaching removes this mailbox's stored mail from Tower.");
+        if (refusal)
+            return refusal;
+        const id = String(args.account_id ?? "");
+        const response = await callAgentDoor(session, deps.fetchImpl, "DELETE", `/api/mail/accounts?account_id=${encodeURIComponent(id)}`);
+        if (!response.ok)
+            return errorResult(doorFailureText("mail_detach", response));
+        return textResult(`Detached ${id}. Its stored mail and its credential went with it.`, { detached: id });
+    }));
+}

package/dist/server.js

@@ -10,6 +10,7 @@ import { registerBriefTools } from "./brief-tools.js";
 import { registerBriefWriteTools } from "./brief-write-tools.js";
 import { registerDocsMsgTools } from "./docs-msg-tools.js";
 import { registerJarvisTools } from "./jarvis-tools.js";
+import { registerMailTools } from "./mail-tools.js";
 import { registerNotesTools } from "./notes-tools.js";
 import { registerNotesWriteTools } from "./notes-write-tools.js";
 import { registerOpsTools } from "./ops-tools.js";
@@ -386,6 +387,11 @@ 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 });
+    // 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
+    // argument).
+    registerMailTools(server, { fetchImpl: deps.fetchImpl });
     // BLI-3732: `jarvis_*` — the assistant itself, on the same device-token path
     // as the three families above, over the doors `cockpit jarvis` already
     // calls. It is the last Tower surface that had a CLI door and no MCP one.

package/dist/verb-census.js

@@ -148,6 +148,14 @@ export const MCP_TWINS = {
     "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" },
+    "mail accounts": { tool: "mail_accounts", door: "GET /api/mail/accounts" },
+    "mail inbox": { tool: "mail_inbox", door: "GET /api/mail/inbox" },
+    "mail read": { tool: "mail_read", door: "GET /api/mail/threads/[id]" },
+    "mail search": { tool: "mail_search", door: "GET /api/mail/search" },
+    "mail send": { tool: "mail_send", door: "POST /api/mail/send" },
+    "mail attachment": { tool: "mail_attachment", door: "GET /api/mail/attachments/[id]?meta=1" },
+    "mail sync": { tool: "mail_sync", door: "POST /api/mail/accounts/[id]/sync" },
+    "mail detach": { tool: "mail_detach", door: "DELETE /api/mail/accounts" },
     "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" },
@@ -194,6 +202,7 @@ export const MCP_TWINS = {
 };
 /** 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)",
     "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)",
 };
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/mcp",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "private": false,
   "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",
@@ -29,7 +29,7 @@
     "readme": "npm run build && node scripts/write-readme-census.mjs"
   },
   "dependencies": {
-    "@bli-cockpit/telemetry-core": "0.1.29",
+    "@bli-cockpit/telemetry-core": "0.1.30",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.3.6"
   },