@try-works/dsh-tool-mode 0.0.0-stage → 0.5.44

package/lib/mcp/protocol.d.ts

@@ -0,0 +1,329 @@
+/**
+ * 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-tool-mode/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, and the pinned revision partitions the
+ * bands: `-32768..-32000` is JSON-RPC's own predefined-error allocation,
+ * `-32020..-32099` is reserved for MCP-defined codes (allocated sequentially,
+ * and this module declares exactly those the revision defines), while
+ * `-32000..-32019` is the IMPLEMENTATION-DEFINED sub-range — the specification
+ * will never define codes there, and receivers must not assume cross-
+ * implementation semantics. `rateLimited` lives in that sub-range deliberately:
+ * it is a documented implementation allocation, never a minted code in the
+ * reserved 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;
+    /**
+     * Implementation-defined (-32000..-32019, never allocated by the specification).
+     *
+     * The revision defines NO rate-limit error, so a refusal uses this documented
+     * implementation code rather than pretending the request was invalid (-32600) or
+     * minting a code in the MCP-reserved band. The HTTP 429 status carries the
+     * semantics; receivers that do not know this code still get a conformant
+     * `JSONRPCErrorResponse` envelope and a `Retry-After` header.
+     */
+    readonly rateLimited: -32001;
+};
+/** 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[];
+/**
+ * What the server may advertise, given what is ACTUALLY WIRED (P26-12).
+ *
+ * The static matrix declared `subscriptions/listen` as implemented unconditionally — while
+ * the only production transport never received a registry and therefore answered `-32601`
+ * for it. An advertised feature that no client can obtain is worse than an absent one: a
+ * client plans around it and fails later.
+ *
+ * The feature is now conditional on the wiring, and the DEFAULT is `false` because that is
+ * the production reality. A caller that has genuinely composed a subscription registry says
+ * so; nothing else can make the claim true by declaring it.
+ *
+ * @param wiring - which optional surfaces are composed.
+ * @returns the advertised-feature matrix for this deployment.
+ */
+export declare function advertisedFeatures(wiring?: {
+    readonly subscriptions?: boolean;
+}): readonly FeatureDeclaration[];
+/**
+ * The capabilities object this server may advertise.
+ *
+ * Derived from the matrix rather than written twice, so the two cannot disagree.
+ * @param wiring - which optional surfaces are composed.
+ * @returns the capability names that are genuinely implemented HERE.
+ */
+export declare function implementedCapabilities(wiring?: {
+    readonly subscriptions?: boolean;
+}): 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[], wiring?: {
+    readonly subscriptions?: boolean;
+}): string[];
+/**
+ * The cache scope a catalog result may declare (P26-14).
+ *
+ * `tools/list` and `server/discover` are AUTHORIZATION-FILTERED: the tool list is the
+ * caller's granted set, so a shared/public cache keyed on tool names would leak one
+ * caller's permitted set to another. `private` is therefore the only admitted scope.
+ */
+export type CatalogCacheScope = 'private';
+/** The catalog caching policy applied to `tools/list` and `server/discover`. */
+export interface CatalogCachePolicy {
+    readonly cacheScope: CatalogCacheScope;
+    /** Time-to-live in milliseconds. Zero means "do not cache". */
+    readonly ttlMs: number;
+}
+/**
+ * Validate and normalize an operator-configured catalog cache policy (P26-14).
+ *
+ * The default is the unchanged safe behavior: `{ cacheScope: 'private', ttlMs: 0 }`.
+ * Invalid configuration is REFUSED with a named error rather than silently rewritten:
+ * emitting a non-private scope would understate the authorization boundary, and a
+ * negative/non-finite TTL is not a cache policy at all.
+ * @param policy - the configured TTL/scope, both optional.
+ * @returns the validated policy.
+ * @throws Error named `INVALID_CATALOG_CACHE_TTL` or `INVALID_CATALOG_CACHE_SCOPE`.
+ */
+export declare function normalizeCachePolicy(policy?: {
+    readonly ttlMs?: number;
+    readonly cacheScope?: string;
+}): CatalogCachePolicy;
+/**
+ * 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. The policy defaults to
+ * private/0 and can carry an operator-configured non-zero TTL; the scope itself is
+ * validated to stay `private` ({@link normalizeCachePolicy}).
+ * @param policy - the catalog cache policy, or undefined for private/0.
+ * @returns the caching fields.
+ */
+export declare function cacheableResultFields(policy?: {
+    readonly ttlMs?: number;
+    readonly cacheScope?: string;
+}): CatalogCachePolicy;
+/**
+ * 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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"}