@bli-cockpit/mcp 0.1.82 → 0.1.83

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,
@@ -503,16 +509,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 +555,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/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-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/package.json

@@ -1,9 +1,16 @@
 {
   "name": "@bli-cockpit/mcp",
-  "version": "0.1.82",
+  "version": "0.1.83",
   "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"
   },