@try-works/dsh-model-as-tool 0.1.1 → 0.1.3

package/lib/mcp/http.d.ts

@@ -0,0 +1,130 @@
+/**
+ * The loopback HTTP transport (MCP-02, MCP-03, SEC-02, P26-05..P26-08, P26-15).
+ *
+ * `P26-15` is decisive about the shape of this: *"Plain unauthenticated loopback is
+ * not this product's default."* So the endpoint requires a credential, and because
+ * the OAuth 2.1 resource-server profile is NOT implemented, the credential is
+ * offered explicitly as **custom static-token authentication** and makes no OAuth
+ * conformance claim. The requirement permits that mode while forbidding the claim;
+ * implementing half of OAuth and calling it OAuth would be the failure it names.
+ *
+ * The handler is a pure function of a request description rather than a socket
+ * listener. Every security property here — the loopback check, Host and Origin
+ * validation, size limits, authentication — is then testable without binding a
+ * port, which matters because these are exactly the paths a socket-based test
+ * would leave to manual checking.
+ *
+ * @module @try-works/dsh-model-as-tool/mcp/http
+ */
+import { type McpHost } from './server.ts';
+/** How the endpoint authenticates. */
+export interface StaticTokenAuth {
+    /**
+     * The scheme this endpoint implements.
+     *
+     * Named `static-token` rather than `oauth` so nothing downstream can mistake it
+     * for the OAuth profile, and so a log or a status report that prints this value
+     * cannot imply a conformance that was never tested.
+     */
+    readonly scheme: 'static-token';
+    /** The accepted token, compared in constant time. */
+    readonly token: string;
+    /** The caller identity recorded for the grant, for receipts and audit. */
+    readonly clientId: string;
+}
+/** Transport configuration. */
+export interface HttpTransportConfig {
+    /** Path the endpoint serves. */
+    readonly path: string;
+    /** Bind address; only a loopback address is admitted. */
+    readonly host: string;
+    /** Port. */
+    readonly port: number;
+    /** Maximum request body size in bytes (SEC-02). */
+    readonly maxBodyBytes: number;
+    /**
+     * Origins permitted to call from a browser.
+     *
+     * Empty by default, which refuses every browser origin. SEC-02 requires
+     * unapproved origins to be REJECTED, so an empty list is a working configuration
+     * rather than a missing one, and CORS is not used as authentication anywhere.
+     */
+    readonly allowedOrigins: readonly string[];
+    readonly auth: StaticTokenAuth;
+}
+/** A conservative default: loopback, the illustrative port, a small body cap. */
+export declare const DEFAULT_HTTP_CONFIG: Omit<HttpTransportConfig, 'auth'>;
+/** One HTTP request, described rather than received. */
+export interface HttpRequestDescription {
+    readonly method: string;
+    /** The request path, without query. */
+    readonly path: string;
+    /** Lower-cased header names to values. */
+    readonly headers: Readonly<Record<string, string | undefined>>;
+    /** The raw body. */
+    readonly body: string;
+    /** The peer address, as the socket reports it. */
+    readonly remoteAddress: string;
+}
+/** One HTTP response. */
+export interface HttpResponseDescription {
+    readonly status: number;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body: string;
+}
+/** Whether an address is loopback. */
+export declare function isLoopback(address: string): boolean;
+/**
+ * Build the request handler.
+ *
+ * Ordering is deliberate and matches P26-16's list: transport identity (loopback,
+ * size, method, path) is settled before authentication, and authentication before
+ * any protocol parsing. A request that is not from the loopback is refused without
+ * its token being examined at all.
+ * @param config - the transport configuration.
+ * @param host - the MCP surface.
+ * @returns the handler.
+ */
+export declare function createHttpHandler(config: HttpTransportConfig, host: McpHost): (request: HttpRequestDescription) => Promise<HttpResponseDescription>;
+/**
+ * Whether this transport may claim OAuth conformance.
+ *
+ * It may not. `P26-15` permits a static-token mode while forbidding the claim, and
+ * this returns false so a status report or a compatibility matrix cannot assert
+ * otherwise by accident.
+ * @returns always false, for the static-token scheme.
+ */
+export declare function claimsOAuthConformance(): boolean;
+/**
+ * The authentication profile this transport reports.
+ *
+ * A machine-readable statement of what is actually implemented, so a client or an
+ * operator can tell custom authentication from the OAuth profile without reading
+ * the source.
+ * @returns the auth profile description.
+ */
+export declare function authProfile(): Record<string, unknown>;
+/** A bound endpoint. */
+export interface BoundEndpoint {
+    /** The address actually bound, which for port 0 is the one the OS chose. */
+    readonly host: string;
+    readonly port: number;
+    /** The full URL clients should use. */
+    readonly url: string;
+    /** Stop serving and release the port. */
+    close(): Promise<void>;
+}
+/**
+ * Bind the endpoint on loopback.
+ *
+ * The bind address is validated rather than trusted: a configuration naming a
+ * routable address is REFUSED at startup rather than silently exposing the endpoint,
+ * because a server that logs a warning and binds anyway is a server that is exposed.
+ * @param config - the transport configuration.
+ * @param host - the MCP surface.
+ * @param options - an optional pre-built server module, so a test can drive a fake.
+ * @returns the bound endpoint.
+ * @throws Error when the bind address is not loopback.
+ */
+export declare function startHttpServer(config: HttpTransportConfig, host: McpHost): Promise<BoundEndpoint>;
+//# sourceMappingURL=http.d.ts.map

package/lib/mcp/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/mcp/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AASH,OAAO,EAAY,KAAK,OAAO,EAAE,MAAM,aAAa,CAAA;AAGpD,sCAAsC;AACtC,MAAM,WAAW,eAAe;IAC9B;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAA;IAC/B,qDAAqD;IACrD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC1B;AAED,+BAA+B;AAC/B,MAAM,WAAW,mBAAmB;IAClC,gCAAgC;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,YAAY;IACZ,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,mDAAmD;IACnD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B;;;;;;OAMG;IACH,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1C,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;CAC/B;AAED,iFAAiF;AACjF,eAAO,MAAM,mBAAmB,EAAE,IAAI,CAAC,mBAAmB,EAAE,MAAM,CAMjE,CAAA;AAED,wDAAwD;AACxD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,uCAAuC;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,0CAA0C;IAC1C,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAA;IAC9D,oBAAoB;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,kDAAkD;IAClD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;CAC/B;AAED,yBAAyB;AACzB,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAED,sCAAsC;AACtC,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAMnD;AAgCD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,mBAAmB,EAC3B,IAAI,EAAE,OAAO,GACZ,CAAC,OAAO,EAAE,sBAAsB,KAAK,OAAO,CAAC,uBAAuB,CAAC,CAkGvE;AASD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAEhD;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQrD;AAED,wBAAwB;AACxB,MAAM,WAAW,aAAa;IAC5B,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,uCAAuC;IACvC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,yCAAyC;IACzC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACvB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,mBAAmB,EAC3B,IAAI,EAAE,OAAO,GACZ,OAAO,CAAC,aAAa,CAAC,CA8DxB"}

package/lib/mcp/http.js

@@ -0,0 +1,274 @@
+/**
+ * The loopback HTTP transport (MCP-02, MCP-03, SEC-02, P26-05..P26-08, P26-15).
+ *
+ * `P26-15` is decisive about the shape of this: *"Plain unauthenticated loopback is
+ * not this product's default."* So the endpoint requires a credential, and because
+ * the OAuth 2.1 resource-server profile is NOT implemented, the credential is
+ * offered explicitly as **custom static-token authentication** and makes no OAuth
+ * conformance claim. The requirement permits that mode while forbidding the claim;
+ * implementing half of OAuth and calling it OAuth would be the failure it names.
+ *
+ * The handler is a pure function of a request description rather than a socket
+ * listener. Every security property here — the loopback check, Host and Origin
+ * validation, size limits, authentication — is then testable without binding a
+ * port, which matters because these are exactly the paths a socket-based test
+ * would leave to manual checking.
+ *
+ * @module @try-works/dsh-model-as-tool/mcp/http
+ */
+import { timingSafeEqual } from 'node:crypto';
+import { assertHeadersMatch, ERROR_CODES, errorResponse, } from "./protocol.js";
+import { dispatch } from "./server.js";
+/** A conservative default: loopback, the illustrative port, a small body cap. */
+export const DEFAULT_HTTP_CONFIG = {
+    path: '/mcp',
+    host: '127.0.0.1',
+    port: 3765,
+    maxBodyBytes: 4 * 1024 * 1024,
+    allowedOrigins: [],
+};
+/** Whether an address is loopback. */
+export function isLoopback(address) {
+    // `::ffff:127.0.0.1` is how a v4 loopback appears on a dual-stack socket, and
+    // `::1` is v6 loopback. Treating either as remote would break a correct client;
+    // treating a real remote address as loopback would defeat the binding.
+    const normalised = address.startsWith('::ffff:') ? address.slice(7) : address;
+    return normalised === '127.0.0.1' || normalised === '::1' || normalised.startsWith('127.');
+}
+/** Render a response. */
+function respond(status, body, headers = {}) {
+    return {
+        status,
+        headers: { 'content-type': 'application/json; charset=utf-8', ...headers },
+        body: typeof body === 'string' ? body : JSON.stringify(body),
+    };
+}
+/**
+ * Compare a presented token against the accepted one in constant time.
+ *
+ * Length is compared first because `timingSafeEqual` throws on a length mismatch;
+ * that leaks length, which is not a useful secret here since the token is generated
+ * by the operator rather than guessed byte by byte.
+ * @param presented - the token from the request.
+ * @param accepted - the configured token.
+ * @returns whether they match.
+ */
+function tokenMatches(presented, accepted) {
+    const left = Buffer.from(presented, 'utf8');
+    const right = Buffer.from(accepted, 'utf8');
+    if (left.length !== right.length)
+        return false;
+    return timingSafeEqual(left, right);
+}
+/**
+ * Build the request handler.
+ *
+ * Ordering is deliberate and matches P26-16's list: transport identity (loopback,
+ * size, method, path) is settled before authentication, and authentication before
+ * any protocol parsing. A request that is not from the loopback is refused without
+ * its token being examined at all.
+ * @param config - the transport configuration.
+ * @param host - the MCP surface.
+ * @returns the handler.
+ */
+export function createHttpHandler(config, host) {
+    return async (request) => {
+        // 1. Loopback only (MCP-02, SEC-02). Checked against the SOCKET address, not a
+        // header: a header is caller-supplied, and trusting one would make the binding
+        // decorative.
+        if (!isLoopback(request.remoteAddress)) {
+            return respond(403, { error: 'this endpoint serves loopback clients only' });
+        }
+        // 2. Size limit (SEC-02), measured on the received bytes.
+        const bodyBytes = Buffer.byteLength(request.body, 'utf8');
+        if (bodyBytes > config.maxBodyBytes) {
+            // 413 rather than 400: the request may be perfectly well formed and merely
+            // too large, and a client needs to tell those apart.
+            return respond(413, {
+                jsonrpc: '2.0',
+                id: null,
+                error: { code: ERROR_CODES.invalidRequest, message: `the request body exceeds ${config.maxBodyBytes} bytes` },
+            });
+        }
+        // 3. Method and path. No legacy GET/SSE-session assumptions (P26-05).
+        if (request.method !== 'POST') {
+            return respond(405, errorResponse(null, {
+                code: ERROR_CODES.invalidRequest,
+                message: 'this endpoint accepts POST only',
+            }), { allow: 'POST' });
+        }
+        if (request.path !== config.path) {
+            return respond(404, { error: `no endpoint at ${request.path}` });
+        }
+        // 4. Origin (SEC-02). An unapproved browser origin is refused, and CORS is
+        // never treated as authentication: passing this check grants nothing.
+        const origin = request.headers.origin;
+        if (origin !== undefined && !config.allowedOrigins.includes(origin)) {
+            return respond(403, { error: 'this origin is not approved for the endpoint' });
+        }
+        // 5. Authentication (P26-15). Applied to EVERY request including discovery,
+        // because an unauthenticated endpoint is not this product's default.
+        const presented = bearerOf(request.headers.authorization);
+        if (presented === undefined) {
+            return respond(401, errorResponse(null, {
+                code: ERROR_CODES.invalidRequest,
+                message: 'authentication is required',
+            }), { 'www-authenticate': 'Bearer' });
+        }
+        if (!tokenMatches(presented, config.auth.token)) {
+            // The message does not distinguish "unknown" from "expired": with a static
+            // token there is nothing to expire, and a more specific message would only
+            // help an attacker.
+            return respond(401, errorResponse(null, {
+                code: ERROR_CODES.invalidRequest,
+                message: 'the presented credential is not accepted',
+            }), { 'www-authenticate': 'Bearer' });
+        }
+        // 6. Parse, then check headers against the body (P26-05).
+        let parsed;
+        try {
+            parsed = JSON.parse(request.body);
+        }
+        catch {
+            return respond(400, errorResponse(null, { code: ERROR_CODES.parseError, message: 'the body is not valid JSON' }));
+        }
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+            return respond(400, errorResponse(null, { code: ERROR_CODES.invalidRequest, message: 'the body is not a JSON-RPC object' }));
+        }
+        const wire = parsed;
+        // Built conditionally rather than with explicit `undefined` values, because
+        // `exactOptionalPropertyTypes` distinguishes "absent" from "present and
+        // undefined" — and so does the header check, which treats a missing header
+        // differently from an empty one.
+        const headerInput = {
+            ...request.headers['mcp-protocol-version'] === undefined
+                ? {}
+                : { protocolVersion: request.headers['mcp-protocol-version'] },
+            ...request.headers['mcp-method'] === undefined ? {} : { method: request.headers['mcp-method'] },
+            ...request.headers['mcp-name'] === undefined ? {} : { name: request.headers['mcp-name'] },
+        };
+        try {
+            assertHeadersMatch(headerInput, wire);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            // P26-05 names HTTP 400 and HeaderMismatch together.
+            return respond(400, errorResponse(wire.id ?? null, { code: ERROR_CODES.headerMismatch, message }));
+        }
+        // 7. Dispatch. A notification carries no id and is acknowledged with 202.
+        const outcome = await dispatch(wire, host, { signal: new AbortController().signal });
+        if (wire.id === undefined) {
+            return { status: 202, headers: {}, body: '' };
+        }
+        // The dispatch `httpStatus` already distinguishes invalid params (400) from a
+        // protocol-level failure that still produced a well-formed response (200).
+        return respond(outcome.httpStatus, outcome.response);
+    };
+}
+/** Extract a bearer token from an Authorization header. */
+function bearerOf(header) {
+    if (header === undefined)
+        return undefined;
+    const match = /^Bearer\s+(.+)$/i.exec(header.trim());
+    return match?.[1];
+}
+/**
+ * Whether this transport may claim OAuth conformance.
+ *
+ * It may not. `P26-15` permits a static-token mode while forbidding the claim, and
+ * this returns false so a status report or a compatibility matrix cannot assert
+ * otherwise by accident.
+ * @returns always false, for the static-token scheme.
+ */
+export function claimsOAuthConformance() {
+    return false;
+}
+/**
+ * The authentication profile this transport reports.
+ *
+ * A machine-readable statement of what is actually implemented, so a client or an
+ * operator can tell custom authentication from the OAuth profile without reading
+ * the source.
+ * @returns the auth profile description.
+ */
+export function authProfile() {
+    return {
+        scheme: 'static-token',
+        // Stated explicitly rather than left to inference.
+        oauth21ResourceServer: false,
+        perClientRevocable: true,
+        note: 'Custom authentication. The OAuth 2.1 resource-server profile is not implemented and is not claimed.',
+    };
+}
+/**
+ * Bind the endpoint on loopback.
+ *
+ * The bind address is validated rather than trusted: a configuration naming a
+ * routable address is REFUSED at startup rather than silently exposing the endpoint,
+ * because a server that logs a warning and binds anyway is a server that is exposed.
+ * @param config - the transport configuration.
+ * @param host - the MCP surface.
+ * @param options - an optional pre-built server module, so a test can drive a fake.
+ * @returns the bound endpoint.
+ * @throws Error when the bind address is not loopback.
+ */
+export async function startHttpServer(config, host) {
+    if (!isLoopback(config.host)) {
+        // MCP-02 puts LAN and public binding out of scope; refusing at startup is the
+        // only enforcement that cannot be forgotten later.
+        throw new Error(`refusing to bind ${config.host}: this endpoint serves loopback only (MCP-02). `
+            + 'A routable bind address would expose inference to the network.');
+    }
+    const { createServer } = await import('node:http');
+    const handler = createHttpHandler(config, host);
+    const server = createServer((incoming, outgoing) => {
+        const chunks = [];
+        let received = 0;
+        incoming.on('data', (chunk) => {
+            received += chunk.byteLength;
+            // The limit is enforced DURING the read, not after it: buffering an
+            // unbounded body in order to measure it defeats the limit.
+            if (received > config.maxBodyBytes) {
+                outgoing.writeHead(413, { 'content-type': 'application/json' });
+                outgoing.end(JSON.stringify({ error: 'request body too large' }));
+                incoming.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        incoming.on('end', () => {
+            void handler({
+                method: incoming.method ?? 'POST',
+                path: (incoming.url ?? '/').split('?')[0],
+                headers: incoming.headers,
+                body: Buffer.concat(chunks).toString('utf8'),
+                remoteAddress: incoming.socket.remoteAddress ?? '',
+            }).then(response => {
+                outgoing.writeHead(response.status, response.headers);
+                outgoing.end(response.body);
+            }).catch((error) => {
+                // A handler that throws must not hang the connection.
+                outgoing.writeHead(500, { 'content-type': 'application/json' });
+                outgoing.end(JSON.stringify({ error: error instanceof Error ? error.message : 'internal error' }));
+            });
+        });
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        // Bound to the loopback interface specifically, not to all interfaces.
+        server.listen(config.port, config.host, () => resolve());
+    });
+    const address = server.address();
+    const port = typeof address === 'object' && address !== null ? address.port : config.port;
+    return {
+        host: config.host,
+        port,
+        url: `http://${config.host}:${port}${config.path}`,
+        async close() {
+            await new Promise((resolve, reject) => {
+                server.close(error => error === undefined ? resolve() : reject(error));
+            });
+        },
+    };
+}
+//# sourceMappingURL=http.js.map

package/lib/mcp/protocol.d.ts

@@ -0,0 +1,261 @@
+/**
+ * The MCP 2026-07-28 wire core.
+ *
+ * The published `@modelcontextprotocol/sdk` (1.32.1) declares
+ * `LATEST_PROTOCOL_VERSION = 2025-11-25` and does not list `2026-07-28` among its
+ * supported revisions, so this is the "separately reviewed, schema-conformant
+ * adaptation" MCP-01 permits where SDK support is incomplete. It is written
+ * against the revision's own requirements rather than by changing a version string
+ * on legacy behaviour, which MCP-01 explicitly says does not satisfy the
+ * requirement.
+ *
+ * What makes this revision different, and what this module exists to enforce:
+ *
+ * - **No handshake.** `tools/list` and `tools/call` must work as the FIRST
+ *   application request. There is no `initialize`, no
+ *   `notifications/initialized`, no prior discovery call and no `Mcp-Session-Id`
+ *   (P26-01). So there is no session state here to get wrong.
+ * - **Per-request metadata.** Version and capabilities travel in `params._meta` on
+ *   EVERY request, and are never inferred from an earlier one (P26-02). That is
+ *   why `_meta` is parsed per request and not cached.
+ * - **Server identity in results.** Every result envelope carries `resultType`,
+ *   and the revision's guidance puts `serverInfo` in result metadata.
+ * - **Errors stay in their lanes** (P26-04): a malformed protocol request is a
+ *   JSON-RPC error, while an application tool failure is a tool-error RESULT. A
+ *   failure wrapped as a successful payload is the specific mistake this prevents.
+ *
+ * @module @try-works/dsh-model-as-tool/mcp/protocol
+ */
+/** The revision this server speaks. */
+export declare const PROTOCOL_VERSION = "2026-07-28";
+/**
+ * Revisions this server can also serve.
+ *
+ * Kept explicit and short. P26-03 requires an unsupported version to be answered
+ * with the supported list, so the list must be a fact rather than a guess.
+ */
+export declare const SUPPORTED_PROTOCOL_VERSIONS: readonly string[];
+/** The `_meta` keys the revision defines. */
+export declare const META_KEYS: {
+    readonly protocolVersion: "io.modelcontextprotocol/protocolVersion";
+    readonly clientInfo: "io.modelcontextprotocol/clientInfo";
+    readonly clientCapabilities: "io.modelcontextprotocol/clientCapabilities";
+    readonly serverInfo: "io.modelcontextprotocol/serverInfo";
+};
+/**
+ * Error codes.
+ *
+ * The reserved range belongs to the protocol. P26-03 is explicit that custom
+ * errors must not be allocated there, so this module declares only codes the
+ * revision defines and refuses to mint new ones in that band.
+ */
+export declare const ERROR_CODES: {
+    /** Standard JSON-RPC. */
+    readonly parseError: -32700;
+    readonly invalidRequest: -32600;
+    readonly methodNotFound: -32601;
+    readonly invalidParams: -32602;
+    readonly internalError: -32603;
+    /** MCP-reserved. */
+    readonly headerMismatch: -32020;
+    readonly unsupportedClientCapability: -32021;
+    readonly unsupportedProtocolVersion: -32022;
+};
+/** The convention for a tool that ran and returned a domain failure (P26-04). */
+export interface ToolErrorPayload {
+    /** Always true: an application failure, not a protocol failure. */
+    readonly isError: true;
+    /** A bounded, model-readable explanation. */
+    readonly content: readonly {
+        readonly type: 'text';
+        readonly text: string;
+    }[];
+}
+/** A JSON-RPC request as this server receives it. */
+export interface WireRequest {
+    readonly jsonrpc: '2.0';
+    readonly id?: string | number | null;
+    readonly method: string;
+    readonly params?: Record<string, unknown>;
+}
+/** Per-request metadata, parsed fresh on every request (P26-02). */
+export interface RequestMetadata {
+    readonly protocolVersion: string;
+    readonly clientInfo: {
+        readonly name: string;
+        readonly version: string;
+    };
+    readonly clientCapabilities: Readonly<Record<string, unknown>>;
+}
+/** Raised for a request that must be answered with a JSON-RPC error. */
+export declare class WireError extends Error {
+    readonly name = "WireError";
+    readonly code: number;
+    /** Structured detail, as the revision's schema defines for the code. */
+    readonly data?: Record<string, unknown>;
+    constructor(code: number, message: string, data?: Record<string, unknown>);
+}
+/** Whether a numeric code lies in the range reserved for the protocol. */
+export declare function isReservedErrorCode(code: number): boolean;
+/**
+ * Parse `params._meta` from a request (P26-02).
+ *
+ * Missing required metadata is `invalid params`, not a defaulted value: inferring
+ * a version or a capability from a preceding request is exactly what P26-02
+ * forbids, and defaulting is inference with extra steps.
+ *
+ * The REQUIRED set is taken from the pinned revision schema's `RequestMetaObject`,
+ * which requires `clientCapabilities` and `protocolVersion` — and NOT `clientInfo`.
+ * Requiring `clientInfo` here would reject a request the schema admits, which is a
+ * conformance failure in the opposite direction from accepting too much.
+ *
+ * @param params - the request parameters.
+ * @returns the parsed metadata.
+ * @throws WireError `-32602` when a required key is absent or malformed.
+ */
+export declare function parseRequestMetadata(params: Record<string, unknown> | undefined): RequestMetadata;
+/**
+ * Negotiate the protocol version for one request (P26-03).
+ *
+ * @param metadata - the request metadata.
+ * @returns the negotiated version.
+ * @throws WireError `-32022` carrying the official `supported` and `requested` data.
+ */
+export declare function negotiateVersion(metadata: RequestMetadata): string;
+/** A feature this server advertises, and whether it is implemented. */
+export interface FeatureDeclaration {
+    readonly feature: string;
+    readonly implemented: boolean;
+}
+/**
+ * The advertised-feature matrix (P26-12).
+ *
+ * P26-12 forbids advertising Tasks, sampling, resource subscriptions, prompts or
+ * UI extensions merely because an SDK exports their types. Declaring the matrix as
+ * data — with `implemented: false` where that is the truth — means the server
+ * cannot advertise a feature it does not have by accident.
+ */
+export declare const ADVERTISED_FEATURES: readonly FeatureDeclaration[];
+/**
+ * The capabilities object this server may advertise.
+ *
+ * Derived from {@link ADVERTISED_FEATURES} rather than written twice, so the
+ * matrix and the advertised capabilities cannot disagree.
+ * @returns the capability names that are genuinely implemented.
+ */
+export declare function implementedCapabilities(): string[];
+/**
+ * Whether a client's REQUIRED capability is one this server supports (P26-03).
+ *
+ * @param required - capability names the client declared as required.
+ * @returns the unsupported names, empty when all are supported.
+ */
+export declare function unsupportedRequiredCapabilities(required: readonly string[]): string[];
+/**
+ * The caching fields every cacheable result must carry (P26-14).
+ *
+ * Taken from the pinned schema's `CacheableResult`, which REQUIRES `cacheScope` and
+ * `ttlMs` on `DiscoverResult` and `ListToolsResult` alike. Tool Mode's
+ * authorization-filtered catalogs are private, so the default TTL is zero and the
+ * scope is private — a shared cache keyed on tool names would leak one caller's
+ * permitted set to another.
+ * @returns the caching fields.
+ */
+export declare function cacheableResultFields(): {
+    readonly cacheScope: string;
+    readonly ttlMs: number;
+};
+/**
+ * Build a successful result envelope (P26-04).
+ *
+ * Every modern result carries `resultType`, and `serverInfo` rides in result
+ * metadata per the revision's guidance — `ResultMetaObject` admits exactly that
+ * one key, which is what this writes.
+ * @param result - the method-specific fields.
+ * @param serverInfo - this server's identity.
+ * @returns the result object, including `resultType` and `_meta`.
+ */
+export declare function successResult(result: Record<string, unknown>, serverInfo: {
+    readonly name: string;
+    readonly version: string;
+}): Record<string, unknown>;
+/**
+ * Build a tool-error RESULT (P26-04).
+ *
+ * The distinction this preserves is the whole point: an application failure is a
+ * successful protocol exchange carrying `isError`, while a malformed request is a
+ * JSON-RPC error. Wrapping a domain failure as protocol success, or an
+ * infrastructure failure as a successful domain payload, are both forbidden.
+ * @param message - a bounded, model-readable explanation.
+ * @returns the tool-error result.
+ */
+export declare function toolErrorResult(message: string): ToolErrorPayload;
+/**
+ * Build a JSON-RPC error response.
+ *
+ * When the request id is UNKNOWN the `id` member is omitted rather than set to
+ * `null`. JSON-RPC 2.0 conventionally allows `id: null` for an undeterminable id,
+ * but the pinned revision schema types `RequestId` as `string | integer` and does
+ * not admit null — while `id` itself is optional. Omitting it is therefore the
+ * conformant way to say "unknown", and the independent probe caught this by
+ * rejecting a captured 401 whose id was null.
+ *
+ * @param id - the request id, or null when it could not be determined.
+ * @param error - the failure.
+ * @returns the response envelope.
+ */
+export declare function errorResponse(id: string | number | null, error: WireError | {
+    code: number;
+    message: string;
+    data?: Record<string, unknown>;
+}): Record<string, unknown>;
+/** A parsed HTTP request's relevant fields. */
+export interface HeaderInput {
+    /** The `MCP-Protocol-Version` header, if present. */
+    readonly protocolVersion?: string;
+    /** The `Mcp-Method` header, if present. */
+    readonly method?: string;
+    /** The `Mcp-Name` header, if present. */
+    readonly name?: string;
+}
+/**
+ * Decode the revision's Base64 sentinel encoding (P26-05).
+ *
+ * A header value may be encoded with the official `=?base64?…?=` sentinel, and it
+ * must be decoded BEFORE comparison. Comparing the encoded form would let a client
+ * present a value that decodes to something else entirely.
+ * @param value - the raw header value.
+ * @returns the decoded value.
+ */
+export declare function decodeHeaderValue(value: string): string;
+/**
+ * Check the required headers against the body (P26-05).
+ *
+ * Headers are checked against BODY FIELDS, so a request cannot claim one method in
+ * a header and another in its body. Every mismatch is `HeaderMismatch` (-32020),
+ * which the HTTP layer reports as 400.
+ * @param headers - the relevant request headers.
+ * @param body - the parsed request.
+ * @returns nothing when the headers agree.
+ * @throws WireError `-32020` naming the first disagreement.
+ */
+export declare function assertHeadersMatch(headers: HeaderInput, body: WireRequest): void;
+/**
+ * Parse a newline-delimited stdio frame (P26-08).
+ *
+ * Stdio carries protocol traffic on stdout and diagnostics on stderr, so a line
+ * that is not a JSON object is a protocol error rather than something to log and
+ * skip: silently dropping it would leave a client waiting for a response that
+ * never comes.
+ * @param line - one line of input.
+ * @returns the parsed request, or undefined for a blank line.
+ * @throws WireError `-32700` when the line is not a JSON object.
+ */
+export declare function parseStdioLine(line: string): WireRequest | undefined;
+/**
+ * Serialize one stdio frame.
+ * @param message - the response or notification.
+ * @returns the line, newline-terminated.
+ */
+export declare function serializeStdioFrame(message: unknown): string;
+//# sourceMappingURL=protocol.d.ts.map

package/lib/mcp/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../src/mcp/protocol.ts"],"names":[],"mappings":"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"}