@bli-cockpit/mcp 0.1.0

package/dist/index.js

@@ -0,0 +1,50 @@
+#!/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.
+ */
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+import { createDefaultTokenResolver } from "./token-resolver.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`);
+    const deps = {
+        resolveToken: resolver,
+        baseUrl,
+        fetchImpl: globalThis.fetch,
+    };
+    const server = createServer(deps);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    process.stderr.write(`[bli-cockpit-mcp] fatal: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});

package/dist/server.d.ts

@@ -0,0 +1,96 @@
+/**
+ * MCP server factory for @bli-cockpit/mcp.
+ *
+ * Pure factory — accepts injected fetch + base URL + token so it can be
+ * unit-tested without binding to a real network or transport.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { TokenResolver } from "./token-resolver.js";
+export type FetchImpl = typeof fetch;
+export interface ServerDeps {
+    /**
+     * Called before every authenticated request. Must return a fresh Supabase
+     * access_token. See `token-resolver.ts` for the built-in implementations
+     * (`createEnvTokenResolver`, `createSessionHelperTokenResolver`).
+     */
+    resolveToken: TokenResolver;
+    baseUrl: string;
+    fetchImpl: FetchImpl;
+}
+export declare const PACKAGE_NAME = "@bli-cockpit/mcp";
+export declare const PACKAGE_VERSION = "0.1.0";
+export declare const emitEventInput: {
+    ticket_id: z.ZodString;
+    event_type: z.ZodString;
+    event_version: z.ZodOptional<z.ZodNumber>;
+    kind: z.ZodOptional<z.ZodEnum<{
+        agent_asserted: "agent_asserted";
+        external_observed: "external_observed";
+        human: "human";
+    }>>;
+    source: z.ZodOptional<z.ZodString>;
+    actor_role: z.ZodOptional<z.ZodString>;
+    payload: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    note_md: z.ZodOptional<z.ZodString>;
+    correlation_id: z.ZodOptional<z.ZodString>;
+    idempotency_key: z.ZodOptional<z.ZodString>;
+    occurred_at: z.ZodOptional<z.ZodString>;
+};
+export declare const getTicketTimelineInput: {
+    ticket_id: z.ZodString;
+    since: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+};
+export declare const getActiveTicketsInput: {
+    source: z.ZodOptional<z.ZodString>;
+    project: z.ZodOptional<z.ZodString>;
+    lane: z.ZodOptional<z.ZodString>;
+    assignee: z.ZodOptional<z.ZodString>;
+};
+export interface ApiErrorBody {
+    code?: string;
+    message?: string;
+    field?: string;
+    details?: unknown;
+}
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    readonly body: ApiErrorBody | string;
+    constructor(status: number, body: ApiErrorBody | string, code?: string);
+}
+export interface EmitEventResult {
+    event_id: string;
+    occurred_at: string;
+    status: "created" | "replay";
+}
+export declare function emitEvent(deps: ServerDeps, args: {
+    ticket_id: string;
+    event_type: string;
+    event_version?: number;
+    kind?: "agent_asserted" | "external_observed" | "human";
+    source?: string;
+    actor_role?: string;
+    payload?: Record<string, unknown>;
+    note_md?: string;
+    correlation_id?: string;
+    idempotency_key?: string;
+    occurred_at?: string;
+}): Promise<EmitEventResult>;
+export declare function getTicketTimeline(deps: ServerDeps, args: {
+    ticket_id: string;
+    since?: string;
+    limit?: number;
+}): Promise<{
+    events: unknown[];
+}>;
+export declare function getActiveTickets(deps: ServerDeps, args: {
+    source?: string;
+    project?: string;
+    lane?: string;
+    assignee?: string;
+}): Promise<{
+    tickets: unknown[];
+}>;
+export declare function createServer(deps: ServerDeps): McpServer;

package/dist/server.js

@@ -0,0 +1,374 @@
+/**
+ * MCP server factory for @bli-cockpit/mcp.
+ *
+ * Pure factory — accepts injected fetch + base URL + token so it can be
+ * unit-tested without binding to a real network or transport.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { registerDocsMsgTools } from "./docs-msg-tools.js";
+export const PACKAGE_NAME = "@bli-cockpit/mcp";
+export const PACKAGE_VERSION = "0.1.0";
+// ---- input schemas (Zod raw shapes) -----------------------------------------
+export const emitEventInput = {
+    ticket_id: z
+        .string()
+        .min(1)
+        .describe("Linear ticket ID (e.g. BLI-2115, KOLM-87)."),
+    event_type: z
+        .string()
+        .min(1)
+        .describe("Canonical event type from the event vocabulary (e.g. ticket_claimed, plan_submitted, worker_dispatched, note)."),
+    event_version: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Event schema version. Defaults to 1 in the API."),
+    kind: z
+        .enum(["agent_asserted", "external_observed", "human"])
+        .optional()
+        .describe("Event kind. Omit to let the API infer it from event_type."),
+    source: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Advanced producer identity override. Omit during normal use so the API derives source from the authenticated operator."),
+    actor_role: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Actor role for the event. Defaults to operator."),
+    payload: z
+        .record(z.string(), z.unknown())
+        .optional()
+        .describe("Event payload object. Defaults to {}."),
+    note_md: z
+        .string()
+        .optional()
+        .describe("Optional markdown note attached to the event."),
+    correlation_id: z
+        .string()
+        .optional()
+        .describe("Correlation ID linking related events (e.g. an agent trace ID)."),
+    idempotency_key: z
+        .string()
+        .optional()
+        .describe("Idempotency key — replays return status 'replay' instead of 'created'."),
+    occurred_at: z
+        .string()
+        .optional()
+        .describe("ISO-8601 timestamp. Defaults to now in the API."),
+};
+export const getTicketTimelineInput = {
+    ticket_id: z.string().min(1).describe("Linear ticket ID."),
+    since: z
+        .string()
+        .optional()
+        .describe("ISO-8601 timestamp; only return events occurring after this."),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(500)
+        .optional()
+        .describe("Max events to return (default 100, max 500)."),
+};
+export const getActiveTicketsInput = {
+    source: z
+        .string()
+        .optional()
+        .describe("Filter by source (e.g. cli:vee, worker, ci)."),
+    project: z
+        .string()
+        .optional()
+        .describe("Filter by project tag (bui, kolm, portpal, bp)."),
+    lane: z
+        .string()
+        .optional()
+        .describe("Filter by lane (e.g. Planning, Executing, Awaiting Review)."),
+    assignee: z.string().optional().describe("Filter by assignee user ID."),
+};
+export class ApiError extends Error {
+    status;
+    code;
+    body;
+    constructor(status, body, code) {
+        const summary = typeof body === "string"
+            ? body
+            : (body.message ?? `HTTP ${status}`);
+        super(`[${code ?? `HTTP-${status}`}] ${summary}`);
+        this.name = "ApiError";
+        this.status = status;
+        this.body = body;
+        this.code = code;
+    }
+}
+async function parseMaybeJson(response) {
+    const text = await response.text();
+    if (!text)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        // BLI-3238 — deliberately silent. This function's contract is "maybe
+        // JSON": a non-JSON body is an expected shape, not a failure, and the
+        // text is returned intact rather than discarded — ApiError carries it
+        // verbatim to the caller, so nothing is lost for a log to recover.
+        return text;
+    }
+}
+async function callApi(deps, method, path, body) {
+    const url = `${deps.baseUrl.replace(/\/$/, "")}${path}`;
+    // Resolve a fresh token per call. Implementations are expected to cache
+    // internally (see createSessionHelperTokenResolver) so burst calls don't
+    // each spawn a subprocess.
+    let token;
+    try {
+        token = await deps.resolveToken();
+    }
+    catch (err) {
+        // Auth-side failure (no session, revoked refresh token, helper missing).
+        // Surface as BLI-E003 per error catalog so it's distinct from network.
+        throw new ApiError(401, {
+            code: "BLI-E003",
+            message: `Token resolution failed: ${err instanceof Error ? err.message : String(err)}`,
+        }, "BLI-E003");
+    }
+    const headers = {
+        Authorization: `Bearer ${token}`,
+        Accept: "application/json",
+    };
+    if (body !== undefined) {
+        headers["Content-Type"] = "application/json";
+    }
+    let response;
+    try {
+        response = await deps.fetchImpl(url, {
+            method,
+            headers,
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+    }
+    catch (err) {
+        // Network / DNS / TLS failure — surface as BLI-E001 per error catalog.
+        throw new ApiError(0, {
+            code: "BLI-E001",
+            message: `Network error contacting ${url}: ${err instanceof Error ? err.message : String(err)}`,
+        }, "BLI-E001");
+    }
+    const parsed = await parseMaybeJson(response);
+    if (!response.ok) {
+        const errBody = parsed && typeof parsed === "object"
+            ? parsed
+            : parsed ?? response.statusText;
+        const code = typeof errBody === "object" && errBody !== null
+            ? errBody.code
+            : undefined;
+        throw new ApiError(response.status, errBody, code);
+    }
+    return parsed;
+}
+export async function emitEvent(deps, args) {
+    const body = {
+        ticket_id: args.ticket_id,
+        event_type: args.event_type,
+        actor_role: args.actor_role ?? "operator",
+        payload: args.payload ?? {},
+        ...(args.event_version !== undefined
+            ? { event_version: args.event_version }
+            : {}),
+        ...(args.kind !== undefined ? { kind: args.kind } : {}),
+        ...(args.source !== undefined ? { source: args.source } : {}),
+        ...(args.note_md !== undefined ? { note_md: args.note_md } : {}),
+        ...(args.correlation_id !== undefined
+            ? { correlation_id: args.correlation_id }
+            : {}),
+        ...(args.idempotency_key !== undefined
+            ? { idempotency_key: args.idempotency_key }
+            : {}),
+        ...(args.occurred_at !== undefined ? { occurred_at: args.occurred_at } : {}),
+    };
+    const response = (await callApi(deps, "POST", "/api/events/emit", body));
+    if (!response || typeof response !== "object") {
+        throw new ApiError(502, {
+            code: "BLI-E001",
+            message: "Malformed response from /api/events/emit",
+            details: response,
+        });
+    }
+    if ("status" in response && response.status === "replay") {
+        const eventId = "event_id" in response && typeof response.event_id === "string"
+            ? response.event_id
+            : "existing_event_id" in response &&
+                typeof response.existing_event_id === "string"
+                ? response.existing_event_id
+                : "";
+        if (!eventId) {
+            throw new ApiError(502, {
+                code: "BLI-E001",
+                message: "Malformed replay response from /api/events/emit",
+                details: response,
+            });
+        }
+        const occurredAt = "existing_received_at" in response &&
+            typeof response.existing_received_at === "string"
+            ? response.existing_received_at
+            : "existing_occurred_at" in response &&
+                typeof response.existing_occurred_at === "string"
+                ? response.existing_occurred_at
+                : "";
+        if (!occurredAt) {
+            throw new ApiError(502, {
+                code: "BLI-E001",
+                message: "Malformed replay timestamp from /api/events/emit",
+                details: response,
+            });
+        }
+        return {
+            event_id: eventId,
+            occurred_at: occurredAt,
+            status: "replay",
+        };
+    }
+    const event = "event" in response && response.event && typeof response.event === "object"
+        ? response.event
+        : null;
+    const eventId = "event_id" in response && typeof response.event_id === "string"
+        ? response.event_id
+        : typeof event?.id === "string"
+            ? event.id
+            : "";
+    const occurredAt = "occurred_at" in response && typeof response.occurred_at === "string"
+        ? response.occurred_at
+        : typeof event?.received_at === "string"
+            ? event.received_at
+            : typeof event?.occurred_at === "string"
+                ? event.occurred_at
+                : "";
+    if (!eventId || !occurredAt) {
+        throw new ApiError(502, {
+            code: "BLI-E001",
+            message: "Malformed created response from /api/events/emit",
+            details: response,
+        });
+    }
+    return {
+        event_id: eventId,
+        occurred_at: occurredAt,
+        status: "created",
+    };
+}
+export async function getTicketTimeline(deps, args) {
+    const params = new URLSearchParams({ ticket_id: args.ticket_id });
+    if (args.since)
+        params.set("since", args.since);
+    if (args.limit !== undefined)
+        params.set("limit", String(args.limit));
+    const response = (await callApi(deps, "GET", `/api/events/timeline?${params.toString()}`));
+    return { events: response?.events ?? [] };
+}
+export async function getActiveTickets(deps, args) {
+    const params = new URLSearchParams();
+    if (args.source)
+        params.set("source", args.source);
+    if (args.project)
+        params.set("project", args.project);
+    if (args.lane)
+        params.set("lane", args.lane);
+    if (args.assignee)
+        params.set("assignee", args.assignee);
+    const query = params.toString();
+    const path = query ? `/api/tickets/active?${query}` : "/api/tickets/active";
+    const response = (await callApi(deps, "GET", path));
+    return { tickets: response?.tickets ?? [] };
+}
+// ---- result formatting helpers ---------------------------------------------
+function jsonContent(value) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(value, null, 2),
+            },
+        ],
+    };
+}
+function errorContent(err) {
+    let message;
+    let code;
+    if (err instanceof ApiError) {
+        message = err.message;
+        code = err.code;
+    }
+    else if (err instanceof Error) {
+        message = err.message;
+    }
+    else {
+        message = String(err);
+    }
+    return {
+        isError: true,
+        content: [
+            {
+                type: "text",
+                text: code ? `[${code}] ${message}` : message,
+            },
+        ],
+    };
+}
+// ---- server factory ---------------------------------------------------------
+export function createServer(deps) {
+    const server = new McpServer({
+        name: PACKAGE_NAME,
+        version: PACKAGE_VERSION,
+    });
+    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.",
+        inputSchema: emitEventInput,
+    }, async (args) => {
+        try {
+            const result = await emitEvent(deps, args);
+            return jsonContent(result);
+        }
+        catch (err) {
+            return errorContent(err);
+        }
+    });
+    server.registerTool("get_ticket_timeline", {
+        title: "Get ticket event timeline",
+        description: "Return the canonical event timeline for a ticket, optionally filtered by since/limit. Wraps GET /api/events/timeline.",
+        inputSchema: getTicketTimelineInput,
+    }, async (args) => {
+        try {
+            const result = await getTicketTimeline(deps, args);
+            return jsonContent(result);
+        }
+        catch (err) {
+            return errorContent(err);
+        }
+    });
+    server.registerTool("get_active_tickets", {
+        title: "List active tickets",
+        description: "Return task-visible tickets with active orchestration state, optionally filtered by source/project/lane/assignee. Wraps GET /api/tickets/active.",
+        inputSchema: getActiveTicketsInput,
+    }, async (args) => {
+        try {
+            const result = await getActiveTickets(deps, args);
+            return jsonContent(result);
+        }
+        catch (err) {
+            return errorContent(err);
+        }
+    });
+    // BLI-3706: docs_*/msg_* over the collector device token, a SEPARATE auth
+    // path from the emit_event/get_ticket_timeline/get_active_tickets tools
+    // above (which use BLI_OPERATOR_TOKEN / the session helper). Registered
+    // unconditionally — the session is loaded fresh per call, so 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.
+    registerDocsMsgTools(server, { fetchImpl: deps.fetchImpl });
+    return server;
+}

package/dist/token-resolver.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Token resolution for the MCP server.
+ *
+ * Two auth paths, matching the `bli-event` bash CLI precedence:
+ *
+ *   1. `BLI_OPERATOR_TOKEN` env var — used verbatim (CI / explicit override)
+ *   2. Fallback: spawn `node <bli-event-session.mjs> get-token` — refreshes
+ *      the cached Supabase session if the access_token is near expiry, and
+ *      prints a fresh access_token on stdout. Exits non-zero if no session
+ *      exists (user must run `bli-event login`).
+ *
+ * The session-helper path spawns a subprocess per resolution. To keep the
+ * overhead invisible for bursts of tool calls (e.g. agent emitting a
+ * timeline fetch + multiple events in sequence), resolved tokens are cached
+ * in-process for a short window. The cache is time-based only — if the
+ * underlying session refresh fails, the NEXT call (after TTL expiry) will
+ * surface the error.
+ */
+import type { ChildProcess, SpawnOptions } from "node:child_process";
+export type TokenResolver = () => Promise<string>;
+/**
+ * Resolver that returns a static token verbatim. Use for the
+ * `BLI_OPERATOR_TOKEN` env var path (CI / override).
+ */
+export declare function createEnvTokenResolver(token: string): TokenResolver;
+export type SpawnFn = (command: string, args: readonly string[], options?: SpawnOptions) => ChildProcess;
+export interface SessionHelperOptions {
+    /** Absolute path to `bli-event-session.mjs`. */
+    helperPath: string;
+    /** Node executable used to run the helper. Default: `process.execPath`. */
+    nodePath?: string;
+    /** Injectable spawn for tests. Default: `child_process.spawn`. */
+    spawn?: SpawnFn;
+    /**
+     * How long (ms) to cache a resolved token in-process before spawning the
+     * helper again. The helper itself refreshes the session when the access
+     * token is near expiry, so a small cache window is all we need to absorb
+     * bursts of tool calls. Default 30_000 (30s). Set to 0 to disable caching.
+     */
+    cacheTtlMs?: number;
+    /**
+     * Clock source for cache bookkeeping. Default `Date.now`.
+     */
+    now?: () => number;
+    /** Env vars forwarded to the helper. Default: `process.env`. */
+    env?: NodeJS.ProcessEnv;
+}
+/** Thrown when the session helper is missing or fails to resolve a token. */
+export declare class SessionHelperError extends Error {
+    readonly exitCode: number | null;
+    readonly stderr: string;
+    constructor(message: string, exitCode: number | null, stderr: string);
+}
+/**
+ * Resolver that shells out to the Node session helper to get (and refresh)
+ * the operator's Supabase access_token.
+ */
+export declare function createSessionHelperTokenResolver(options: SessionHelperOptions): TokenResolver;
+export interface ResolveHelperPathOptions {
+    /**
+     * Env vars to inspect. Default: `process.env`.
+     */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * The `import.meta.url` of the calling module — used to walk up the tree
+     * looking for a sibling `scripts/bli-event-session.mjs`. Default:
+     * `import.meta.url` of this module. Tests can inject a synthetic path.
+     */
+    fromUrl?: string;
+    /**
+     * Override for `fs.existsSync` so tests can fake the filesystem.
+     */
+    existsSync?: (p: string) => boolean;
+}
+/**
+ * Locate `scripts/bli-event-session.mjs` on disk, or return `null`.
+ *
+ * Order:
+ *   1. If `BLI_SESSION_HELPER` env var points at a readable file, use it.
+ *   2. Walk up from `import.meta.url` looking for a sibling
+ *      `scripts/bli-event-session.mjs` (handles dev checkouts + installed
+ *      npm workspaces where the MCP dist/ lives under `packages/bli-cockpit-mcp/`
+ *      inside the monorepo root).
+ *   3. Return `null` — caller surfaces a clear error.
+ */
+export declare function resolveSessionHelperPath(options?: ResolveHelperPathOptions): string | null;
+export interface DefaultTokenResolverOptions {
+    env?: NodeJS.ProcessEnv;
+    /**
+     * Injectable dependencies forwarded to `createSessionHelperTokenResolver`
+     * when the env override is not set.
+     */
+    spawn?: SpawnFn;
+    nodePath?: string;
+    cacheTtlMs?: number;
+    now?: () => number;
+    /** Override helper-path discovery (tests). */
+    resolveHelperPath?: () => string | null;
+}
+export interface DefaultTokenResolverResult {
+    /** The resolver to install on the server. */
+    resolver: TokenResolver;
+    /** Which source fed the resolver — useful for startup logging. */
+    source: "env" | "session-helper";
+    /** If source is `session-helper`, the resolved helper path. */
+    helperPath?: string;
+}
+/**
+ * Build a `TokenResolver` using the documented precedence order:
+ *   1. `BLI_OPERATOR_TOKEN` env var (verbatim)
+ *   2. Session helper (`scripts/bli-event-session.mjs get-token`)
+ *
+ * Throws with a clear, user-actionable message when neither path is
+ * available (no env var, and no session helper on disk).
+ */
+export declare function createDefaultTokenResolver(options?: DefaultTokenResolverOptions): DefaultTokenResolverResult;