@12-apps/mcp 3.3.0 → 3.4.0

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 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';
+import { z } from 'zod';
 
 /**
  * Raised when a JSON Schema cannot be turned into a flat, self-contained tool
@@ -23,6 +24,69 @@ declare class UnsupportedSchemaError extends Error {
  */
 declare function inlineSchemaRefs(schema: JsonSchema): JsonSchema;
 
+/**
+ * How a route is DECLARED, one step before it becomes an OpenAPI operation and
+ * two before it becomes a tool.
+ *
+ * This package already owns everything downstream of an OpenAPI document —
+ * `generateTools` turns operations into tools, `dispatchTool` proxies a call,
+ * `redactResponseSchema`/`redactResponseBody` narrow both halves. What it did
+ * not own was the shape a consumer writes its routes down in, so every consumer
+ * declared its own. That is fine for one app and wrong for several: a monorepo
+ * where the shift routes, the lifecycle routes and the audit routes are each
+ * packaged separately needs those packages to produce endpoint lists the HOST
+ * can concatenate, which they can only do if they all mean the same thing by
+ * "an endpoint".
+ *
+ * Deliberately zod-shaped rather than JSON-Schema-shaped. A route validates its
+ * input with zod at runtime; describing it a second time in JSON Schema is a
+ * copy that drifts, and the drift is invisible — the manifest keeps advertising
+ * the shape the route stopped accepting. Converting zod → JSON Schema at
+ * generate time makes the validator the single source of truth.
+ *
+ * zod is a PEER dependency: it is referenced here as a type only, so this
+ * package pulls no copy of its own and cannot end up type-checking against a
+ * different one than the consumer declares its schemas with.
+ */
+/** The methods an MCP-exposed route may use. */
+type HttpMethod = "get" | "post" | "put" | "patch" | "delete";
+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. */
+    operationId: string;
+    method: HttpMethod;
+    /** OpenAPI path template, e.g. `/api/products/{id}`. */
+    path: string;
+    /** What the tool is FOR, in the words an agent reads when choosing it. */
+    summary: string;
+    tags?: string[];
+    /** Object schema whose properties become query parameters. */
+    query?: z.ZodType;
+    /** Object schema whose properties become path parameters. */
+    params?: z.ZodType;
+    /** Request body schema (writes only). */
+    body?: z.ZodType;
+}
+/**
+ * A declared endpoint either answers 200 with a schema'd JSON body (the
+ * default) or 204 No Content (fire-and-forget writes).
+ *
+ * The union is what makes the two mutually exclusive: a 204 entry cannot carry
+ * a response schema, so a manifest can never advertise a body its route will
+ * not send — a mismatch an agent experiences as a tool that returns nothing
+ * where its own schema promised an object.
+ */
+type McpEndpoint = McpEndpointBase & ({
+    /** Success status (defaults to 200 with a JSON body). */
+    status?: 200;
+    /** Success (200) response schema. */
+    response: z.ZodType;
+} | {
+    /** 204 No Content — no response schema. */
+    status: 204;
+    response?: never;
+});
+
 /** Raised when tool arguments cannot be routed onto the HTTP request. */
 declare class DispatchInputError extends Error {
     constructor(message: string);
@@ -404,4 +468,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 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, 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 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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/mcp",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "type": "module",
   "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": {
@@ -51,7 +51,8 @@
   },
   "peerDependencies": {
     "react": ">=19.0.0",
-    "hono": ">=4.0.0"
+    "hono": ">=4.0.0",
+    "zod": ">=4.0.0"
   },
   "devDependencies": {
     "@12-apps/eslint-config": "^1.20.0",
@@ -67,7 +68,8 @@
     "react-dom": "^19.2.0",
     "tsup": "^8.0.0",
     "typescript": "^5.8.2",
-    "vitest": "^3.2.4"
+    "vitest": "^3.2.4",
+    "zod": "^4.3.5"
   },
   "engines": {
     "node": ">=22.0.0"
@@ -103,6 +105,9 @@
   "peerDependenciesMeta": {
     "hono": {
       "optional": true
+    },
+    "zod": {
+      "optional": true
     }
   }
 }

package/src/index.ts

@@ -28,6 +28,11 @@ export {
 } from "./guide";
 export { generateTools } from "./openapi/generate";
 export { inlineSchemaRefs, UnsupportedSchemaError } from "./openapi/refs";
+// The shape a route is DECLARED in, upstream of the OpenAPI document. It lives
+// 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 {
   OpenApiDocument,
   OpenApiOperation,

package/src/openapi/endpoint.ts

@@ -0,0 +1,71 @@
+import type { z } from "zod";
+
+/**
+ * How a route is DECLARED, one step before it becomes an OpenAPI operation and
+ * two before it becomes a tool.
+ *
+ * This package already owns everything downstream of an OpenAPI document —
+ * `generateTools` turns operations into tools, `dispatchTool` proxies a call,
+ * `redactResponseSchema`/`redactResponseBody` narrow both halves. What it did
+ * not own was the shape a consumer writes its routes down in, so every consumer
+ * declared its own. That is fine for one app and wrong for several: a monorepo
+ * where the shift routes, the lifecycle routes and the audit routes are each
+ * packaged separately needs those packages to produce endpoint lists the HOST
+ * can concatenate, which they can only do if they all mean the same thing by
+ * "an endpoint".
+ *
+ * Deliberately zod-shaped rather than JSON-Schema-shaped. A route validates its
+ * input with zod at runtime; describing it a second time in JSON Schema is a
+ * copy that drifts, and the drift is invisible — the manifest keeps advertising
+ * the shape the route stopped accepting. Converting zod → JSON Schema at
+ * generate time makes the validator the single source of truth.
+ *
+ * zod is a PEER dependency: it is referenced here as a type only, so this
+ * package pulls no copy of its own and cannot end up type-checking against a
+ * different one than the consumer declares its schemas with.
+ */
+
+/** The methods an MCP-exposed route may use. */
+export type HttpMethod = "get" | "post" | "put" | "patch" | "delete";
+
+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. */
+  operationId: string;
+  method: HttpMethod;
+  /** OpenAPI path template, e.g. `/api/products/{id}`. */
+  path: string;
+  /** What the tool is FOR, in the words an agent reads when choosing it. */
+  summary: string;
+  tags?: string[];
+  /** Object schema whose properties become query parameters. */
+  query?: z.ZodType;
+  /** Object schema whose properties become path parameters. */
+  params?: z.ZodType;
+  /** Request body schema (writes only). */
+  body?: z.ZodType;
+}
+
+/**
+ * A declared endpoint either answers 200 with a schema'd JSON body (the
+ * default) or 204 No Content (fire-and-forget writes).
+ *
+ * The union is what makes the two mutually exclusive: a 204 entry cannot carry
+ * a response schema, so a manifest can never advertise a body its route will
+ * not send — a mismatch an agent experiences as a tool that returns nothing
+ * where its own schema promised an object.
+ */
+export type McpEndpoint = McpEndpointBase &
+  (
+    | {
+        /** Success status (defaults to 200 with a JSON body). */
+        status?: 200;
+        /** Success (200) response schema. */
+        response: z.ZodType;
+      }
+    | {
+        /** 204 No Content — no response schema. */
+        status: 204;
+        response?: never;
+      }
+  );