@bli-cockpit/mcp 0.1.12 → 0.1.13

package/README.md

@@ -367,7 +367,13 @@ The server resolves an access_token before every authenticated request using the
 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.
+If both paths are unavailable (no env override, and no session file on disk),
+the server **still starts** and only those three tools refuse, by name, when
+called — every device-token tool is unaffected (BLI-3804). It used to exit at
+startup, which meant a machine that installed the published package registered
+a `bli-tower` server with NO tools at all: `scripts/bli-event-session.mjs`
+exists in the bli-cockpit repo and nowhere else. `src/startup-auth.ts` carries
+the account.
 
 ## Install
 
@@ -453,10 +459,68 @@ The server surfaces API error codes from the canonical catalog
 | `BLI-E403` | Authenticated caller cannot access the requested ticket. |
 | `BLI-W003` | Idempotency replay (informational; not an error). |
 
+## The smoke — does this server actually answer? (BLI-3804)
+
+The unit suites prove each tool's shape against an injected fetch, and
+`verb-census.test.ts` proves a twin EXISTS for every Tower CLI verb. Neither
+starts a server, opens a transport or reaches Tower, which is how five QA ticks
+(`docs/reports/jarvis-qa-loop/tick15.md` … `tick19.md`) recorded these tools as
+untested end to end while the published server was exiting at startup.
+
+```bash
+npm run mcp:smoke --workspace=@bli-cockpit/mcp                       # all six families
+npm run mcp:smoke --workspace=@bli-cockpit/mcp -- --skip jarvis_ask  # no model spend
+npm run mcp:smoke --workspace=@bli-cockpit/mcp -- --only docs_list --json
+```
+
+It builds the server, spawns `dist/index.js` over stdio the way an agent host
+does, lists the tools, and calls one cheap READ per family — `docs_list`
+(limit 1), `msg_channels`, `work_list_issues` (limit 1), `cal_calendars`,
+`mail_accounts`, `jarvis_ask` — never a write, never a dispatch. The device
+token is never passed to it: the server reads
+`~/.config/bli-cockpit/session.json` itself, so the smoke exercises the real
+auth path. Output is one line per tool — name, verdict, the door's own reason
+label, milliseconds:
+
+```
+bli-tower smoke — 78 tools registered, 6 called
+tool              verdict      reason                        ms
+docs_list         ok           answered                      719
+msg_channels      ok           answered                      795
+work_list_issues  ok           answered                      760
+cal_calendars     ok           answered                      762
+mail_accounts     ok           answered                      478
+jarvis_ask        ok           answered                      6483
+```
+
+**A refusal by name is a pass.** The question is whether the server answers,
+not whether this account has a mailbox: `cal_calendars` and `mail_accounts`
+answering "nothing is attached" is a healthy machine. The exit code turns
+non-zero only when something never answered — the server would not start, the
+transport broke, a call timed out, a tool was not registered, or Tower could
+not be reached.
+
+`--server <path>` points it at an INSTALLED server instead of this checkout's
+build, which matters more than it sounds: the repo build resolves a credential
+the published install cannot, so a green smoke here has never proven the
+fleet's server starts.
+
+```bash
+npm run mcp:smoke --workspace=@bli-cockpit/mcp -- \
+  --server "$(npm root -g)/@bli-cockpit/cli/node_modules/@bli-cockpit/mcp/dist/index.js"
+```
+
+On a laptop, `cockpit doctor`'s `mcp-answers` row asks the same first question
+of the REGISTERED server every run
+(`packages/cockpit-local-collector/src/commands/doctor-mcp.ts`), so a machine
+whose MCP is registered and not answering says so without anyone running this
+script.
+
 ## Development
 
 ```bash
-npm run typecheck --workspace=@bli-cockpit/mcp
+npm run typecheck --workspace=@bli-cockpit/mcp   # also typechecks scripts/
 npm test --workspace=@bli-cockpit/mcp
 npm run build --workspace=@bli-cockpit/mcp
+npm run mcp:smoke --workspace=@bli-cockpit/mcp   # needs a paired machine
 ```

package/dist/index.d.ts

@@ -1,18 +1,22 @@
 #!/usr/bin/env node
 /**
- * @bli-cockpit/mcp — MCP server adapter for the BLI Cockpit event stream.
+ * @bli-cockpit/mcp — `bli-tower`, the MCP entry point.
  *
- * Exposes three tools backed by the canonical REST contract at
- * `POST /api/events/emit` (see docs/plans/cockpit-agent-ops-control-plane.md §6).
+ * TWO credentials, and only one of them is needed to serve (BLI-3804):
  *
- * 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.
+ *   * Every agent-door tool — `docs_*`, `msg_*`, `work_*`, `mail_*`, `cal_*`,
+ *     `jarvis_*`, `brief_*`, `notes_*`, `ops_*`, `settings_*`, `scout_*`,
+ *     `search`, `workbook_*` — reads this machine's COLLECTOR DEVICE TOKEN
+ *     per call from `~/.config/bli-cockpit/session.json`
+ *     (`agent-door-session.ts`). Nothing about it is resolved here.
+ *   * `emit_event` / `get_ticket_timeline` / `get_active_tickets` — the legacy
+ *     event stream — need `BLI_OPERATOR_TOKEN`, or `scripts/bli-event-session.mjs`
+ *     found by walking up from this module (set `BLI_SESSION_HELPER` to point
+ *     at it directly).
  *
- * If neither path is available, the server prints a clear error and exits.
+ * When the second one is absent the server STILL STARTS and those three tools
+ * refuse by name when called. It used to exit 1 before connecting the
+ * transport, which meant no tools at all on every machine outside the repo —
+ * `startup-auth.ts` carries the full account.
  */
 export {};

package/dist/index.js

@@ -1,42 +1,38 @@
 #!/usr/bin/env node
 /**
- * @bli-cockpit/mcp — MCP server adapter for the BLI Cockpit event stream.
+ * @bli-cockpit/mcp — `bli-tower`, the MCP entry point.
  *
- * Exposes three tools backed by the canonical REST contract at
- * `POST /api/events/emit` (see docs/plans/cockpit-agent-ops-control-plane.md §6).
+ * TWO credentials, and only one of them is needed to serve (BLI-3804):
  *
- * 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.
+ *   * Every agent-door tool — `docs_*`, `msg_*`, `work_*`, `mail_*`, `cal_*`,
+ *     `jarvis_*`, `brief_*`, `notes_*`, `ops_*`, `settings_*`, `scout_*`,
+ *     `search`, `workbook_*` — reads this machine's COLLECTOR DEVICE TOKEN
+ *     per call from `~/.config/bli-cockpit/session.json`
+ *     (`agent-door-session.ts`). Nothing about it is resolved here.
+ *   * `emit_event` / `get_ticket_timeline` / `get_active_tickets` — the legacy
+ *     event stream — need `BLI_OPERATOR_TOKEN`, or `scripts/bli-event-session.mjs`
+ *     found by walking up from this module (set `BLI_SESSION_HELPER` to point
+ *     at it directly).
  *
- * If neither path is available, the server prints a clear error and exits.
+ * When the second one is absent the server STILL STARTS and those three tools
+ * refuse by name when called. It used to exit 1 before connecting the
+ * transport, which meant no tools at all on every machine outside the repo —
+ * `startup-auth.ts` carries the full account.
  */
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { createServer } from "./server.js";
-import { createDefaultTokenResolver } from "./token-resolver.js";
+import { resolveStartupAuth } from "./startup-auth.js";
 async function main() {
     const baseUrl = process.env.BLI_API_BASE_URL ?? "http://127.0.0.1:3100";
-    let resolver;
-    let sourceLabel;
-    try {
-        const result = createDefaultTokenResolver({ env: process.env });
-        resolver = result.resolver;
-        sourceLabel =
-            result.source === "env"
-                ? "BLI_OPERATOR_TOKEN env var"
-                : `session helper at ${result.helperPath}`;
-    }
-    catch (err) {
-        process.stderr.write(`[bli-cockpit-mcp] ${err instanceof Error ? err.message : String(err)}\n`);
-        process.exit(1);
-    }
-    process.stderr.write(`[bli-cockpit-mcp] auth source: ${sourceLabel}\n`);
+    // BLI-3804: a missing LEGACY credential degrades three tools, it does not
+    // kill the server. This used to `process.exit(1)` before the transport was
+    // connected, so every machine that installed the published package — where
+    // `scripts/bli-event-session.mjs` does not exist — registered no `bli-tower`
+    // tools at all. See `startup-auth.ts` for the whole story.
+    const auth = resolveStartupAuth({ env: process.env });
+    process.stderr.write(`[bli-cockpit-mcp] auth source: ${auth.sourceLabel}\n`);
     const deps = {
-        resolveToken: resolver,
+        resolveToken: auth.resolver,
         baseUrl,
         fetchImpl: globalThis.fetch,
     };

package/dist/startup-auth.d.ts

@@ -0,0 +1,44 @@
+/**
+ * What this server does when the LEGACY event-stream credential is missing
+ * (BLI-3804).
+ *
+ * Two auth paths live on this one server and they are unrelated
+ * (`agent-door-session.ts` says why): every `docs_*`, `msg_*`, `work_*`,
+ * `mail_*`, `cal_*`, `jarvis_*`, `brief_*`, `notes_*`, `ops_*`, `settings_*`,
+ * `scout_*`, `search` and `workbook_*` tool — 78 of the 81 — authenticates
+ * with this machine's COLLECTOR DEVICE TOKEN, read per call from
+ * `~/.config/bli-cockpit/session.json`. Only `emit_event`,
+ * `get_ticket_timeline` and `get_active_tickets` need `BLI_OPERATOR_TOKEN` or
+ * the `bli-event-session.mjs` helper.
+ *
+ * Until this module existed, `index.ts` resolved that legacy credential at
+ * STARTUP and called `process.exit(1)` when it could not — before the
+ * transport was connected and before a single tool was registered. The helper
+ * is discovered by walking up from this module's own location looking for
+ * `scripts/bli-event-session.mjs`, which exists in the bli-cockpit repo and
+ * nowhere else, so on every machine that installed the published package the
+ * server died at startup and the agent host reported no `bli-tower` tools at
+ * all. Proven 2026-09-06 against the registered bin on the reference Mac:
+ * `[bli-cockpit-mcp] No auth available: …`, exit 1. Five QA ticks
+ * (`docs/reports/jarvis-qa-loop/tick15.md` … `tick19.md`) recorded the
+ * symptom — "no `mcp__bli-tower__*` in this session" — as a client-side gap.
+ *
+ * `server.ts` already stated the intended behaviour in a comment beside the
+ * agent-door registrations: "Registered unconditionally — … a machine with no
+ * `cockpit login` pairing yet still serves the three event tools; only a
+ * docs/msg call on that machine fails, by name." This module makes the
+ * converse true as well: a machine with no LEGACY operator token still serves
+ * every agent-door tool, and only the three event-stream tools fail — by name,
+ * with the reason, when they are called.
+ */
+import type { TokenResolver } from "./token-resolver.js";
+export interface StartupAuth {
+    resolver: TokenResolver;
+    /** One line for stderr. Says which half of the server is live and which is not. */
+    sourceLabel: string;
+    /** `true` when only the three legacy event-stream tools are unavailable. */
+    legacyToolsDegraded: boolean;
+}
+export declare function resolveStartupAuth(options: {
+    env: NodeJS.ProcessEnv;
+}): StartupAuth;

package/dist/startup-auth.js

@@ -0,0 +1,61 @@
+/**
+ * What this server does when the LEGACY event-stream credential is missing
+ * (BLI-3804).
+ *
+ * Two auth paths live on this one server and they are unrelated
+ * (`agent-door-session.ts` says why): every `docs_*`, `msg_*`, `work_*`,
+ * `mail_*`, `cal_*`, `jarvis_*`, `brief_*`, `notes_*`, `ops_*`, `settings_*`,
+ * `scout_*`, `search` and `workbook_*` tool — 78 of the 81 — authenticates
+ * with this machine's COLLECTOR DEVICE TOKEN, read per call from
+ * `~/.config/bli-cockpit/session.json`. Only `emit_event`,
+ * `get_ticket_timeline` and `get_active_tickets` need `BLI_OPERATOR_TOKEN` or
+ * the `bli-event-session.mjs` helper.
+ *
+ * Until this module existed, `index.ts` resolved that legacy credential at
+ * STARTUP and called `process.exit(1)` when it could not — before the
+ * transport was connected and before a single tool was registered. The helper
+ * is discovered by walking up from this module's own location looking for
+ * `scripts/bli-event-session.mjs`, which exists in the bli-cockpit repo and
+ * nowhere else, so on every machine that installed the published package the
+ * server died at startup and the agent host reported no `bli-tower` tools at
+ * all. Proven 2026-09-06 against the registered bin on the reference Mac:
+ * `[bli-cockpit-mcp] No auth available: …`, exit 1. Five QA ticks
+ * (`docs/reports/jarvis-qa-loop/tick15.md` … `tick19.md`) recorded the
+ * symptom — "no `mcp__bli-tower__*` in this session" — as a client-side gap.
+ *
+ * `server.ts` already stated the intended behaviour in a comment beside the
+ * agent-door registrations: "Registered unconditionally — … a machine with no
+ * `cockpit login` pairing yet still serves the three event tools; only a
+ * docs/msg call on that machine fails, by name." This module makes the
+ * converse true as well: a machine with no LEGACY operator token still serves
+ * every agent-door tool, and only the three event-stream tools fail — by name,
+ * with the reason, when they are called.
+ */
+import { createDefaultTokenResolver } from "./token-resolver.js";
+export function resolveStartupAuth(options) {
+    try {
+        const result = createDefaultTokenResolver({ env: options.env });
+        return {
+            resolver: result.resolver,
+            sourceLabel: result.source === "env"
+                ? "BLI_OPERATOR_TOKEN env var"
+                : `session helper at ${result.helperPath}`,
+            legacyToolsDegraded: false,
+        };
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        return {
+            // Not a startup failure — a per-call one. `server.ts`'s `callApi` turns
+            // this throw into BLI-E003 on the ONE tool that needed it, which is the
+            // difference between three unavailable tools and no server at all.
+            resolver: async () => {
+                throw new Error(reason);
+            },
+            sourceLabel: "none for the legacy event-stream tools (emit_event, get_ticket_timeline, get_active_tickets); "
+                + `they will refuse by name when called — ${reason} `
+                + "Every device-token tool (docs_*, msg_*, work_*, mail_*, cal_*, jarvis_*, …) is unaffected.",
+            legacyToolsDegraded: true,
+        };
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/mcp",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "private": false,
   "description": "bli-tower \u2014 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",
@@ -22,10 +22,11 @@
     "build": "tsc",
     "prepack": "node ../../scripts/build-workspace-dep.mjs @bli-cockpit/telemetry-core && rm -rf dist && tsc",
     "pretypecheck": "node ../../scripts/build-workspace-dep.mjs @bli-cockpit/telemetry-core",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.scripts.json",
     "pretest": "node ../../scripts/build-workspace-dep.mjs @bli-cockpit/telemetry-core",
     "test": "vitest run",
     "start": "node dist/index.js",
+    "mcp:smoke": "npm run build --silent && node scripts/smoke.ts",
     "readme": "npm run build && node scripts/write-readme-census.mjs"
   },
   "dependencies": {