# burgee/mcp

> Every export of burgee/mcp, with its signature and doc comment: annotationsOf, MCP_PROTOCOL_VERSION, serveMcp, toolsOf, plus 4 types.

Source: https://burgee.interlace.tools/docs/api/mcp

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

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

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

## Functions

### annotationsOf

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.

```ts
function annotationsOf(effects?: Effects): ToolAnnotations;
```

| Parameter | Type |
| :-- | :-- |
| `effects` (optional) | `Effects` |

**Returns** `ToolAnnotations`

### serveMcp

Serve until the input closes.

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

| Parameter | Type |
| :-- | :-- |
| `manifest` | `Manifest` |
| `opts` | `ServeOptions` |

**Returns** `Promise<void>`

### toolsOf

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.

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

| Parameter | Type |
| :-- | :-- |
| `manifest` | `Manifest` |

**Returns** `Tool[]`

## Constants

### MCP_PROTOCOL_VERSION

```ts
const MCP_PROTOCOL_VERSION = "2025-06-18";
```

## Interfaces

### ServeOptions

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

### Tool

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

### ToolAnnotations

```ts
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';
}
```

## Types

### Invoke

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

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