@kammcs/buildit-mcp 0.0.0-stage → 0.2.0

package/dist/toolsets/catalog.js

@@ -0,0 +1,72 @@
+/**
+ * Every tool, resource and prompt this server can offer. Add new ones here
+ * (see CLAUDE.md). Order doesn't matter: the registry sorts the list it
+ * serves.
+ */
+import { PROMPTS } from '../prompts.js';
+import { RESOURCES } from '../resources.js';
+import { listChannelsTool, readChannelTool, readThreadTool } from '../tools/chat.js';
+import { addCommentTool, listCommentsTool } from '../tools/comments.js';
+import { getItemTool, searchItemsTool } from '../tools/items-read.js';
+import { assignItemTool, createItemTool, linkItemsTool, rankItemTool, transitionItemTool, unlinkItemsTool, updateItemTool, } from '../tools/items-write.js';
+import { createPageTool, getPageTool, listPagesTool, searchPagesTool, updatePageTool, } from '../tools/pages.js';
+import { listReleasesTool, listSprintsTool, planReleaseTool, planSprintTool, writeReleaseNotesTool, } from '../tools/planning.js';
+import { applyPlanTool, getWorkflowTool, listWorkTypesTool, proposeArchiveStatusTool, proposeBulkUpdateTool, proposeDeleteItemTool, proposeFieldChangeTool, proposeLabelChangeTool, proposeMoveItemTool, proposeWorkflowChangeTool, proposeWorkTypeChangeTool, } from '../tools/plans.js';
+import { describeProjectTool, findUsersTool, listProjectsTool } from '../tools/projects.js';
+import { createChannelTool, createProjectTool } from '../tools/setup.js';
+import { whoamiTool } from '../tools/whoami.js';
+export const CATALOG = [
+    // items
+    whoamiTool,
+    listProjectsTool,
+    describeProjectTool,
+    findUsersTool,
+    searchItemsTool,
+    getItemTool,
+    createItemTool,
+    updateItemTool,
+    assignItemTool,
+    transitionItemTool,
+    linkItemsTool,
+    unlinkItemsTool,
+    rankItemTool,
+    // comments
+    listCommentsTool,
+    addCommentTool,
+    // planning
+    listSprintsTool,
+    planSprintTool,
+    listReleasesTool,
+    planReleaseTool,
+    writeReleaseNotesTool,
+    // pages
+    listPagesTool,
+    searchPagesTool,
+    getPageTool,
+    createPageTool,
+    updatePageTool,
+    // chat
+    listChannelsTool,
+    readChannelTool,
+    readThreadTool,
+    // admin
+    createChannelTool,
+    createProjectTool,
+    getWorkflowTool,
+    listWorkTypesTool,
+    proposeWorkflowChangeTool,
+    proposeWorkTypeChangeTool,
+    proposeFieldChangeTool,
+    proposeLabelChangeTool,
+    // destructive
+    proposeDeleteItemTool,
+    proposeMoveItemTool,
+    proposeBulkUpdateTool,
+    proposeArchiveStatusTool,
+    // listed with any propose_* tool
+    applyPlanTool,
+];
+/** Resource templates (buildit://items/{key}, buildit://pages/{id}). */
+export const RESOURCE_CATALOG = RESOURCES;
+/** Prompts (plan_epic, triage, standup). */
+export const PROMPT_CATALOG = PROMPTS;

package/dist/toolsets/registry.js

@@ -0,0 +1,97 @@
+import { callOperation } from '../api/operations.js';
+import { expandScopes, TOOLSETS } from './toolsets.js';
+/** The context for one call of `tool`. */
+export function createToolContext(init) {
+    const apiOptions = {
+        tool: init.tool,
+        ...(init.client ? { client: init.client } : {}),
+        ...(init.signal ? { signal: init.signal } : {}),
+    };
+    return {
+        api: init.api,
+        logger: init.logger,
+        ...(init.signal ? { signal: init.signal } : {}),
+        apiOptions,
+        call: (id, args = {}) => callOperation(init.api, id, args, apiOptions),
+    };
+}
+/** Identity helper that keeps the argument and output types tied to the schemas. */
+export function defineTool(definition) {
+    return definition;
+}
+const TOOLSET_ORDER = new Map(TOOLSETS.map((t, i) => [t.name, i]));
+function compareTools(a, b) {
+    const byToolset = (TOOLSET_ORDER.get(a.toolset) ?? 99) - (TOOLSET_ORDER.get(b.toolset) ?? 99);
+    if (byToolset !== 0)
+        return byToolset;
+    return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+}
+/**
+ * The tools a caller may see, in a fixed order (toolset order, then name).
+ *
+ * @param grantedScopes the token's scopes from /v1/me, or `null` to skip the
+ *   scope rule (used when serving a call: the API checks scopes itself).
+ * @param limited whether /v1/me shows project or channel limits on the token:
+ *   tools marked `unlimitedOnly` are then left out (ignored when
+ *   `grantedScopes` is null, since the identity isn't known).
+ */
+export function selectTools(catalog, policy, grantedScopes, limited = false) {
+    const toolsets = new Set(policy.toolsets);
+    const excluded = new Set(policy.excludeTools);
+    const scopes = grantedScopes === null ? null : expandScopes(grantedScopes);
+    const allowed = (tool) => (!policy.readOnly || tool.annotations.readOnlyHint) && !excluded.has(tool.name);
+    const listed = catalog
+        .filter((tool) => tool.withPlans !== true)
+        .filter((tool) => toolsets.has(tool.toolset))
+        .filter(allowed)
+        .filter((tool) => scopes === null || tool.scopes.every((s) => scopes.has(s)))
+        .filter((tool) => scopes === null || !limited || tool.unlimitedOnly !== true);
+    const proposes = listed.some((tool) => tool.name.startsWith(PROPOSE_PREFIX));
+    const companions = proposes
+        ? catalog.filter((tool) => tool.withPlans === true).filter(allowed)
+        : [];
+    return [...listed, ...companions].sort(compareTools);
+}
+/** Tools that propose a plan start with this; apply_plan comes with them. */
+export const PROPOSE_PREFIX = 'propose_';
+/** The resources or prompts a caller may see: by toolset and, when known, scopes. */
+export function selectGated(defs, toolsets, grantedScopes) {
+    const enabled = new Set(toolsets);
+    const scopes = grantedScopes === null ? null : expandScopes(grantedScopes);
+    return defs
+        .filter((d) => enabled.has(d.toolset))
+        .filter((d) => scopes === null || d.scopes.every((s) => scopes.has(s)));
+}
+export function definePrompt(definition) {
+    return definition;
+}
+/** Names in `names` that no tool in the catalog has (for a startup warning). */
+export function unknownToolNames(catalog, names) {
+    const known = new Set(catalog.map((t) => t.name));
+    return names.filter((n) => !known.has(n));
+}
+/** Throws if the catalog breaks the rules every tool must follow (checked by the tests). */
+export function assertValidCatalog(catalog) {
+    const seen = new Set();
+    for (const tool of catalog) {
+        if (!/^[a-z][a-z0-9_]{0,63}$/.test(tool.name))
+            throw new Error(`Bad tool name: ${tool.name}`);
+        if (seen.has(tool.name))
+            throw new Error(`Duplicate tool name: ${tool.name}`);
+        seen.add(tool.name);
+        const toolset = TOOLSETS.find((t) => t.name === tool.toolset);
+        if (!toolset)
+            throw new Error(`${tool.name}: unknown toolset ${tool.toolset}`);
+        for (const scope of tool.scopes) {
+            if (!toolset.scopes.includes(scope)) {
+                throw new Error(`${tool.name}: scope ${scope} is not declared by toolset ${tool.toolset}`);
+            }
+        }
+        if (tool.annotations.readOnlyHint && tool.annotations.destructiveHint) {
+            throw new Error(`${tool.name}: a read-only tool can't be destructive`);
+        }
+        if (tool.withPlans === true && tool.scopes.length > 0) {
+            throw new Error(`${tool.name}: a tool listed with plans takes the plan's scope, not its own`);
+        }
+    }
+}

package/dist/toolsets/toolsets.js

@@ -0,0 +1,89 @@
+/**
+ * The toolsets and the token scopes their tools use.
+ *
+ * A toolset is a group of tools that can be switched on or off together
+ * (BUILDIT_TOOLSETS, --toolsets, or the X-Buildit-Toolsets header in HTTP
+ * mode). Each tool also declares the exact scopes it needs; a tool is only
+ * listed when the token has them.
+ */
+import { SCOPE_IMPLIES, SCOPES } from '../api/generated/operations.js';
+/** Token scopes defined by the agent API (from the contract). */
+export { SCOPE_IMPLIES, SCOPES };
+/**
+ * Adds the implied scopes, transitively, as the contract defines them
+ * (projects:delete implies projects:write, which implies projects:read).
+ * Unknown scope strings are kept as they are. The API is the authority; this
+ * only keeps the tool list from hiding tools a granted scope allows.
+ */
+export function expandScopes(granted) {
+    const out = new Set();
+    const pending = [...granted];
+    for (let scope = pending.pop(); scope !== undefined; scope = pending.pop()) {
+        if (out.has(scope))
+            continue;
+        out.add(scope);
+        if (Object.hasOwn(SCOPE_IMPLIES, scope))
+            pending.push(...SCOPE_IMPLIES[scope]);
+    }
+    return out;
+}
+export const TOOLSET_NAMES = [
+    'items',
+    'comments',
+    'planning',
+    'pages',
+    'chat',
+    'admin',
+    'destructive',
+];
+/** In the order tools are listed. */
+export const TOOLSETS = [
+    {
+        name: 'items',
+        description: 'Projects and their items: search, read, create, update, transition, assign, link.',
+        defaultEnabled: true,
+        scopes: ['projects:read', 'projects:write'],
+    },
+    {
+        name: 'comments',
+        description: 'Comments on items: list and add.',
+        defaultEnabled: true,
+        scopes: ['projects:read', 'projects:write'],
+    },
+    {
+        name: 'planning',
+        description: 'Sprints and releases, and release notes pages.',
+        defaultEnabled: false,
+        // Release notes are written as a page.
+        scopes: ['projects:read', 'projects:write', 'pages:write'],
+    },
+    {
+        name: 'pages',
+        description: 'Channel pages: list, read, create and edit.',
+        defaultEnabled: false,
+        scopes: ['pages:read', 'pages:write'],
+    },
+    {
+        name: 'chat',
+        description: 'Channel messages and threads (read only; never direct messages).',
+        defaultEnabled: false,
+        scopes: ['chat:read'],
+    },
+    {
+        name: 'admin',
+        description: 'New channels and projects; workflows, work types, fields and labels, each change previewed and confirmed.',
+        defaultEnabled: false,
+        scopes: ['projects:read', 'projects:admin'],
+    },
+    {
+        name: 'destructive',
+        description: 'Delete, move, bulk update and archive; every change is previewed and confirmed.',
+        defaultEnabled: false,
+        // Archiving a status also changes the workflow.
+        scopes: ['projects:read', 'projects:delete', 'projects:admin'],
+    },
+];
+export const DEFAULT_TOOLSETS = TOOLSETS.filter((t) => t.defaultEnabled).map((t) => t.name);
+export function isToolsetName(value) {
+    return TOOLSET_NAMES.includes(value);
+}

package/dist/transports/http.js

@@ -0,0 +1,212 @@
+/**
+ * Streamable HTTP mode: stateless, one MCP server instance per request.
+ *
+ * - Every POST must carry `Authorization: Bearer <token>`; that request's
+ *   API calls use that token, and nothing is kept afterwards.
+ * - Host and Origin are checked before anything else (DNS-rebinding
+ *   protection): on a loopback bind only localhost names pass; elsewhere the
+ *   configured lists apply, and any request with an Origin header is refused
+ *   unless its hostname is listed. Off loopback, allowed hosts are required
+ *   unless the operator explicitly opts out (allowAnyHost).
+ * - GET and DELETE on the endpoint answer 405: there are no sessions to
+ *   resume or end, and no standalone event stream.
+ * - `X-Buildit-Toolsets` narrows the toolsets for one request: only toolsets
+ *   the server's own config enables can be picked, and read-only mode and
+ *   the exclude list still apply. The header can never add a toolset.
+ * - Both protocol eras are served: 2026-07-28 (stateless, per-request _meta)
+ *   and the 2025-11-25 initialize handshake (through the SDK's stateless
+ *   fallback).
+ */
+import { randomUUID } from 'node:crypto';
+import { serve } from '@hono/node-server';
+import { hostHeaderValidation, originValidation } from '@modelcontextprotocol/hono';
+import { createMcpHandler, isJsonContentType, localhostAllowedHostnames, localhostAllowedOrigins, readRequestBody, } from '@modelcontextprotocol/server';
+import { Hono } from 'hono';
+import { ApiClient } from '../api/client.js';
+import { ConfigError, isLoopbackHost, parseToolsets } from '../config.js';
+import { IdentityCache, invalidatesIdentity } from '../identity.js';
+import { createMcpServer, DEGRADED_LIST_TTL_MS, listedByPolicy, resolveListedTools, identityFromApi, } from '../server.js';
+import { CATALOG } from '../toolsets/catalog.js';
+export const MCP_PATH = '/mcp';
+export const TOOLSETS_HEADER = 'x-buildit-toolsets';
+const MAX_BODY_BYTES = 1024 * 1024;
+function jsonRpcError(code, message) {
+    return { jsonrpc: '2.0', error: { code, message }, id: null };
+}
+/** The bearer token from an Authorization header, or undefined. */
+export function bearerToken(header) {
+    if (header === undefined)
+        return undefined;
+    const match = /^Bearer[ \t]+([^\s]+)[ \t]*$/i.exec(header.trim());
+    return match?.[1];
+}
+/** The list methods whose answer depends on the token's scopes. */
+const LIST_METHODS = new Set([
+    'tools/list',
+    'resources/list',
+    'resources/templates/list',
+    'prompts/list',
+]);
+/** Whether a JSON-RPC body (single or batch) lists tools, resources or prompts. */
+function listsTools(body) {
+    const messages = Array.isArray(body) ? body : [body];
+    return messages.some((m) => {
+        const method = m !== null && typeof m === 'object' ? m.method : undefined;
+        return typeof method === 'string' && LIST_METHODS.has(method);
+    });
+}
+export function createHttpApp(config, logger, options = {}) {
+    const catalog = options.catalog ?? CATALOG;
+    const loopback = isLoopbackHost(config.http.host);
+    if (!loopback && config.http.allowedHosts === undefined && config.http.allowAnyHost !== true) {
+        throw new ConfigError(`Binding to ${config.http.host} needs allowed hosts (BUILDIT_ALLOWED_HOSTS), or BUILDIT_ALLOW_ANY_HOST=true to serve without the Host check.`);
+    }
+    const allowedHosts = config.http.allowedHosts ?? (loopback ? localhostAllowedHostnames() : undefined);
+    const allowedOrigins = config.http.allowedOrigins ?? (loopback ? localhostAllowedOrigins() : []);
+    const basePolicy = {
+        readOnly: config.readOnly,
+        excludeTools: config.excludeTools,
+    };
+    // The token's scopes and limits, briefly, so listing doesn't read /v1/me on every request.
+    const identities = new IdentityCache(options.identityCache);
+    const handler = createMcpHandler(async (ctx) => {
+        const auth = ctx.authInfo;
+        // Unreachable: the route below only calls the handler with authInfo.
+        if (!auth)
+            throw new Error('missing caller');
+        const extra = auth.extra;
+        const token = auth.token;
+        const reqLogger = logger.child({ http_request_id: extra.requestId });
+        const api = new ApiClient({
+            baseUrl: config.apiUrl,
+            token,
+            logger: reqLogger,
+            ...(options.fetch ? { fetch: options.fetch } : {}),
+            onError: (err) => {
+                if (invalidatesIdentity(err))
+                    identities.evict(token);
+            },
+        });
+        const policy = { ...basePolicy, toolsets: extra.toolsets };
+        // Listing reads the token's scopes (cached briefly); a call is checked by the API itself.
+        if (!extra.lists) {
+            return createMcpServer({ ...listedByPolicy(catalog, policy), api, logger: reqLogger });
+        }
+        const readIdentity = identityFromApi(api);
+        const listed = await resolveListedTools(() => identities.get(token, readIdentity), catalog, policy, reqLogger);
+        return createMcpServer({
+            tools: listed.tools,
+            resources: listed.resources,
+            prompts: listed.prompts,
+            api,
+            logger: reqLogger,
+            // A list made without the token's scopes is cached briefly, so it is soon read again.
+            ...(listed.identity === 'known' ? {} : { toolsListTtlMs: DEGRADED_LIST_TTL_MS }),
+        });
+    }, {
+        onerror: (error) => {
+            logger.warn('mcp handler error', { error });
+        },
+        maxRequestBodySize: MAX_BODY_BYTES,
+    });
+    const app = new Hono();
+    // Access log: method, path, status and timing only. Never headers or bodies.
+    app.use('*', async (c, next) => {
+        const started = Date.now();
+        await next();
+        logger.info('http request', {
+            method: c.req.method,
+            path: c.req.path,
+            status: c.res.status,
+            duration_ms: Date.now() - started,
+        });
+    });
+    // Before the Host check: container and platform probes call it by
+    // localhost or the instance's address, and it says nothing but "ok".
+    app.get('/healthz', (c) => c.json({ status: 'ok' }));
+    if (allowedHosts !== undefined)
+        app.use('*', hostHeaderValidation(allowedHosts));
+    app.use('*', originValidation(allowedOrigins));
+    const methodNotAllowed = (c) => {
+        c.header('Allow', 'POST');
+        return c.json(jsonRpcError(-32000, 'Method not allowed. This server is stateless: POST only.'), 405);
+    };
+    app.on(['GET', 'DELETE', 'PUT', 'PATCH'], MCP_PATH, methodNotAllowed);
+    app.post(MCP_PATH, async (c) => {
+        const token = bearerToken(c.req.header('authorization'));
+        if (token === undefined) {
+            c.header('WWW-Authenticate', 'Bearer realm="buildit-mcp"');
+            return c.json(jsonRpcError(-32001, 'Unauthorized: send "Authorization: Bearer <token>" with a buildIt.Social personal access token.'), 401);
+        }
+        let toolsets = config.toolsets;
+        const header = c.req.header(TOOLSETS_HEADER);
+        if (header !== undefined) {
+            let asked;
+            try {
+                asked = parseToolsets(header, 'X-Buildit-Toolsets');
+            }
+            catch (err) {
+                if (!(err instanceof ConfigError))
+                    throw err;
+                return c.json(jsonRpcError(-32602, err.message), 400);
+            }
+            // The configured toolsets are a ceiling: the header can only narrow them.
+            toolsets = config.toolsets.filter((t) => asked.includes(t));
+        }
+        let parsedBody = undefined;
+        if (isJsonContentType(c.req.header('content-type'))) {
+            const body = await readRequestBody(c.req.raw.clone(), MAX_BODY_BYTES);
+            if (body.tooLarge) {
+                return c.json(jsonRpcError(-32000, 'Payload too large.'), 413);
+            }
+            try {
+                parsedBody = JSON.parse(body.text);
+            }
+            catch {
+                return c.json(jsonRpcError(-32700, 'Parse error: the body is not valid JSON.'), 400);
+            }
+        }
+        const extra = {
+            toolsets,
+            lists: listsTools(parsedBody),
+            requestId: randomUUID(),
+        };
+        return handler.fetch(c.req.raw, {
+            ...(parsedBody === undefined ? {} : { parsedBody }),
+            authInfo: { token, clientId: 'buildit-personal-access-token', scopes: [], extra },
+        });
+    });
+    app.notFound((c) => c.json(jsonRpcError(-32000, `Not found. The MCP endpoint is ${MCP_PATH}.`), 404));
+    app.onError((err, c) => {
+        logger.error('http handler failed', { error: err });
+        return c.json(jsonRpcError(-32603, 'Internal error.'), 500);
+    });
+    return { app, handler };
+}
+export async function startHttp(config, logger, options = {}) {
+    const { app, handler } = createHttpApp(config, logger, options);
+    const server = await new Promise((resolve, reject) => {
+        const s = serve({ fetch: app.fetch, hostname: config.http.host, port: config.http.port }, () => {
+            resolve(s);
+        });
+        s.once('error', reject);
+    });
+    const port = server.address().port;
+    const hostForUrl = config.http.host.includes(':') ? `[${config.http.host}]` : config.http.host;
+    const url = `http://${hostForUrl}:${port}${MCP_PATH}`;
+    logger.info('listening', { url });
+    return {
+        url,
+        port,
+        close: async () => {
+            await handler.close();
+            await new Promise((resolve) => {
+                server.close(() => {
+                    resolve();
+                });
+                if ('closeAllConnections' in server)
+                    server.closeAllConnections();
+            });
+        },
+    };
+}

package/dist/transports/stdio.js

@@ -0,0 +1,203 @@
+import { isJSONRPCRequest, } from '@modelcontextprotocol/server';
+import { serveStdio, StdioServerTransport, } from '@modelcontextprotocol/server/stdio';
+import { ApiClient } from '../api/client.js';
+import { invalidatesIdentity } from '../identity.js';
+import { createSwitchableMcpServer, DEGRADED_LIST_TTL_MS, listedByPolicy, resolveListedTools, identityFromApi, } from '../server.js';
+import { CATALOG } from '../toolsets/catalog.js';
+import { compareVersions, SERVER_VERSION } from '../version.js';
+/** A known identity is read again at most this often. */
+export const IDENTITY_REFRESH_MS = 60_000;
+/** Methods whose answer depends on the token's scopes: they wait for a due refresh. */
+const LIST_METHODS = new Set([
+    'tools/list',
+    'resources/list',
+    'resources/templates/list',
+    'prompts/list',
+]);
+/** Methods that use something listed: they trigger a due refresh. */
+const CALL_METHODS = new Set(['tools/call', 'resources/read', 'prompts/get']);
+/**
+ * The token's identity for one stdio connection, and the server whose
+ * visible tools follow it.
+ */
+export class StdioIdentity {
+    read;
+    logger;
+    now;
+    listed;
+    refreshAt = 0;
+    pending;
+    generation = 0;
+    server;
+    constructor(read, logger, now = Date.now) {
+        this.read = read;
+        this.logger = logger;
+        this.now = now;
+    }
+    /** The latest listing, if any. */
+    get current() {
+        return this.listed;
+    }
+    /** Whether the identity should be read again before it is relied on. */
+    get due() {
+        return this.listed === undefined || this.now() >= this.refreshAt;
+    }
+    /** Reads the identity again if it is due (one read at a time), and returns the listing. */
+    refresh() {
+        if (this.pending)
+            return this.pending;
+        if (this.listed && !this.due)
+            return Promise.resolve(this.listed);
+        const generation = this.generation;
+        const pending = this.read()
+            .then((result) => {
+            const before = this.listed?.identity;
+            this.listed = result;
+            const wait = result.identity === 'known' ? IDENTITY_REFRESH_MS : (result.error?.retryAfterMs ?? 0);
+            // An invalidation during the read asks for another one.
+            this.refreshAt = generation === this.generation ? this.now() + wait : 0;
+            if (result.identity === 'known' && before !== 'known') {
+                this.logger.info('token identified', {
+                    scopes: result.scopes,
+                    limited: result.limited,
+                    tools: result.tools.length,
+                });
+            }
+            this.server?.show(result);
+            return result;
+        })
+            .finally(() => {
+            if (this.pending === pending)
+                this.pending = undefined;
+        });
+        this.pending = pending;
+        return pending;
+    }
+    /** Read the identity again on the next list or call (after an auth error). */
+    invalidate() {
+        this.generation++;
+        this.refreshAt = 0;
+    }
+    /** The server whose visible tools follow the identity from now on. */
+    attach(server) {
+        this.server = server;
+        if (this.listed)
+            server.show(this.listed);
+    }
+    /** Called before a message reaches the server: refreshes the identity when it is due. */
+    async beforeMessage(message) {
+        if (!isJSONRPCRequest(message) || !this.due)
+            return;
+        if (LIST_METHODS.has(message.method)) {
+            await this.refresh();
+            return;
+        }
+        if (!CALL_METHODS.has(message.method))
+            return;
+        if (this.listed?.identity === 'refused') {
+            // The called tool may be hidden until the token is accepted: wait for the answer.
+            await this.refresh();
+        }
+        else {
+            // The call goes ahead; the API checks it either way.
+            void this.refresh();
+        }
+    }
+}
+/**
+ * A transport that lets `before` run (in order) ahead of each incoming
+ * message, so the identity can be refreshed before a list or call is served.
+ */
+class GatedTransport {
+    inner;
+    before;
+    onclose;
+    onerror;
+    onmessage;
+    queue = Promise.resolve();
+    constructor(inner, before) {
+        this.inner = inner;
+        this.before = before;
+    }
+    start() {
+        this.inner.onmessage = (message, extra) => {
+            this.queue = this.queue
+                .then(() => this.before(message))
+                .catch(() => undefined)
+                .then(() => {
+                this.onmessage?.(message, extra);
+            });
+        };
+        this.inner.onerror = (error) => this.onerror?.(error);
+        this.inner.onclose = () => this.onclose?.();
+        return this.inner.start();
+    }
+    send(message, options) {
+        return this.inner.send(message, options);
+    }
+    close() {
+        return this.inner.close();
+    }
+}
+export function startStdio(config, logger, options = {}) {
+    if (config.token === undefined)
+        throw new Error('stdio mode needs a token');
+    const catalog = options.catalog ?? CATALOG;
+    const policy = {
+        toolsets: config.toolsets,
+        readOnly: config.readOnly,
+        excludeTools: config.excludeTools,
+    };
+    const invalidations = { listener: () => undefined };
+    const api = new ApiClient({
+        baseUrl: config.apiUrl,
+        token: config.token,
+        logger,
+        ...(options.fetch ? { fetch: options.fetch } : {}),
+        onError: (err) => {
+            if (invalidatesIdentity(err))
+                invalidations.listener();
+        },
+    });
+    const identity = new StdioIdentity(() => resolveListedTools(identityFromApi(api), catalog, policy, logger), logger, options.now);
+    invalidations.listener = () => {
+        identity.invalidate();
+    };
+    // Read the identity at startup.
+    void identity.refresh();
+    // Warn early when the API needs a newer server.
+    void api
+        .getMeta()
+        .then((meta) => {
+        if (meta.min_mcp_version && compareVersions(SERVER_VERSION, meta.min_mcp_version) < 0) {
+            logger.warn('this buildit-mcp is older than the API supports; update it', {
+                version: SERVER_VERSION,
+                min_version: meta.min_mcp_version,
+            });
+        }
+    })
+        .catch(() => undefined);
+    // Everything the configuration allows is registered; the identity decides what is shown.
+    const allowed = listedByPolicy(catalog, policy);
+    const wire = options.stdin && options.stdout
+        ? new StdioServerTransport(options.stdin, options.stdout)
+        : new StdioServerTransport();
+    return serveStdio(async () => {
+        const listed = await identity.refresh();
+        const switchable = createSwitchableMcpServer({
+            tools: allowed.tools,
+            resources: allowed.resources,
+            prompts: allowed.prompts,
+            api,
+            logger,
+            ...(listed.identity === 'known' ? {} : { toolsListTtlMs: DEGRADED_LIST_TTL_MS }),
+        });
+        identity.attach(switchable);
+        return switchable.server;
+    }, {
+        onerror: (error) => {
+            logger.error('stdio transport error', { error });
+        },
+        transport: new GatedTransport(wire, (message) => identity.beforeMessage(message)),
+    });
+}