PROTOCOL_VERSIONconstconst PROTOCOL_VERSION: "2025-06-18"The version of the protocol this server speaks.
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":{}}'PROTOCOL_VERSIONconstconst PROTOCOL_VERSION: "2025-06-18"The version of the protocol this server speaks.
ToolOutputtypeno test imports ittype 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 ittype 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.
McpConfigtypetype 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.
McpRefusaltypeno test imports ittype McpRefusal = Refusal | "tier-too-low" | "tier-unknown" | "channel" | "read-only-key";Why a call was refused, a closed set.
MCP_REFUSALSconstconst MCP_REFUSALS: readonly McpRefusal[]Every refusal, for a program that walks them.
CallResulttypeno test imports ittype 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 itfunction refused(reason: McpRefusal, message: string): CallResultA call that was refused: one sentence, and the reason as data.
toolsOffunctionno test imports itfunction toolsOf(config: McpConfig): Result<readonly Served[], readonly ToolProblem[]>The tools the caller is served, or the names that collide.
failedStatusfunctionfunction failedStatus(code: number): booleanWhether 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.
callToolfunctionfunction 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).
RPCconstno test imports itconst 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.
handleLinefunctionfunction 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.
Transporttypetype Transport = {
readonly lines: AsyncIterable<string>;
readonly write: (line: string) => void;
};Lines in and lines out: what a tool server is served over.
servefunctionfunction 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.