codebase-snapshot 0.9.0 → 0.9.4

package/dist/mcp.d.cts

@@ -0,0 +1,399 @@
+import { Readable, Writable } from 'node:stream';
+
+/**
+ * JSON-RPC 2.0 envelopes and the Model Context Protocol revisions this server speaks.
+ *
+ * Two protocol eras coexist and this file is the only place that knows which revision belongs
+ * to which era. The legacy era (`2025-11-25` and earlier) opens every connection with an
+ * `initialize` handshake. The modern era (`2026-07-28`) removed the handshake: every request
+ * carries the protocol version and client capabilities in `_meta`, `server/discover` is
+ * mandatory, every result carries `resultType`, and `ping` no longer exists.
+ *
+ * The constants are read by the negotiation in `era.ts`, by the dispatch in `server.ts` and by
+ * the `describe` contract, so a revision cannot be added to one of them and forgotten in the
+ * others.
+ */
+/** A JSON object as it appears on the wire: the shape every `params`/`result` takes. */
+type JsonObject = Record<string, unknown>;
+type JsonRpcId = string | number;
+interface JsonRpcError {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+interface JsonRpcSuccessResponse {
+    jsonrpc: "2.0";
+    id: JsonRpcId | null;
+    result: JsonObject;
+}
+interface JsonRpcErrorResponse {
+    jsonrpc: "2.0";
+    id: JsonRpcId | null;
+    error: JsonRpcError;
+}
+type JsonRpcResponse = JsonRpcSuccessResponse | JsonRpcErrorResponse;
+/**
+ * Revisions that open with the `initialize` handshake, newest first.
+ *
+ * The server echoes the requested revision when it is in this list and otherwise answers with
+ * the newest entry: the legacy lifecycle says a server that cannot speak the requested version
+ * responds with one it does speak, and the client decides whether to continue.
+ */
+declare const LEGACY_PROTOCOL_VERSIONS: readonly string[];
+/** Revisions that carry version and capabilities on every request, newest first. */
+declare const MODERN_PROTOCOL_VERSIONS: readonly string[];
+/** Everything advertised in `server/discover` and in an unsupported-version error. */
+declare const SUPPORTED_PROTOCOL_VERSIONS: readonly string[];
+/**
+ * JSON-RPC error codes, plus the one the modern era added.
+ *
+ * `-32022` is not a generic bad-params error: a client that receives it knows to read
+ * `data.supported` and retry with a mutually supported revision. Reporting it as `-32602`
+ * would leave a modern client with no way to recover.
+ */
+declare const ERROR_CODES: {
+    readonly parseError: -32700;
+    readonly invalidRequest: -32600;
+    readonly methodNotFound: -32601;
+    readonly invalidParams: -32602;
+    readonly internalError: -32603;
+    readonly unsupportedProtocolVersion: -32022;
+};
+/** Method names, kept as constants so a typo is a compile error rather than a `-32601`. */
+declare const METHOD: {
+    readonly initialize: "initialize";
+    readonly initialized: "notifications/initialized";
+    readonly discover: "server/discover";
+    readonly ping: "ping";
+    readonly toolsList: "tools/list";
+    readonly toolsCall: "tools/call";
+    readonly resourcesList: "resources/list";
+    readonly resourcesRead: "resources/read";
+    readonly resourceTemplatesList: "resources/templates/list";
+    readonly promptsList: "prompts/list";
+    readonly promptsGet: "prompts/get";
+    readonly cancelled: "notifications/cancelled";
+};
+/**
+ * A JSON Schema subset, as far as this server needs it.
+ *
+ * Deliberately not `unknown`: the tool table is authored by hand, and the compiler catching a
+ * misspelled keyword is worth more than accepting every dialect feature we never emit.
+ */
+interface JsonSchema {
+    type?: "object" | "string" | "number" | "integer" | "boolean" | "array";
+    description?: string;
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    items?: JsonSchema;
+    enum?: readonly string[];
+    default?: string | number | boolean;
+    additionalProperties?: boolean;
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    maxLength?: number;
+}
+/** An `inputSchema` root: MCP requires a top-level object schema. */
+interface InputSchema extends JsonSchema {
+    type: "object";
+    properties: Record<string, JsonSchema>;
+}
+
+type ProtocolEra = "legacy" | "modern";
+/** Per-connection state. The modern era has no session, so this stays empty until legacy init. */
+interface SessionState {
+    /** Which era the connection committed to, or null before the first decisive request. */
+    era: ProtocolEra | null;
+    /** The revision in force. Null in legacy until `initialize` has been negotiated. */
+    protocolVersion: string | null;
+    /** True once `initialize` has been answered, which is the legacy lifecycle's gate. */
+    ready: boolean;
+}
+declare function createSession(): SessionState;
+/** The modern request metadata, when a request carries it at all. */
+interface ModernMeta {
+    version: string;
+    clientCapabilities: JsonObject;
+    clientInfo: JsonObject | null;
+}
+type MetaInspection = {
+    kind: "absent";
+} | {
+    kind: "incomplete";
+    missing: string;
+} | {
+    kind: "present";
+    meta: ModernMeta;
+};
+/**
+ * Reads `_meta` from a request.
+ *
+ * `absent` and `incomplete` are different answers: a request with no `_meta` at all is a legacy
+ * client, while a request with `_meta` that lacks a required key is a modern client making a
+ * mistake — and telling those two apart is what keeps the legacy era from being rejected for a
+ * field it never had.
+ */
+declare function inspectModernMeta(params: JsonObject | undefined): MetaInspection;
+type EraDecision = {
+    kind: "era";
+    era: ProtocolEra;
+    version: string | null;
+} | {
+    kind: "error";
+    code: number;
+    message: string;
+    data?: unknown;
+};
+/**
+ * Decides which era a request belongs to, and whether its version is acceptable.
+ *
+ * Once a connection commits to an era it stays committed. A legacy client that suddenly sends
+ * modern `_meta` is confused rather than clever, and silently switching would answer half a
+ * session in each shape.
+ */
+declare function classifyRequest(method: string, params: JsonObject | undefined, session: SessionState): EraDecision;
+interface LegacyNegotiation {
+    version: string;
+    /** False when the client asked for something we cannot speak and was negotiated down. */
+    matched: boolean;
+}
+/**
+ * Legacy version negotiation: echo a supported request, otherwise answer with our best.
+ *
+ * A client that asked for a modern revision here gets the newest *legacy* revision, not an error:
+ * under this lifecycle the server's answer is the offer, and the client decides.
+ */
+declare function negotiateLegacyVersion(requested: unknown): LegacyNegotiation;
+
+/**
+ * The capability records the MCP server serves.
+ *
+ * These are the shapes the protocol layer deals in, kept apart from the handlers that fill them so
+ * the server can be tested with a fixed set of stubs and the tool table can be built without a
+ * running transport.
+ */
+
+/** Everything a handler may touch. Deliberately small: no transport, no session, no protocol. */
+interface ToolContext {
+    /** Repository the server was launched for; every relative path resolves against it. */
+    cwd: string;
+    /** Absolute directories a `root` argument is allowed to resolve into. */
+    roots: string[];
+    /** Writes one line to stderr. Never stdout, which carries protocol messages only. */
+    log: (line: string) => void;
+}
+/**
+ * Client-facing hints.
+ *
+ * `readOnlyHint` is the one that changes behaviour rather than appearance: clients use it to
+ * auto-approve a call. Six of the seven tools never touch the filesystem, so they are marked
+ * read-only and only `snapshot_generate` prompts.
+ */
+interface ToolAnnotations {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    idempotentHint: boolean;
+    openWorldHint: boolean;
+}
+/** What a handler returns. The protocol layer turns this into a `CallToolResult`. */
+interface ToolOutcome {
+    /** The text block a model reads. Keep it short: bulk content belongs in a windowed read. */
+    text: string;
+    /** Typed mirror of `text`, declared by the tool's `outputSchema`. */
+    structured?: JsonObject;
+    /** True for a tool-level failure. Reported inside the result, not as a JSON-RPC error. */
+    isError?: boolean;
+}
+interface McpTool {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: InputSchema;
+    outputSchema?: InputSchema;
+    annotations: ToolAnnotations;
+    handler(args: JsonObject, context: ToolContext): Promise<ToolOutcome>;
+}
+/** One addressable resource, as `resources/list` reports it. */
+interface McpResourceDescriptor {
+    uri: string;
+    name: string;
+    title?: string;
+    description: string;
+    mimeType: string;
+}
+interface McpResourceContents {
+    uri: string;
+    mimeType: string;
+    text: string;
+}
+/** A parameterised resource family, as `resources/templates/list` reports it. */
+interface McpResourceTemplate {
+    uriTemplate: string;
+    name: string;
+    title?: string;
+    description: string;
+    mimeType: string;
+}
+/**
+ * Resources are computed per call rather than declared once.
+ *
+ * The list depends on what is on disk — a snapshot that has not been generated has manifest
+ * resources that do not exist yet — so a static table would advertise resources whose read then
+ * fails, which is worse than an honest short list.
+ */
+interface ResourceProvider {
+    list(context: ToolContext): Promise<McpResourceDescriptor[]>;
+    templates(): McpResourceTemplate[];
+    /** Resolves one URI. Returns null when this server does not own it. */
+    read(uri: string, context: ToolContext): Promise<McpResourceContents | null>;
+}
+interface PromptArgument {
+    name: string;
+    description: string;
+    required: boolean;
+}
+interface PromptMessage {
+    role: "user" | "assistant";
+    content: {
+        type: "text";
+        text: string;
+    };
+}
+interface McpPrompt {
+    name: string;
+    title?: string;
+    description: string;
+    arguments: PromptArgument[];
+    build(args: JsonObject): {
+        description: string;
+        messages: PromptMessage[];
+    };
+}
+/** Identity reported at handshake and in every modern result's `_meta`. */
+interface McpServerInfo {
+    name: string;
+    title: string;
+    version: string;
+    websiteUrl: string;
+}
+
+interface McpServerOptions {
+    info: McpServerInfo;
+    instructions: string;
+    tools: McpTool[];
+    resources: ResourceProvider;
+    prompts: McpPrompt[];
+    context: ToolContext;
+}
+interface McpServer {
+    /** Handles one already-parsed message. Returns null when no response is due. */
+    handle(message: unknown): Promise<JsonRpcResponse | null>;
+    /** Exposed for tests and for `mcp --list`, which prints the negotiation table. */
+    readonly session: SessionState;
+}
+declare function createMcpServer(options: McpServerOptions): McpServer;
+
+/** Every tool this server exposes, in the order a first-time caller should read them. */
+declare function buildTools(): McpTool[];
+
+declare function buildPrompts(): McpPrompt[];
+
+declare function buildResourceProvider(): ResourceProvider;
+
+interface ServerOptions {
+    /** Repository the tools operate on. Also the only directory they may read. */
+    cwd: string;
+    /** Additional directories callers may name as `root`. Defaults to `cwd` alone. */
+    roots?: string[];
+    /** Where operational notes go. Never stdout, which carries protocol messages only. */
+    log?: (line: string) => void;
+}
+/** Builds a server with every capability this package implements. */
+declare function createServer(options: ServerOptions): McpServer;
+/**
+ * Serves MCP over stdio until the client closes the stream.
+ *
+ * Writes are serialised through one promise chain: two tool calls finishing together must not
+ * interleave half-written lines, and a single response can be large. Reading is not serialised —
+ * a slow tool must not stop a cancellation notification from being read — and the process waits
+ * for every accepted request to answer before it resolves.
+ */
+declare function runStdioServer(options: ServerOptions): Promise<number>;
+
+/**
+ * The stdio transport: one JSON-RPC message per line, UTF-8, nothing else on the stream.
+ *
+ * MCP's stdio binding is newline-delimited JSON, not LSP's `Content-Length` framing, and the
+ * server MUST NOT write anything to stdout that is not a valid message. `JSON.stringify` escapes
+ * newlines inside strings, so serialising a message can never produce a second line — the writer
+ * deliberately does not pretty-print, because `JSON.stringify(value, null, 2)` would.
+ *
+ * Framing is separated from parsing on purpose: this module hands raw lines to its caller and the
+ * server decides what a bad line means (a `-32700` response), which keeps the line splitting
+ * testable without a running server.
+ */
+
+/**
+ * Largest single message this transport will buffer.
+ *
+ * A line with no newline grows the buffer until the process runs out of memory, so an oversized
+ * message is discarded rather than accepted: the snapshot itself is never this large, and a
+ * client that streams more than this is not sending a message.
+ */
+declare const MAX_LINE_BYTES: number;
+interface MessageWriter {
+    /** Serialises one message onto the stream. Rejects if the stream reports a write error. */
+    write(value: unknown): Promise<void>;
+}
+/**
+ * Creates a writer that emits exactly one line per message.
+ *
+ * Writes are awaited through the stream's callback rather than fire-and-forget: a tool result can
+ * be tens of kilobytes, and queueing several without backpressure interleaves them with the next
+ * response on a slow pipe.
+ */
+declare function createWriter(output: Writable): MessageWriter;
+interface LineReaderOptions {
+    /** Called for every complete, non-empty line, with the trailing CR already removed. */
+    onLine: (line: string) => void;
+    /** Called when one line exceeds {@link MAX_LINE_BYTES}; the line is discarded. */
+    onOverflow?: (bytes: number) => void;
+}
+/**
+ * Reads newline-delimited lines from `input` until it ends.
+ *
+ * Three details are what make this work against real clients rather than against our own tests:
+ * a chunk boundary can fall anywhere inside a line (including inside a multi-byte character,
+ * which `setEncoding` handles); a Windows client may terminate lines with CRLF; and the final
+ * line may arrive without a newline before the stream ends.
+ *
+ * Returns a function that removes the listeners, so a caller can shut a transport down without
+ * racing a late `end` event.
+ */
+declare function createLineReader(input: Readable, options: LineReaderOptions): () => void;
+
+/**
+ * The instructions an MCP client shows its model at handshake.
+ *
+ * This text is the cheapest documentation the project has: it arrives before the first tool call,
+ * in the model's own context, on every client that supports the field. It is therefore about
+ * *order* rather than features — an agent that reads a part end to end has already lost the
+ * budget this tool exists to protect.
+ */
+declare const SERVER_INSTRUCTIONS: string;
+
+/**
+ * A JSON Schema checker for tool arguments, sized to the schemas this server publishes.
+ *
+ * The alternative was Ajv, which is the right answer for arbitrary schemas and the wrong one for
+ * a package whose single dependency is a compiler. Every schema here is a flat object of scalar
+ * properties, so the checker is small, readable and — unlike a general-purpose validator — it can
+ * reject unknown properties by default, which is what turns an agent's typo (`maxPartByte`) into a
+ * named error instead of a silently ignored option.
+ */
+
+/** Human-readable problems, each prefixed with the argument path that caused it. */
+declare function validateArguments(schema: InputSchema, value: unknown): string[];
+
+export { ERROR_CODES, type JsonRpcResponse, type JsonSchema, LEGACY_PROTOCOL_VERSIONS, type LineReaderOptions, MAX_LINE_BYTES, METHOD, MODERN_PROTOCOL_VERSIONS, type McpPrompt, type McpResourceContents, type McpResourceDescriptor, type McpResourceTemplate, type McpServer, type McpServerInfo, type McpServerOptions, type McpTool, type MessageWriter, type ProtocolEra, type ResourceProvider, SERVER_INSTRUCTIONS, SUPPORTED_PROTOCOL_VERSIONS, type ServerOptions, type SessionState, type ToolAnnotations, type ToolContext, type ToolOutcome, buildPrompts, buildResourceProvider, buildTools, classifyRequest, createLineReader, createMcpServer, createServer, createSession, createWriter, inspectModernMeta, negotiateLegacyVersion, runStdioServer, validateArguments };