@12-apps/mcp 3.12.0 → 3.14.0

package/dist/generate/index.d.ts

@@ -1,4 +1,4 @@
-import { T as ToolManifest, O as OpenApiDocument } from '../generate-Dx3cK8th.js';
+import { T as ToolManifest, O as OpenApiDocument } from '../generate-BCDqBUjZ.js';
 
 /**
  * `@12-apps/mcp/generate` — the `mcp:generate` / `mcp:check` gate (12-23), moved

package/dist/{generate-Dx3cK8th.d.ts → generate-BCDqBUjZ.d.ts}

@@ -181,4 +181,4 @@ interface OpenApiDocument {
  */
 declare function generateTools(doc: OpenApiDocument, options?: GenerateOptions): GeneratedTool[];
 
-export { type AuthResolver as A, type DispatchConfig as D, type GeneratedTool as G, type JsonSchema as J, type OpenApiDocument as O, type ParameterLocation as P, type RequestAuth as R, type ToolManifest as T, type DispatchResult as a, type ToolAnnotations as b, type GenerateOptions as c, type OpenApiOperation as d, type OpenApiParameter as e, type OpenApiRequestBody as f, type OpenApiResponse as g, type ToolParameter as h, generateTools as i };
+export { type AuthResolver as A, type DispatchConfig as D, type GeneratedTool as G, type JsonSchema as J, type OpenApiDocument as O, type ParameterLocation as P, type RequestAuth as R, type ToolManifest as T, type ToolAnnotations as a, type DispatchResult as b, type GenerateOptions as c, type OpenApiOperation as d, type OpenApiParameter as e, type OpenApiRequestBody as f, type OpenApiResponse as g, type ToolParameter as h, generateTools as i };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-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';
+import { J as JsonSchema, a as ToolAnnotations, G as GeneratedTool, D as DispatchConfig, b as DispatchResult, R as RequestAuth, T as ToolManifest } from './generate-BCDqBUjZ.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-BCDqBUjZ.js';
 export { A as AiCapability, a as AiConnectPromptCopy, b as AiConnectPromptSpec, c as AiHostBrand, d as AiHostConfigureStage, e as AiHostGuide, f as AiHostLink, g as AiProvider, h as aiConnectPrompt, p as providerForHostId } from './guide-KQNcXlMG.js';
 import { z } from 'zod';
 export { A as AI_CAPABILITIES, a as AI_CONNECT_PROMPT, b as AI_HOST_GUIDES, c as AI_PERMISSION_MODEL, E as EN_US_AI_CAPABILITIES, d as EN_US_AI_CONNECT_PROMPT, e as EN_US_AI_HOST_GUIDES, f as EN_US_AI_PERMISSION_MODEL, P as PT_BR_AI_CAPABILITIES, g as PT_BR_AI_CONNECT_PROMPT, h as PT_BR_AI_HOST_GUIDES, i as PT_BR_AI_PERMISSION_MODEL } from './locales-eKE_OJw4.js';
@@ -51,6 +51,36 @@ declare function inlineSchemaRefs(schema: JsonSchema): JsonSchema;
  */
 /** The methods an MCP-exposed route may use. */
 type HttpMethod = "get" | "post" | "put" | "patch" | "delete";
+/**
+ * What a PACKAGE can say about how its own tool behaves.
+ *
+ * The host still owns the final `ToolAnnotations` — every field required, and
+ * `mcp:lint` unchanged in demanding that each tool ends classified. What
+ * changes is who supplies the DEFAULT. A package declaring
+ * `getSupplierVersions` knows perfectly well that it reads and does not
+ * destroy; a host cannot know that without reading the package's source, so
+ * today it restates the classification by hand — 48 lines of policy hints for
+ * one package's eight-endpoint factory, growing with every collection plugged
+ * in, and wrong the moment the package changes a verb.
+ *
+ * Every field is OPTIONAL here, which is the whole difference from
+ * `ToolAnnotations`: this is a suggestion the host merges under its own table,
+ * so a package that knows two of the four says two and stays silent on the
+ * rest. Deliberately spelled without the `Hint` suffix and as a structural
+ * twin of `@12-apps/wiring`'s `WireMcpAnnotations`, so an `McpEndpoint` still
+ * satisfies `WireMcpTool` — restated rather than imported because this package
+ * takes no dependency on the wiring contract.
+ */
+interface McpAnnotationDefaults {
+    /** Human title override; hosts may re-derive from the operation id. */
+    title?: string;
+    /** The tool only reads — never mutates host state. */
+    readOnly?: boolean;
+    /** A destructive write (delete/purge), as opposed to an additive one. */
+    destructive?: boolean;
+    /** The tool reaches beyond the host's own data (external services). */
+    openWorld?: boolean;
+}
 interface McpEndpointBase {
     /** Stable tool id — this becomes the MCP tool name, so renaming it is a
      *  breaking change for every agent that has learned the old one. */
@@ -67,6 +97,11 @@ interface McpEndpointBase {
     params?: z.ZodType;
     /** Request body schema (writes only). */
     body?: z.ZodType;
+    /**
+     * Behavior the package can assert about its own tool. Optional, and merged
+     * UNDER the host's table — see {@link McpAnnotationDefaults}.
+     */
+    annotations?: McpAnnotationDefaults;
 }
 /**
  * A declared endpoint either answers 200 with a schema'd JSON body (the
@@ -88,6 +123,63 @@ type McpEndpoint = McpEndpointBase & ({
     response?: never;
 });
 
+/**
+ * Composing a tool's behavior classification out of two sources.
+ *
+ * The rule the host's gate enforces is unchanged: every served tool ends with
+ * a COMPLETE `ToolAnnotations` — a title and all three hints — and a tool that
+ * ends unclassified fails `mcp:lint`. ChatGPT App review treats a missing hint
+ * as a blocker, and the Anthropic connector directory derives auto-permissions
+ * from `readOnlyHint`/`destructiveHint`, so there is no defensible default for
+ * "we did not say".
+ *
+ * What this adds is where the answer may COME FROM. A package that declares
+ * `getSupplierVersions` knows it reads and does not destroy; the host cannot
+ * know that without reading the package's source, so it restated the
+ * classification by hand — one line per tool, per collection, wrong the moment
+ * the package changed a verb. Now the package can assert what it knows and the
+ * host's table becomes what it should always have been: OVERRIDES, plus the
+ * tools the host itself owns.
+ *
+ * ## Precedence, and why it runs this way
+ *
+ * The HOST wins every field it states. A package's claim is a default, not a
+ * fact about the host's deployment: the same endpoint can be read-only in one
+ * app and reach an external service in another (a host that proxies its
+ * catalog reads through a vendor), and the host is the only party that knows.
+ * Inverting this would make a package version bump silently re-classify a tool
+ * an operator had already audited — the exact thing an audited classification
+ * exists to prevent.
+ *
+ * ## What it refuses
+ *
+ * A field neither side supplies. `resolveToolAnnotations` throws naming the
+ * tool and the missing fields, which keeps the completeness property a
+ * REFUSAL rather than a lint pass over a table that quietly grew a gap. The
+ * host's own gate can keep its message; this one fires first and says the same
+ * thing in the same terms.
+ */
+
+/** The host's half — whatever it chose to state, per tool. */
+type ToolAnnotationOverrides = Partial<ToolAnnotations>;
+/**
+ * Merge a package's declared defaults under a host's overrides.
+ *
+ * The four fields are resolved into one record and checked generically rather
+ * than branch by branch — which keeps the "host wins, and `false` is an
+ * answer" rule stated exactly once per field instead of once per field per
+ * check.
+ *
+ * `??` and not `||` throughout, and that is the trap the whole merge turns on:
+ * `false` is a real classification — "this tool does not destroy" — and must
+ * not fall through to the package's answer.
+ *
+ * @param name the tool id, for the refusal message
+ * @param defaults what the package asserted (`McpEndpoint.annotations`)
+ * @param overrides what the host's own table says; wins every field it states
+ */
+declare function resolveToolAnnotations(name: string, defaults: McpAnnotationDefaults | undefined, overrides: ToolAnnotationOverrides | undefined): ToolAnnotations;
+
 /** Raised when tool arguments cannot be routed onto the HTTP request. */
 declare class DispatchInputError extends Error {
     constructor(message: string);
@@ -469,4 +561,4 @@ interface AuthorizationServerMetadata {
  */
 declare function buildAuthorizationServerMetadata(input: AuthorizationServerMetadataInput): AuthorizationServerMetadata;
 
-export { type AuthorizationServerMetadata, type AuthorizationServerMetadataInput, type AuthorizationServerPaths, type BuildManifestOptions, DispatchConfig, DispatchInputError, DispatchResult, GeneratedTool, HTTP_STATUS_META_KEY, type HttpMethod, type JsonRpcRequest, type JsonRpcResponse, JsonSchema, MCP_PROTOCOL_VERSION, type McpEndpoint, 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, redactResponseBody, redactResponseSchema, serializeManifest, serializeSurfaceLock, surfaceDigest, surfaceLockProblem };
+export { type AuthorizationServerMetadata, type AuthorizationServerMetadataInput, type AuthorizationServerPaths, type BuildManifestOptions, DispatchConfig, DispatchInputError, DispatchResult, GeneratedTool, HTTP_STATUS_META_KEY, type HttpMethod, type JsonRpcRequest, type JsonRpcResponse, JsonSchema, MCP_PROTOCOL_VERSION, type McpAnnotationDefaults, type McpEndpoint, type McpJsonRpcOptions, type McpServerInfo, type McpToolDescriptor, type McpToolResult, PROTECTED_RESOURCE_METADATA_PATH, type ProtectedResourceMetadata, type ProtectedResourceMetadataInput, type RegistryOptions, RequestAuth, type SurfaceLock, type SurfaceLockCheck, type ToolAnnotationOverrides, ToolAnnotations, ToolManifest, type ToolRegistry, UNAUTHORIZED_CODE, UnsupportedSchemaError, bearerChallenge, buildAuthorizationServerMetadata, buildManifest, buildProtectedResourceMetadata, createToolRegistry, dispatchTool, handleMcpJsonRpc, inlineSchemaRefs, redactResponseBody, redactResponseSchema, resolveToolAnnotations, serializeManifest, serializeSurfaceLock, surfaceDigest, surfaceLockProblem };

package/dist/index.js

@@ -94,6 +94,38 @@ function inlineSchemaRefs(schema) {
 }
 __name(inlineSchemaRefs, "inlineSchemaRefs");
 
+// src/openapi/annotations.ts
+function titleOf(candidate) {
+  return typeof candidate === "string" && candidate.trim() !== "" ? candidate : void 0;
+}
+__name(titleOf, "titleOf");
+function resolveToolAnnotations(name, defaults, overrides) {
+  const host = overrides ?? {};
+  const declared = defaults ?? {};
+  const resolved = {
+    title: titleOf(host.title ?? declared.title),
+    readOnlyHint: host.readOnlyHint ?? declared.readOnly,
+    openWorldHint: host.openWorldHint ?? declared.openWorld,
+    destructiveHint: host.destructiveHint ?? declared.destructive
+  };
+  const missing = REQUIRED_FIELDS.filter((field) => resolved[field] === void 0);
+  if (missing.length > 0) refuse(name, missing);
+  return resolved;
+}
+__name(resolveToolAnnotations, "resolveToolAnnotations");
+var REQUIRED_FIELDS = [
+  "title",
+  "readOnlyHint",
+  "openWorldHint",
+  "destructiveHint"
+];
+function refuse(name, missing) {
+  throw new Error(
+    `MCP tool "${name}" ends unclassified: neither the package nor the host supplied ${missing.join(", ")}. Every served tool needs a complete classification \u2014 a missing hint blocks ChatGPT App review, and the connector directory derives auto-permissions from readOnlyHint/destructiveHint.`
+  );
+}
+__name(refuse, "refuse");
+
 // src/dispatch/proxy.ts
 var DispatchInputError = class extends Error {
   static {
@@ -395,6 +427,7 @@ export {
   providerForHostId,
   redactResponseBody,
   redactResponseSchema,
+  resolveToolAnnotations,
   serializeManifest,
   serializeSurfaceLock,
   surfaceDigest,

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/openapi/refs.ts","../src/dispatch/proxy.ts","../src/server/redact.ts","../src/server/registry.ts","../src/server/jsonrpc.ts"],"sourcesContent":["import type { JsonSchema } from \"../types\";\n\n/**\n * Raised when a JSON Schema cannot be turned into a flat, self-contained tool\n * input — an unresolvable `$ref`, an unsupported pointer, or a recursive schema.\n * The MCP tool surface is deliberately finite and flat (it is handed to an LLM\n * and committed to the drift manifest), so recursion is rejected rather than\n * silently truncated.\n */\nexport class UnsupportedSchemaError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"UnsupportedSchemaError\";\n  }\n}\n\n/** Local-definition containers a `$ref` may point into, in resolution order. */\nconst REF_PREFIXES = [\"#/$defs/\", \"#/definitions/\", \"#/components/schemas/\"] as const;\nconst DEF_CONTAINERS = [\"$defs\", \"definitions\"] as const;\n\n/** The definition name a supported local pointer targets, or `null` if unsupported. */\nfunction refName(ref: string): string | null {\n  const prefix = REF_PREFIXES.find((candidate) => ref.startsWith(candidate));\n  return prefix ? decodeURIComponent(ref.slice(prefix.length)) : null;\n}\n\n/** Collect the `$defs`/`definitions` maps hoisted onto a schema root into one lookup. */\nfunction collectDefs(root: JsonSchema): Record<string, JsonSchema> {\n  const defs: Record<string, JsonSchema> = {};\n  DEF_CONTAINERS.forEach((key) => {\n    const container = root[key];\n    if (container && typeof container === \"object\") {\n      Object.assign(defs, container as Record<string, JsonSchema>);\n    }\n  });\n  return defs;\n}\n\nfunction inlineRef(\n  ref: string,\n  defs: Record<string, JsonSchema>,\n  active: Set<string>,\n): unknown {\n  const name = refName(ref);\n  if (name === null) throw new UnsupportedSchemaError(`Unsupported $ref pointer: ${ref}`);\n  const target = defs[name];\n  if (!target) throw new UnsupportedSchemaError(`Unresolved $ref: ${ref}`);\n  if (active.has(name)) throw new UnsupportedSchemaError(`Recursive schema not supported: ${name}`);\n  active.add(name);\n  const resolved = walk(target, defs, active);\n  active.delete(name);\n  return resolved;\n}\n\n/** Deep-copy `node`, inlining every `$ref` and stripping definition containers. */\nfunction walk(node: unknown, defs: Record<string, JsonSchema>, active: Set<string>): unknown {\n  if (Array.isArray(node)) return node.map((item) => walk(item, defs, active));\n  if (!node || typeof node !== \"object\") return node;\n\n  const obj = node as Record<string, unknown>;\n  if (typeof obj.$ref === \"string\") return inlineRef(obj.$ref, defs, active);\n\n  const out: Record<string, unknown> = {};\n  Object.entries(obj).forEach(([key, value]) => {\n    if (!DEF_CONTAINERS.includes(key as (typeof DEF_CONTAINERS)[number])) {\n      out[key] = walk(value, defs, active);\n    }\n  });\n  return out;\n}\n\n/**\n * Inline every local `$ref` in a JSON Schema and drop the now-empty `$defs`/\n * `definitions` containers, yielding a flat, self-contained schema. Diamond reuse\n * (the same definition referenced by sibling branches) is fine; only a true cycle\n * — a definition that references itself up the resolution stack — is rejected.\n *\n * A schema with no `$ref`/definitions is returned structurally unchanged, so\n * inlining an already-flat spec is a no-op (the drift gate stays a stable diff).\n */\nexport function inlineSchemaRefs(schema: JsonSchema): JsonSchema {\n  const defs = collectDefs(schema);\n  return walk(schema, defs, new Set<string>()) as JsonSchema;\n}\n","import type { DispatchConfig, DispatchResult, GeneratedTool } from \"../types\";\n\n/** Raised when tool arguments cannot be routed onto the HTTP request. */\nexport class DispatchInputError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"DispatchInputError\";\n  }\n}\n\n/** Expand a path template (`/products/{id}`) using the path args, URL-encoding each. */\nfunction expandPath(\n  tool: GeneratedTool,\n  args: Record<string, unknown>,\n): string {\n  return tool.path.replace(/\\{([^}]+)\\}/g, (_match, key: string) => {\n    const value = args[key];\n    if (value === undefined || value === null) {\n      throw new DispatchInputError(`Missing required path parameter: ${key}`);\n    }\n    return encodeURIComponent(String(value));\n  });\n}\n\n/**\n * Route the non-path parameters (query + header) from the flat args. A missing\n * required parameter is a hard error; a missing optional one is simply omitted.\n */\nfunction routeParams(\n  tool: GeneratedTool,\n  args: Record<string, unknown>,\n): { query: URLSearchParams; headers: Record<string, string> } {\n  const query = new URLSearchParams();\n  const headers: Record<string, string> = {};\n\n  tool.parameters\n    .filter((param) => param.in !== \"path\")\n    .forEach((param) => {\n      const value = args[param.name];\n      if (value === undefined || value === null) {\n        if (param.required) {\n          throw new DispatchInputError(`Missing required ${param.in} parameter: ${param.name}`);\n        }\n        return;\n      }\n      if (param.in === \"query\") query.set(param.name, String(value));\n      else headers[param.name] = String(value);\n    });\n\n  return { query, headers };\n}\n\n/**\n * Reconstruct the request body from the flat args using the routing metadata.\n * Anything not claimed by a known body property is dropped — the input schema is\n * `additionalProperties: false`, so a validated call never carries extras and an\n * unvalidated one cannot smuggle fields upstream.\n */\nfunction routeBody(tool: GeneratedTool, args: Record<string, unknown>): unknown {\n  if (tool.bodyIsWhole) return args.body;\n  if (!tool.bodyProps.length) return undefined;\n  const payload: Record<string, unknown> = {};\n  tool.bodyProps.forEach((key) => {\n    if (args[key] !== undefined) payload[key] = args[key];\n  });\n  return Object.keys(payload).length ? payload : undefined;\n}\n\n/**\n * Execute one generated tool by proxying to its HTTP endpoint, forwarding the\n * caller's bearer verbatim. This function performs NO authorization — the\n * endpoint does, exactly as it would for a first-party request. That is the whole\n * point of the passthrough: the agent can do precisely what the user can.\n */\nexport async function dispatchTool(\n  tool: GeneratedTool,\n  args: Record<string, unknown>,\n  config: DispatchConfig,\n): Promise<DispatchResult> {\n  const doFetch = config.fetchImpl ?? fetch;\n  const pathname = expandPath(tool, args);\n  const { query, headers } = routeParams(tool, args);\n  const body = routeBody(tool, args);\n\n  const url = new URL(pathname, config.baseUrl);\n  for (const [key, value] of query) url.searchParams.set(key, value);\n\n  // Carry the proxy origin as the standard reverse-proxy forwarded headers. The\n  // wrapped endpoint's auth guard re-derives the request origin (to check the\n  // access token's `aud`) WITHOUT a request object, so it can only see the origin\n  // through these headers. `baseUrl` is exactly the origin the token was minted\n  // and transport-verified against, so forwarding its scheme+host makes the\n  // wrapped guard reconstruct the SAME origin — the `aud` survives the replay in\n  // both dev (http) and prod (any proxied https origin). Omitting them let the\n  // guard default the scheme to https and 401 a valid http-minted bearer.\n  const base = new URL(config.baseUrl);\n\n  const init: RequestInit = {\n    method: tool.method,\n    headers: {\n      accept: \"application/json\",\n      authorization: `Bearer ${config.bearer}`,\n      \"x-forwarded-proto\": base.protocol.replace(/:$/, \"\"),\n      \"x-forwarded-host\": base.host,\n      ...headers,\n    },\n  };\n  if (body !== undefined) {\n    (init.headers as Record<string, string>)[\"content-type\"] = \"application/json\";\n    init.body = JSON.stringify(body);\n  }\n\n  const response = await doFetch(url.toString(), init);\n  const text = await response.text();\n  let parsed: unknown = text;\n  const contentType = response.headers.get(\"content-type\") ?? \"\";\n  if (contentType.includes(\"application/json\") && text) {\n    try {\n      parsed = JSON.parse(text);\n    } catch {\n      parsed = text;\n    }\n  }\n\n  return { status: response.status, ok: response.ok, body: parsed };\n}\n","import type { JsonSchema } from \"../types\";\n\n/**\n * Both halves of the redaction contract: the SCHEMA a tool advertises, and the\n * BODY it returns.\n *\n * They only work as a pair, and the failure mode when they disagree is not a\n * cosmetic one. The dispatcher forwards the wrapped endpoint's response body\n * verbatim, so a narrowed `outputSchema` alone would only change what the\n * manifest CLAIMS is returned — the value still reaches the agent. Strip the\n * body but leave the schema advertising the field, and every successful call\n * fails validation against the very schema the manifest published, worst of all\n * when the field was `required`.\n *\n * So `redactResponseSchema` removes the paths at generate time and\n * `redactResponseBody` removes the same paths at dispatch, from one list. A host\n * that takes one and hand-rolls the other is back to the disagreement this pair\n * exists to prevent.\n */\n\n/** Structural keywords that wrap a value without naming a field. */\nconst SCHEMA_WRAPPERS = [\"items\", \"anyOf\", \"oneOf\", \"allOf\"] as const;\n\nfunction isSchema(value: unknown): value is JsonSchema {\n  return Boolean(value) && typeof value === \"object\";\n}\n\n/** Drop `field` from an object schema's properties AND its `required` list. */\nfunction deleteProperty(schema: JsonSchema, field: string): true {\n  delete (schema.properties as Record<string, JsonSchema>)[field];\n  if (Array.isArray(schema.required)) {\n    const kept = (schema.required as string[]).filter((name) => name !== field);\n    if (kept.length) schema.required = kept;\n    else delete schema.required;\n  }\n  return true;\n}\n\n/**\n * Descend into wrappers without consuming a segment, so `data.taxId` addresses\n * an array of rows and a `.nullable()` union branch alike.\n */\nfunction omitInWrappers(schema: JsonSchema, segments: readonly string[]): boolean {\n  return SCHEMA_WRAPPERS.reduce((removed, keyword) => {\n    const child = schema[keyword];\n    const branches = Array.isArray(child) ? child : [child];\n    return branches.reduce<boolean>(\n      (acc, branch) => (isSchema(branch) && omitSchemaPath(branch, segments)) || acc,\n      removed,\n    );\n  }, false);\n}\n\nfunction omitSchemaPath(schema: JsonSchema, segments: readonly string[]): boolean {\n  const inWrappers = omitInWrappers(schema, segments);\n\n  const properties = schema.properties as Record<string, JsonSchema> | undefined;\n  const [head, ...rest] = segments;\n  if (!properties || !head || !(head in properties)) return inWrappers;\n\n  if (rest.length === 0) return deleteProperty(schema, head);\n\n  const child = properties[head];\n  return (isSchema(child) && omitSchemaPath(child, rest)) || inWrappers;\n}\n\n/**\n * Return `schema` without the listed dotted paths — the advertised half.\n *\n * THROWS when a path names nothing, rather than returning quietly: a typo'd or\n * stale redaction would otherwise protect nothing at all, and it would do so\n * invisibly, which is the one outcome a redaction list must never have. Failing\n * here turns it into a generator error naming the offending path.\n *\n * The input is cloned, not narrowed in place: a caller may hold the converted\n * schema for other uses (a shared `$defs` component, a schema reused across two\n * operations), and mutating it would redact those too.\n *\n * `operationId` only shapes the error message — pass it so the failure names\n * which tool declared the bad path.\n */\nexport function redactResponseSchema(\n  schema: JsonSchema,\n  paths: readonly string[],\n  operationId?: string,\n): JsonSchema {\n  if (!paths.length) return schema;\n\n  const clone = structuredClone(schema);\n  paths.forEach((path) => {\n    if (!omitSchemaPath(clone, path.split(\".\"))) {\n      const subject = operationId ? `MCP endpoint \"${operationId}\"` : \"This response schema\";\n      throw new Error(\n        `${subject} declares a response redaction for \"${path}\", which is not a field of its response schema`,\n      );\n    }\n  });\n  return clone;\n}\n\n/** Walk one dotted path, mapping over arrays, and delete the leaf. */\nfunction stripPath(value: unknown, segments: readonly string[]): void {\n  if (value === null || typeof value !== \"object\") return;\n\n  if (Array.isArray(value)) {\n    value.forEach((entry) => stripPath(entry, segments));\n    return;\n  }\n\n  const [head, ...rest] = segments;\n  if (!head) return;\n\n  const record = value as Record<string, unknown>;\n  if (rest.length === 0) {\n    delete record[head];\n    return;\n  }\n  if (head in record) stripPath(record[head], rest);\n}\n\n/**\n * Return `body` without the listed dotted paths.\n *\n * The input is deep-cloned first: dispatch results are handed straight to the\n * JSON-RPC encoder AND reused as `structuredContent`, so mutating in place\n * could leak a half-redacted object into one of the two surfaces.\n */\nexport function redactResponseBody(\n  body: unknown,\n  paths: readonly string[] | undefined,\n): unknown {\n  if (!paths?.length || body === null || typeof body !== \"object\") return body;\n\n  const clone = structuredClone(body);\n  paths.forEach((path) => stripPath(clone, path.split(\".\")));\n  return clone;\n}\n","import { dispatchTool } from \"../dispatch/proxy\";\nimport type {\n  GeneratedTool,\n  JsonSchema,\n  RequestAuth,\n  ToolAnnotations,\n} from \"../types\";\nimport { redactResponseBody } from \"./redact\";\n\n/**\n * The registry is the transport-agnostic seam between the generated tools and the\n * MCP SDK. The consuming app owns the HTTP/JSON-RPC transport (mounting it at\n * `/api/mcp`) and, per request, resolves {@link RequestAuth} and calls\n * {@link ToolRegistry.listTools} / {@link ToolRegistry.callTool}. Keeping the\n * SDK out of this package means the core stays testable and portable.\n */\n\n/** An MCP tool descriptor as advertised to clients (subset of the MCP schema). */\nexport interface McpToolDescriptor {\n  name: string;\n  description: string;\n  inputSchema: JsonSchema;\n  outputSchema?: JsonSchema;\n  annotations: ToolAnnotations;\n}\n\n/**\n * `_meta` key carrying the upstream HTTP status of a dispatched call.\n *\n * `isError` is one bit, and it collapses answers that mean opposite things: a\n * 404 for a record that does not exist, a 403 a guard correctly refused, a\n * domain refusal (\"this store does not use comandas\"), and a 500 where the route\n * threw all arrive identical. Callers that need to tell \"correctly refused\" from\n * \"actually broken\" — `mcp:smoke` above all — cannot, because the status is\n * known at dispatch and then dropped. Publishing it under a namespaced `_meta`\n * key (permitted by the MCP result schema) keeps `isError` as the agent-facing\n * signal while making the distinction recoverable.\n */\nexport const HTTP_STATUS_META_KEY = \"dispatch/httpStatus\";\n\n/** An MCP tool-call result (subset of the MCP schema). */\nexport interface McpToolResult {\n  content: Array<{ type: \"text\"; text: string }>;\n  isError: boolean;\n  /** Machine-readable output matching the advertised outputSchema. */\n  structuredContent?: Record<string, unknown>;\n  /** Out-of-band metadata; carries {@link HTTP_STATUS_META_KEY} when dispatched. */\n  _meta?: Record<string, unknown>;\n}\n\nexport interface ToolRegistry {\n  listTools(auth?: RequestAuth): McpToolDescriptor[];\n  callTool(\n    name: string,\n    args: Record<string, unknown>,\n    auth: RequestAuth,\n  ): Promise<McpToolResult>;\n}\n\nexport interface RegistryOptions {\n  tools: GeneratedTool[];\n  /** Origin the tools proxy to (usually the app's own public URL). */\n  baseUrl: string;\n  fetchImpl?: typeof fetch;\n  /**\n   * Optional visibility filter — e.g. hide mutating tools, or tools whose\n   * required scope the caller lacks. Authorization is still enforced upstream;\n   * this only shapes what the agent is shown.\n   */\n  isVisible?: (tool: GeneratedTool, auth?: RequestAuth) => boolean;\n}\n\nfunction textResult(\n  value: unknown,\n  isError: boolean,\n  httpStatus?: number,\n): McpToolResult {\n  const text =\n    typeof value === \"string\" ? value : JSON.stringify(value, null, 2);\n  const result: McpToolResult = { content: [{ type: \"text\", text }], isError };\n  if (httpStatus !== undefined) {\n    result._meta = { [HTTP_STATUS_META_KEY]: httpStatus };\n  }\n  return result;\n}\n\nfunction successfulResult(tool: GeneratedTool, value: unknown): McpToolResult {\n  // Redact BEFORE rendering the text block: the agent reads `content` even when\n  // it ignores `structuredContent`, so stripping only the latter would still\n  // hand over the field.\n  const safe = redactResponseBody(value, tool.redactResponse);\n  const result = textResult(safe, false);\n  if (\n    tool.outputSchema &&\n    safe !== null &&\n    typeof safe === \"object\" &&\n    !Array.isArray(safe)\n  ) {\n    result.structuredContent = safe as Record<string, unknown>;\n  }\n  return result;\n}\n\nexport function createToolRegistry(options: RegistryOptions): ToolRegistry {\n  const byName = new Map(options.tools.map((tool) => [tool.name, tool]));\n\n  return {\n    listTools(auth) {\n      return options.tools\n        .filter((tool) =>\n          options.isVisible ? options.isVisible(tool, auth) : true,\n        )\n        .map((tool) => ({\n          name: tool.name,\n          description: tool.description,\n          inputSchema: tool.inputSchema,\n          ...(tool.outputSchema ? { outputSchema: tool.outputSchema } : {}),\n          annotations: tool.annotations,\n        }));\n    },\n\n    async callTool(name, args, auth) {\n      const tool = byName.get(name);\n      if (!tool) return textResult(`Unknown tool: ${name}`, true);\n\n      try {\n        const result = await dispatchTool(tool, args, {\n          baseUrl: options.baseUrl,\n          bearer: auth.bearer,\n          fetchImpl: options.fetchImpl,\n        });\n        // A non-2xx from the endpoint (e.g. 403 tenant-forbidden) is surfaced to\n        // the agent as an error result, NOT thrown — the permission decision was\n        // made upstream and its message is the useful signal. The status rides\n        // along in `_meta` so a caller can tell a correct refusal from a break.\n        return result.ok\n          ? successfulResult(tool, result.body)\n          : textResult(result.body, true, result.status);\n      } catch (error) {\n        const message = error instanceof Error ? error.message : String(error);\n        return textResult(`Tool dispatch failed: ${message}`, true);\n      }\n    },\n  };\n}\n","import type { RequestAuth } from \"../types\";\n\nimport type { ToolRegistry } from \"./registry\";\n\n/**\n * The MCP JSON-RPC 2.0 request half of the Streamable HTTP transport.\n *\n * Implemented directly rather than via the MCP SDK because the SDK's transport is\n * Node-`http` oriented, and a host serving Web `Request`/`Response` (a Next route\n * handler, a Hono route) has no `http.IncomingMessage` to hand it. It covers the\n * methods a client needs to discover and call tools: `initialize`, `tools/list`,\n * `tools/call`, plus `ping`.\n *\n * WHAT IS MECHANISM AND LIVES HERE: the envelope, the method table, the error\n * codes, the well-formedness rule, and the notification convention. None of it\n * varies per host — it is JSON-RPC 2.0 and the MCP specification.\n *\n * WHAT IS VOCABULARY AND STAYS WITH THE HOST: the server's NAME, its version, and\n * the `instructions` string an agent reads on connect. Those describe one\n * particular product's tool surface, so they arrive as {@link McpJsonRpcOptions}\n * rather than being written here.\n */\n\n/** The MCP protocol revision this transport implements. */\nexport const MCP_PROTOCOL_VERSION = \"2025-06-18\";\n\n/**\n * JSON-RPC error code for \"authentication required\", returned by `tools/call`\n * when the request carried no valid bearer. Outside the reserved -32768..-32000\n * band's *defined* codes on purpose: it is an implementation-defined server\n * error, and a host maps it to HTTP 401.\n */\nexport const UNAUTHORIZED_CODE = -32001;\n\n/** JSON-RPC \"Invalid Request\" — a payload that isn't a well-formed request object. */\nconst INVALID_REQUEST_CODE = -32600;\n\n/** JSON-RPC \"Method not found\". */\nconst METHOD_NOT_FOUND_CODE = -32601;\n\n/** JSON-RPC \"Invalid params\". */\nconst INVALID_PARAMS_CODE = -32602;\n\nexport interface JsonRpcRequest {\n  jsonrpc: \"2.0\";\n  id?: string | number | null;\n  method: string;\n  params?: unknown;\n}\n\nexport interface JsonRpcResponse {\n  jsonrpc: \"2.0\";\n  id: string | number | null;\n  result?: unknown;\n  error?: { code: number; message: string };\n}\n\n/** What a client is told it connected to, in `initialize`'s `serverInfo`. */\nexport interface McpServerInfo {\n  /** The server's name, as a connected host displays it. */\n  name: string;\n  /**\n   * The advertised surface version.\n   *\n   * This is the ONLY signal a client gets that the tool surface changed: the\n   * transport is request/response only, so `notifications/tools/list_changed`\n   * can never be sent, and a host that cached `tools/list` at the handshake has\n   * no other reason to ask again. See `server/surface-lock.ts` for the guard\n   * that makes forgetting to move it a build error instead of a comment.\n   */\n  version: string;\n}\n\nexport interface McpJsonRpcOptions {\n  /** The host's identity, returned verbatim in `initialize`. */\n  serverInfo: McpServerInfo;\n  /**\n   * Server-level guidance surfaced to the model on `initialize` (the MCP spec's\n   * optional `instructions` field). Omitted from the result when absent, rather\n   * than sent empty — a blank string is a claim that there is guidance.\n   */\n  instructions?: string;\n  /**\n   * Override the advertised protocol revision. Defaults to\n   * {@link MCP_PROTOCOL_VERSION}; a host should not normally set it.\n   */\n  protocolVersion?: string;\n}\n\nfunction ok(id: JsonRpcRequest[\"id\"], result: unknown): JsonRpcResponse {\n  return { jsonrpc: \"2.0\", id: id ?? null, result };\n}\n\nfunction fail(id: JsonRpcRequest[\"id\"], code: number, message: string): JsonRpcResponse {\n  return { jsonrpc: \"2.0\", id: id ?? null, error: { code, message } };\n}\n\n/** A parsed body is a usable request only if it's an object carrying a string `method`. */\nfunction isWellFormed(request: JsonRpcRequest): boolean {\n  return request != null && typeof request === \"object\" && typeof request.method === \"string\";\n}\n\nasync function handleToolsCall(\n  request: JsonRpcRequest,\n  registry: ToolRegistry,\n  auth: RequestAuth | null,\n): Promise<JsonRpcResponse> {\n  if (!auth) return fail(request.id, UNAUTHORIZED_CODE, \"Authentication required\");\n  const params = (request.params ?? {}) as { name?: string; arguments?: Record<string, unknown> };\n  if (!params.name) return fail(request.id, INVALID_PARAMS_CODE, \"Missing tool name\");\n  const result = await registry.callTool(params.name, params.arguments ?? {}, auth);\n  return ok(request.id, result);\n}\n\nfunction handleInitialize(\n  request: JsonRpcRequest,\n  options: McpJsonRpcOptions,\n): JsonRpcResponse {\n  return ok(request.id, {\n    protocolVersion: options.protocolVersion ?? MCP_PROTOCOL_VERSION,\n    // Deliberately does NOT claim `listChanged`: this transport has no\n    // server→client stream, so the notification could never be sent, and\n    // advertising it would stop a host from ever re-reading `tools/list`.\n    capabilities: { tools: {} },\n    serverInfo: options.serverInfo,\n    ...(options.instructions ? { instructions: options.instructions } : {}),\n  });\n}\n\n/**\n * Handle one MCP JSON-RPC request.\n *\n * Returns `null` for notifications (no id, no reply expected). `auth` is the\n * verified caller identity, or `null` when the request carried no valid bearer —\n * `tools/call` then returns {@link UNAUTHORIZED_CODE}, which the host surfaces as\n * HTTP 401. Discovery (`initialize`, `ping`, `tools/list`) stays open, so a client\n * can read the surface before it has a token.\n */\nexport async function handleMcpJsonRpc(\n  request: JsonRpcRequest,\n  registry: ToolRegistry,\n  auth: RequestAuth | null,\n  options: McpJsonRpcOptions,\n): Promise<JsonRpcResponse | null> {\n  // A host casts the parsed body to JsonRpcRequest without validating it, so a\n  // malformed payload can arrive here: a `null` body/batch element, a non-object,\n  // or an object with no `method`. Reject any of these as Invalid Request rather\n  // than dereferencing `request`/`request.method` and throwing a 500 below.\n  if (!isWellFormed(request)) {\n    return fail(request?.id ?? null, INVALID_REQUEST_CODE, \"Invalid Request\");\n  }\n  switch (request.method) {\n    case \"initialize\":\n      return handleInitialize(request, options);\n    case \"ping\":\n      return ok(request.id, {});\n    case \"tools/list\":\n      return ok(request.id, { tools: registry.listTools(auth ?? undefined) });\n    case \"tools/call\":\n      return handleToolsCall(request, registry, auth);\n    default:\n      // JSON-RPC notifications (`notifications/*`) expect no reply — silently\n      // ignore any we don't explicitly handle, rather than returning an error.\n      if (request.method.startsWith(\"notifications/\")) return null;\n      return fail(request.id, METHOD_NOT_FOUND_CODE, `Method not found: ${request.method}`);\n  }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/openapi/refs.ts","../src/openapi/annotations.ts","../src/dispatch/proxy.ts","../src/server/redact.ts","../src/server/registry.ts","../src/server/jsonrpc.ts"],"sourcesContent":["import type { JsonSchema } from \"../types\";\n\n/**\n * Raised when a JSON Schema cannot be turned into a flat, self-contained tool\n * input — an unresolvable `$ref`, an unsupported pointer, or a recursive schema.\n * The MCP tool surface is deliberately finite and flat (it is handed to an LLM\n * and committed to the drift manifest), so recursion is rejected rather than\n * silently truncated.\n */\nexport class UnsupportedSchemaError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"UnsupportedSchemaError\";\n  }\n}\n\n/** Local-definition containers a `$ref` may point into, in resolution order. */\nconst REF_PREFIXES = [\"#/$defs/\", \"#/definitions/\", \"#/components/schemas/\"] as const;\nconst DEF_CONTAINERS = [\"$defs\", \"definitions\"] as const;\n\n/** The definition name a supported local pointer targets, or `null` if unsupported. */\nfunction refName(ref: string): string | null {\n  const prefix = REF_PREFIXES.find((candidate) => ref.startsWith(candidate));\n  return prefix ? decodeURIComponent(ref.slice(prefix.length)) : null;\n}\n\n/** Collect the `$defs`/`definitions` maps hoisted onto a schema root into one lookup. */\nfunction collectDefs(root: JsonSchema): Record<string, JsonSchema> {\n  const defs: Record<string, JsonSchema> = {};\n  DEF_CONTAINERS.forEach((key) => {\n    const container = root[key];\n    if (container && typeof container === \"object\") {\n      Object.assign(defs, container as Record<string, JsonSchema>);\n    }\n  });\n  return defs;\n}\n\nfunction inlineRef(\n  ref: string,\n  defs: Record<string, JsonSchema>,\n  active: Set<string>,\n): unknown {\n  const name = refName(ref);\n  if (name === null) throw new UnsupportedSchemaError(`Unsupported $ref pointer: ${ref}`);\n  const target = defs[name];\n  if (!target) throw new UnsupportedSchemaError(`Unresolved $ref: ${ref}`);\n  if (active.has(name)) throw new UnsupportedSchemaError(`Recursive schema not supported: ${name}`);\n  active.add(name);\n  const resolved = walk(target, defs, active);\n  active.delete(name);\n  return resolved;\n}\n\n/** Deep-copy `node`, inlining every `$ref` and stripping definition containers. */\nfunction walk(node: unknown, defs: Record<string, JsonSchema>, active: Set<string>): unknown {\n  if (Array.isArray(node)) return node.map((item) => walk(item, defs, active));\n  if (!node || typeof node !== \"object\") return node;\n\n  const obj = node as Record<string, unknown>;\n  if (typeof obj.$ref === \"string\") return inlineRef(obj.$ref, defs, active);\n\n  const out: Record<string, unknown> = {};\n  Object.entries(obj).forEach(([key, value]) => {\n    if (!DEF_CONTAINERS.includes(key as (typeof DEF_CONTAINERS)[number])) {\n      out[key] = walk(value, defs, active);\n    }\n  });\n  return out;\n}\n\n/**\n * Inline every local `$ref` in a JSON Schema and drop the now-empty `$defs`/\n * `definitions` containers, yielding a flat, self-contained schema. Diamond reuse\n * (the same definition referenced by sibling branches) is fine; only a true cycle\n * — a definition that references itself up the resolution stack — is rejected.\n *\n * A schema with no `$ref`/definitions is returned structurally unchanged, so\n * inlining an already-flat spec is a no-op (the drift gate stays a stable diff).\n */\nexport function inlineSchemaRefs(schema: JsonSchema): JsonSchema {\n  const defs = collectDefs(schema);\n  return walk(schema, defs, new Set<string>()) as JsonSchema;\n}\n","/**\n * Composing a tool's behavior classification out of two sources.\n *\n * The rule the host's gate enforces is unchanged: every served tool ends with\n * a COMPLETE `ToolAnnotations` — a title and all three hints — and a tool that\n * ends unclassified fails `mcp:lint`. ChatGPT App review treats a missing hint\n * as a blocker, and the Anthropic connector directory derives auto-permissions\n * from `readOnlyHint`/`destructiveHint`, so there is no defensible default for\n * \"we did not say\".\n *\n * What this adds is where the answer may COME FROM. A package that declares\n * `getSupplierVersions` knows it reads and does not destroy; the host cannot\n * know that without reading the package's source, so it restated the\n * classification by hand — one line per tool, per collection, wrong the moment\n * the package changed a verb. Now the package can assert what it knows and the\n * host's table becomes what it should always have been: OVERRIDES, plus the\n * tools the host itself owns.\n *\n * ## Precedence, and why it runs this way\n *\n * The HOST wins every field it states. A package's claim is a default, not a\n * fact about the host's deployment: the same endpoint can be read-only in one\n * app and reach an external service in another (a host that proxies its\n * catalog reads through a vendor), and the host is the only party that knows.\n * Inverting this would make a package version bump silently re-classify a tool\n * an operator had already audited — the exact thing an audited classification\n * exists to prevent.\n *\n * ## What it refuses\n *\n * A field neither side supplies. `resolveToolAnnotations` throws naming the\n * tool and the missing fields, which keeps the completeness property a\n * REFUSAL rather than a lint pass over a table that quietly grew a gap. The\n * host's own gate can keep its message; this one fires first and says the same\n * thing in the same terms.\n */\n\nimport type { ToolAnnotations } from \"../types\";\nimport type { McpAnnotationDefaults } from \"./endpoint\";\n\n/** The host's half — whatever it chose to state, per tool. */\nexport type ToolAnnotationOverrides = Partial<ToolAnnotations>;\n\n/**\n * Merge a package's declared defaults under a host's overrides.\n *\n * @param name the tool id, for the refusal message\n * @param defaults what the package asserted (`McpEndpoint.annotations`)\n * @param overrides what the host's own table says; wins every field it states\n */\n/** A title only counts when it has something in it. */\nfunction titleOf(candidate: string | undefined): string | undefined {\n  return typeof candidate === \"string\" && candidate.trim() !== \"\" ? candidate : undefined;\n}\n\n/**\n * Merge a package's declared defaults under a host's overrides.\n *\n * The four fields are resolved into one record and checked generically rather\n * than branch by branch — which keeps the \"host wins, and `false` is an\n * answer\" rule stated exactly once per field instead of once per field per\n * check.\n *\n * `??` and not `||` throughout, and that is the trap the whole merge turns on:\n * `false` is a real classification — \"this tool does not destroy\" — and must\n * not fall through to the package's answer.\n *\n * @param name the tool id, for the refusal message\n * @param defaults what the package asserted (`McpEndpoint.annotations`)\n * @param overrides what the host's own table says; wins every field it states\n */\nexport function resolveToolAnnotations(\n  name: string,\n  defaults: McpAnnotationDefaults | undefined,\n  overrides: ToolAnnotationOverrides | undefined,\n): ToolAnnotations {\n  const host = overrides ?? {};\n  const declared = defaults ?? {};\n  const resolved: Partial<ToolAnnotations> = {\n    title: titleOf(host.title ?? declared.title),\n    readOnlyHint: host.readOnlyHint ?? declared.readOnly,\n    openWorldHint: host.openWorldHint ?? declared.openWorld,\n    destructiveHint: host.destructiveHint ?? declared.destructive,\n  };\n\n  const missing = REQUIRED_FIELDS.filter((field) => resolved[field] === undefined);\n  if (missing.length > 0) refuse(name, missing);\n  return resolved as ToolAnnotations;\n}\n\n/** Every field a served tool must end with — the completeness property itself. */\nconst REQUIRED_FIELDS = [\n  \"title\",\n  \"readOnlyHint\",\n  \"openWorldHint\",\n  \"destructiveHint\",\n] as const satisfies readonly (keyof ToolAnnotations)[];\n\nfunction refuse(name: string, missing: readonly string[]): never {\n  throw new Error(\n    `MCP tool \"${name}\" ends unclassified: neither the package nor the host supplied ` +\n      `${missing.join(\", \")}. Every served tool needs a complete classification — a missing ` +\n      `hint blocks ChatGPT App review, and the connector directory derives auto-permissions ` +\n      `from readOnlyHint/destructiveHint.`,\n  );\n}\n","import type { DispatchConfig, DispatchResult, GeneratedTool } from \"../types\";\n\n/** Raised when tool arguments cannot be routed onto the HTTP request. */\nexport class DispatchInputError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"DispatchInputError\";\n  }\n}\n\n/** Expand a path template (`/products/{id}`) using the path args, URL-encoding each. */\nfunction expandPath(\n  tool: GeneratedTool,\n  args: Record<string, unknown>,\n): string {\n  return tool.path.replace(/\\{([^}]+)\\}/g, (_match, key: string) => {\n    const value = args[key];\n    if (value === undefined || value === null) {\n      throw new DispatchInputError(`Missing required path parameter: ${key}`);\n    }\n    return encodeURIComponent(String(value));\n  });\n}\n\n/**\n * Route the non-path parameters (query + header) from the flat args. A missing\n * required parameter is a hard error; a missing optional one is simply omitted.\n */\nfunction routeParams(\n  tool: GeneratedTool,\n  args: Record<string, unknown>,\n): { query: URLSearchParams; headers: Record<string, string> } {\n  const query = new URLSearchParams();\n  const headers: Record<string, string> = {};\n\n  tool.parameters\n    .filter((param) => param.in !== \"path\")\n    .forEach((param) => {\n      const value = args[param.name];\n      if (value === undefined || value === null) {\n        if (param.required) {\n          throw new DispatchInputError(`Missing required ${param.in} parameter: ${param.name}`);\n        }\n        return;\n      }\n      if (param.in === \"query\") query.set(param.name, String(value));\n      else headers[param.name] = String(value);\n    });\n\n  return { query, headers };\n}\n\n/**\n * Reconstruct the request body from the flat args using the routing metadata.\n * Anything not claimed by a known body property is dropped — the input schema is\n * `additionalProperties: false`, so a validated call never carries extras and an\n * unvalidated one cannot smuggle fields upstream.\n */\nfunction routeBody(tool: GeneratedTool, args: Record<string, unknown>): unknown {\n  if (tool.bodyIsWhole) return args.body;\n  if (!tool.bodyProps.length) return undefined;\n  const payload: Record<string, unknown> = {};\n  tool.bodyProps.forEach((key) => {\n    if (args[key] !== undefined) payload[key] = args[key];\n  });\n  return Object.keys(payload).length ? payload : undefined;\n}\n\n/**\n * Execute one generated tool by proxying to its HTTP endpoint, forwarding the\n * caller's bearer verbatim. This function performs NO authorization — the\n * endpoint does, exactly as it would for a first-party request. That is the whole\n * point of the passthrough: the agent can do precisely what the user can.\n */\nexport async function dispatchTool(\n  tool: GeneratedTool,\n  args: Record<string, unknown>,\n  config: DispatchConfig,\n): Promise<DispatchResult> {\n  const doFetch = config.fetchImpl ?? fetch;\n  const pathname = expandPath(tool, args);\n  const { query, headers } = routeParams(tool, args);\n  const body = routeBody(tool, args);\n\n  const url = new URL(pathname, config.baseUrl);\n  for (const [key, value] of query) url.searchParams.set(key, value);\n\n  // Carry the proxy origin as the standard reverse-proxy forwarded headers. The\n  // wrapped endpoint's auth guard re-derives the request origin (to check the\n  // access token's `aud`) WITHOUT a request object, so it can only see the origin\n  // through these headers. `baseUrl` is exactly the origin the token was minted\n  // and transport-verified against, so forwarding its scheme+host makes the\n  // wrapped guard reconstruct the SAME origin — the `aud` survives the replay in\n  // both dev (http) and prod (any proxied https origin). Omitting them let the\n  // guard default the scheme to https and 401 a valid http-minted bearer.\n  const base = new URL(config.baseUrl);\n\n  const init: RequestInit = {\n    method: tool.method,\n    headers: {\n      accept: \"application/json\",\n      authorization: `Bearer ${config.bearer}`,\n      \"x-forwarded-proto\": base.protocol.replace(/:$/, \"\"),\n      \"x-forwarded-host\": base.host,\n      ...headers,\n    },\n  };\n  if (body !== undefined) {\n    (init.headers as Record<string, string>)[\"content-type\"] = \"application/json\";\n    init.body = JSON.stringify(body);\n  }\n\n  const response = await doFetch(url.toString(), init);\n  const text = await response.text();\n  let parsed: unknown = text;\n  const contentType = response.headers.get(\"content-type\") ?? \"\";\n  if (contentType.includes(\"application/json\") && text) {\n    try {\n      parsed = JSON.parse(text);\n    } catch {\n      parsed = text;\n    }\n  }\n\n  return { status: response.status, ok: response.ok, body: parsed };\n}\n","import type { JsonSchema } from \"../types\";\n\n/**\n * Both halves of the redaction contract: the SCHEMA a tool advertises, and the\n * BODY it returns.\n *\n * They only work as a pair, and the failure mode when they disagree is not a\n * cosmetic one. The dispatcher forwards the wrapped endpoint's response body\n * verbatim, so a narrowed `outputSchema` alone would only change what the\n * manifest CLAIMS is returned — the value still reaches the agent. Strip the\n * body but leave the schema advertising the field, and every successful call\n * fails validation against the very schema the manifest published, worst of all\n * when the field was `required`.\n *\n * So `redactResponseSchema` removes the paths at generate time and\n * `redactResponseBody` removes the same paths at dispatch, from one list. A host\n * that takes one and hand-rolls the other is back to the disagreement this pair\n * exists to prevent.\n */\n\n/** Structural keywords that wrap a value without naming a field. */\nconst SCHEMA_WRAPPERS = [\"items\", \"anyOf\", \"oneOf\", \"allOf\"] as const;\n\nfunction isSchema(value: unknown): value is JsonSchema {\n  return Boolean(value) && typeof value === \"object\";\n}\n\n/** Drop `field` from an object schema's properties AND its `required` list. */\nfunction deleteProperty(schema: JsonSchema, field: string): true {\n  delete (schema.properties as Record<string, JsonSchema>)[field];\n  if (Array.isArray(schema.required)) {\n    const kept = (schema.required as string[]).filter((name) => name !== field);\n    if (kept.length) schema.required = kept;\n    else delete schema.required;\n  }\n  return true;\n}\n\n/**\n * Descend into wrappers without consuming a segment, so `data.taxId` addresses\n * an array of rows and a `.nullable()` union branch alike.\n */\nfunction omitInWrappers(schema: JsonSchema, segments: readonly string[]): boolean {\n  return SCHEMA_WRAPPERS.reduce((removed, keyword) => {\n    const child = schema[keyword];\n    const branches = Array.isArray(child) ? child : [child];\n    return branches.reduce<boolean>(\n      (acc, branch) => (isSchema(branch) && omitSchemaPath(branch, segments)) || acc,\n      removed,\n    );\n  }, false);\n}\n\nfunction omitSchemaPath(schema: JsonSchema, segments: readonly string[]): boolean {\n  const inWrappers = omitInWrappers(schema, segments);\n\n  const properties = schema.properties as Record<string, JsonSchema> | undefined;\n  const [head, ...rest] = segments;\n  if (!properties || !head || !(head in properties)) return inWrappers;\n\n  if (rest.length === 0) return deleteProperty(schema, head);\n\n  const child = properties[head];\n  return (isSchema(child) && omitSchemaPath(child, rest)) || inWrappers;\n}\n\n/**\n * Return `schema` without the listed dotted paths — the advertised half.\n *\n * THROWS when a path names nothing, rather than returning quietly: a typo'd or\n * stale redaction would otherwise protect nothing at all, and it would do so\n * invisibly, which is the one outcome a redaction list must never have. Failing\n * here turns it into a generator error naming the offending path.\n *\n * The input is cloned, not narrowed in place: a caller may hold the converted\n * schema for other uses (a shared `$defs` component, a schema reused across two\n * operations), and mutating it would redact those too.\n *\n * `operationId` only shapes the error message — pass it so the failure names\n * which tool declared the bad path.\n */\nexport function redactResponseSchema(\n  schema: JsonSchema,\n  paths: readonly string[],\n  operationId?: string,\n): JsonSchema {\n  if (!paths.length) return schema;\n\n  const clone = structuredClone(schema);\n  paths.forEach((path) => {\n    if (!omitSchemaPath(clone, path.split(\".\"))) {\n      const subject = operationId ? `MCP endpoint \"${operationId}\"` : \"This response schema\";\n      throw new Error(\n        `${subject} declares a response redaction for \"${path}\", which is not a field of its response schema`,\n      );\n    }\n  });\n  return clone;\n}\n\n/** Walk one dotted path, mapping over arrays, and delete the leaf. */\nfunction stripPath(value: unknown, segments: readonly string[]): void {\n  if (value === null || typeof value !== \"object\") return;\n\n  if (Array.isArray(value)) {\n    value.forEach((entry) => stripPath(entry, segments));\n    return;\n  }\n\n  const [head, ...rest] = segments;\n  if (!head) return;\n\n  const record = value as Record<string, unknown>;\n  if (rest.length === 0) {\n    delete record[head];\n    return;\n  }\n  if (head in record) stripPath(record[head], rest);\n}\n\n/**\n * Return `body` without the listed dotted paths.\n *\n * The input is deep-cloned first: dispatch results are handed straight to the\n * JSON-RPC encoder AND reused as `structuredContent`, so mutating in place\n * could leak a half-redacted object into one of the two surfaces.\n */\nexport function redactResponseBody(\n  body: unknown,\n  paths: readonly string[] | undefined,\n): unknown {\n  if (!paths?.length || body === null || typeof body !== \"object\") return body;\n\n  const clone = structuredClone(body);\n  paths.forEach((path) => stripPath(clone, path.split(\".\")));\n  return clone;\n}\n","import { dispatchTool } from \"../dispatch/proxy\";\nimport type {\n  GeneratedTool,\n  JsonSchema,\n  RequestAuth,\n  ToolAnnotations,\n} from \"../types\";\nimport { redactResponseBody } from \"./redact\";\n\n/**\n * The registry is the transport-agnostic seam between the generated tools and the\n * MCP SDK. The consuming app owns the HTTP/JSON-RPC transport (mounting it at\n * `/api/mcp`) and, per request, resolves {@link RequestAuth} and calls\n * {@link ToolRegistry.listTools} / {@link ToolRegistry.callTool}. Keeping the\n * SDK out of this package means the core stays testable and portable.\n */\n\n/** An MCP tool descriptor as advertised to clients (subset of the MCP schema). */\nexport interface McpToolDescriptor {\n  name: string;\n  description: string;\n  inputSchema: JsonSchema;\n  outputSchema?: JsonSchema;\n  annotations: ToolAnnotations;\n}\n\n/**\n * `_meta` key carrying the upstream HTTP status of a dispatched call.\n *\n * `isError` is one bit, and it collapses answers that mean opposite things: a\n * 404 for a record that does not exist, a 403 a guard correctly refused, a\n * domain refusal (\"this store does not use comandas\"), and a 500 where the route\n * threw all arrive identical. Callers that need to tell \"correctly refused\" from\n * \"actually broken\" — `mcp:smoke` above all — cannot, because the status is\n * known at dispatch and then dropped. Publishing it under a namespaced `_meta`\n * key (permitted by the MCP result schema) keeps `isError` as the agent-facing\n * signal while making the distinction recoverable.\n */\nexport const HTTP_STATUS_META_KEY = \"dispatch/httpStatus\";\n\n/** An MCP tool-call result (subset of the MCP schema). */\nexport interface McpToolResult {\n  content: Array<{ type: \"text\"; text: string }>;\n  isError: boolean;\n  /** Machine-readable output matching the advertised outputSchema. */\n  structuredContent?: Record<string, unknown>;\n  /** Out-of-band metadata; carries {@link HTTP_STATUS_META_KEY} when dispatched. */\n  _meta?: Record<string, unknown>;\n}\n\nexport interface ToolRegistry {\n  listTools(auth?: RequestAuth): McpToolDescriptor[];\n  callTool(\n    name: string,\n    args: Record<string, unknown>,\n    auth: RequestAuth,\n  ): Promise<McpToolResult>;\n}\n\nexport interface RegistryOptions {\n  tools: GeneratedTool[];\n  /** Origin the tools proxy to (usually the app's own public URL). */\n  baseUrl: string;\n  fetchImpl?: typeof fetch;\n  /**\n   * Optional visibility filter — e.g. hide mutating tools, or tools whose\n   * required scope the caller lacks. Authorization is still enforced upstream;\n   * this only shapes what the agent is shown.\n   */\n  isVisible?: (tool: GeneratedTool, auth?: RequestAuth) => boolean;\n}\n\nfunction textResult(\n  value: unknown,\n  isError: boolean,\n  httpStatus?: number,\n): McpToolResult {\n  const text =\n    typeof value === \"string\" ? value : JSON.stringify(value, null, 2);\n  const result: McpToolResult = { content: [{ type: \"text\", text }], isError };\n  if (httpStatus !== undefined) {\n    result._meta = { [HTTP_STATUS_META_KEY]: httpStatus };\n  }\n  return result;\n}\n\nfunction successfulResult(tool: GeneratedTool, value: unknown): McpToolResult {\n  // Redact BEFORE rendering the text block: the agent reads `content` even when\n  // it ignores `structuredContent`, so stripping only the latter would still\n  // hand over the field.\n  const safe = redactResponseBody(value, tool.redactResponse);\n  const result = textResult(safe, false);\n  if (\n    tool.outputSchema &&\n    safe !== null &&\n    typeof safe === \"object\" &&\n    !Array.isArray(safe)\n  ) {\n    result.structuredContent = safe as Record<string, unknown>;\n  }\n  return result;\n}\n\nexport function createToolRegistry(options: RegistryOptions): ToolRegistry {\n  const byName = new Map(options.tools.map((tool) => [tool.name, tool]));\n\n  return {\n    listTools(auth) {\n      return options.tools\n        .filter((tool) =>\n          options.isVisible ? options.isVisible(tool, auth) : true,\n        )\n        .map((tool) => ({\n          name: tool.name,\n          description: tool.description,\n          inputSchema: tool.inputSchema,\n          ...(tool.outputSchema ? { outputSchema: tool.outputSchema } : {}),\n          annotations: tool.annotations,\n        }));\n    },\n\n    async callTool(name, args, auth) {\n      const tool = byName.get(name);\n      if (!tool) return textResult(`Unknown tool: ${name}`, true);\n\n      try {\n        const result = await dispatchTool(tool, args, {\n          baseUrl: options.baseUrl,\n          bearer: auth.bearer,\n          fetchImpl: options.fetchImpl,\n        });\n        // A non-2xx from the endpoint (e.g. 403 tenant-forbidden) is surfaced to\n        // the agent as an error result, NOT thrown — the permission decision was\n        // made upstream and its message is the useful signal. The status rides\n        // along in `_meta` so a caller can tell a correct refusal from a break.\n        return result.ok\n          ? successfulResult(tool, result.body)\n          : textResult(result.body, true, result.status);\n      } catch (error) {\n        const message = error instanceof Error ? error.message : String(error);\n        return textResult(`Tool dispatch failed: ${message}`, true);\n      }\n    },\n  };\n}\n","import type { RequestAuth } from \"../types\";\n\nimport type { ToolRegistry } from \"./registry\";\n\n/**\n * The MCP JSON-RPC 2.0 request half of the Streamable HTTP transport.\n *\n * Implemented directly rather than via the MCP SDK because the SDK's transport is\n * Node-`http` oriented, and a host serving Web `Request`/`Response` (a Next route\n * handler, a Hono route) has no `http.IncomingMessage` to hand it. It covers the\n * methods a client needs to discover and call tools: `initialize`, `tools/list`,\n * `tools/call`, plus `ping`.\n *\n * WHAT IS MECHANISM AND LIVES HERE: the envelope, the method table, the error\n * codes, the well-formedness rule, and the notification convention. None of it\n * varies per host — it is JSON-RPC 2.0 and the MCP specification.\n *\n * WHAT IS VOCABULARY AND STAYS WITH THE HOST: the server's NAME, its version, and\n * the `instructions` string an agent reads on connect. Those describe one\n * particular product's tool surface, so they arrive as {@link McpJsonRpcOptions}\n * rather than being written here.\n */\n\n/** The MCP protocol revision this transport implements. */\nexport const MCP_PROTOCOL_VERSION = \"2025-06-18\";\n\n/**\n * JSON-RPC error code for \"authentication required\", returned by `tools/call`\n * when the request carried no valid bearer. Outside the reserved -32768..-32000\n * band's *defined* codes on purpose: it is an implementation-defined server\n * error, and a host maps it to HTTP 401.\n */\nexport const UNAUTHORIZED_CODE = -32001;\n\n/** JSON-RPC \"Invalid Request\" — a payload that isn't a well-formed request object. */\nconst INVALID_REQUEST_CODE = -32600;\n\n/** JSON-RPC \"Method not found\". */\nconst METHOD_NOT_FOUND_CODE = -32601;\n\n/** JSON-RPC \"Invalid params\". */\nconst INVALID_PARAMS_CODE = -32602;\n\nexport interface JsonRpcRequest {\n  jsonrpc: \"2.0\";\n  id?: string | number | null;\n  method: string;\n  params?: unknown;\n}\n\nexport interface JsonRpcResponse {\n  jsonrpc: \"2.0\";\n  id: string | number | null;\n  result?: unknown;\n  error?: { code: number; message: string };\n}\n\n/** What a client is told it connected to, in `initialize`'s `serverInfo`. */\nexport interface McpServerInfo {\n  /** The server's name, as a connected host displays it. */\n  name: string;\n  /**\n   * The advertised surface version.\n   *\n   * This is the ONLY signal a client gets that the tool surface changed: the\n   * transport is request/response only, so `notifications/tools/list_changed`\n   * can never be sent, and a host that cached `tools/list` at the handshake has\n   * no other reason to ask again. See `server/surface-lock.ts` for the guard\n   * that makes forgetting to move it a build error instead of a comment.\n   */\n  version: string;\n}\n\nexport interface McpJsonRpcOptions {\n  /** The host's identity, returned verbatim in `initialize`. */\n  serverInfo: McpServerInfo;\n  /**\n   * Server-level guidance surfaced to the model on `initialize` (the MCP spec's\n   * optional `instructions` field). Omitted from the result when absent, rather\n   * than sent empty — a blank string is a claim that there is guidance.\n   */\n  instructions?: string;\n  /**\n   * Override the advertised protocol revision. Defaults to\n   * {@link MCP_PROTOCOL_VERSION}; a host should not normally set it.\n   */\n  protocolVersion?: string;\n}\n\nfunction ok(id: JsonRpcRequest[\"id\"], result: unknown): JsonRpcResponse {\n  return { jsonrpc: \"2.0\", id: id ?? null, result };\n}\n\nfunction fail(id: JsonRpcRequest[\"id\"], code: number, message: string): JsonRpcResponse {\n  return { jsonrpc: \"2.0\", id: id ?? null, error: { code, message } };\n}\n\n/** A parsed body is a usable request only if it's an object carrying a string `method`. */\nfunction isWellFormed(request: JsonRpcRequest): boolean {\n  return request != null && typeof request === \"object\" && typeof request.method === \"string\";\n}\n\nasync function handleToolsCall(\n  request: JsonRpcRequest,\n  registry: ToolRegistry,\n  auth: RequestAuth | null,\n): Promise<JsonRpcResponse> {\n  if (!auth) return fail(request.id, UNAUTHORIZED_CODE, \"Authentication required\");\n  const params = (request.params ?? {}) as { name?: string; arguments?: Record<string, unknown> };\n  if (!params.name) return fail(request.id, INVALID_PARAMS_CODE, \"Missing tool name\");\n  const result = await registry.callTool(params.name, params.arguments ?? {}, auth);\n  return ok(request.id, result);\n}\n\nfunction handleInitialize(\n  request: JsonRpcRequest,\n  options: McpJsonRpcOptions,\n): JsonRpcResponse {\n  return ok(request.id, {\n    protocolVersion: options.protocolVersion ?? MCP_PROTOCOL_VERSION,\n    // Deliberately does NOT claim `listChanged`: this transport has no\n    // server→client stream, so the notification could never be sent, and\n    // advertising it would stop a host from ever re-reading `tools/list`.\n    capabilities: { tools: {} },\n    serverInfo: options.serverInfo,\n    ...(options.instructions ? { instructions: options.instructions } : {}),\n  });\n}\n\n/**\n * Handle one MCP JSON-RPC request.\n *\n * Returns `null` for notifications (no id, no reply expected). `auth` is the\n * verified caller identity, or `null` when the request carried no valid bearer —\n * `tools/call` then returns {@link UNAUTHORIZED_CODE}, which the host surfaces as\n * HTTP 401. Discovery (`initialize`, `ping`, `tools/list`) stays open, so a client\n * can read the surface before it has a token.\n */\nexport async function handleMcpJsonRpc(\n  request: JsonRpcRequest,\n  registry: ToolRegistry,\n  auth: RequestAuth | null,\n  options: McpJsonRpcOptions,\n): Promise<JsonRpcResponse | null> {\n  // A host casts the parsed body to JsonRpcRequest without validating it, so a\n  // malformed payload can arrive here: a `null` body/batch element, a non-object,\n  // or an object with no `method`. Reject any of these as Invalid Request rather\n  // than dereferencing `request`/`request.method` and throwing a 500 below.\n  if (!isWellFormed(request)) {\n    return fail(request?.id ?? null, INVALID_REQUEST_CODE, \"Invalid Request\");\n  }\n  switch (request.method) {\n    case \"initialize\":\n      return handleInitialize(request, options);\n    case \"ping\":\n      return ok(request.id, {});\n    case \"tools/list\":\n      return ok(request.id, { tools: registry.listTools(auth ?? undefined) });\n    case \"tools/call\":\n      return handleToolsCall(request, registry, auth);\n    default:\n      // JSON-RPC notifications (`notifications/*`) expect no reply — silently\n      // ignore any we don't explicitly handle, rather than returning an error.\n      if (request.method.startsWith(\"notifications/\")) return null;\n      return fail(request.id, METHOD_NOT_FOUND_CODE, `Method not found: ${request.method}`);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AASO,IAAM,yBAAN,cAAqC,MAAM;AAAA,EATlD,OASkD;AAAA;AAAA;AAAA,EAChD,YAAY,SAAiB;AAC3B,UAAM,OAAO;AACb,SAAK,OAAO;AAAA,EACd;AACF;AAGA,IAAM,eAAe,CAAC,YAAY,kBAAkB,uBAAuB;AAC3E,IAAM,iBAAiB,CAAC,SAAS,aAAa;AAG9C,SAAS,QAAQ,KAA4B;AAC3C,QAAM,SAAS,aAAa,KAAK,CAAC,cAAc,IAAI,WAAW,SAAS,CAAC;AACzE,SAAO,SAAS,mBAAmB,IAAI,MAAM,OAAO,MAAM,CAAC,IAAI;AACjE;AAHS;AAMT,SAAS,YAAY,MAA8C;AACjE,QAAM,OAAmC,CAAC;AAC1C,iBAAe,QAAQ,CAAC,QAAQ;AAC9B,UAAM,YAAY,KAAK,GAAG;AAC1B,QAAI,aAAa,OAAO,cAAc,UAAU;AAC9C,aAAO,OAAO,MAAM,SAAuC;AAAA,IAC7D;AAAA,EACF,CAAC;AACD,SAAO;AACT;AATS;AAWT,SAAS,UACP,KACA,MACA,QACS;AACT,QAAM,OAAO,QAAQ,GAAG;AACxB,MAAI,SAAS,KAAM,OAAM,IAAI,uBAAuB,6BAA6B,GAAG,EAAE;AACtF,QAAM,SAAS,KAAK,IAAI;AACxB,MAAI,CAAC,OAAQ,OAAM,IAAI,uBAAuB,oBAAoB,GAAG,EAAE;AACvE,MAAI,OAAO,IAAI,IAAI,EAAG,OAAM,IAAI,uBAAuB,mCAAmC,IAAI,EAAE;AAChG,SAAO,IAAI,IAAI;AACf,QAAM,WAAW,KAAK,QAAQ,MAAM,MAAM;AAC1C,SAAO,OAAO,IAAI;AAClB,SAAO;AACT;AAdS;AAiBT,SAAS,KAAK,MAAe,MAAkC,QAA8B;AAC3F,MAAI,MAAM,QAAQ,IAAI,EAAG,QAAO,KAAK,IAAI,CAAC,SAAS,KAAK,MAAM,MAAM,MAAM,CAAC;AAC3E,MAAI,CAAC,QAAQ,OAAO,SAAS,SAAU,QAAO;AAE9C,QAAM,MAAM;AACZ,MAAI,OAAO,IAAI,SAAS,SAAU,QAAO,UAAU,IAAI,MAAM,MAAM,MAAM;AAEzE,QAAM,MAA+B,CAAC;AACtC,SAAO,QAAQ,GAAG,EAAE,QAAQ,CAAC,CAAC,KAAK,KAAK,MAAM;AAC5C,QAAI,CAAC,eAAe,SAAS,GAAsC,GAAG;AACpE,UAAI,GAAG,IAAI,KAAK,OAAO,MAAM,MAAM;AAAA,IACrC;AAAA,EACF,CAAC;AACD,SAAO;AACT;AAdS;AAyBF,SAAS,iBAAiB,QAAgC;AAC/D,QAAM,OAAO,YAAY,MAAM;AAC/B,SAAO,KAAK,QAAQ,MAAM,oBAAI,IAAY,CAAC;AAC7C;AAHgB;;;AC7BhB,SAAS,QAAQ,WAAmD;AAClE,SAAO,OAAO,cAAc,YAAY,UAAU,KAAK,MAAM,KAAK,YAAY;AAChF;AAFS;AAoBF,SAAS,uBACd,MACA,UACA,WACiB;AACjB,QAAM,OAAO,aAAa,CAAC;AAC3B,QAAM,WAAW,YAAY,CAAC;AAC9B,QAAM,WAAqC;AAAA,IACzC,OAAO,QAAQ,KAAK,SAAS,SAAS,KAAK;AAAA,IAC3C,cAAc,KAAK,gBAAgB,SAAS;AAAA,IAC5C,eAAe,KAAK,iBAAiB,SAAS;AAAA,IAC9C,iBAAiB,KAAK,mBAAmB,SAAS;AAAA,EACpD;AAEA,QAAM,UAAU,gBAAgB,OAAO,CAAC,UAAU,SAAS,KAAK,MAAM,MAAS;AAC/E,MAAI,QAAQ,SAAS,EAAG,QAAO,MAAM,OAAO;AAC5C,SAAO;AACT;AAjBgB;AAoBhB,IAAM,kBAAkB;AAAA,EACtB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAEA,SAAS,OAAO,MAAc,SAAmC;AAC/D,QAAM,IAAI;AAAA,IACR,aAAa,IAAI,kEACZ,QAAQ,KAAK,IAAI,CAAC;AAAA,EAGzB;AACF;AAPS;;;AC/FF,IAAM,qBAAN,cAAiC,MAAM;AAAA,EAH9C,OAG8C;AAAA;AAAA;AAAA,EAC5C,YAAY,SAAiB;AAC3B,UAAM,OAAO;AACb,SAAK,OAAO;AAAA,EACd;AACF;AAGA,SAAS,WACP,MACA,MACQ;AACR,SAAO,KAAK,KAAK,QAAQ,gBAAgB,CAAC,QAAQ,QAAgB;AAChE,UAAM,QAAQ,KAAK,GAAG;AACtB,QAAI,UAAU,UAAa,UAAU,MAAM;AACzC,YAAM,IAAI,mBAAmB,oCAAoC,GAAG,EAAE;AAAA,IACxE;AACA,WAAO,mBAAmB,OAAO,KAAK,CAAC;AAAA,EACzC,CAAC;AACH;AAXS;AAiBT,SAAS,YACP,MACA,MAC6D;AAC7D,QAAM,QAAQ,IAAI,gBAAgB;AAClC,QAAM,UAAkC,CAAC;AAEzC,OAAK,WACF,OAAO,CAAC,UAAU,MAAM,OAAO,MAAM,EACrC,QAAQ,CAAC,UAAU;AAClB,UAAM,QAAQ,KAAK,MAAM,IAAI;AAC7B,QAAI,UAAU,UAAa,UAAU,MAAM;AACzC,UAAI,MAAM,UAAU;AAClB,cAAM,IAAI,mBAAmB,oBAAoB,MAAM,EAAE,eAAe,MAAM,IAAI,EAAE;AAAA,MACtF;AACA;AAAA,IACF;AACA,QAAI,MAAM,OAAO,QAAS,OAAM,IAAI,MAAM,MAAM,OAAO,KAAK,CAAC;AAAA,QACxD,SAAQ,MAAM,IAAI,IAAI,OAAO,KAAK;AAAA,EACzC,CAAC;AAEH,SAAO,EAAE,OAAO,QAAQ;AAC1B;AAtBS;AA8BT,SAAS,UAAU,MAAqB,MAAwC;AAC9E,MAAI,KAAK,YAAa,QAAO,KAAK;AAClC,MAAI,CAAC,KAAK,UAAU,OAAQ,QAAO;AACnC,QAAM,UAAmC,CAAC;AAC1C,OAAK,UAAU,QAAQ,CAAC,QAAQ;AAC9B,QAAI,KAAK,GAAG,MAAM,OAAW,SAAQ,GAAG,IAAI,KAAK,GAAG;AAAA,EACtD,CAAC;AACD,SAAO,OAAO,KAAK,OAAO,EAAE,SAAS,UAAU;AACjD;AARS;AAgBT,eAAsB,aACpB,MACA,MACA,QACyB;AACzB,QAAM,UAAU,OAAO,aAAa;AACpC,QAAM,WAAW,WAAW,MAAM,IAAI;AACtC,QAAM,EAAE,OAAO,QAAQ,IAAI,YAAY,MAAM,IAAI;AACjD,QAAM,OAAO,UAAU,MAAM,IAAI;AAEjC,QAAM,MAAM,IAAI,IAAI,UAAU,OAAO,OAAO;AAC5C,aAAW,CAAC,KAAK,KAAK,KAAK,MAAO,KAAI,aAAa,IAAI,KAAK,KAAK;AAUjE,QAAM,OAAO,IAAI,IAAI,OAAO,OAAO;AAEnC,QAAM,OAAoB;AAAA,IACxB,QAAQ,KAAK;AAAA,IACb,SAAS;AAAA,MACP,QAAQ;AAAA,MACR,eAAe,UAAU,OAAO,MAAM;AAAA,MACtC,qBAAqB,KAAK,SAAS,QAAQ,MAAM,EAAE;AAAA,MACnD,oBAAoB,KAAK;AAAA,MACzB,GAAG;AAAA,IACL;AAAA,EACF;AACA,MAAI,SAAS,QAAW;AACtB,IAAC,KAAK,QAAmC,cAAc,IAAI;AAC3D,SAAK,OAAO,KAAK,UAAU,IAAI;AAAA,EACjC;AAEA,QAAM,WAAW,MAAM,QAAQ,IAAI,SAAS,GAAG,IAAI;AACnD,QAAM,OAAO,MAAM,SAAS,KAAK;AACjC,MAAI,SAAkB;AACtB,QAAM,cAAc,SAAS,QAAQ,IAAI,cAAc,KAAK;AAC5D,MAAI,YAAY,SAAS,kBAAkB,KAAK,MAAM;AACpD,QAAI;AACF,eAAS,KAAK,MAAM,IAAI;AAAA,IAC1B,QAAQ;AACN,eAAS;AAAA,IACX;AAAA,EACF;AAEA,SAAO,EAAE,QAAQ,SAAS,QAAQ,IAAI,SAAS,IAAI,MAAM,OAAO;AAClE;AAnDsB;;;ACrDtB,IAAM,kBAAkB,CAAC,SAAS,SAAS,SAAS,OAAO;AAE3D,SAAS,SAAS,OAAqC;AACrD,SAAO,QAAQ,KAAK,KAAK,OAAO,UAAU;AAC5C;AAFS;AAKT,SAAS,eAAe,QAAoB,OAAqB;AAC/D,SAAQ,OAAO,WAA0C,KAAK;AAC9D,MAAI,MAAM,QAAQ,OAAO,QAAQ,GAAG;AAClC,UAAM,OAAQ,OAAO,SAAsB,OAAO,CAAC,SAAS,SAAS,KAAK;AAC1E,QAAI,KAAK,OAAQ,QAAO,WAAW;AAAA,QAC9B,QAAO,OAAO;AAAA,EACrB;AACA,SAAO;AACT;AARS;AAcT,SAAS,eAAe,QAAoB,UAAsC;AAChF,SAAO,gBAAgB,OAAO,CAAC,SAAS,YAAY;AAClD,UAAM,QAAQ,OAAO,OAAO;AAC5B,UAAM,WAAW,MAAM,QAAQ,KAAK,IAAI,QAAQ,CAAC,KAAK;AACtD,WAAO,SAAS;AAAA,MACd,CAAC,KAAK,WAAY,SAAS,MAAM,KAAK,eAAe,QAAQ,QAAQ,KAAM;AAAA,MAC3E;AAAA,IACF;AAAA,EACF,GAAG,KAAK;AACV;AATS;AAWT,SAAS,eAAe,QAAoB,UAAsC;AAChF,QAAM,aAAa,eAAe,QAAQ,QAAQ;AAElD,QAAM,aAAa,OAAO;AAC1B,QAAM,CAAC,MAAM,GAAG,IAAI,IAAI;AACxB,MAAI,CAAC,cAAc,CAAC,QAAQ,EAAE,QAAQ,YAAa,QAAO;AAE1D,MAAI,KAAK,WAAW,EAAG,QAAO,eAAe,QAAQ,IAAI;AAEzD,QAAM,QAAQ,WAAW,IAAI;AAC7B,SAAQ,SAAS,KAAK,KAAK,eAAe,OAAO,IAAI,KAAM;AAC7D;AAXS;AA4BF,SAAS,qBACd,QACA,OACA,aACY;AACZ,MAAI,CAAC,MAAM,OAAQ,QAAO;AAE1B,QAAM,QAAQ,gBAAgB,MAAM;AACpC,QAAM,QAAQ,CAAC,SAAS;AACtB,QAAI,CAAC,eAAe,OAAO,KAAK,MAAM,GAAG,CAAC,GAAG;AAC3C,YAAM,UAAU,cAAc,iBAAiB,WAAW,MAAM;AAChE,YAAM,IAAI;AAAA,QACR,GAAG,OAAO,uCAAuC,IAAI;AAAA,MACvD;AAAA,IACF;AAAA,EACF,CAAC;AACD,SAAO;AACT;AAjBgB;AAoBhB,SAAS,UAAU,OAAgB,UAAmC;AACpE,MAAI,UAAU,QAAQ,OAAO,UAAU,SAAU;AAEjD,MAAI,MAAM,QAAQ,KAAK,GAAG;AACxB,UAAM,QAAQ,CAAC,UAAU,UAAU,OAAO,QAAQ,CAAC;AACnD;AAAA,EACF;AAEA,QAAM,CAAC,MAAM,GAAG,IAAI,IAAI;AACxB,MAAI,CAAC,KAAM;AAEX,QAAM,SAAS;AACf,MAAI,KAAK,WAAW,GAAG;AACrB,WAAO,OAAO,IAAI;AAClB;AAAA,EACF;AACA,MAAI,QAAQ,OAAQ,WAAU,OAAO,IAAI,GAAG,IAAI;AAClD;AAjBS;AA0BF,SAAS,mBACd,MACA,OACS;AACT,MAAI,CAAC,OAAO,UAAU,SAAS,QAAQ,OAAO,SAAS,SAAU,QAAO;AAExE,QAAM,QAAQ,gBAAgB,IAAI;AAClC,QAAM,QAAQ,CAAC,SAAS,UAAU,OAAO,KAAK,MAAM,GAAG,CAAC,CAAC;AACzD,SAAO;AACT;AATgB;;;ACzFT,IAAM,uBAAuB;AAkCpC,SAAS,WACP,OACA,SACA,YACe;AACf,QAAM,OACJ,OAAO,UAAU,WAAW,QAAQ,KAAK,UAAU,OAAO,MAAM,CAAC;AACnE,QAAM,SAAwB,EAAE,SAAS,CAAC,EAAE,MAAM,QAAQ,KAAK,CAAC,GAAG,QAAQ;AAC3E,MAAI,eAAe,QAAW;AAC5B,WAAO,QAAQ,EAAE,CAAC,oBAAoB,GAAG,WAAW;AAAA,EACtD;AACA,SAAO;AACT;AAZS;AAcT,SAAS,iBAAiB,MAAqB,OAA+B;AAI5E,QAAM,OAAO,mBAAmB,OAAO,KAAK,cAAc;AAC1D,QAAM,SAAS,WAAW,MAAM,KAAK;AACrC,MACE,KAAK,gBACL,SAAS,QACT,OAAO,SAAS,YAChB,CAAC,MAAM,QAAQ,IAAI,GACnB;AACA,WAAO,oBAAoB;AAAA,EAC7B;AACA,SAAO;AACT;AAfS;AAiBF,SAAS,mBAAmB,SAAwC;AACzE,QAAM,SAAS,IAAI,IAAI,QAAQ,MAAM,IAAI,CAAC,SAAS,CAAC,KAAK,MAAM,IAAI,CAAC,CAAC;AAErE,SAAO;AAAA,IACL,UAAU,MAAM;AACd,aAAO,QAAQ,MACZ;AAAA,QAAO,CAAC,SACP,QAAQ,YAAY,QAAQ,UAAU,MAAM,IAAI,IAAI;AAAA,MACtD,EACC,IAAI,CAAC,UAAU;AAAA,QACd,MAAM,KAAK;AAAA,QACX,aAAa,KAAK;AAAA,QAClB,aAAa,KAAK;AAAA,QAClB,GAAI,KAAK,eAAe,EAAE,cAAc,KAAK,aAAa,IAAI,CAAC;AAAA,QAC/D,aAAa,KAAK;AAAA,MACpB,EAAE;AAAA,IACN;AAAA,IAEA,MAAM,SAAS,MAAM,MAAM,MAAM;AAC/B,YAAM,OAAO,OAAO,IAAI,IAAI;AAC5B,UAAI,CAAC,KAAM,QAAO,WAAW,iBAAiB,IAAI,IAAI,IAAI;AAE1D,UAAI;AACF,cAAM,SAAS,MAAM,aAAa,MAAM,MAAM;AAAA,UAC5C,SAAS,QAAQ;AAAA,UACjB,QAAQ,KAAK;AAAA,UACb,WAAW,QAAQ;AAAA,QACrB,CAAC;AAKD,eAAO,OAAO,KACV,iBAAiB,MAAM,OAAO,IAAI,IAClC,WAAW,OAAO,MAAM,MAAM,OAAO,MAAM;AAAA,MACjD,SAAS,OAAO;AACd,cAAM,UAAU,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AACrE,eAAO,WAAW,yBAAyB,OAAO,IAAI,IAAI;AAAA,MAC5D;AAAA,IACF;AAAA,EACF;AACF;AAzCgB;;;AC/ET,IAAM,uBAAuB;AAQ7B,IAAM,oBAAoB;AAGjC,IAAM,uBAAuB;AAG7B,IAAM,wBAAwB;AAG9B,IAAM,sBAAsB;AAgD5B,SAAS,GAAG,IAA0B,QAAkC;AACtE,SAAO,EAAE,SAAS,OAAO,IAAI,MAAM,MAAM,OAAO;AAClD;AAFS;AAIT,SAAS,KAAK,IAA0B,MAAc,SAAkC;AACtF,SAAO,EAAE,SAAS,OAAO,IAAI,MAAM,MAAM,OAAO,EAAE,MAAM,QAAQ,EAAE;AACpE;AAFS;AAKT,SAAS,aAAa,SAAkC;AACtD,SAAO,WAAW,QAAQ,OAAO,YAAY,YAAY,OAAO,QAAQ,WAAW;AACrF;AAFS;AAIT,eAAe,gBACb,SACA,UACA,MAC0B;AAC1B,MAAI,CAAC,KAAM,QAAO,KAAK,QAAQ,IAAI,mBAAmB,yBAAyB;AAC/E,QAAM,SAAU,QAAQ,UAAU,CAAC;AACnC,MAAI,CAAC,OAAO,KAAM,QAAO,KAAK,QAAQ,IAAI,qBAAqB,mBAAmB;AAClF,QAAM,SAAS,MAAM,SAAS,SAAS,OAAO,MAAM,OAAO,aAAa,CAAC,GAAG,IAAI;AAChF,SAAO,GAAG,QAAQ,IAAI,MAAM;AAC9B;AAVe;AAYf,SAAS,iBACP,SACA,SACiB;AACjB,SAAO,GAAG,QAAQ,IAAI;AAAA,IACpB,iBAAiB,QAAQ,mBAAmB;AAAA;AAAA;AAAA;AAAA,IAI5C,cAAc,EAAE,OAAO,CAAC,EAAE;AAAA,IAC1B,YAAY,QAAQ;AAAA,IACpB,GAAI,QAAQ,eAAe,EAAE,cAAc,QAAQ,aAAa,IAAI,CAAC;AAAA,EACvE,CAAC;AACH;AAbS;AAwBT,eAAsB,iBACpB,SACA,UACA,MACA,SACiC;AAKjC,MAAI,CAAC,aAAa,OAAO,GAAG;AAC1B,WAAO,KAAK,SAAS,MAAM,MAAM,sBAAsB,iBAAiB;AAAA,EAC1E;AACA,UAAQ,QAAQ,QAAQ;AAAA,IACtB,KAAK;AACH,aAAO,iBAAiB,SAAS,OAAO;AAAA,IAC1C,KAAK;AACH,aAAO,GAAG,QAAQ,IAAI,CAAC,CAAC;AAAA,IAC1B,KAAK;AACH,aAAO,GAAG,QAAQ,IAAI,EAAE,OAAO,SAAS,UAAU,QAAQ,MAAS,EAAE,CAAC;AAAA,IACxE,KAAK;AACH,aAAO,gBAAgB,SAAS,UAAU,IAAI;AAAA,IAChD;AAGE,UAAI,QAAQ,OAAO,WAAW,gBAAgB,EAAG,QAAO;AACxD,aAAO,KAAK,QAAQ,IAAI,uBAAuB,qBAAqB,QAAQ,MAAM,EAAE;AAAA,EACxF;AACF;AA5BsB;","names":[]}

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@12-apps/mcp",
-  "version": "3.12.0",
+  "version": "3.14.0",
   "type": "module",
+  "sideEffects": false,
   "description": "App-agnostic MCP server core: generate one MCP tool per OpenAPI operation and proxy each call carrying the caller's bearer token (permission passthrough). Also ships the OAuth 2.1 authorization server (./oauth, ./hono: register/authorize/token, JWKS and both .well-known documents), the package-owned Prisma partial + migration for its three tables, the mcp:generate/mcp:check (./generate) and mcp:coverage (./coverage) gates, and the reusable AI-connect onboarding UI (./react).",
   "exports": {
     ".": {
@@ -50,9 +51,9 @@
     "prisma:sync:check": "node scripts/sync-mcp-schema.mjs --check"
   },
   "dependencies": {
-    "@12-apps/onboarding": "^2.4.0",
-    "@12-apps/rbac": "^4.7.0",
-    "@12-apps/ui": "^6.9.0",
+    "@12-apps/onboarding": "^2.7.0",
+    "@12-apps/rbac": "^4.10.0",
+    "@12-apps/ui": "^6.10.0",
     "@mui/icons-material": "^6.5.0",
     "jose": "^6.1.3",
     "react": "^19.2.0"
@@ -75,10 +76,10 @@
     }
   },
   "devDependencies": {
-    "@12-apps/eslint-config": "^1.21.1",
-    "@12-apps/i18n": "^1.1.0",
-    "@12-apps/typescript-config": "^1.20.1",
-    "@12-apps/wiring": "^1.12.0",
+    "@12-apps/eslint-config": "^1.22.0",
+    "@12-apps/i18n": "^1.2.0",
+    "@12-apps/typescript-config": "^1.21.0",
+    "@12-apps/wiring": "^1.14.0",
     "@mui/material": "^6.5.0",
     "@testing-library/react": "^16.1.0",
     "@types/node": "^22.15.3",

package/src/index.ts

@@ -29,7 +29,16 @@ export { inlineSchemaRefs, UnsupportedSchemaError } from "./openapi/refs";
 // here so that packages which own a domain can ship that domain's endpoints and
 // a host can concatenate them — which requires all of them to mean the same
 // thing by "an endpoint". See `openapi/endpoint.ts`.
-export type { McpEndpoint, HttpMethod } from "./openapi/endpoint";
+export type { McpEndpoint, HttpMethod, McpAnnotationDefaults } from "./openapi/endpoint";
+/**
+ * Composing a tool's classification from a package's declared defaults and the
+ * host's own table — the host still wins every field it states, and a field
+ * neither side supplies is a refusal. See `./openapi/annotations`.
+ */
+export {
+  resolveToolAnnotations,
+  type ToolAnnotationOverrides,
+} from "./openapi/annotations";
 export type {
   OpenApiDocument,
   OpenApiOperation,

package/src/openapi/annotations.ts

@@ -0,0 +1,106 @@
+/**
+ * Composing a tool's behavior classification out of two sources.
+ *
+ * The rule the host's gate enforces is unchanged: every served tool ends with
+ * a COMPLETE `ToolAnnotations` — a title and all three hints — and a tool that
+ * ends unclassified fails `mcp:lint`. ChatGPT App review treats a missing hint
+ * as a blocker, and the Anthropic connector directory derives auto-permissions
+ * from `readOnlyHint`/`destructiveHint`, so there is no defensible default for
+ * "we did not say".
+ *
+ * What this adds is where the answer may COME FROM. A package that declares
+ * `getSupplierVersions` knows it reads and does not destroy; the host cannot
+ * know that without reading the package's source, so it restated the
+ * classification by hand — one line per tool, per collection, wrong the moment
+ * the package changed a verb. Now the package can assert what it knows and the
+ * host's table becomes what it should always have been: OVERRIDES, plus the
+ * tools the host itself owns.
+ *
+ * ## Precedence, and why it runs this way
+ *
+ * The HOST wins every field it states. A package's claim is a default, not a
+ * fact about the host's deployment: the same endpoint can be read-only in one
+ * app and reach an external service in another (a host that proxies its
+ * catalog reads through a vendor), and the host is the only party that knows.
+ * Inverting this would make a package version bump silently re-classify a tool
+ * an operator had already audited — the exact thing an audited classification
+ * exists to prevent.
+ *
+ * ## What it refuses
+ *
+ * A field neither side supplies. `resolveToolAnnotations` throws naming the
+ * tool and the missing fields, which keeps the completeness property a
+ * REFUSAL rather than a lint pass over a table that quietly grew a gap. The
+ * host's own gate can keep its message; this one fires first and says the same
+ * thing in the same terms.
+ */
+
+import type { ToolAnnotations } from "../types";
+import type { McpAnnotationDefaults } from "./endpoint";
+
+/** The host's half — whatever it chose to state, per tool. */
+export type ToolAnnotationOverrides = Partial<ToolAnnotations>;
+
+/**
+ * Merge a package's declared defaults under a host's overrides.
+ *
+ * @param name the tool id, for the refusal message
+ * @param defaults what the package asserted (`McpEndpoint.annotations`)
+ * @param overrides what the host's own table says; wins every field it states
+ */
+/** A title only counts when it has something in it. */
+function titleOf(candidate: string | undefined): string | undefined {
+  return typeof candidate === "string" && candidate.trim() !== "" ? candidate : undefined;
+}
+
+/**
+ * Merge a package's declared defaults under a host's overrides.
+ *
+ * The four fields are resolved into one record and checked generically rather
+ * than branch by branch — which keeps the "host wins, and `false` is an
+ * answer" rule stated exactly once per field instead of once per field per
+ * check.
+ *
+ * `??` and not `||` throughout, and that is the trap the whole merge turns on:
+ * `false` is a real classification — "this tool does not destroy" — and must
+ * not fall through to the package's answer.
+ *
+ * @param name the tool id, for the refusal message
+ * @param defaults what the package asserted (`McpEndpoint.annotations`)
+ * @param overrides what the host's own table says; wins every field it states
+ */
+export function resolveToolAnnotations(
+  name: string,
+  defaults: McpAnnotationDefaults | undefined,
+  overrides: ToolAnnotationOverrides | undefined,
+): ToolAnnotations {
+  const host = overrides ?? {};
+  const declared = defaults ?? {};
+  const resolved: Partial<ToolAnnotations> = {
+    title: titleOf(host.title ?? declared.title),
+    readOnlyHint: host.readOnlyHint ?? declared.readOnly,
+    openWorldHint: host.openWorldHint ?? declared.openWorld,
+    destructiveHint: host.destructiveHint ?? declared.destructive,
+  };
+
+  const missing = REQUIRED_FIELDS.filter((field) => resolved[field] === undefined);
+  if (missing.length > 0) refuse(name, missing);
+  return resolved as ToolAnnotations;
+}
+
+/** Every field a served tool must end with — the completeness property itself. */
+const REQUIRED_FIELDS = [
+  "title",
+  "readOnlyHint",
+  "openWorldHint",
+  "destructiveHint",
+] as const satisfies readonly (keyof ToolAnnotations)[];
+
+function refuse(name: string, missing: readonly string[]): never {
+  throw new Error(
+    `MCP tool "${name}" ends unclassified: neither the package nor the host supplied ` +
+      `${missing.join(", ")}. Every served tool needs a complete classification — a missing ` +
+      `hint blocks ChatGPT App review, and the connector directory derives auto-permissions ` +
+      `from readOnlyHint/destructiveHint.`,
+  );
+}

package/src/openapi/endpoint.ts

@@ -28,6 +28,37 @@ import type { z } from "zod";
 /** The methods an MCP-exposed route may use. */
 export type HttpMethod = "get" | "post" | "put" | "patch" | "delete";
 
+/**
+ * What a PACKAGE can say about how its own tool behaves.
+ *
+ * The host still owns the final `ToolAnnotations` — every field required, and
+ * `mcp:lint` unchanged in demanding that each tool ends classified. What
+ * changes is who supplies the DEFAULT. A package declaring
+ * `getSupplierVersions` knows perfectly well that it reads and does not
+ * destroy; a host cannot know that without reading the package's source, so
+ * today it restates the classification by hand — 48 lines of policy hints for
+ * one package's eight-endpoint factory, growing with every collection plugged
+ * in, and wrong the moment the package changes a verb.
+ *
+ * Every field is OPTIONAL here, which is the whole difference from
+ * `ToolAnnotations`: this is a suggestion the host merges under its own table,
+ * so a package that knows two of the four says two and stays silent on the
+ * rest. Deliberately spelled without the `Hint` suffix and as a structural
+ * twin of `@12-apps/wiring`'s `WireMcpAnnotations`, so an `McpEndpoint` still
+ * satisfies `WireMcpTool` — restated rather than imported because this package
+ * takes no dependency on the wiring contract.
+ */
+export interface McpAnnotationDefaults {
+  /** Human title override; hosts may re-derive from the operation id. */
+  title?: string;
+  /** The tool only reads — never mutates host state. */
+  readOnly?: boolean;
+  /** A destructive write (delete/purge), as opposed to an additive one. */
+  destructive?: boolean;
+  /** The tool reaches beyond the host's own data (external services). */
+  openWorld?: boolean;
+}
+
 interface McpEndpointBase {
   /** Stable tool id — this becomes the MCP tool name, so renaming it is a
    *  breaking change for every agent that has learned the old one. */
@@ -44,6 +75,11 @@ interface McpEndpointBase {
   params?: z.ZodType;
   /** Request body schema (writes only). */
   body?: z.ZodType;
+  /**
+   * Behavior the package can assert about its own tool. Optional, and merged
+   * UNDER the host's table — see {@link McpAnnotationDefaults}.
+   */
+  annotations?: McpAnnotationDefaults;
 }
 
 /**