IF Commons GitHub

surfaces/mcp/server

Written to: 5 requirements: 5 proved, 0 partly, 0 failing, 0 with no test recorded. 0013-mcp-surface FR-005, 0013-mcp-surface FR-002, 0013-mcp-surface FR-003, 0013-mcp-surface FR-004, 0013-mcp-surface FR-006

A tool server in the Model Context Protocol (commons headless 0013-mcp-surface): JSON-RPC 2.0, one message to a line, over any transport that gives lines and takes lines. handleLine is the whole server as a function: a line in, the line to answer with (or none, for a notification) out. It answers initialize, ping, tools/list and tools/call; the tools are those the caller's tier may see (served), a call is gated by governance as a machine's (the tier, the channel, the key that may only read, what only a person may do and give, and the confirmation a flag cannot stand for) and then run through a port, ToolRunner, which the host wires to the command line's run with the caller's tier.

The server touches no process global and no stream: serve takes a Transport (lines in, lines out), and stdioTransport is the standard streams'. Standard output carries the protocol and nothing else. A call that is refused is a tool result with isError and a refusal that names why in a closed set, so a client and an agent can tell a tier from a channel from a confirmation; a call to a word that is no tool at all is the protocol's invalid parameters.

import { handleLine } from "./server.ts";
// handleLine(config, '{"jsonrpc":"2.0","id":1,"method":"ping"}') // resolves to '{"jsonrpc":"2.0","id":1,"result":{}}'

Source: commons/headless/src/surfaces/mcp/server.ts

8 of 15 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

PROTOCOL_VERSIONconst
const PROTOCOL_VERSION: "2025-06-18"

The version of the protocol this server speaks.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

ToolOutputtypeno test imports it
type ToolOutput = { readonly code: number; readonly out: string; readonly err: string };

What ran a tool: the status and the two streams, as the command line's run gives them.

ToolRunnertypeno test imports it
type ToolRunner = (argv: readonly string[]) => Promise<ToolOutput>;

The port that runs a command by its argument vector (the words, options and operands, with no program name). The host wires it to the command line's run with the caller's tier.

McpConfigtype
type McpConfig = {
  readonly program: Program;
  /** The tier the caller holds: fixed by the host (a key, a forced command), never taken from a message. */
  readonly tier: TierName;
  /** Whether the caller's key may only read: a command that changes something is then refused. */
  readonly mayOnlyRead: boolean;
  readonly run: ToolRunner;
};

What the server is: the program, who calls it, and how a command runs.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

McpRefusaltypeno test imports it
type McpRefusal = Refusal | "tier-too-low" | "tier-unknown" | "channel" | "read-only-key";

Why a call was refused, a closed set.

MCP_REFUSALSconst
const MCP_REFUSALS: readonly McpRefusal[]

Every refusal, for a program that walks them.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

CallResulttypeno test imports it
type CallResult = {
  readonly content: readonly { readonly type: "text"; readonly text: string }[];
  readonly structuredContent?: Json;
  readonly isError: boolean;
};

The result of a call that ran, or was refused.

refusedfunctionno test imports it
function refused(reason: McpRefusal, message: string): CallResult

A call that was refused: one sentence, and the reason as data.

toolsOffunctionno test imports it
function toolsOf(config: McpConfig): Result<readonly Served[], readonly ToolProblem[]>

The tools the caller is served, or the names that collide.

failedStatusfunction
function failedStatus(code: number): boolean

Whether a status is one a tool ended as, and not one that it failed with: 0 (ok), 1 (findings) and 4 (pending) are results; the rest are errors.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

callToolfunction
function callTool(config: McpConfig, name: string, args: unknown): Promise<CallResult | undefined>

A tool call: refused where governance says so, else run and told. The order is the tier (a hidden tool is refused for it), the channel, the key that may only read, then decide as a machine surface that cannot ask and takes no flag for a confirmation (a destructive action goes only as a preview here).

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

RPCconstno test imports it
const RPC: { readonly parse: -32700; readonly invalidRequest: -32600; readonly methodNotFound: -32601; readonly invalidParams: -32602; readonly internal: -32603; }

The codes of JSON-RPC 2.0 this server uses.

handleLinefunction
function handleLine(config: McpConfig, line: string): Promise<string | undefined>

One line in, the line to answer with out, or undefined for a notification (no id), which is never answered. A line that is not JSON is a parse error, one that is not a request an invalid request (a batch is one: this protocol version has none), a method that is not served method not found.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

Transporttype
type Transport = {
  readonly lines: AsyncIterable<string>;
  readonly write: (line: string) => void;
};

Lines in and lines out: what a tool server is served over.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

servefunction
function serve(config: McpConfig, transport: Transport): Promise<void>

Serves a transport until its lines end: each line is answered in order, and a line is never written with a line break inside it.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.