burgee/mcp

burgee/mcp — the MCP server, by itself. See index.ts for why it is not in the barrel.

import { annotationsOf, MCP_PROTOCOL_VERSION, serveMcp, … } from 'burgee/mcp';

FunctionsCopy Anchor Link

annotationsOfCopy Anchor Link

MCP's hints, from the declared effects. destructiveHint is only ever false by declaration.

No declaration returns no hints (G1). That is not a gap: MCP defines a default for each of the three — readOnlyHint: false, destructiveHint: true, idempotentHint: false — so an absent hint already reads as assume the worst, in the client's own vocabulary and without burgee inventing a value it has no basis for. effects: 'undeclared' is the positive half: this command is not a read_only one, and it is not a withheld one either — nobody said.

function annotationsOf(effects?: Effects): ToolAnnotations;

Returns ToolAnnotations

serveMcpCopy Anchor Link

Serve until the input closes.

function serveMcp(manifest: Manifest, opts: ServeOptions): Promise<void>;

Returns Promise<void>

toolsOfCopy Anchor Link

The tool list: every runnable, visible command an author has not withheld.

One word is absent and one is not, and until 2026-09-21 they were the same thing. An author who wrote 'withheld' thought about it and said no; that is what the word is for and it still means absent. An author who wrote nothing — which on burgee's own API checkCommand refuses, and which every command built through the commander or yargs façade is, because neither incumbent has a notion of effects and neither can be made to acquire one without breaking the suites that grade the façades — was treated the same way, so a migrated user's whole program was silently not a tool.

Reading silence as refusal was conservative and it was also the thing standing between the product and its own pitch. Absent-from-the-list is strictly worse for the caller than present-with-honest-annotations: an agent that cannot see a command cannot decide about it, and cannot ask. So an undeclared command is listed and says so — see {@link annotationsOf} for why it carries no hints rather than a reassuring default.

function toolsOf(manifest: Manifest): Tool[];

Returns Tool[]

ConstantsCopy Anchor Link

MCP_PROTOCOL_VERSIONCopy Anchor Link

const MCP_PROTOCOL_VERSION = "2025-06-18";

InterfacesCopy Anchor Link

ServeOptionsCopy Anchor Link

interface ServeOptions {
    input: NodeJS.ReadableStream;
    output: {
        write: (s: string) => unknown;
    };
    invoke: Invoke;
}

ToolCopy Anchor Link

interface Tool {
    name: string;
    description: string;
    inputSchema: JsonSchema;
    annotations: ToolAnnotations;
}

ToolAnnotationsCopy Anchor Link

interface ToolAnnotations {
    readOnlyHint?: boolean;
    idempotentHint?: boolean;
    destructiveHint?: boolean;
    /**
     * `'undeclared'`, and only ever that (G1). It appears on a command whose author said
     * nothing — every commander and yargs command that did not call `.effects()` — and never
     * beside a hint, because a hint is what a declaration produces.
     */
    effects?: 'undeclared';
}

TypesCopy Anchor Link

InvokeCopy Anchor Link

What a tool call runs: the same execute a --json caller reaches, with the streams captured.

type Invoke = (argv: string[]) => Promise<{
    stdout: string;
    stderr: string;
    code: number;
}>;