@12-apps/mcp 3.1.0 → 3.2.1

package/dist/index.d.ts

@@ -0,0 +1,382 @@
+import { J as JsonSchema, G as GeneratedTool, D as DispatchConfig, a as DispatchResult, b as ToolAnnotations, R as RequestAuth, T as ToolManifest } from './generate-Dx3cK8th.js';
+export { A as AuthResolver, c as GenerateOptions, O as OpenApiDocument, d as OpenApiOperation, e as OpenApiParameter, f as OpenApiRequestBody, g as OpenApiResponse, P as ParameterLocation, h as ToolParameter, i as generateTools } from './generate-Dx3cK8th.js';
+export { A as AI_CAPABILITIES, a as AI_PERMISSION_MODEL, b as AiCapability, c as AiConnectPromptSpec, d as AiHostBrand, e as AiHostConfigureStage, f as AiHostGuide, g as AiHostLink, h as AiProvider, i as aiConnectPrompt, j as aiHostGuides, p as providerForHostId } from './guide-DV5MQbCg.js';
+
+/**
+ * Raised when a JSON Schema cannot be turned into a flat, self-contained tool
+ * input — an unresolvable `$ref`, an unsupported pointer, or a recursive schema.
+ * The MCP tool surface is deliberately finite and flat (it is handed to an LLM
+ * and committed to the drift manifest), so recursion is rejected rather than
+ * silently truncated.
+ */
+declare class UnsupportedSchemaError extends Error {
+    constructor(message: string);
+}
+/**
+ * Inline every local `$ref` in a JSON Schema and drop the now-empty `$defs`/
+ * `definitions` containers, yielding a flat, self-contained schema. Diamond reuse
+ * (the same definition referenced by sibling branches) is fine; only a true cycle
+ * — a definition that references itself up the resolution stack — is rejected.
+ *
+ * A schema with no `$ref`/definitions is returned structurally unchanged, so
+ * inlining an already-flat spec is a no-op (the drift gate stays a stable diff).
+ */
+declare function inlineSchemaRefs(schema: JsonSchema): JsonSchema;
+
+/** Raised when tool arguments cannot be routed onto the HTTP request. */
+declare class DispatchInputError extends Error {
+    constructor(message: string);
+}
+/**
+ * Execute one generated tool by proxying to its HTTP endpoint, forwarding the
+ * caller's bearer verbatim. This function performs NO authorization — the
+ * endpoint does, exactly as it would for a first-party request. That is the whole
+ * point of the passthrough: the agent can do precisely what the user can.
+ */
+declare function dispatchTool(tool: GeneratedTool, args: Record<string, unknown>, config: DispatchConfig): Promise<DispatchResult>;
+
+/**
+ * The registry is the transport-agnostic seam between the generated tools and the
+ * MCP SDK. The consuming app owns the HTTP/JSON-RPC transport (mounting it at
+ * `/api/mcp`) and, per request, resolves {@link RequestAuth} and calls
+ * {@link ToolRegistry.listTools} / {@link ToolRegistry.callTool}. Keeping the
+ * SDK out of this package means the core stays testable and portable.
+ */
+/** An MCP tool descriptor as advertised to clients (subset of the MCP schema). */
+interface McpToolDescriptor {
+    name: string;
+    description: string;
+    inputSchema: JsonSchema;
+    outputSchema?: JsonSchema;
+    annotations: ToolAnnotations;
+}
+/**
+ * `_meta` key carrying the upstream HTTP status of a dispatched call.
+ *
+ * `isError` is one bit, and it collapses answers that mean opposite things: a
+ * 404 for a record that does not exist, a 403 a guard correctly refused, a
+ * domain refusal ("this store does not use comandas"), and a 500 where the route
+ * threw all arrive identical. Callers that need to tell "correctly refused" from
+ * "actually broken" — `mcp:smoke` above all — cannot, because the status is
+ * known at dispatch and then dropped. Publishing it under a namespaced `_meta`
+ * key (permitted by the MCP result schema) keeps `isError` as the agent-facing
+ * signal while making the distinction recoverable.
+ */
+declare const HTTP_STATUS_META_KEY = "dispatch/httpStatus";
+/** An MCP tool-call result (subset of the MCP schema). */
+interface McpToolResult {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError: boolean;
+    /** Machine-readable output matching the advertised outputSchema. */
+    structuredContent?: Record<string, unknown>;
+    /** Out-of-band metadata; carries {@link HTTP_STATUS_META_KEY} when dispatched. */
+    _meta?: Record<string, unknown>;
+}
+interface ToolRegistry {
+    listTools(auth?: RequestAuth): McpToolDescriptor[];
+    callTool(name: string, args: Record<string, unknown>, auth: RequestAuth): Promise<McpToolResult>;
+}
+interface RegistryOptions {
+    tools: GeneratedTool[];
+    /** Origin the tools proxy to (usually the app's own public URL). */
+    baseUrl: string;
+    fetchImpl?: typeof fetch;
+    /**
+     * Optional visibility filter — e.g. hide mutating tools, or tools whose
+     * required scope the caller lacks. Authorization is still enforced upstream;
+     * this only shapes what the agent is shown.
+     */
+    isVisible?: (tool: GeneratedTool, auth?: RequestAuth) => boolean;
+}
+declare function createToolRegistry(options: RegistryOptions): ToolRegistry;
+
+/**
+ * The MCP JSON-RPC 2.0 request half of the Streamable HTTP transport.
+ *
+ * Implemented directly rather than via the MCP SDK because the SDK's transport is
+ * Node-`http` oriented, and a host serving Web `Request`/`Response` (a Next route
+ * handler, a Hono route) has no `http.IncomingMessage` to hand it. It covers the
+ * methods a client needs to discover and call tools: `initialize`, `tools/list`,
+ * `tools/call`, plus `ping`.
+ *
+ * WHAT IS MECHANISM AND LIVES HERE: the envelope, the method table, the error
+ * codes, the well-formedness rule, and the notification convention. None of it
+ * varies per host — it is JSON-RPC 2.0 and the MCP specification.
+ *
+ * WHAT IS VOCABULARY AND STAYS WITH THE HOST: the server's NAME, its version, and
+ * the `instructions` string an agent reads on connect. Those describe one
+ * particular product's tool surface, so they arrive as {@link McpJsonRpcOptions}
+ * rather than being written here.
+ */
+/** The MCP protocol revision this transport implements. */
+declare const MCP_PROTOCOL_VERSION = "2025-06-18";
+/**
+ * JSON-RPC error code for "authentication required", returned by `tools/call`
+ * when the request carried no valid bearer. Outside the reserved -32768..-32000
+ * band's *defined* codes on purpose: it is an implementation-defined server
+ * error, and a host maps it to HTTP 401.
+ */
+declare const UNAUTHORIZED_CODE = -32001;
+interface JsonRpcRequest {
+    jsonrpc: "2.0";
+    id?: string | number | null;
+    method: string;
+    params?: unknown;
+}
+interface JsonRpcResponse {
+    jsonrpc: "2.0";
+    id: string | number | null;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+    };
+}
+/** What a client is told it connected to, in `initialize`'s `serverInfo`. */
+interface McpServerInfo {
+    /** The server's name, as a connected host displays it. */
+    name: string;
+    /**
+     * The advertised surface version.
+     *
+     * This is the ONLY signal a client gets that the tool surface changed: the
+     * transport is request/response only, so `notifications/tools/list_changed`
+     * can never be sent, and a host that cached `tools/list` at the handshake has
+     * no other reason to ask again. See `server/surface-lock.ts` for the guard
+     * that makes forgetting to move it a build error instead of a comment.
+     */
+    version: string;
+}
+interface McpJsonRpcOptions {
+    /** The host's identity, returned verbatim in `initialize`. */
+    serverInfo: McpServerInfo;
+    /**
+     * Server-level guidance surfaced to the model on `initialize` (the MCP spec's
+     * optional `instructions` field). Omitted from the result when absent, rather
+     * than sent empty — a blank string is a claim that there is guidance.
+     */
+    instructions?: string;
+    /**
+     * Override the advertised protocol revision. Defaults to
+     * {@link MCP_PROTOCOL_VERSION}; a host should not normally set it.
+     */
+    protocolVersion?: string;
+}
+/**
+ * Handle one MCP JSON-RPC request.
+ *
+ * Returns `null` for notifications (no id, no reply expected). `auth` is the
+ * verified caller identity, or `null` when the request carried no valid bearer —
+ * `tools/call` then returns {@link UNAUTHORIZED_CODE}, which the host surfaces as
+ * HTTP 401. Discovery (`initialize`, `ping`, `tools/list`) stays open, so a client
+ * can read the surface before it has a token.
+ */
+declare function handleMcpJsonRpc(request: JsonRpcRequest, registry: ToolRegistry, auth: RequestAuth | null, options: McpJsonRpcOptions): Promise<JsonRpcResponse | null>;
+
+/**
+ * The manifest is the committed source-of-truth artifact the CI drift gate
+ * (`mcp:check` → `12-apps/ci` `mcp-contract.yml`) diffs against a fresh
+ * regeneration. If an endpoint's schema changes without the manifest being
+ * regenerated, the diff fails the build — that is how the served MCP surface is
+ * kept in lockstep with the endpoint surface.
+ */
+interface BuildManifestOptions {
+    /** Bumped intentionally on any tool-shape change (mirrors the golden catalog). */
+    version: number;
+    /** Human label for the spec, e.g. "acme web @ openapi.json". */
+    source: string;
+}
+declare function buildManifest(tools: GeneratedTool[], options: BuildManifestOptions): ToolManifest;
+/**
+ * Canonical JSON for a manifest — deep-key-sorted and trailing-newline'd, so the
+ * committed artifact and a regeneration diff cleanly (no key-order or whitespace
+ * churn). `mcp:check` regenerates, serializes with this, and `git diff --exit-code`s.
+ */
+declare function serializeManifest(manifest: ToolManifest): string;
+
+/**
+ * Making a server's advertised version impossible to leave behind.
+ *
+ * THE PROBLEM, which every MCP server on this transport has. `tools/list` is
+ * answered on request and there is no server→client stream, so a server cannot
+ * push `notifications/tools/list_changed` — and one that declares
+ * `capabilities.tools.listChanged` without being able to send it is worse than
+ * one that is honest, because the host then stops checking for itself. What is
+ * left is `serverInfo.version` from the `initialize` handshake. A host caches the
+ * tool list against it, so a version that never moves gives it no reason to ever
+ * ask again: a tool that shipped stays invisible to every ALREADY CONNECTED
+ * client for as long as that connection lives.
+ *
+ * That is not a hypothetical. In the origin host a new tool reached production,
+ * answered on its route, and did not appear in a live connector — behind a
+ * `serverInfo.version` frozen at its initial value while ~280 tools were added
+ * underneath it. Nothing was broken; the only thing asking anyone to bump it was
+ * a comment, and a rule enforced by a comment is not enforced.
+ *
+ * THE MECHANISM. An app commits a lock recording WHICH surface its current
+ * version stands for. Its generator recomputes the digest and refuses to write
+ * the artifacts when the digest moved while the version did not, naming the
+ * value to set. Because the same generator run under `--check` is what the
+ * contract gate already diffs, the failure lands in CI and in a pre-push hook
+ * without a new job, without git history, and without any event-sensitivity.
+ *
+ * WHY A DIGEST OF THE SURFACE, NOT A PATHS FILTER. A `paths:` list over the
+ * server's own directory is wrong in both directions: it fires on edits no
+ * client can see (a comment in an auth helper) and misses real ones that enter
+ * from outside it (a schema whose ceiling is imported from a storage module).
+ * Hashing what the tools ARE — the canonical manifest serialization — has
+ * neither failure mode: it is exactly the bytes `tools/list` would return.
+ */
+/** The committed record: which surface an app's current version stands for. */
+interface SurfaceLock {
+    /** The app's surface version at the time `digest` was recorded. */
+    version: number;
+    /** Digest of the served tool surface (see {@link surfaceDigest}). */
+    digest: string;
+}
+/** Everything {@link surfaceLockProblem} needs to judge one generation. */
+interface SurfaceLockCheck {
+    /** The lock as committed, or `null` when there is none to contradict. */
+    previous: SurfaceLock | null;
+    /** The surface version the app currently declares. */
+    version: number;
+    /** Digest of the surface being generated now. */
+    digest: string;
+    /**
+     * Where the app's version constant lives, repo-relative — quoted in the
+     * failure so the fix is a path and a value rather than a hunt.
+     */
+    versionLocation: string;
+    /** The constant's name, if the app does not use the default. */
+    versionName?: string;
+}
+/**
+ * Digest of a served tool surface — every tool's name, description, annotations
+ * and input/output schemas, in the manifest's own canonical (deep-key-sorted)
+ * serialization. Stable across unrelated reordering, and identical for two
+ * surfaces that a client could not tell apart.
+ */
+declare function surfaceDigest(tools: GeneratedTool[], source: string): string;
+/** Canonical JSON for a committed lock (trailing newline, like the manifest). */
+declare function serializeSurfaceLock(lock: SurfaceLock): string;
+/**
+ * Decide whether an app's current version may stand for its current surface.
+ *
+ * Returns the problem as a sentence ready to print, or `null` when the pair is
+ * consistent. Four outcomes, and three of them pass:
+ *
+ *   - surface unchanged → fine, whatever the version did (a release bump with no
+ *     surface change is legitimate and must not be blocked);
+ *   - surface changed AND version moved → fine, that is the whole contract;
+ *   - no lock to contradict (first run, or the file was deleted) → fine, it is
+ *     simply recorded;
+ *   - surface changed and version did not → the failure this exists for.
+ */
+declare function surfaceLockProblem(check: SurfaceLockCheck): string | null;
+
+/**
+ * OAuth 2.0 Protected Resource Metadata (RFC 9728), as required by the MCP
+ * authorization spec: the MCP endpoint is an OAuth *resource server*. Agent hosts
+ * (Claude.ai / ChatGPT connectors) discover where to obtain a token by reading
+ * `/.well-known/oauth-protected-resource`, and on a 401 the resource server points
+ * them at that document via a `WWW-Authenticate` challenge.
+ *
+ * This module only builds the discovery documents/headers — validating the
+ * resulting access token is the app's job (the {@link import("../types").AuthResolver}),
+ * because it depends on the app's authorization server and key material.
+ */
+interface ProtectedResourceMetadataInput {
+    /** Canonical resource identifier — the MCP endpoint URL (the token audience). */
+    resource: string;
+    /** Authorization server issuer URLs that can mint tokens for this resource. */
+    authorizationServers: string[];
+    /** Scopes the resource server understands (advertised to clients). */
+    scopesSupported?: string[];
+    /** Human-facing docs URL for the protected resource, if any. */
+    resourceDocumentation?: string;
+}
+/** The RFC 9728 metadata document served at `/.well-known/oauth-protected-resource`. */
+interface ProtectedResourceMetadata {
+    resource: string;
+    authorization_servers: string[];
+    bearer_methods_supported: string[];
+    scopes_supported?: string[];
+    resource_documentation?: string;
+}
+declare function buildProtectedResourceMetadata(input: ProtectedResourceMetadataInput): ProtectedResourceMetadata;
+/**
+ * Build the `WWW-Authenticate` value for an unauthorized MCP response, pointing
+ * the client at the protected-resource metadata so it can start the OAuth flow.
+ * Per RFC 9728 §5.1 the challenge carries a `resource_metadata` parameter.
+ */
+declare function bearerChallenge(params: {
+    resourceMetadataUrl: string;
+    error?: "invalid_token" | "insufficient_scope";
+    errorDescription?: string;
+}): string;
+/** Standard path for the protected-resource metadata document. */
+declare const PROTECTED_RESOURCE_METADATA_PATH = "/.well-known/oauth-protected-resource";
+
+/**
+ * OAuth 2.0 Authorization Server Metadata (RFC 8414), the discovery half that
+ * complements the RFC 9728 protected-resource metadata in `resource-metadata.ts`.
+ * Agent hosts (Claude.ai / ChatGPT connectors) read
+ * `/.well-known/oauth-authorization-server` to learn where to start the OAuth
+ * 2.1 Authorization Code + PKCE flow.
+ *
+ * This builder is a pure function of `(issuer, scopes)` with no Next.js/request
+ * coupling, so it can move verbatim into the future `@12-apps/mcp` extraction.
+ * It derives every endpoint from the same issuer origin the resource metadata
+ * advertises, so the two discovery documents cannot drift.
+ */
+interface AuthorizationServerMetadataInput {
+    /** Authorization server issuer URL (origin) — also the resource issuer. */
+    issuer: string;
+    /** Scopes the authorization server advertises (from the shared scope source). */
+    scopesSupported: string[];
+    /**
+     * Client authentication methods the token endpoint accepts. Defaults to
+     * public PKCE clients (`none`) plus HTTP Basic client-secret auth.
+     */
+    tokenEndpointAuthMethods?: string[];
+    /**
+     * Where the endpoints are actually mounted, if not at the defaults below. A
+     * host that moves an endpoint MUST move it here too: this document is the only
+     * thing a connector reads before its first request, so a path that lies here is
+     * a flow that fails at the first hop (12-23 — `createApiMcpOauth` passes its
+     * resolved paths, so the two cannot disagree).
+     */
+    paths?: Partial<AuthorizationServerPaths>;
+}
+/** The endpoint paths this document advertises, relative to the issuer origin. */
+interface AuthorizationServerPaths {
+    authorize: string;
+    token: string;
+    register: string;
+    jwks: string;
+}
+/** The RFC 8414 document served at `/.well-known/oauth-authorization-server`. */
+interface AuthorizationServerMetadata {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    registration_endpoint: string;
+    jwks_uri: string;
+    scopes_supported: string[];
+    response_types_supported: string[];
+    grant_types_supported: string[];
+    code_challenge_methods_supported: string[];
+    token_endpoint_auth_methods_supported: string[];
+}
+/**
+ * Build the RFC 8414 authorization-server metadata document from an issuer
+ * origin and the supported scopes. Endpoints are derived from `issuer`; the
+ * OAuth 2.1 + PKCE contract fixes `response_types_supported`,
+ * `grant_types_supported`, and `code_challenge_methods_supported`.
+ */
+declare function buildAuthorizationServerMetadata(input: AuthorizationServerMetadataInput): AuthorizationServerMetadata;
+
+export { type AuthorizationServerMetadata, type AuthorizationServerMetadataInput, type AuthorizationServerPaths, type BuildManifestOptions, DispatchConfig, DispatchInputError, DispatchResult, GeneratedTool, HTTP_STATUS_META_KEY, type JsonRpcRequest, type JsonRpcResponse, JsonSchema, MCP_PROTOCOL_VERSION, type McpJsonRpcOptions, type McpServerInfo, type McpToolDescriptor, type McpToolResult, PROTECTED_RESOURCE_METADATA_PATH, type ProtectedResourceMetadata, type ProtectedResourceMetadataInput, type RegistryOptions, RequestAuth, type SurfaceLock, type SurfaceLockCheck, ToolAnnotations, ToolManifest, type ToolRegistry, UNAUTHORIZED_CODE, UnsupportedSchemaError, bearerChallenge, buildAuthorizationServerMetadata, buildManifest, buildProtectedResourceMetadata, createToolRegistry, dispatchTool, handleMcpJsonRpc, inlineSchemaRefs, serializeManifest, serializeSurfaceLock, surfaceDigest, surfaceLockProblem };