@bli-cockpit/mcp 0.1.82 → 0.1.84

package/README.md

@@ -1,5 +1,7 @@
 # @bli-cockpit/mcp — bli-tower
 
+**Connecting an agent? Start at [`docs/onboarding/connect-an-agent-to-tower.md`](../../docs/onboarding/connect-an-agent-to-tower.md):** supported clients, setup, verify, troubleshooting. This file is the tool reference.
+
 Two, deliberately separate, tool families over one MCP server (bin
 `bli-cockpit-mcp`, server id `bli-tower`):
 
@@ -34,9 +36,13 @@ refusal words, so the choice is about where the agent runs and what it costs.
   CLI, `cockpit <noun> <verb>`. Nothing loads into the context window until a
   command runs, the human-readable output is the tersest form of every read,
   and a person can run the exact same line to check it.
-- **The agent has no shell** (claude.ai, Claude Desktop chat, IDE chat panes,
-  any connector-only host): use this server. It is the only door those hosts
-  have.
+- **The agent has no shell** (Claude Desktop chat, IDE chat panes, any host
+  that can start a local stdio server): use this server. It is the only door
+  those hosts have. The claude.ai web app, ChatGPT and dot cannot start a local
+  program; they use Tower's hosted address, `https://<dashboard>/api/mcp`, with
+  "Sign in with Tower" (BLI-12416, pending its first live proof; see the connect
+  page's "Remote hosts"). The hosted server is `@bli-cockpit/mcp/remote`, built
+  from the same `createServer`, minus the five laptop-only tools.
 
 Measured on 2026-09-26 against production, same account, same moment. Bytes
 the model actually reads; tokens are an estimate at about 4 bytes a token.
@@ -59,7 +65,7 @@ unless a script needs the fields.
 
 **Which half a host shows the model.** A tool result has a text half
 (`content`) and a structured half (`structuredContent`), and hosts disagree:
-Claude Code, claude.ai and Claude Desktop give the model the text half; Codex
+Claude Code and Claude Desktop give the model the text half; Codex
 gives it the structured half and drops the text. Every read on this server is
 written so EACH half stands alone. That was not always true: until BLI-10432,
 `docs_list`, `msg_channels`, `msg_read`, every `careers_*` tool,
@@ -103,7 +109,7 @@ about what an agent can reach.
 
 <!-- BEGIN GENERATED verb census — `npm run mcp:readme` -->
 
-**123 of 128 Tower verbs have an MCP twin.**
+**124 of 129 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
@@ -166,6 +172,7 @@ three tables below.
 | `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 draft` | `mail_draft` | `POST /api/mail/drafts` |
 | `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` |
@@ -503,16 +510,37 @@ the account.
 
 ## Install
 
+**Current path (every tool except the three legacy ones).** Install the CLI and
+let it register the server:
+
+```bash
+npm i -g @bli-cockpit/cli && cockpit doctor
+```
+
+`cockpit doctor` signs the machine in (device token in
+`~/.config/bli-cockpit/session.json`) and registers `bli-tower` in
+`~/.claude.json` and `~/.codex/config.toml`. See "Registration on an intern
+machine" above, and the
+[connect page](../../docs/onboarding/connect-an-agent-to-tower.md) for manual
+registration in Claude Desktop or any other stdio host, verification and
+troubleshooting.
+
+**Building from this checkout** (development only):
+
 ```bash
 npm install        # from repo root — registers the workspace
 npm run build --workspace=@bli-cockpit/mcp
 ```
 
-The `bin` entry exposes a `bli-cockpit-mcp` CLI that speaks MCP over stdio.
+The `bin` entry exposes a `bli-cockpit-mcp` program that speaks MCP over stdio. The `./remote` export (`handleRemoteMcpRequest`) is the stateless Streamable HTTP handler the dashboard's `/api/mcp` route calls.
+
+### Legacy event-stream install (frozen)
 
-### Claude Code (`~/.claude/settings.json`)
+Only needed for `emit_event`, `get_ticket_timeline` and `get_active_tickets`.
+Do not follow this to connect an agent to Tower; the section above is the way.
 
 ```jsonc
+// ~/.claude/settings.json — LEGACY
 {
   "mcpServers": {
     "bli-cockpit": {
@@ -528,22 +556,12 @@ The `bin` entry exposes a `bli-cockpit-mcp` CLI that speaks MCP over stdio.
 }
 ```
 
-Run `bli-event login` once on the host; the MCP auto-resolves the
-access_token from `~/.config/bli-event/session.json` and refreshes it
-transparently.
-
-For CI (or any environment without a session file), set
-`BLI_OPERATOR_TOKEN` to a Supabase access_token in the env block — it
-will be used verbatim without refresh.
-
-For deployed cockpits, set `BLI_API_BASE_URL` to the production URL.
-Never commit tokens — keep them in local settings only.
-
-### Claude Desktop
-
-Same shape, but the file lives at:
-- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
-- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+Run `bli-event login` once on the host; the legacy tools auto-resolve the
+access_token from `~/.config/bli-event/session.json` and refresh it
+transparently. For CI (or any environment without a session file), set
+`BLI_OPERATOR_TOKEN` to a Supabase access_token in the env block; it is used
+verbatim without refresh. For deployed cockpits, set `BLI_API_BASE_URL` to the
+production URL. Never commit tokens.
 
 ## Example invocations
 

package/dist/agent-door-session.d.ts

@@ -33,6 +33,9 @@ export type LoadAgentDoorSessionResult = {
     message: string;
 };
 export declare function agentDoorSessionFilePath(homeDir?: string): string;
+export declare function runWithAgentDoorSession<T>(session: AgentDoorSession, run: () => T): T;
+/** True inside a hosted request: nothing on this host's disk is the caller's. */
+export declare function inRemoteAgentDoorScope(): boolean;
 export declare function loadAgentDoorSession(options?: {
     env?: NodeJS.ProcessEnv;
     homeDir?: string;

package/dist/agent-door-session.js

@@ -18,6 +18,7 @@
  *
  * The token is never logged, printed, or included in an error.
  */
+import { AsyncLocalStorage } from "node:async_hooks";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -26,7 +27,26 @@ export const DEFAULT_DASHBOARD_URL = "https://bli-cockpit-dashboard.vercel.app";
 export function agentDoorSessionFilePath(homeDir = os.homedir()) {
     return path.join(homeDir, ...SESSION_RELATIVE_PATH);
 }
+/**
+ * BLI-12416: the hosted server (`remote.ts`) answers many people from one
+ * process, so a credential from env or `session.json` would be one person's
+ * for everybody. A request-scoped session wins over both: every tool path
+ * that calls `loadAgentDoorSession` then works remotely without threading a
+ * session through ~100 handlers. Two concurrent scopes never see each other's
+ * value (`AsyncLocalStorage`), and nothing here ever logs the token.
+ */
+const requestSession = new AsyncLocalStorage();
+export function runWithAgentDoorSession(session, run) {
+    return requestSession.run(session, run);
+}
+/** True inside a hosted request: nothing on this host's disk is the caller's. */
+export function inRemoteAgentDoorScope() {
+    return requestSession.getStore() !== undefined;
+}
 export function loadAgentDoorSession(options = {}) {
+    const scoped = requestSession.getStore();
+    if (scoped)
+        return { ok: true, session: scoped };
     const env = options.env ?? process.env;
     const envToken = (env.BLI_COCKPIT_MCP_DEVICE_TOKEN ?? "").trim();
     if (envToken.length > 0) {

package/dist/agent-door.d.ts

@@ -9,7 +9,7 @@
  * because both talk to the identical on-disk cache directory on the same
  * machine, and neither depends on the other package to say so.
  */
-import type { AgentDoorSession } from "./agent-door-session.js";
+import { type AgentDoorSession } from "./agent-door-session.js";
 export type FetchImpl = typeof fetch;
 export interface AgentDoorResponse {
     ok: boolean;

package/dist/agent-door.js

@@ -12,6 +12,7 @@
 import os from "node:os";
 import { getUserLocalCockpitPaths } from "@bli-cockpit/telemetry-core";
 import { invalidateReadCacheSurface, readCacheSurfaceForPath, } from "@bli-cockpit/telemetry-core/node-read-cache";
+import { inRemoteAgentDoorScope } from "./agent-door-session.js";
 /**
  * How long a door gets before this server gives up on it (BLI-10432).
  *
@@ -76,7 +77,8 @@ export async function callAgentDoor(session, fetchImpl, method, path, body, time
             transportError: `Tower answered ${response.status} with a body this server could not read as JSON.`,
         };
     }
-    if (method !== "GET" && response.ok) {
+    // Hosted requests have no per-person on-disk read cache to invalidate.
+    if (method !== "GET" && response.ok && !inRemoteAgentDoorScope()) {
         const surface = readCacheSurfaceForPath(path);
         if (surface) {
             const stateDir = getUserLocalCockpitPaths(os.homedir()).state_dir;

package/dist/mail-tools.d.ts

@@ -6,7 +6,9 @@
  * 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.
+ * second copy of anybody's credentials. Or, when the person should be the one
+ * to press send, save the reply as a DRAFT in their own mailbox (`mail_draft`,
+ * BLI-12530): it reaches nobody, so unlike `mail_send` it needs no `confirm`.
  *
  * TWO DELIBERATE ASYMMETRIES with the CLI, both recorded in `verb-census.ts`:
  *

package/dist/mail-tools.js

@@ -6,7 +6,9 @@
  * 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.
+ * second copy of anybody's credentials. Or, when the person should be the one
+ * to press send, save the reply as a DRAFT in their own mailbox (`mail_draft`,
+ * BLI-12530): it reaches nobody, so unlike `mail_send` it needs no `confirm`.
  *
  * TWO DELIBERATE ASYMMETRIES with the CLI, both recorded in `verb-census.ts`:
  *
@@ -32,6 +34,23 @@ function messageLine(message) {
     return `${message.is_unread ? "*" : " "} ${message.internal_date.slice(0, 16)}  ${from}  ${message.subject ?? "(no subject)"}  [thread ${message.thread_id ?? "?"}]`;
 }
 const ADDRESS = EMAIL_INPUT.describe("An email address.");
+/**
+ * The JSON `mail_send` and `mail_draft` post. One shape, because the two doors
+ * take the same fields: a message that can be sent can be saved unsent, and a
+ * field added to one cannot be forgotten by the other.
+ */
+function composedBody(args) {
+    return {
+        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 } : {}),
+    };
+}
 export function registerMailTools(server, deps) {
     const register = registrarFor(server);
     register("mail_accounts", {
@@ -186,21 +205,42 @@ export function registerMailTools(server, deps) {
         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 } : {}),
-        });
+        const response = await callAgentDoor(session, deps.fetchImpl, "POST", "/api/mail/send", composedBody(args));
         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_draft", {
+        title: "Save a draft in one mailbox",
+        description: "Saves a message as a DRAFT in one of YOUR mailboxes, for a person to read, edit and send themselves. Use it "
+            + "when you are preparing mail on somebody's behalf and they should be the one to press send. NOTHING IS SENT and "
+            + "nobody is notified, so unlike mail_send there is no confirm flag. `account_id` is REQUIRED and is the mailbox the "
+            + "draft is saved in (mail_accounts) — with several attached, that is never something to guess. "
+            + "`in_reply_to_message_id` (a message id from mail_read) threads the draft into that conversation the way mail_send "
+            + "threads a reply; Gmail files it there only when the subject matches the original's, and the answer says whether it "
+            + "did (`threaded`). Only the mailbox's OWNER can draft into it, and only Gmail mailboxes can take one: an IMAP "
+            + "mailbox is refused as imap_drafts_unsupported. Answers the provider draft id, the thread id and the account id.",
+        inputSchema: {
+            account_id: z.string().uuid().describe("The mailbox the draft is saved in (mail_accounts). Never guessed."),
+            to: z.array(ADDRESS).min(1).max(50).describe("Recipient email addresses, so the draft is ready to send as it is."),
+            cc: z.array(ADDRESS).max(50).optional().describe("Copied email addresses."),
+            subject: z.string().max(998).describe("The subject line. For a reply, keep the original's subject or Gmail will not thread it."),
+            text: z.string().min(1).max(500_000).describe("The plain-text body."),
+            in_reply_to_message_id: z.string().uuid().optional().describe("A message id from mail_read: save this as a reply in that thread."),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const response = await callAgentDoor(session, deps.fetchImpl, "POST", "/api/mail/drafts", composedBody(args));
+        if (!response.ok)
+            return errorResult(doorFailureText("mail_draft", response));
+        const draft = response.body.draft;
+        // Both halves carry the ids (BLI-10432): a client that hands the model only
+        // `content`, or only `structuredContent`, must still learn where the draft is.
+        return textResult(`Saved a draft in ${draft?.address ?? "that mailbox"} for ${args.to.join(", ")}`
+            + `${draft?.threaded ? " (in the reply's thread)" : args.in_reply_to_message_id ? " (Gmail did NOT file it in that thread: its subject has to match the original's)" : ""}. `
+            + "Nothing was sent: it waits in Drafts for a person to read, edit and send. "
+            + `draft_id=${draft?.provider_draft_id ?? "(none returned)"} thread_id=${draft?.provider_thread_id ?? "(none)"} account_id=${draft?.account_id ?? String(args.account_id)}`, { draft });
+    }));
     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 "

package/dist/remote.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Tower's tools at an HTTPS address (BLI-12416).
+ *
+ * `handleRemoteMcpRequest` answers ONE Streamable HTTP request: a new server
+ * and a stateless web-standard transport per request (no session id, plain
+ * JSON replies), built from the SAME `createServer` the stdio bin uses so the
+ * tool list cannot fork. The caller's bearer rides an `AsyncLocalStorage`
+ * scope, so every tool calls Tower's own `/api/*` doors with THEIR token and
+ * the doors enforce who they are. Nothing here widens a read.
+ *
+ * Left out of the hosted list, with reasons, in `REMOTE_EXCLUDED_TOOLS`.
+ * Nothing is logged but tool name, outcome, milliseconds, bytes and a label;
+ * never a token, an argument or an answer.
+ */
+/**
+ * ChatGPT only guarantees the first 512 characters of server instructions are
+ * read, so this is the whole briefing: what Tower is, where to start, how
+ * writes behave.
+ */
+export declare const REMOTE_INSTRUCTIONS: string;
+export interface RemoteMcpSession {
+    /** The origin the tools call back, e.g. `https://tower.example`. */
+    dashboardUrl: string;
+    /** The caller's own bearer (device token or OAuth access token). */
+    bearer: string;
+    /** A short label for the log line, e.g. a token hash prefix. Never the token. */
+    label: string;
+}
+export interface RemoteMcpDeps {
+    fetchImpl?: typeof fetch;
+    log?: (line: string, fields: Record<string, unknown>) => void;
+}
+export declare function handleRemoteMcpRequest(request: Request, session: RemoteMcpSession, deps?: RemoteMcpDeps): Promise<Response>;

package/dist/remote.js

@@ -0,0 +1,68 @@
+/**
+ * Tower's tools at an HTTPS address (BLI-12416).
+ *
+ * `handleRemoteMcpRequest` answers ONE Streamable HTTP request: a new server
+ * and a stateless web-standard transport per request (no session id, plain
+ * JSON replies), built from the SAME `createServer` the stdio bin uses so the
+ * tool list cannot fork. The caller's bearer rides an `AsyncLocalStorage`
+ * scope, so every tool calls Tower's own `/api/*` doors with THEIR token and
+ * the doors enforce who they are. Nothing here widens a read.
+ *
+ * Left out of the hosted list, with reasons, in `REMOTE_EXCLUDED_TOOLS`.
+ * Nothing is logged but tool name, outcome, milliseconds, bytes and a label;
+ * never a token, an argument or an answer.
+ */
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { runWithAgentDoorSession } from "./agent-door-session.js";
+import { createServer } from "./server.js";
+/**
+ * ChatGPT only guarantees the first 512 characters of server instructions are
+ * read, so this is the whole briefing: what Tower is, where to start, how
+ * writes behave.
+ */
+export const REMOTE_INSTRUCTIONS = "Tower is Build Launch Iterate's workspace: documents, messages, issues, mail, calendar, meeting notes and the daily brief. "
+    + "Start with tower_search to find anything, then use the matching docs_*, msg_*, work_*, mail_*, cal_* or notes_* tool. "
+    + "You act as the signed-in person and see only what they can see. Tools that change data are marked as writes, so the app asks the person to confirm first.";
+const TAG = "[mcp-remote]";
+function defaultLog(line, fields) {
+    console.info(`${TAG} ${line}`, JSON.stringify(fields));
+}
+export async function handleRemoteMcpRequest(request, session, deps = {}) {
+    const log = deps.log ?? defaultLog;
+    const fetchImpl = deps.fetchImpl ?? globalThis.fetch;
+    const started = Date.now();
+    const server = createServer({
+        // The three legacy event tools are excluded, so this is never called.
+        resolveToken: async () => {
+            throw new Error("The legacy event stream is not served remotely.");
+        },
+        baseUrl: session.dashboardUrl,
+        fetchImpl,
+    }, {
+        remote: {
+            instructions: REMOTE_INSTRUCTIONS,
+            onToolCall: (call) => log("tool call", { ...call, label: session.label }),
+        },
+    });
+    const transport = new WebStandardStreamableHTTPServerTransport({
+        sessionIdGenerator: undefined,
+        enableJsonResponse: true,
+    });
+    return runWithAgentDoorSession({ dashboardUrl: session.dashboardUrl, deviceToken: session.bearer }, async () => {
+        try {
+            await server.connect(transport);
+            const response = await transport.handleRequest(request);
+            log("request handled", { method: request.method, status: response.status, ms: Date.now() - started, label: session.label });
+            return response;
+        }
+        catch (error) {
+            log("request failed", {
+                method: request.method,
+                reason: error instanceof Error ? error.name : "unknown",
+                ms: Date.now() - started,
+                label: session.label,
+            });
+            throw error;
+        }
+    });
+}

package/dist/server-icons.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Tower's mark as MCP `serverInfo.icons` (spec 2025-11-25, SEP-973), so a host
+ * that renders server icons shows Tower's own logo with nothing to upload
+ * (BLI-12426). Data URIs, not URLs: the icon travels inside the `initialize`
+ * answer and works on every deployment address and on a laptop's stdio run.
+ *
+ * Source: `docs/design/brand/tower-icon.svg` (the PNG is its 128 px render).
+ * `server-icons.test.ts` fails when the SVG here stops matching that file.
+ * Many hosts do not read this field yet; ChatGPT's create dialog also takes an
+ * upload (`docs/design/brand/tower-icon-256.png`).
+ */
+export declare const TOWER_SERVER_ICONS: {
+    src: string;
+    mimeType: string;
+    sizes: string[];
+}[];

package/dist/server-icons.js

@@ -0,0 +1,17 @@
+/**
+ * Tower's mark as MCP `serverInfo.icons` (spec 2025-11-25, SEP-973), so a host
+ * that renders server icons shows Tower's own logo with nothing to upload
+ * (BLI-12426). Data URIs, not URLs: the icon travels inside the `initialize`
+ * answer and works on every deployment address and on a laptop's stdio run.
+ *
+ * Source: `docs/design/brand/tower-icon.svg` (the PNG is its 128 px render).
+ * `server-icons.test.ts` fails when the SVG here stops matching that file.
+ * Many hosts do not read this field yet; ChatGPT's create dialog also takes an
+ * upload (`docs/design/brand/tower-icon-256.png`).
+ */
+const TOWER_ICON_PNG_128 = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAIAAAACACAMAAAD04JH5AAAA2FBMVEUAAADy8e3s6+f19PDy7+rx4dXz5tzw1cTqdDTpaSTpZyHtoHXw0r7pZB3oVwjoWQzoVQfslmbdXRjRUg7UVRDmZR+QgXcrHRYvIRktHxhENi7cy8Dz6eCFhYQUFhcYGhsvMDHd3NkwMjLa2tb6+fWHiIb49/O+vbtPUFAjJSV6e3qRkY/m5eEsLi4VFxiUlJIfICFERkbY19RnaGcnKSm0tLGnp6VRU1I8Pj6Oj413d3bKysdbXFzh4N2bm5mAgX/S0s/NzMlqa2qwsK4uLzDX1tOsrKnFxcKJMVDUAAAAAXRSTlMAQObYZgAAA6NJREFUeNrtm2dD2zAQhiMrBdoyunfwyiAmdqBNgEAIo7T9//+osS0neMR3GrY79H4DbN3j92SdLKRWq1hkKYMoVQut8GpK1UYnFM0QBlcdPYEwYAZiVBScIdByBOZUpaIlBDWED2WQ5h6/zISagm8kqO3xmZqOnyWoO3ouC/UDpAkaiB+q6fiyAO0nK20JNbBKguAbsL3zlOnZ87ZQCwYDEKz7u3v7B7FevBQDYBaIDgG7eyz+wb4gAOsFgveqAIgsEB4DVTjwZwCISgkAaR5A+M7GAegaQHQckHRge+fV60hv3gqOhJIA7a137z8s9fHT5y/irYiOw6Fo59AMZdkS0ymZUpwAOK5EIxqgBIBC6vYYgN0HrxUAGHQg9Y6i+ObQAy89HnEDLP0FZTLBV/quCICpTo4G+N8BAksAYOw71omS8MuGTm1uADJy3a/fAgXxJ1PbtQ1+gNCFMwUWBOejshjltcC9UODAjIgDkEv5HPhXEgB0OpTOwJxIAJDr07iZfAUoLgxBvlIsqAwAuYlt9LI1cJ6td55lputibx7d6txKOUAHk7AV666fmQUsupmCPwq9Ss0MvMiSe0MKgIzOo244XvsYD5E5Y6NkPR5x7egNOjkDJqzglGyW7UlIAPo96r8X0HQNBLjyw3Ye7rgdiN7g4BJqH56UzjM5QALY0fsznEKfDCAAXWRygANgGTi9lnfg1knnAOlAPIZ2wOZhAOM+nYMygHXZj9+ByQD8aIMB4pK4zgHKgTgDQCFEArCS+JCMRcUDUT8zEHkBXAixACydq8EXMxR7DqIQYgFYSQwwxSj1E1QI0Q4kJZFbC8S6Aerr+EZsWgIVQjxAXBK5pyJQIcQDsJLIKbAQ4gHILDgs7nRr5S8ACyEHwI9Z7ovfS88Wj3q5K36i1r+QSzS5FY++7aSev9fNXYJbOhNeI3LTAB3RlToNoAE0gAbQABpAA2gADaAB/mIAq2mAxh3QABpAA2gADaAB/h0AsTtpFqBfjwMjl8n+5acAPHv1F769hXx7Sumx7zCl4pvmMPl9yW6NogZ5AeCdLSX7VTY5wNEJMFtr+PbWce5tVw0Q727nsEC5A7y766sB4OiGmD1+Ph4gOWLBYQG8y7Ezhv9bmonPlwRY3BkQP+Qhp8cHjZqInz7sVf9Rs9URm+Y8aPC4YVH8mrNQeOayxvgbTp02+viMoJ40tDar4nPP0eMDh68rdYESKDzrCpUxwNEr7Y5FoX4DijSqxkMGuGsAAAAASUVORK5CYII=";
+const TOWER_ICON_SVG = "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA2NCA2NCI+CiAgPHJlY3Qgd2lkdGg9IjY0IiBoZWlnaHQ9IjY0IiByeD0iMTQiIGZpbGw9IiNGMkYxRUQiLz4KICA8ZyB0cmFuc2Zvcm09InRyYW5zbGF0ZSg0IDQpIHNjYWxlKC44NzUpIj4KICA8cGF0aCBmaWxsPSIjMTgxQTFCIiBkPSJNMzAgOGg0djZoMjB2NEgxMHYtNGgyMHpNMTIgMThoNDBsLTUgMTRIMTd6TTI4IDMyaDh2MjRoNnY0SDIydi00aDZ6Ii8+CiAgPHBhdGggZmlsbD0iI0YyRjFFRCIgZD0iTTE3IDIyaDd2NmgtNXpNMjcgMjJoMTB2NkgyN3pNNDAgMjJoN2wtMiA2aC01eiIvPgogIDxwYXRoIGZpbGw9IiNFODU5MEMiIGQ9Ik0yOSA0aDZ2NmgtNnoiLz4KICA8L2c+Cjwvc3ZnPgo=";
+export const TOWER_SERVER_ICONS = [
+    { src: TOWER_ICON_PNG_128, mimeType: "image/png", sizes: ["128x128"] },
+    { src: TOWER_ICON_SVG, mimeType: "image/svg+xml", sizes: ["any"] },
+];

package/dist/server.d.ts

@@ -6,6 +6,7 @@
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
+import { type CreateServerOptions } from "./tool-registration.js";
 import type { TokenResolver } from "./token-resolver.js";
 export type FetchImpl = typeof fetch;
 export interface ServerDeps {
@@ -99,4 +100,5 @@ export declare function getActiveTickets(deps: ServerDeps, args: {
 }): Promise<{
     tickets: unknown[];
 }>;
-export declare function createServer(deps: ServerDeps): McpServer;
+export type { CreateServerOptions } from "./tool-registration.js";
+export declare function createServer(deps: ServerDeps, options?: CreateServerOptions): McpServer;

package/dist/server.js

@@ -35,6 +35,8 @@ import { registerCareersTools } from "./careers-tools.js";
 import { registerRenameTools } from "./rename-tools.js";
 import { registerUsageTools } from "./usage-tools.js";
 import { registerSourcesTools } from "./sources-tools.js";
+import { TOWER_SERVER_ICONS } from "./server-icons.js";
+import { installToolRegistration } from "./tool-registration.js";
 export const PACKAGE_NAME = "@bli-cockpit/mcp";
 /**
  * The version this server tells a client in `initialize`, read from the
@@ -368,12 +370,11 @@ function errorContent(err) {
         ],
     };
 }
-// ---- server factory ---------------------------------------------------------
-export function createServer(deps) {
-    const server = new McpServer({
-        name: PACKAGE_NAME,
-        version: PACKAGE_VERSION,
-    });
+export function createServer(deps, options = {}) {
+    const server = new McpServer({ name: PACKAGE_NAME, version: PACKAGE_VERSION, icons: TOWER_SERVER_ICONS }, options.remote ? { instructions: options.remote.instructions } : undefined);
+    const remote = options.remote !== undefined;
+    // BLI-12416: annotations from the catalog, hosted exclusions and call logging.
+    installToolRegistration(server, options);
     server.registerTool("emit_event", {
         title: "Emit a cockpit event",
         description: "Append a canonical event to the BLI Cockpit event stream for a given ticket. Wraps POST /api/events/emit. Supports idempotency_key for at-most-once writes.",
@@ -447,7 +448,11 @@ export function createServer(deps) {
     // 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.
-    registerJarvisTools(server, { fetchImpl: deps.fetchImpl });
+    registerJarvisTools(server, {
+        fetchImpl: deps.fetchImpl,
+        // Hosted: "last turn" is never read from the host's own disk.
+        ...(remote ? { readBookmark: async () => null } : {}),
+    });
     // BLI-3912: `models_*` — the model-card shelf, over the same door
     // `cockpit models` calls. Read-only: a card is changed by re-reading the
     // provider, never by an agent editing a number.

package/dist/tool-annotations.d.ts

@@ -0,0 +1,29 @@
+/**
+ * MCP tool annotations and the hosted server's exclusions (BLI-12416).
+ *
+ * ChatGPT treats a tool WITHOUT `readOnlyHint: true` as a write and asks the
+ * person to confirm every call, so ~109 unannotated tools would nag on every
+ * read. `tool-catalog.ts` already sorts every tool into read, dry-run and
+ * write; the hints derive from it here and nowhere else, and
+ * `tool-annotations.test.ts` fails when a registered tool has none or
+ * disagrees with the catalog.
+ */
+export interface TowerToolAnnotations {
+    readOnlyHint: boolean;
+    destructiveHint?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * Writes a person cannot take back by writing again: deletes, revokes,
+ * detaches and a merge. These also carry `destructiveHint: true`.
+ */
+export declare const DESTRUCTIVE_TOOLS: readonly ["docs_delete", "cal_delete", "cal_detach", "mail_detach", "notes_detach", "notes_rmdir", "settings_delete", "team_device_revoke", "github_merge"];
+/**
+ * Tools the HOSTED server leaves out, each with the reason. A hosted process
+ * is one machine answering many people: a tool that reads that machine's
+ * files or spawns a program there would act on the host, not on the caller's
+ * computer, so it is absent rather than quietly wrong.
+ */
+export declare const REMOTE_EXCLUDED_TOOLS: Readonly<Record<string, string>>;
+/** `null` when the tool is in no catalog list (the test then fails, loudly). */
+export declare function annotationsFor(name: string, catalog: ReadonlySet<string>): TowerToolAnnotations | null;

package/dist/tool-annotations.js

@@ -0,0 +1,51 @@
+/**
+ * MCP tool annotations and the hosted server's exclusions (BLI-12416).
+ *
+ * ChatGPT treats a tool WITHOUT `readOnlyHint: true` as a write and asks the
+ * person to confirm every call, so ~109 unannotated tools would nag on every
+ * read. `tool-catalog.ts` already sorts every tool into read, dry-run and
+ * write; the hints derive from it here and nowhere else, and
+ * `tool-annotations.test.ts` fails when a registered tool has none or
+ * disagrees with the catalog.
+ */
+import { READ_TOOLS } from "./tool-catalog.js";
+/**
+ * Writes a person cannot take back by writing again: deletes, revokes,
+ * detaches and a merge. These also carry `destructiveHint: true`.
+ */
+export const DESTRUCTIVE_TOOLS = [
+    "docs_delete",
+    "cal_delete",
+    "cal_detach",
+    "mail_detach",
+    "notes_detach",
+    "notes_rmdir",
+    "settings_delete",
+    "team_device_revoke",
+    "github_merge",
+];
+/**
+ * Tools the HOSTED server leaves out, each with the reason. A hosted process
+ * is one machine answering many people: a tool that reads that machine's
+ * files or spawns a program there would act on the host, not on the caller's
+ * computer, so it is absent rather than quietly wrong.
+ */
+export const REMOTE_EXCLUDED_TOOLS = {
+    emit_event: "legacy event stream; authenticates with an operator token the host does not hold",
+    get_ticket_timeline: "legacy event stream; authenticates with an operator token the host does not hold",
+    get_active_tickets: "legacy event stream; authenticates with an operator token the host does not hold",
+    notes_upload: "reads a file by path from the machine the server runs on; use notes_paste with the text",
+    sources_check: "spawns `cockpit sources check` on the machine the server runs on",
+};
+const READS = new Set(READ_TOOLS);
+const DESTRUCTIVE = new Set(DESTRUCTIVE_TOOLS);
+/** `null` when the tool is in no catalog list (the test then fails, loudly). */
+export function annotationsFor(name, catalog) {
+    if (!catalog.has(name))
+        return null;
+    if (READS.has(name))
+        return { readOnlyHint: true };
+    return DESTRUCTIVE.has(name)
+        ? { readOnlyHint: false, destructiveHint: true }
+        : { readOnlyHint: false, destructiveHint: false };
+}

package/dist/tool-catalog.d.ts

@@ -21,7 +21,7 @@ export declare const DRY_RUN_TOOLS: readonly ["ops_recompile", "memory_requeue"]
  * candidates, share calendars. Never called by the smoke; covered by the unit
  * suites (`write-tools.test.ts` and each family's own).
  */
-export declare const WRITE_TOOLS: readonly ["emit_event", "docs_create", "docs_update", "docs_delete", "docs_link", "msg_create_channel", "msg_dm", "msg_send", "work_create_issue", "work_update_issue", "work_move_issue", "work_comment_issue", "careers_rescreen", "careers_send_takehome", "careers_invite", "careers_grade", "careers_decide", "careers_followup", "careers_interview", "careers_takehome_set", "careers_settings_set", "rename_resolve", "github_merge", "github_retitle", "github_rerun", "mail_send", "mail_sync", "mail_detach", "cal_create", "cal_share", "cal_sync", "cal_detach", "cal_delete", "jarvis_dispatch", "notes_mkdir", "notes_rmdir", "notes_rename", "notes_upload", "notes_paste", "notes_share", "notes_unshare", "notes_move", "notes_sync", "notes_detach", "memory_experience", "scout_start", "scout_dismiss", "scout_undo", "brief_rewrite", "brief_correct", "brief_done", "brief_undone", "settings_set", "settings_delete", "model_set", "team_invite", "team_role", "team_device_revoke"];
+export declare const WRITE_TOOLS: readonly ["emit_event", "docs_create", "docs_update", "docs_delete", "docs_link", "msg_create_channel", "msg_dm", "msg_send", "work_create_issue", "work_update_issue", "work_move_issue", "work_comment_issue", "careers_rescreen", "careers_send_takehome", "careers_invite", "careers_grade", "careers_decide", "careers_followup", "careers_interview", "careers_takehome_set", "careers_settings_set", "rename_resolve", "github_merge", "github_retitle", "github_rerun", "mail_send", "mail_draft", "mail_sync", "mail_detach", "cal_create", "cal_share", "cal_sync", "cal_detach", "cal_delete", "jarvis_dispatch", "notes_mkdir", "notes_rmdir", "notes_rename", "notes_upload", "notes_paste", "notes_share", "notes_unshare", "notes_move", "notes_sync", "notes_detach", "memory_experience", "scout_start", "scout_dismiss", "scout_undo", "brief_rewrite", "brief_correct", "brief_done", "brief_undone", "settings_set", "settings_delete", "model_set", "team_invite", "team_role", "team_device_revoke"];
 /** Reads that spend a model turn. The smoke's `--no-model` leaves these out. */
 export declare const MODEL_SPENDING_TOOLS: readonly ["jarvis_ask", "jarvis_check"];
 /**

package/dist/tool-catalog.js

@@ -116,6 +116,8 @@ export const WRITE_TOOLS = [
     "github_retitle",
     "github_rerun",
     "mail_send",
+    // BLI-12530: writes into a mailbox (a draft), reaches nobody. Never smoked.
+    "mail_draft",
     "mail_sync",
     "mail_detach",
     "cal_create",

package/dist/tool-registration.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The one hook every tool registers through (BLI-12416).
+ *
+ * ~30 modules call `server.registerTool`. Rather than edit each, `createServer`
+ * installs this wrapper once, before any of them run, and it does three things
+ * to every registration:
+ *
+ *   1. adds `annotations` derived from `tool-catalog.ts` (`tool-annotations.ts`),
+ *      so ChatGPT runs reads without a prompt and confirms writes;
+ *   2. hosted mode only: removes the tools in `REMOTE_EXCLUDED_TOOLS`, which
+ *      would otherwise touch the host's own disk or spawn a program there;
+ *   3. hosted mode only: reports tool, outcome, milliseconds and response bytes
+ *      per call (never arguments or answers) to `onToolCall`.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export interface ToolCallReport {
+    tool: string;
+    outcome: "ok" | "tool_error" | "threw";
+    ms: number;
+    bytes: number;
+}
+export interface CreateServerOptions {
+    /**
+     * The hosted server: leaves out `REMOTE_EXCLUDED_TOOLS`, never reads this
+     * machine's turn bookmark, and carries `instructions`.
+     */
+    remote?: {
+        instructions: string;
+        onToolCall?: (call: ToolCallReport) => void;
+    };
+}
+export declare function installToolRegistration(server: McpServer, options: CreateServerOptions): void;

package/dist/tool-registration.js

@@ -0,0 +1,48 @@
+/**
+ * The one hook every tool registers through (BLI-12416).
+ *
+ * ~30 modules call `server.registerTool`. Rather than edit each, `createServer`
+ * installs this wrapper once, before any of them run, and it does three things
+ * to every registration:
+ *
+ *   1. adds `annotations` derived from `tool-catalog.ts` (`tool-annotations.ts`),
+ *      so ChatGPT runs reads without a prompt and confirms writes;
+ *   2. hosted mode only: removes the tools in `REMOTE_EXCLUDED_TOOLS`, which
+ *      would otherwise touch the host's own disk or spawn a program there;
+ *   3. hosted mode only: reports tool, outcome, milliseconds and response bytes
+ *      per call (never arguments or answers) to `onToolCall`.
+ */
+import { REMOTE_EXCLUDED_TOOLS, annotationsFor } from "./tool-annotations.js";
+import { DRY_RUN_TOOLS, READ_TOOLS, WRITE_TOOLS } from "./tool-catalog.js";
+const CATALOGUED_TOOLS = new Set([...READ_TOOLS, ...DRY_RUN_TOOLS, ...WRITE_TOOLS]);
+export function installToolRegistration(server, options) {
+    const remote = options.remote !== undefined;
+    const onToolCall = options.remote?.onToolCall;
+    const register = server.registerTool.bind(server);
+    server.registerTool = (name, config, handler) => {
+        const annotations = annotationsFor(name, CATALOGUED_TOOLS);
+        const measured = onToolCall
+            ? async (...args) => {
+                const started = Date.now();
+                try {
+                    const result = await handler(...args);
+                    onToolCall({
+                        tool: name,
+                        outcome: result?.isError ? "tool_error" : "ok",
+                        ms: Date.now() - started,
+                        bytes: JSON.stringify(result ?? null).length,
+                    });
+                    return result;
+                }
+                catch (error) {
+                    onToolCall({ tool: name, outcome: "threw", ms: Date.now() - started, bytes: 0 });
+                    throw error;
+                }
+            }
+            : handler;
+        const handle = register(name, annotations && !config.annotations ? { ...config, annotations } : config, measured);
+        if (remote && name in REMOTE_EXCLUDED_TOOLS)
+            handle.remove();
+        return handle;
+    };
+}

package/dist/verb-census.js

@@ -268,6 +268,8 @@ export const MCP_TWINS = {
     "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" },
+    // BLI-12530: the same message, saved unsent in the owner's own mailbox.
+    "mail draft": { tool: "mail_draft", door: "POST /api/mail/drafts" },
     "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 sync-status": { tool: "mail_sync_status", door: "GET /api/mail/sync-status" },

package/package.json

@@ -1,9 +1,16 @@
 {
   "name": "@bli-cockpit/mcp",
-  "version": "0.1.82",
+  "version": "0.1.84",
   "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",
+  "exports": {
+    "./remote": {
+      "types": "./dist/remote.d.ts",
+      "default": "./dist/remote.js"
+    },
+    "./package.json": "./package.json"
+  },
   "bin": {
     "bli-cockpit-mcp": "./dist/index.js"
   },