@bli-cockpit/mcp 0.1.0

package/README.md

@@ -0,0 +1,213 @@
+# @bli-cockpit/mcp — bli-tower
+
+Two, deliberately separate, tool families over one MCP server (bin
+`bli-cockpit-mcp`, server id `bli-tower`):
+
+1. **`docs_*`/`msg_*` (BLI-3706)** — the SAME `/api/docs/**` and `/api/msg/**`
+   agent doors `cockpit docs`/`cockpit msg` call, authenticated with this
+   machine's collector device token (`~/.config/bli-cockpit/session.json`,
+   written by `cockpit login`). This is the live, actively-developed half.
+2. **`emit_event`/`get_ticket_timeline`/`get_active_tickets`** — the legacy
+   event-stream write path, authenticated with `BLI_OPERATOR_TOKEN` or the
+   `bli-event` session helper. See "Legacy event-stream tools" below.
+
+The two halves use DIFFERENT credentials and DIFFERENT base URLs on purpose
+(`docs-msg-tools.ts` talks to the production Tower dashboard; the event-stream
+tools talk to `BLI_API_BASE_URL`, historically a local worker) — see
+`docs/architecture/cli-caller-identity.md` for why `docs_*`/`msg_*` needed no
+new server-side door: every `/api/docs/**`/`/api/msg/**` route already accepts
+a collector device token.
+
+## `docs_*` / `msg_*` tools (BLI-3706)
+
+| Tool | Wraps | Notes |
+| --- | --- | --- |
+| `docs_list` | `GET /api/docs/documents` | Every document you may read: id, slug, title, visibility. Never a body. |
+| `docs_read` | `GET /api/docs/documents/[id]` | One document's title and full body, by id or slug (resolved against `docs_list` first). |
+| `docs_create` | `POST /api/docs/documents` | Creates a document. Omitting `body_markdown` creates an empty one. |
+| `docs_update` | `PATCH /api/docs/documents/[id]` | Updates title/body/visibility/parent (a parent change IS a move). |
+| `msg_channels` | `GET /api/msg/channels` | Every channel you are a member of. |
+| `msg_read` | `GET /api/msg/channels/[id]/messages` | Recent messages of one channel, or one thread's replies. `channel` is an id or a `#name`. |
+| `msg_send` | `POST /api/msg/channels/[id]/messages` | Posts a message. |
+
+**Auth: this machine's collector device token, not `BLI_OPERATOR_TOKEN`.**
+Run `cockpit login` once; the server reads
+`~/.config/bli-cockpit/session.json` fresh on every call (never cached at
+startup, so a machine with no pairing yet still serves the event-stream tools
+below — only a `docs_*`/`msg_*` call on that machine fails, by name). Two
+optional env overrides, mirroring `@bli-cockpit/memory-mcp`'s own:
+
+| Var | Required | Purpose |
+| --- | --- | --- |
+| `BLI_COCKPIT_MCP_DEVICE_TOKEN` | no | Override the device token (skips the session file). |
+| `BLI_COCKPIT_MCP_DASHBOARD_URL` | no | Override the dashboard base URL (defaults to production, or `COCKPIT_DASHBOARD_URL` if set). |
+
+A door refusal or a network failure both come back as an MCP `isError` result
+naming the door's own `reason` label (e.g. `document_not_found_or_unreadable`)
+— never a generic "something went wrong".
+
+## Registration on an intern machine
+
+`cockpit memory install` (run unasked by `do-everything` and the daily sync
+tick) registers `bli-tower` beside `bli-memory` in the SAME two files —
+`~/.claude.json`'s `mcpServers` and `~/.codex/config.toml`'s
+`[mcp_servers.bli-tower]` table — resolving this package's own bin the same
+way it resolves `bli-memory-mcp`'s (beside the running `@bli-cockpit/cli`
+install, then PATH). `bli-tower` has no Claude Code hooks and no Codex skill,
+so nothing is written to `~/.claude/settings.json` for it. See
+`packages/cockpit-local-collector/src/commands/tower-mcp-install.ts`.
+
+## Legacy event-stream tools
+
+Thin wrapper over the canonical REST event-stream contracts (see
+`docs/plans/cockpit-agent-ops-control-plane.md` §6) — the FROZEN active-emission
+substrate (`AGENTS.md` "What this repo is"), not where new work goes.
+
+| Tool | Wraps | Notes |
+| --- | --- | --- |
+| `emit_event` | `POST /api/events/emit` | Appends a canonical event. Supports `idempotency_key`. |
+| `get_ticket_timeline` | `GET /api/events/timeline?ticket_id=...` | Returns the canonical timeline for a task-visible ticket. |
+| `get_active_tickets` | `GET /api/tickets/active?...` | Returns active, task-visible tickets derived from `orchestration_events`. |
+
+### `emit_event`
+
+| Field | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `ticket_id` | string | yes | Linear ticket ID, e.g. `BUI-412`. |
+| `event_type` | string | yes | Canonical event type (e.g. `worker_dispatched`, `note`). |
+| `payload` | object | no (default `{}`) | Event payload. |
+| `note_md` | string | no | Optional markdown note. |
+| `correlation_id` | string | no | E.g. an agent trace ID. |
+| `idempotency_key` | string | no | Replays return `status: "replay"`. |
+
+Returns `{ event_id, occurred_at, status: "created" | "replay" }`.
+
+### `get_ticket_timeline`
+
+| Field | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `ticket_id` | string | yes | |
+| `since` | string (ISO-8601) | no | |
+| `limit` | number (1–500) | no (default 100) | |
+
+The API resolves `ticket_id` through `tasks.linear_ticket_id` and denies
+callers who cannot see that task.
+
+### `get_active_tickets`
+
+All four filters (`source`, `project`, `lane`, `assignee`) optional strings.
+The API derives active work from `orchestration_events`, resolves tickets back
+to `tasks.linear_ticket_id`, and returns only tasks visible to the caller.
+
+## Environment variables (legacy event-stream tools only)
+
+`docs_*`/`msg_*`'s own two optional overrides are documented above, beside
+those tools — this table is `emit_event`/`get_ticket_timeline`/
+`get_active_tickets`'s, a separate credential and base URL.
+
+| Var | Required | Default | Purpose |
+| --- | --- | --- | --- |
+| `BLI_OPERATOR_TOKEN` | no | — | If set, used verbatim as the bearer token on every request. Intended for CI. When unset, the server falls back to the session helper. |
+| `BLI_SESSION_HELPER` | no | auto-discovered | Absolute path to `scripts/bli-event-session.mjs`. Only needed if the MCP binary lives outside the bli-cockpit repo layout. |
+| `BLI_API_BASE_URL` | no | `http://127.0.0.1:3100` | Cockpit dashboard base URL. |
+
+## Authentication (legacy event-stream tools only)
+
+The server resolves an access_token before every authenticated request using the same precedence as the `bli-event` CLI:
+
+1. `BLI_OPERATOR_TOKEN` (verbatim, no refresh) — CI path.
+2. Session helper — shells out to `node scripts/bli-event-session.mjs get-token`, which reads `~/.config/bli-event/session.json` and refreshes the access_token when near expiry. Run `bli-event login` once on your laptop to create the session. Tokens are cached in-process for 30s to avoid spawning a subprocess on every tool call.
+
+If both paths are unavailable (no env override, and no session file on disk), the server exits at startup with an actionable error.
+
+## Install
+
+```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.
+
+### Claude Code (`~/.claude/settings.json`)
+
+```jsonc
+{
+  "mcpServers": {
+    "bli-cockpit": {
+      "command": "node",
+      "args": [
+        "/absolute/path/to/bli-cockpit/packages/bli-cockpit-mcp/dist/index.js"
+      ],
+      "env": {
+        "BLI_API_BASE_URL": "http://127.0.0.1:3100"
+      }
+    }
+  }
+}
+```
+
+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`
+
+## Example invocations
+
+```jsonc
+// emit a worker dispatch event
+{
+  "name": "emit_event",
+  "arguments": {
+    "ticket_id": "BUI-412",
+    "event_type": "worker_dispatched",
+    "payload": { "role": "builder", "model": "sonnet" },
+    "correlation_id": "trace_abc123"
+  }
+}
+
+// idempotent note from a hook
+{
+  "name": "emit_event",
+  "arguments": {
+    "ticket_id": "BUI-412",
+    "event_type": "note",
+    "note_md": "ship completed; preview URL https://...",
+    "idempotency_key": "ship-2026-04-17-1"
+  }
+}
+```
+
+## Errors
+
+The server surfaces API error codes from the canonical catalog
+(`docs/architecture/event-stream.md#errors`) as MCP tool errors. Common ones:
+
+| Code | Cause |
+| --- | --- |
+| `BLI-E001` | Network / Supabase unreachable. |
+| `BLI-E002` | Unknown `event_type`. |
+| `BLI-E003` | Bad / expired JWT. |
+| `BLI-E004` | Payload schema validation failed. |
+| `BLI-E403` | Authenticated caller cannot access the requested ticket. |
+| `BLI-W003` | Idempotency replay (informational; not an error). |
+
+## Development
+
+```bash
+npm run typecheck --workspace=@bli-cockpit/mcp
+npm test --workspace=@bli-cockpit/mcp
+npm run build --workspace=@bli-cockpit/mcp
+```

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

@@ -0,0 +1,39 @@
+/**
+ * Who is this machine, for the docs/msg tools (BLI-3706).
+ *
+ * `emit_event`/`get_ticket_timeline`/`get_active_tickets` in this same server
+ * authenticate with `BLI_OPERATOR_TOKEN` or the `bli-event-session.mjs` helper
+ * (`token-resolver.ts`) — a bearer JWT against the legacy event-stream worker.
+ * `/api/docs/**` and `/api/msg/**` are a different door entirely
+ * (`resolveCaller({ allowDeviceToken: true })` on the dashboard): they take the
+ * collector's own `bli_dev_*` device token, the credential `cockpit login`
+ * already wrote to `~/.config/bli-cockpit/session.json`. This module reads
+ * that file directly rather than depending on `@bli-cockpit/local-collector`
+ * or `@bli-cockpit/memory-mcp` — this package does not declare either as a
+ * dependency, and `packages/cockpit-memory-mcp/src/session.ts` already reads
+ * the identical file for the identical reason (its own header explains why: a
+ * package installed on its own should invent no fourth credential). The two
+ * copies are intentionally near-identical; see this file's own header in the
+ * PR that added it for the duplication call.
+ *
+ * The token is never logged, printed, or included in an error.
+ */
+export declare const SESSION_RELATIVE_PATH: string[];
+export declare const DEFAULT_DASHBOARD_URL = "https://bli-cockpit-dashboard.vercel.app";
+export interface AgentDoorSession {
+    dashboardUrl: string;
+    deviceToken: string;
+}
+export type LoadAgentDoorSessionResult = {
+    ok: true;
+    session: AgentDoorSession;
+} | {
+    ok: false;
+    reason: "session_file_missing" | "session_file_unreadable" | "session_file_invalid" | "session_missing_token";
+    message: string;
+};
+export declare function agentDoorSessionFilePath(homeDir?: string): string;
+export declare function loadAgentDoorSession(options?: {
+    env?: NodeJS.ProcessEnv;
+    homeDir?: string;
+}): LoadAgentDoorSessionResult;

package/dist/agent-door-session.js

@@ -0,0 +1,80 @@
+/**
+ * Who is this machine, for the docs/msg tools (BLI-3706).
+ *
+ * `emit_event`/`get_ticket_timeline`/`get_active_tickets` in this same server
+ * authenticate with `BLI_OPERATOR_TOKEN` or the `bli-event-session.mjs` helper
+ * (`token-resolver.ts`) — a bearer JWT against the legacy event-stream worker.
+ * `/api/docs/**` and `/api/msg/**` are a different door entirely
+ * (`resolveCaller({ allowDeviceToken: true })` on the dashboard): they take the
+ * collector's own `bli_dev_*` device token, the credential `cockpit login`
+ * already wrote to `~/.config/bli-cockpit/session.json`. This module reads
+ * that file directly rather than depending on `@bli-cockpit/local-collector`
+ * or `@bli-cockpit/memory-mcp` — this package does not declare either as a
+ * dependency, and `packages/cockpit-memory-mcp/src/session.ts` already reads
+ * the identical file for the identical reason (its own header explains why: a
+ * package installed on its own should invent no fourth credential). The two
+ * copies are intentionally near-identical; see this file's own header in the
+ * PR that added it for the duplication call.
+ *
+ * The token is never logged, printed, or included in an error.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+export const SESSION_RELATIVE_PATH = [".config", "bli-cockpit", "session.json"];
+export const DEFAULT_DASHBOARD_URL = "https://bli-cockpit-dashboard.vercel.app";
+export function agentDoorSessionFilePath(homeDir = os.homedir()) {
+    return path.join(homeDir, ...SESSION_RELATIVE_PATH);
+}
+export function loadAgentDoorSession(options = {}) {
+    const env = options.env ?? process.env;
+    const envToken = (env.BLI_COCKPIT_MCP_DEVICE_TOKEN ?? "").trim();
+    if (envToken.length > 0) {
+        return {
+            ok: true,
+            session: {
+                deviceToken: envToken,
+                dashboardUrl: normalizeUrl(env.BLI_COCKPIT_MCP_DASHBOARD_URL ?? env.COCKPIT_DASHBOARD_URL ?? ""),
+            },
+        };
+    }
+    const file = agentDoorSessionFilePath(options.homeDir ?? env.HOME ?? os.homedir());
+    let raw;
+    try {
+        raw = fs.readFileSync(file, "utf8");
+    }
+    catch (error) {
+        const missing = error?.code === "ENOENT";
+        return {
+            ok: false,
+            reason: missing ? "session_file_missing" : "session_file_unreadable",
+            message: missing
+                ? "This machine is not paired with Tower. Run `cockpit login` once, then restart your agent."
+                : "The Tower session file exists but could not be read. Run `cockpit login` again.",
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, reason: "session_file_invalid", message: "The Tower session file is not valid JSON. Run `cockpit login` again." };
+    }
+    const record = parsed && typeof parsed === "object" ? parsed : {};
+    const deviceToken = typeof record.device_token === "string" ? record.device_token.trim() : "";
+    if (deviceToken.length === 0) {
+        return { ok: false, reason: "session_missing_token", message: "The Tower session file carries no device token. Run `cockpit login` again." };
+    }
+    const fileUrl = typeof record.dashboard_url === "string" ? record.dashboard_url : "";
+    return {
+        ok: true,
+        session: {
+            deviceToken,
+            dashboardUrl: normalizeUrl(env.BLI_COCKPIT_MCP_DASHBOARD_URL ?? env.COCKPIT_DASHBOARD_URL ?? fileUrl),
+        },
+    };
+}
+function normalizeUrl(value) {
+    const trimmed = value.trim().replace(/\/+$/, "");
+    return trimmed.length > 0 ? trimmed : DEFAULT_DASHBOARD_URL;
+}

package/dist/agent-door.d.ts

@@ -0,0 +1,15 @@
+/**
+ * One call to `/api/docs/**` or `/api/msg/**` with this machine's device
+ * token (BLI-3706). Deadline-bounded; a transport failure and a door refusal
+ * are kept apart, same rule as `packages/cockpit-memory-mcp/src/door.ts`.
+ */
+import type { AgentDoorSession } from "./agent-door-session.js";
+export type FetchImpl = typeof fetch;
+export interface AgentDoorResponse {
+    ok: boolean;
+    status: number;
+    body: Record<string, unknown>;
+    /** Set only when no JSON answer was produced at all — DNS, TLS, timeout, non-JSON body. */
+    transportError: string | null;
+}
+export declare function callAgentDoor(session: AgentDoorSession, fetchImpl: FetchImpl, method: "GET" | "POST" | "PATCH", path: string, body?: unknown, timeoutMs?: number): Promise<AgentDoorResponse>;

package/dist/agent-door.js

@@ -0,0 +1,55 @@
+/**
+ * One call to `/api/docs/**` or `/api/msg/**` with this machine's device
+ * token (BLI-3706). Deadline-bounded; a transport failure and a door refusal
+ * are kept apart, same rule as `packages/cockpit-memory-mcp/src/door.ts`.
+ */
+const DEFAULT_TIMEOUT_MS = 15_000;
+export async function callAgentDoor(session, fetchImpl, method, path, body, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    const url = `${session.dashboardUrl}${path}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    timer.unref?.();
+    let response;
+    try {
+        response = await fetchImpl(url, {
+            method,
+            headers: {
+                authorization: `Bearer ${session.deviceToken}`,
+                "content-type": "application/json",
+                accept: "application/json",
+            },
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+            signal: controller.signal,
+        });
+    }
+    catch (error) {
+        const timedOut = error?.name === "AbortError";
+        return {
+            ok: false,
+            status: 0,
+            body: {},
+            transportError: timedOut
+                ? `Tower did not answer within ${timeoutMs} ms; the request was abandoned.`
+                : error instanceof Error
+                    ? error.message.split("\n")[0] ?? "unknown"
+                    : String(error),
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    let parsed = {};
+    try {
+        const text = await response.text();
+        parsed = text ? JSON.parse(text) : {};
+    }
+    catch {
+        return {
+            ok: false,
+            status: response.status,
+            body: {},
+            transportError: `Tower answered ${response.status} with a body this server could not read as JSON.`,
+        };
+    }
+    return { ok: response.ok, status: response.status, body: parsed, transportError: null };
+}

package/dist/docs-msg-tools.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `docs_*` and `msg_*` MCP tools (BLI-3706) — the same `/api/docs/**` and
+ * `/api/msg/**` doors `cockpit docs`/`cockpit msg` call, over this machine's
+ * device token (`agent-door-session.ts`/`agent-door.ts`).
+ *
+ * Every tool loads the session fresh per call (a cheap file read) rather than
+ * once at server startup: unlike BLI Memory's server, THIS package still
+ * starts and serves `emit_event`/`get_ticket_timeline`/`get_active_tickets`
+ * on a machine with no collector pairing at all, so a missing session must
+ * fail the ONE call that needed it, never the whole process.
+ */
+import { loadAgentDoorSession } from "./agent-door-session.js";
+import { type FetchImpl } from "./agent-door.js";
+export interface DocsMsgDeps {
+    fetchImpl: FetchImpl;
+    /** Injectable for tests; defaults to reading `~/.config/bli-cockpit/session.json`. */
+    loadSession?: typeof loadAgentDoorSession;
+}
+export declare function registerDocsMsgTools(server: {
+    registerTool: (...args: never[]) => unknown;
+}, deps: DocsMsgDeps): void;

package/dist/docs-msg-tools.js

@@ -0,0 +1,188 @@
+/**
+ * `docs_*` and `msg_*` MCP tools (BLI-3706) — the same `/api/docs/**` and
+ * `/api/msg/**` doors `cockpit docs`/`cockpit msg` call, over this machine's
+ * device token (`agent-door-session.ts`/`agent-door.ts`).
+ *
+ * Every tool loads the session fresh per call (a cheap file read) rather than
+ * once at server startup: unlike BLI Memory's server, THIS package still
+ * starts and serves `emit_event`/`get_ticket_timeline`/`get_active_tickets`
+ * on a machine with no collector pairing at all, so a missing session must
+ * fail the ONE call that needed it, never the whole process.
+ */
+import { z } from "zod";
+import { loadAgentDoorSession } from "./agent-door-session.js";
+import { callAgentDoor } from "./agent-door.js";
+function textResult(text, structured) {
+    return { content: [{ type: "text", text }], ...(structured ? { structuredContent: structured } : {}) };
+}
+function errorResult(text) {
+    return { isError: true, content: [{ type: "text", text }] };
+}
+async function withSession(deps, run) {
+    const loadSession = deps.loadSession ?? loadAgentDoorSession;
+    const loaded = loadSession();
+    if (!loaded.ok)
+        return errorResult(`This machine is not paired with Tower (${loaded.reason}). ${loaded.message}`);
+    return run(loaded.session);
+}
+function doorFailureText(door, response) {
+    if (response.transportError) {
+        return `Tower could not be reached for ${door} (${response.transportError}). Nothing was read or written.`;
+    }
+    const reason = typeof response.body.reason === "string" ? response.body.reason : typeof response.body.error === "string" ? response.body.error : "unknown_error";
+    const message = typeof response.body.message === "string" ? response.body.message : `Tower answered ${response.status}.`;
+    return `Tower refused ${door} (${reason}): ${message}`;
+}
+async function resolveDocumentId(deps, session, ref) {
+    const response = await callAgentDoor(session, deps.fetchImpl, "GET", "/api/docs/documents");
+    if (!response.ok)
+        return { status: "list_failed", text: doorFailureText("docs_list", response) };
+    const documents = (Array.isArray(response.body.documents) ? response.body.documents : []);
+    const match = documents.find((doc) => doc.id === ref || doc.slug === ref);
+    return match ? { status: "ok", id: match.id } : { status: "not_found" };
+}
+async function resolveChannelId(deps, session, ref) {
+    const response = await callAgentDoor(session, deps.fetchImpl, "GET", "/api/msg/channels");
+    if (!response.ok)
+        return { status: "list_failed", text: doorFailureText("msg_channels", response) };
+    const channels = (Array.isArray(response.body.channels) ? response.body.channels : []);
+    const bare = ref.startsWith("#") ? ref.slice(1) : ref;
+    const match = channels.find((channel) => channel.id === ref || channel.name === bare);
+    return match ? { status: "ok", id: match.id } : { status: "not_found" };
+}
+export function registerDocsMsgTools(server, deps) {
+    const register = server.registerTool.bind(server);
+    register("docs_list", {
+        title: "List Tower documents",
+        description: "Every document you may read: id, slug, title, visibility, source. Never a document's body — call docs_read for that.",
+        inputSchema: {},
+    }, async () => withSession(deps, async (session) => {
+        const response = await callAgentDoor(session, deps.fetchImpl, "GET", "/api/docs/documents");
+        if (!response.ok)
+            return errorResult(doorFailureText("docs_list", response));
+        const documents = response.body.documents ?? [];
+        return textResult(`${documents.length} document(s).`, { documents });
+    }));
+    register("docs_read", {
+        title: "Read a Tower document",
+        description: "One document's title and full body, by its id or slug (docs_list returns both).",
+        inputSchema: { id: z.string().min(1).max(200).describe("A document id, or its slug.") },
+    }, async (args) => withSession(deps, async (session) => {
+        const ref = String(args.id ?? "");
+        const resolved = await resolveDocumentId(deps, session, ref);
+        if (resolved.status === "list_failed")
+            return errorResult(resolved.text);
+        if (resolved.status === "not_found")
+            return errorResult(`No document matches "${ref}" — check docs_list for the id or slug.`);
+        const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/docs/documents/${encodeURIComponent(resolved.id)}`);
+        if (!response.ok)
+            return errorResult(doorFailureText("docs_read", response));
+        const document = response.body.document;
+        return textResult(`${document?.title ?? ""}\n\n${document?.body_markdown ?? ""}`, { document });
+    }));
+    register("docs_create", {
+        title: "Create a Tower document",
+        description: "Creates a new document. Omitting body creates an empty one, matching the browser's own default.",
+        inputSchema: {
+            title: z.string().min(1).max(200),
+            body_markdown: z.string().max(200_000).optional(),
+            parent_id: z.string().uuid().optional(),
+            visibility: z.enum(["org", "private"]).optional(),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const response = await callAgentDoor(session, deps.fetchImpl, "POST", "/api/docs/documents", {
+            title: args.title,
+            body_markdown: args.body_markdown ?? "",
+            ...(args.parent_id ? { parent_id: args.parent_id } : {}),
+            ...(args.visibility ? { visibility: args.visibility } : {}),
+        });
+        if (!response.ok)
+            return errorResult(doorFailureText("docs_create", response));
+        const document = response.body.document;
+        return textResult(`Created "${document?.title ?? ""}" (${document?.id ?? ""}).`, { document });
+    }));
+    register("docs_update", {
+        title: "Update a Tower document",
+        description: "Updates a document's title, body, visibility, or parent (a parent change IS a move). Only the fields you pass change.",
+        inputSchema: {
+            id: z.string().min(1).max(200).describe("A document id, or its slug."),
+            title: z.string().min(1).max(200).optional(),
+            body_markdown: z.string().max(200_000).optional(),
+            visibility: z.enum(["org", "private"]).optional(),
+            parent_id: z.string().uuid().nullable().optional(),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const ref = String(args.id ?? "");
+        const resolved = await resolveDocumentId(deps, session, ref);
+        if (resolved.status === "list_failed")
+            return errorResult(resolved.text);
+        if (resolved.status === "not_found")
+            return errorResult(`No document matches "${ref}" — check docs_list for the id or slug.`);
+        const response = await callAgentDoor(session, deps.fetchImpl, "PATCH", `/api/docs/documents/${encodeURIComponent(resolved.id)}`, {
+            ...(args.title !== undefined ? { title: args.title } : {}),
+            ...(args.body_markdown !== undefined ? { body_markdown: args.body_markdown } : {}),
+            ...(args.visibility !== undefined ? { visibility: args.visibility } : {}),
+            ...(args.parent_id !== undefined ? { parent_id: args.parent_id } : {}),
+        });
+        if (!response.ok)
+            return errorResult(doorFailureText("docs_update", response));
+        const document = response.body.document;
+        return textResult(`Updated "${document?.title ?? ""}" (${document?.id ?? resolved.id}).`, { document });
+    }));
+    register("msg_channels", {
+        title: "List Tower channels",
+        description: "Every channel you are a member of.",
+        inputSchema: {},
+    }, async () => withSession(deps, async (session) => {
+        const response = await callAgentDoor(session, deps.fetchImpl, "GET", "/api/msg/channels");
+        if (!response.ok)
+            return errorResult(doorFailureText("msg_channels", response));
+        const channels = response.body.channels ?? [];
+        return textResult(`${channels.length} channel(s).`, { channels });
+    }));
+    register("msg_read", {
+        title: "Read a Tower channel",
+        description: "Recent messages of one channel, newest first. `channel` is a channel id, or its name with or without a leading #.",
+        inputSchema: {
+            channel: z.string().min(1).max(200),
+            limit: z.number().int().min(1).max(200).optional(),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const ref = String(args.channel ?? "");
+        const resolved = await resolveChannelId(deps, session, ref);
+        if (resolved.status === "list_failed")
+            return errorResult(resolved.text);
+        if (resolved.status === "not_found")
+            return errorResult(`No channel matches "${ref}" — check msg_channels for the id or name.`);
+        const query = args.limit ? `?limit=${args.limit}` : "";
+        const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/msg/channels/${encodeURIComponent(resolved.id)}/messages${query}`);
+        if (!response.ok)
+            return errorResult(doorFailureText("msg_read", response));
+        const messages = response.body.messages ?? [];
+        return textResult(`${messages.length} message(s) in ${ref}.`, { channelId: resolved.id, messages });
+    }));
+    register("msg_send", {
+        title: "Send a Tower message",
+        description: "Posts a message to one channel. `channel` is a channel id, or its name with or without a leading #.",
+        inputSchema: {
+            channel: z.string().min(1).max(200),
+            content: z.string().min(1).max(8_000),
+            thread_parent_id: z.string().uuid().optional(),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const ref = String(args.channel ?? "");
+        const resolved = await resolveChannelId(deps, session, ref);
+        if (resolved.status === "list_failed")
+            return errorResult(resolved.text);
+        if (resolved.status === "not_found")
+            return errorResult(`No channel matches "${ref}" — check msg_channels for the id or name.`);
+        const response = await callAgentDoor(session, deps.fetchImpl, "POST", `/api/msg/channels/${encodeURIComponent(resolved.id)}/messages`, {
+            content: args.content,
+            ...(args.thread_parent_id ? { thread_parent_id: args.thread_parent_id } : {}),
+        });
+        if (!response.ok)
+            return errorResult(doorFailureText("msg_send", response));
+        const message = response.body.message;
+        return textResult(`Sent to ${ref} (${message?.id ?? "?"}).`, { message });
+    }));
+}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * @bli-cockpit/mcp — MCP server adapter for the BLI Cockpit event stream.
+ *
+ * Exposes three tools backed by the canonical REST contract at
+ * `POST /api/events/emit` (see docs/plans/cockpit-agent-ops-control-plane.md §6).
+ *
+ * Auth (precedence order, matches the `bli-event` bash CLI):
+ *   1. `BLI_OPERATOR_TOKEN` env var — used verbatim (CI / override).
+ *   2. Otherwise: shell out to `node scripts/bli-event-session.mjs get-token`
+ *      which reads `~/.config/bli-event/session.json`, refreshes the
+ *      access_token if near expiry, and prints a fresh token on stdout.
+ *      Set `BLI_SESSION_HELPER` to an absolute path if the helper can't be
+ *      discovered by walking up from this module's location.
+ *
+ * If neither path is available, the server prints a clear error and exits.
+ */
+export {};