@bli-cockpit/mcp 0.1.81 → 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,
@@ -103,7 +109,7 @@ about what an agent can reach.
 
 <!-- BEGIN GENERATED verb census — `npm run mcp:readme` -->
 
-**119 of 124 Tower verbs have an MCP twin.**
+**123 of 128 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
@@ -150,6 +156,10 @@ three tables below.
 | `cockpit docs sync-status` | `docs_sync_status` | `GET /api/docs/notion-sync` |
 | `cockpit docs tree` | `docs_tree` | `GET /api/docs/tree` |
 | `cockpit docs update` | `docs_update` | `PATCH /api/docs/documents/[id]` |
+| `cockpit github merge` | `github_merge` | `POST /api/github/pull-request (merge)` |
+| `cockpit github pr` | `github_pr` | `POST /api/github/pull-request (read)` |
+| `cockpit github rerun` | `github_rerun` | `POST /api/github/pull-request (rerun)` |
+| `cockpit github retitle` | `github_retitle` | `POST /api/github/pull-request (retitle)` |
 | `cockpit issue comment` | `work_comment_issue` | `POST /api/work/issues/[id]/comments` |
 | `cockpit issue create` | `work_create_issue` | `POST /api/work/issues` |
 | `cockpit issue history` | `work_issue_history` | `GET /api/work/issues/[id]/history` |
@@ -499,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": {
@@ -524,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/github-tools.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `github_pr` / `github_merge` / `github_retitle` / `github_rerun` (BLI-12385):
+ * the MCP twins of `cockpit github pr|merge|retitle|rerun`, over the same door
+ * (`POST /api/github/pull-request`) with the same device token.
+ *
+ * The door runs JARVIS's own GitHub implementations, so the lock is the same:
+ * the caller's OWN GitHub login (on the roster) must hold write, maintain or
+ * admin on the repo, and a change is TWO STEPS. The first call (no `confirm`)
+ * changes nothing and returns what would happen plus an eight-character code;
+ * the second carries `confirm`. The code is signed to the caller, repo, pull
+ * request and exact change. An agent must pass a code only after the PERSON has
+ * sent it back: whether to merge is theirs, and the descriptions say so.
+ * A refusal keeps the door's reason label and sentence verbatim.
+ */
+import { type ToolDeps } from "./tool-result.js";
+export declare function registerGithubTools(server: {
+    registerTool: (...args: never[]) => unknown;
+}, deps: ToolDeps): void;

package/dist/github-tools.js

@@ -0,0 +1,116 @@
+/**
+ * `github_pr` / `github_merge` / `github_retitle` / `github_rerun` (BLI-12385):
+ * the MCP twins of `cockpit github pr|merge|retitle|rerun`, over the same door
+ * (`POST /api/github/pull-request`) with the same device token.
+ *
+ * The door runs JARVIS's own GitHub implementations, so the lock is the same:
+ * the caller's OWN GitHub login (on the roster) must hold write, maintain or
+ * admin on the repo, and a change is TWO STEPS. The first call (no `confirm`)
+ * changes nothing and returns what would happen plus an eight-character code;
+ * the second carries `confirm`. The code is signed to the caller, repo, pull
+ * request and exact change. An agent must pass a code only after the PERSON has
+ * sent it back: whether to merge is theirs, and the descriptions say so.
+ * A refusal keeps the door's reason label and sentence verbatim.
+ */
+import { z } from "zod";
+import { callAgentDoor } from "./agent-door.js";
+import { dataResult, doorFailureText, errorResult, registrarFor, textResult, withSession, } from "./tool-result.js";
+const PATH = "/api/github/pull-request";
+const TWO_STEPS = "TWO STEPS: call it WITHOUT confirm first. That changes nothing and returns what would happen plus an "
+    + "eight-character confirmation code; show the person exactly that and ask them to send the code back. Only then "
+    + "call again with the SAME arguments plus confirm set to the code THE PERSON gave you. Never invent a code, "
+    + "never reuse one the person did not send, and never change the arguments between the two calls (the code is "
+    + "signed to the exact change). It runs only if the person's OWN GitHub login has write, maintain or admin on the "
+    + "repo; otherwise it refuses with github_login_unknown or github_permission_insufficient: relay that as written. "
+    + "Only BLI-INC repositories.";
+const repoField = z.string().min(1).max(100).describe("`owner/repo` or a bare repo name in BLI-INC, e.g. bli-cockpit.");
+const numberField = z.number().int().min(1).describe("The pull request number.");
+const confirmField = z
+    .string()
+    .min(1)
+    .max(64)
+    .optional()
+    .describe("The code the preview returned, which the PERSON sent back. Omit on the first call.");
+export function registerGithubTools(server, deps) {
+    const register = registrarFor(server);
+    async function press(tool, session, body) {
+        const response = await callAgentDoor(session, deps.fetchImpl, "POST", PATH, body);
+        if (!response.ok)
+            return errorResult(doorFailureText(tool, response));
+        const result = (response.body["result"] ?? {});
+        if (result["status"] === "needs_confirmation") {
+            return textResult(`Nothing has been changed. Would ${String(result["preview"] ?? "make this change")} `
+                + `To go ahead, the person must send back the code ${String(result["confirmationCode"] ?? "")}; `
+                + `then call ${tool} again with the same arguments and confirm set to that code.`, result);
+        }
+        if (result["status"] === "done")
+            return textResult(String(result["sayThis"] ?? "Done."), result);
+        return dataResult("GitHub pull request", result);
+    }
+    register("github_pr", {
+        title: "Read one pull request from GitHub",
+        description: "GitHub's own live record of ONE pull request in BLI-INC: merged (and by whom), open/closed, draft, mergeable, "
+            + "title and CI. GitHub is the source of truth: when somebody asserts a state, read it here. Pass `claim` "
+            + "(merged, open, closed, ci_green or mergeable) to get GitHub's verdict on that assertion with the correction "
+            + "sentence. `cockpit github pr`, same door.",
+        inputSchema: {
+            repo: repoField,
+            pull_number: numberField,
+            claim: z.enum(["merged", "open", "closed", "ci_green", "mergeable"]).optional().describe("The state somebody asserted."),
+        },
+    }, async (args) => withSession(deps, (session) => press("github_pr", session, {
+        action: "read",
+        repo: String(args.repo),
+        pullNumber: args.pull_number,
+        ...(args.claim ? { claim: args.claim } : {}),
+    })));
+    register("github_merge", {
+        title: "Merge a pull request (two steps, caller's own GitHub access)",
+        description: `Merge ONE pull request in BLI-INC, squash by default. \`cockpit github merge\`, same door. ${TWO_STEPS}`,
+        inputSchema: {
+            repo: repoField,
+            pull_number: numberField,
+            method: z.enum(["squash", "merge", "rebase"]).optional().describe("Defaults to squash."),
+            confirm: confirmField,
+        },
+    }, async (args) => withSession(deps, (session) => press("github_merge", session, {
+        action: "merge",
+        repo: String(args.repo),
+        pullNumber: args.pull_number,
+        ...(args.method ? { method: args.method } : {}),
+        ...(args.confirm ? { confirm: String(args.confirm) } : {}),
+    })));
+    register("github_retitle", {
+        title: "Retitle a pull request (two steps, caller's own GitHub access)",
+        description: `Change the title of ONE pull request in BLI-INC. \`cockpit github retitle\`, same door. ${TWO_STEPS}`,
+        inputSchema: {
+            repo: repoField,
+            pull_number: numberField,
+            title: z.string().min(1).max(256).describe("The new title."),
+            confirm: confirmField,
+        },
+    }, async (args) => withSession(deps, (session) => press("github_retitle", session, {
+        action: "retitle",
+        repo: String(args.repo),
+        pullNumber: args.pull_number,
+        title: String(args.title),
+        ...(args.confirm ? { confirm: String(args.confirm) } : {}),
+    })));
+    register("github_rerun", {
+        title: "Re-run failed workflow jobs (two steps, caller's own GitHub access)",
+        description: "Re-run the FAILED jobs of workflow runs in BLI-INC: pass pull_number for every failed workflow on that pull "
+            + `request's head commit, or run_id for one run (exactly one). \`cockpit github rerun\`, same door. ${TWO_STEPS}`,
+        inputSchema: {
+            repo: repoField,
+            pull_number: numberField.optional(),
+            run_id: z.number().int().min(1).optional().describe("One workflow run, instead of pull_number."),
+            confirm: confirmField,
+        },
+    }, async (args) => withSession(deps, (session) => press("github_rerun", session, {
+        action: "rerun",
+        repo: String(args.repo),
+        ...(args.pull_number ? { pullNumber: args.pull_number } : {}),
+        ...(args.run_id ? { runId: args.run_id } : {}),
+        ...(args.confirm ? { confirm: String(args.confirm) } : {}),
+    })));
+}

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

@@ -23,6 +23,7 @@ import { registerMemoryExperienceTools } from "./memory-experience-tools.js";
 import { registerMemoryProfileTools } from "./memory-profile-tools.js";
 import { registerMemoryRequeueTools } from "./memory-requeue-tools.js";
 import { registerModelsTools } from "./models-tools.js";
+import { registerGithubTools } from "./github-tools.js";
 import { registerOpsTools } from "./ops-tools.js";
 import { registerPagesTools } from "./pages-tools.js";
 import { registerSearchTool } from "./search-tool.js";
@@ -34,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
@@ -367,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.",
@@ -429,6 +431,8 @@ export function createServer(deps) {
     // BLI-12378: the twins of `cockpit rename list|resolve`, the human's call on
     // whether a correction becomes a rule.
     registerRenameTools(server, deps);
+    // BLI-12385: GitHub PR read, and merge / retitle / re-run behind the two-step code.
+    registerGithubTools(server, deps);
     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
@@ -444,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

@@ -10,7 +10,7 @@
  * from `src/` under Node's type stripping, so it may import nothing.
  */
 /** Tools that change nothing. The smoke calls every one. */
-export declare const READ_TOOLS: readonly ["get_ticket_timeline", "get_active_tickets", "docs_list", "docs_tree", "docs_read", "docs_sync_status", "msg_channels", "msg_read", "msg_thread", "work_list_issues", "work_get_issue", "work_issue_history", "work_list_projects", "careers_list", "careers_show", "careers_resume_url", "careers_takehome_show", "careers_settings_show", "rename_pending", "usage_people", "usage_sessions", "mail_accounts", "mail_inbox", "mail_read", "mail_search", "mail_attachment", "mail_sync_status", "cal_today", "cal_week", "cal_next", "cal_find", "cal_calendars", "cal_sync_status", "jarvis_ask", "jarvis_trace", "jarvis_check", "models_list", "models_card", "models_compare", "brief_read", "brief_history", "brief_status", "brief_missed", "notes_folders", "notes_list", "notes_show", "notes_shelf", "notes_shelves", "notes_place", "notes_accounts", "notes_sync_status", "notes_granola_status", "ops_status", "slack_coverage", "slack_read", "memory_profile", "memory_consolidation", "settings_show", "settings_list", "model_show", "team_members", "team_device_list", "scout_board", "workbook_read", "tower_search", "sources_check"];
+export declare const READ_TOOLS: readonly ["get_ticket_timeline", "get_active_tickets", "docs_list", "docs_tree", "docs_read", "docs_sync_status", "msg_channels", "msg_read", "msg_thread", "work_list_issues", "work_get_issue", "work_issue_history", "work_list_projects", "careers_list", "careers_show", "careers_resume_url", "careers_takehome_show", "careers_settings_show", "rename_pending", "github_pr", "usage_people", "usage_sessions", "mail_accounts", "mail_inbox", "mail_read", "mail_search", "mail_attachment", "mail_sync_status", "cal_today", "cal_week", "cal_next", "cal_find", "cal_calendars", "cal_sync_status", "jarvis_ask", "jarvis_trace", "jarvis_check", "models_list", "models_card", "models_compare", "brief_read", "brief_history", "brief_status", "brief_missed", "notes_folders", "notes_list", "notes_show", "notes_shelf", "notes_shelves", "notes_place", "notes_accounts", "notes_sync_status", "notes_granola_status", "ops_status", "slack_coverage", "slack_read", "memory_profile", "memory_consolidation", "settings_show", "settings_list", "model_show", "team_members", "team_device_list", "scout_board", "workbook_read", "tower_search", "sources_check"];
 /**
  * Tools that write, but answer a dry run that writes nothing. The smoke calls
  * each one ONLY with its dry-run flag set (`scripts/smoke.ts` says which).
@@ -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", "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_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

@@ -30,6 +30,7 @@ export const READ_TOOLS = [
     "careers_takehome_show",
     "careers_settings_show",
     "rename_pending",
+    "github_pr",
     "usage_people",
     "usage_sessions",
     "mail_accounts",
@@ -111,6 +112,9 @@ export const WRITE_TOOLS = [
     "careers_takehome_set",
     "careers_settings_set",
     "rename_resolve",
+    "github_merge",
+    "github_retitle",
+    "github_rerun",
     "mail_send",
     "mail_sync",
     "mail_detach",

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

@@ -234,6 +234,11 @@ export const MCP_TWINS = {
     // BLI-12378: the human's call on whether a correction becomes a rule.
     "rename list": { tool: "rename_pending", door: "GET /api/jarvis/rename-scope" },
     "rename resolve": { tool: "rename_resolve", door: "POST /api/jarvis/rename-scope" },
+    // BLI-12385: GitHub PR read and the two-step merge / retitle / re-run.
+    "github pr": { tool: "github_pr", door: "POST /api/github/pull-request (read)" },
+    "github merge": { tool: "github_merge", door: "POST /api/github/pull-request (merge)" },
+    "github retitle": { tool: "github_retitle", door: "POST /api/github/pull-request (retitle)" },
+    "github rerun": { tool: "github_rerun", door: "POST /api/github/pull-request (rerun)" },
     "usage sessions": { tool: "usage_sessions", door: "GET /api/usage/sessions" },
     "usage people": { tool: "usage_people", door: "GET /api/usage/people" },
     "docs list": { tool: "docs_list", door: "GET /api/docs/documents" },

package/package.json

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