@12-apps/mcp 1.0.0

package/README.md

@@ -0,0 +1,53 @@
+# @12-apps/mcp
+
+App-agnostic core for exposing an app's HTTP endpoints as an MCP server, where
+**the agent acts with exactly the calling user's permissions**.
+
+## The idea
+
+Generate **one MCP tool per OpenAPI operation**, and dispatch each tool call by
+**proxying to the real endpoint carrying the caller's bearer token**. Because the
+proxy hits the same endpoints a browser would, all existing auth/authorization
+(session guards, tenant scoping, role checks) runs unchanged — this package holds
+**zero** authorization logic. An agent can do precisely what the user can, no
+more.
+
+This is the passthrough pattern, not the "golden catalog" curation pattern: 1:1
+tools, no hand-written field maps. That is what makes it generatable and portable
+across apps.
+
+## The two invariants a consuming app must satisfy
+
+1. **Schema'd HTTP surface** — every agent-exposable operation is an HTTP endpoint
+   described in an OpenAPI document generated from runtime schemas (Zod →
+   OpenAPI). That document is this package's only input.
+2. **One standard bearer auth** — every endpoint authenticates a caller from an
+   `Authorization: Bearer <token>` resolving to the same identity/permissions as a
+   normal session. The proxy forwards the token blindly.
+
+## What this package provides
+
+| Export | Role |
+|--------|------|
+| `generateTools(doc, opts)` | OpenAPI operations → `GeneratedTool[]` (input schema + HTTP routing metadata). Deterministic. |
+| `createToolRegistry({ tools, baseUrl })` | Transport-agnostic `listTools` / `callTool`; `callTool` proxies with the caller's bearer. |
+| `dispatchTool(tool, args, cfg)` | The generic auth-proxy: routes flat args → path/query/header/body, forwards the bearer. |
+| `buildManifest` / `serializeManifest` | The committed drift artifact `mcp:check` regenerates + diffs (see `12-apps/ci` `mcp-contract.yml`). |
+| `buildProtectedResourceMetadata` / `bearerChallenge` | OAuth 2.0 Protected Resource Metadata (RFC 9728) + `WWW-Authenticate` for the resource-server mode. |
+
+## What the app provides (not here)
+
+- The **OpenAPI document** (from its Zod-schema'd routes).
+- The **`AuthResolver`** — validates the incoming access token (OAuth
+  resource-server: signature / audience / scope) and returns the bearer to
+  forward. In future-pay this is the `getRequestSession()` shim over NextAuth
+  `auth()`.
+- Binding `ToolRegistry` to the **MCP transport** (the `@modelcontextprotocol/sdk`
+  HTTP server at `/api/mcp`).
+
+## Status
+
+Scaffold: the generator, dispatcher, registry, manifest, and OAuth
+resource-metadata helpers are implemented and dependency-light (no MCP SDK). The
+SDK/HTTP transport binding and the app-side `AuthResolver` land in the pilot's
+next phase (`apps/web`). See the pilot design notes under `docs/`.

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@12-apps/mcp",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "App-agnostic MCP server core: generate one MCP tool per OpenAPI operation and proxy each call to the endpoint carrying the caller's bearer token (permission passthrough).",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.3",
+    "eslint": "^9.39.1",
+    "typescript": "^5.8.2",
+    "vitest": "^3.2.4",
+    "@12-apps/typescript-config": "0.0.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/12-apps/shared-packages.git",
+    "directory": "packages/mcp"
+  },
+  "files": [
+    "src",
+    "dist",
+    "prisma",
+    "*.js",
+    "*.mjs",
+    "*.md"
+  ],
+  "scripts": {
+    "clean": "rm -rf node_modules coverage",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest watch",
+    "lint": "eslint src --max-warnings 0",
+    "check-types": "tsc --noEmit",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/auth/authorization-server-metadata.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from "vitest";
+
+import { buildAuthorizationServerMetadata } from "./authorization-server-metadata";
+// Barrel import (deliverable 2.2): the builder must be re-exported from the
+// package entry so the future `@12-apps/mcp` extraction inherits both halves.
+import { buildAuthorizationServerMetadata as buildFromBarrel } from "../index";
+
+describe("buildAuthorizationServerMetadata", () => {
+  it("derives every endpoint from the issuer and fixes the RFC 8414 arrays", () => {
+    const meta = buildAuthorizationServerMetadata({
+      issuer: "https://app.example.com",
+      scopesSupported: ["mcp:read", "mcp:write"],
+    });
+
+    expect(meta.issuer).toBe("https://app.example.com");
+    expect(meta.authorization_endpoint).toBe(
+      "https://app.example.com/api/oauth/authorize",
+    );
+    expect(meta.token_endpoint).toBe("https://app.example.com/api/oauth/token");
+    expect(meta.registration_endpoint).toBe(
+      "https://app.example.com/api/oauth/register",
+    );
+    expect(meta.jwks_uri).toBe("https://app.example.com/.well-known/jwks.json");
+
+    // Fixed per the OAuth 2.1 + PKCE contract — must never drift.
+    expect(meta.response_types_supported).toEqual(["code"]);
+    expect(meta.grant_types_supported).toEqual([
+      "authorization_code",
+      "refresh_token",
+    ]);
+    expect(meta.code_challenge_methods_supported).toEqual(["S256"]);
+    expect(meta.token_endpoint_auth_methods_supported).toEqual([
+      "none",
+      "client_secret_basic",
+    ]);
+  });
+
+  it("passes the supplied scopes through to scopes_supported", () => {
+    const meta = buildAuthorizationServerMetadata({
+      issuer: "https://tenant.futuredrink.com.br",
+      scopesSupported: ["mcp:read"],
+    });
+
+    expect(meta.scopes_supported).toEqual(["mcp:read"]);
+    // Endpoints stay on the supplied issuer origin.
+    expect(meta.issuer).toBe("https://tenant.futuredrink.com.br");
+    expect(meta.authorization_endpoint).toBe(
+      "https://tenant.futuredrink.com.br/api/oauth/authorize",
+    );
+  });
+
+  it("honours a custom token_endpoint_auth_methods override", () => {
+    const meta = buildAuthorizationServerMetadata({
+      issuer: "https://app.example.com",
+      scopesSupported: ["mcp:read", "mcp:write"],
+      tokenEndpointAuthMethods: ["none"],
+    });
+
+    expect(meta.token_endpoint_auth_methods_supported).toEqual(["none"]);
+  });
+
+  it("is re-exported from the package barrel", () => {
+    expect(buildFromBarrel).toBe(buildAuthorizationServerMetadata);
+
+    const meta = buildFromBarrel({
+      issuer: "https://app.example.com",
+      scopesSupported: ["mcp:read", "mcp:write"],
+    });
+    expect(meta.code_challenge_methods_supported).toEqual(["S256"]);
+  });
+});

package/src/auth/authorization-server-metadata.ts

@@ -0,0 +1,73 @@
+/**
+ * OAuth 2.0 Authorization Server Metadata (RFC 8414), the discovery half that
+ * complements the RFC 9728 protected-resource metadata in `resource-metadata.ts`.
+ * Agent hosts (Claude.ai / ChatGPT connectors) read
+ * `/.well-known/oauth-authorization-server` to learn where to start the OAuth
+ * 2.1 Authorization Code + PKCE flow.
+ *
+ * This builder is a pure function of `(issuer, scopes)` with no Next.js/request
+ * coupling, so it can move verbatim into the future `@12-apps/mcp` extraction.
+ * It derives every endpoint from the same issuer origin the resource metadata
+ * advertises, so the two discovery documents cannot drift.
+ */
+
+export interface AuthorizationServerMetadataInput {
+  /** Authorization server issuer URL (origin) — also the resource issuer. */
+  issuer: string;
+  /** Scopes the authorization server advertises (from the shared scope source). */
+  scopesSupported: string[];
+  /**
+   * Client authentication methods the token endpoint accepts. Defaults to
+   * public PKCE clients (`none`) plus HTTP Basic client-secret auth.
+   */
+  tokenEndpointAuthMethods?: string[];
+}
+
+/** The RFC 8414 document served at `/.well-known/oauth-authorization-server`. */
+export interface AuthorizationServerMetadata {
+  issuer: string;
+  authorization_endpoint: string;
+  token_endpoint: string;
+  registration_endpoint: string;
+  jwks_uri: string;
+  scopes_supported: string[];
+  response_types_supported: string[];
+  grant_types_supported: string[];
+  code_challenge_methods_supported: string[];
+  token_endpoint_auth_methods_supported: string[];
+}
+
+const AUTHORIZE_PATH = "/api/oauth/authorize";
+const TOKEN_PATH = "/api/oauth/token";
+const REGISTRATION_PATH = "/api/oauth/register";
+const JWKS_PATH = "/.well-known/jwks.json";
+
+const DEFAULT_TOKEN_ENDPOINT_AUTH_METHODS = [
+  "none",
+  "client_secret_basic",
+] as const;
+
+/**
+ * Build the RFC 8414 authorization-server metadata document from an issuer
+ * origin and the supported scopes. Endpoints are derived from `issuer`; the
+ * OAuth 2.1 + PKCE contract fixes `response_types_supported`,
+ * `grant_types_supported`, and `code_challenge_methods_supported`.
+ */
+export function buildAuthorizationServerMetadata(
+  input: AuthorizationServerMetadataInput,
+): AuthorizationServerMetadata {
+  const origin = input.issuer;
+  return {
+    issuer: origin,
+    authorization_endpoint: `${origin}${AUTHORIZE_PATH}`,
+    token_endpoint: `${origin}${TOKEN_PATH}`,
+    registration_endpoint: `${origin}${REGISTRATION_PATH}`,
+    jwks_uri: `${origin}${JWKS_PATH}`,
+    scopes_supported: input.scopesSupported,
+    response_types_supported: ["code"],
+    grant_types_supported: ["authorization_code", "refresh_token"],
+    code_challenge_methods_supported: ["S256"],
+    token_endpoint_auth_methods_supported:
+      input.tokenEndpointAuthMethods ?? [...DEFAULT_TOKEN_ENDPOINT_AUTH_METHODS],
+  };
+}

package/src/auth/resource-metadata.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from "vitest";
+
+import { bearerChallenge, buildProtectedResourceMetadata } from "./resource-metadata";
+
+describe("buildProtectedResourceMetadata", () => {
+  it("emits the RFC 9728 fields", () => {
+    const meta = buildProtectedResourceMetadata({
+      resource: "https://app.example.com/api/mcp",
+      authorizationServers: ["https://app.example.com"],
+      scopesSupported: ["mcp:read"],
+    });
+    expect(meta).toEqual({
+      resource: "https://app.example.com/api/mcp",
+      authorization_servers: ["https://app.example.com"],
+      bearer_methods_supported: ["header"],
+      scopes_supported: ["mcp:read"],
+    });
+  });
+
+  it("omits scopes when not provided", () => {
+    const meta = buildProtectedResourceMetadata({
+      resource: "r",
+      authorizationServers: ["a"],
+    });
+    expect(meta.scopes_supported).toBeUndefined();
+  });
+});
+
+describe("bearerChallenge", () => {
+  it("points at the resource metadata and carries the error", () => {
+    const challenge = bearerChallenge({
+      resourceMetadataUrl: "https://app.example.com/.well-known/oauth-protected-resource",
+      error: "invalid_token",
+      errorDescription: "expired",
+    });
+    expect(challenge).toBe(
+      'Bearer resource_metadata="https://app.example.com/.well-known/oauth-protected-resource", error="invalid_token", error_description="expired"',
+    );
+  });
+
+  it("emits a bare challenge when no error is given", () => {
+    expect(bearerChallenge({ resourceMetadataUrl: "https://x/.well-known/oauth-protected-resource" })).toBe(
+      'Bearer resource_metadata="https://x/.well-known/oauth-protected-resource"',
+    );
+  });
+});

package/src/auth/resource-metadata.ts

@@ -0,0 +1,68 @@
+/**
+ * OAuth 2.0 Protected Resource Metadata (RFC 9728), as required by the MCP
+ * authorization spec: the MCP endpoint is an OAuth *resource server*. Agent hosts
+ * (Claude.ai / ChatGPT connectors) discover where to obtain a token by reading
+ * `/.well-known/oauth-protected-resource`, and on a 401 the resource server points
+ * them at that document via a `WWW-Authenticate` challenge.
+ *
+ * This module only builds the discovery documents/headers — validating the
+ * resulting access token is the app's job (the {@link import("../types").AuthResolver}),
+ * because it depends on the app's authorization server and key material.
+ */
+
+export interface ProtectedResourceMetadataInput {
+  /** Canonical resource identifier — the MCP endpoint URL (the token audience). */
+  resource: string;
+  /** Authorization server issuer URLs that can mint tokens for this resource. */
+  authorizationServers: string[];
+  /** Scopes the resource server understands (advertised to clients). */
+  scopesSupported?: string[];
+  /** Human-facing docs URL for the protected resource, if any. */
+  resourceDocumentation?: string;
+}
+
+/** The RFC 9728 metadata document served at `/.well-known/oauth-protected-resource`. */
+export interface ProtectedResourceMetadata {
+  resource: string;
+  authorization_servers: string[];
+  bearer_methods_supported: string[];
+  scopes_supported?: string[];
+  resource_documentation?: string;
+}
+
+export function buildProtectedResourceMetadata(
+  input: ProtectedResourceMetadataInput,
+): ProtectedResourceMetadata {
+  return {
+    resource: input.resource,
+    authorization_servers: input.authorizationServers,
+    // MCP clients present the token in the Authorization header only.
+    bearer_methods_supported: ["header"],
+    ...(input.scopesSupported ? { scopes_supported: input.scopesSupported } : {}),
+    ...(input.resourceDocumentation
+      ? { resource_documentation: input.resourceDocumentation }
+      : {}),
+  };
+}
+
+/**
+ * Build the `WWW-Authenticate` value for an unauthorized MCP response, pointing
+ * the client at the protected-resource metadata so it can start the OAuth flow.
+ * Per RFC 9728 §5.1 the challenge carries a `resource_metadata` parameter.
+ */
+export function bearerChallenge(params: {
+  resourceMetadataUrl: string;
+  error?: "invalid_token" | "insufficient_scope";
+  errorDescription?: string;
+}): string {
+  const parts = [`Bearer resource_metadata="${params.resourceMetadataUrl}"`];
+  if (params.error) parts.push(`error="${params.error}"`);
+  if (params.errorDescription) {
+    parts.push(`error_description="${params.errorDescription}"`);
+  }
+  return parts.join(", ");
+}
+
+/** Standard path for the protected-resource metadata document. */
+export const PROTECTED_RESOURCE_METADATA_PATH =
+  "/.well-known/oauth-protected-resource";

package/src/dispatch/proxy.test.ts

@@ -0,0 +1,130 @@
+import { describe, expect, it } from "vitest";
+
+import { dispatchTool, DispatchInputError } from "./proxy";
+import type { GeneratedTool } from "../types";
+
+const getTool: GeneratedTool = {
+  name: "getProduct",
+  description: "",
+  method: "GET",
+  path: "/products/{id}",
+  inputSchema: {},
+  parameters: [
+    { name: "id", in: "path", required: true, schema: {} },
+    { name: "include", in: "query", required: false, schema: {} },
+    { name: "x-trace", in: "header", required: false, schema: {} },
+  ],
+  bodyProps: [],
+  bodyIsWhole: false,
+  mutating: false,
+  security: [],
+};
+
+const postTool: GeneratedTool = {
+  name: "createProduct",
+  description: "",
+  method: "POST",
+  path: "/products",
+  inputSchema: {},
+  parameters: [],
+  bodyProps: ["name", "priceCents"],
+  bodyIsWhole: false,
+  mutating: true,
+  security: [],
+};
+
+interface Captured {
+  url: string;
+  init: RequestInit;
+}
+
+function fakeFetch(status: number, payload: unknown, captured: Captured[]): typeof fetch {
+  return (async (url: string, init: RequestInit) => {
+    captured.push({ url, init });
+    return new Response(JSON.stringify(payload), {
+      status,
+      headers: { "content-type": "application/json" },
+    });
+  }) as unknown as typeof fetch;
+}
+
+describe("dispatchTool", () => {
+  it("expands the path, forwards the bearer, and routes query + header args", async () => {
+    const captured: Captured[] = [];
+    const result = await dispatchTool(
+      getTool,
+      { id: "abc 1", include: "variations", "x-trace": "t1" },
+      { baseUrl: "https://app.example.com", bearer: "tok123", fetchImpl: fakeFetch(200, { ok: 1 }, captured) },
+    );
+
+    expect(captured).toHaveLength(1);
+    const { url, init } = captured[0];
+    expect(url).toBe("https://app.example.com/products/abc%201?include=variations");
+    const headers = init.headers as Record<string, string>;
+    expect(headers.authorization).toBe("Bearer tok123");
+    expect(headers["x-trace"]).toBe("t1");
+    expect(init.body).toBeUndefined();
+    expect(result.ok).toBe(true);
+    expect(result.status).toBe(200);
+    expect(result.body).toEqual({ ok: 1 });
+  });
+
+  it("sends only known body props as a JSON body for a write", async () => {
+    const captured: Captured[] = [];
+    await dispatchTool(
+      postTool,
+      { name: "Cola", priceCents: 500, sneaky: "drop-me" },
+      { baseUrl: "https://app.example.com", bearer: "t", fetchImpl: fakeFetch(201, {}, captured) },
+    );
+    const { init } = captured[0];
+    expect(init.method).toBe("POST");
+    expect(JSON.parse(init.body as string)).toEqual({ name: "Cola", priceCents: 500 });
+    expect((init.headers as Record<string, string>)["content-type"]).toBe("application/json");
+  });
+
+  it("throws on a missing required path parameter", async () => {
+    await expect(
+      dispatchTool(getTool, {}, { baseUrl: "https://app.example.com", bearer: "t", fetchImpl: fakeFetch(200, {}, []) }),
+    ).rejects.toBeInstanceOf(DispatchInputError);
+  });
+
+  it("surfaces a non-2xx response as ok:false", async () => {
+    const result = await dispatchTool(
+      getTool,
+      { id: "1" },
+      { baseUrl: "https://app.example.com", bearer: "t", fetchImpl: fakeFetch(403, { error: "forbidden" }, []) },
+    );
+    expect(result.ok).toBe(false);
+    expect(result.status).toBe(403);
+    expect(result.body).toEqual({ error: "forbidden" });
+  });
+
+  // Regression (FUT-105 AC1): the proxy replay must carry the mint origin as the
+  // standard reverse-proxy forwarded headers so the wrapped route reconstructs the
+  // SAME origin the access token's `aud` was minted against. Without these, the
+  // wrapped guard's origin resolver defaults the proto to https and the aud check
+  // fails on an http dev origin → a valid Bearer 401s.
+  it("forwards the baseUrl origin as x-forwarded-proto / x-forwarded-host", async () => {
+    const captured: Captured[] = [];
+    await dispatchTool(
+      getTool,
+      { id: "1" },
+      { baseUrl: "http://localhost:4105", bearer: "t", fetchImpl: fakeFetch(200, {}, captured) },
+    );
+    const headers = captured[0].init.headers as Record<string, string>;
+    expect(headers["x-forwarded-proto"]).toBe("http");
+    expect(headers["x-forwarded-host"]).toBe("localhost:4105");
+  });
+
+  it("derives forwarded proto/host from an https origin with a default port", async () => {
+    const captured: Captured[] = [];
+    await dispatchTool(
+      getTool,
+      { id: "1" },
+      { baseUrl: "https://menu.example.com", bearer: "t", fetchImpl: fakeFetch(200, {}, captured) },
+    );
+    const headers = captured[0].init.headers as Record<string, string>;
+    expect(headers["x-forwarded-proto"]).toBe("https");
+    expect(headers["x-forwarded-host"]).toBe("menu.example.com");
+  });
+});

package/src/dispatch/proxy.ts

@@ -0,0 +1,126 @@
+import type { DispatchConfig, DispatchResult, GeneratedTool } from "../types";
+
+/** Raised when tool arguments cannot be routed onto the HTTP request. */
+export class DispatchInputError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "DispatchInputError";
+  }
+}
+
+/** Expand a path template (`/products/{id}`) using the path args, URL-encoding each. */
+function expandPath(
+  tool: GeneratedTool,
+  args: Record<string, unknown>,
+): string {
+  return tool.path.replace(/\{([^}]+)\}/g, (_match, key: string) => {
+    const value = args[key];
+    if (value === undefined || value === null) {
+      throw new DispatchInputError(`Missing required path parameter: ${key}`);
+    }
+    return encodeURIComponent(String(value));
+  });
+}
+
+/**
+ * Route the non-path parameters (query + header) from the flat args. A missing
+ * required parameter is a hard error; a missing optional one is simply omitted.
+ */
+function routeParams(
+  tool: GeneratedTool,
+  args: Record<string, unknown>,
+): { query: URLSearchParams; headers: Record<string, string> } {
+  const query = new URLSearchParams();
+  const headers: Record<string, string> = {};
+
+  tool.parameters
+    .filter((param) => param.in !== "path")
+    .forEach((param) => {
+      const value = args[param.name];
+      if (value === undefined || value === null) {
+        if (param.required) {
+          throw new DispatchInputError(`Missing required ${param.in} parameter: ${param.name}`);
+        }
+        return;
+      }
+      if (param.in === "query") query.set(param.name, String(value));
+      else headers[param.name] = String(value);
+    });
+
+  return { query, headers };
+}
+
+/**
+ * Reconstruct the request body from the flat args using the routing metadata.
+ * Anything not claimed by a known body property is dropped — the input schema is
+ * `additionalProperties: false`, so a validated call never carries extras and an
+ * unvalidated one cannot smuggle fields upstream.
+ */
+function routeBody(tool: GeneratedTool, args: Record<string, unknown>): unknown {
+  if (tool.bodyIsWhole) return args.body;
+  if (!tool.bodyProps.length) return undefined;
+  const payload: Record<string, unknown> = {};
+  tool.bodyProps.forEach((key) => {
+    if (args[key] !== undefined) payload[key] = args[key];
+  });
+  return Object.keys(payload).length ? payload : undefined;
+}
+
+/**
+ * Execute one generated tool by proxying to its HTTP endpoint, forwarding the
+ * caller's bearer verbatim. This function performs NO authorization — the
+ * endpoint does, exactly as it would for a first-party request. That is the whole
+ * point of the passthrough: the agent can do precisely what the user can.
+ */
+export async function dispatchTool(
+  tool: GeneratedTool,
+  args: Record<string, unknown>,
+  config: DispatchConfig,
+): Promise<DispatchResult> {
+  const doFetch = config.fetchImpl ?? fetch;
+  const pathname = expandPath(tool, args);
+  const { query, headers } = routeParams(tool, args);
+  const body = routeBody(tool, args);
+
+  const url = new URL(pathname, config.baseUrl);
+  for (const [key, value] of query) url.searchParams.set(key, value);
+
+  // Carry the proxy origin as the standard reverse-proxy forwarded headers. The
+  // wrapped endpoint's auth guard re-derives the request origin (to check the
+  // access token's `aud`) WITHOUT a request object, so it can only see the origin
+  // through these headers. `baseUrl` is exactly the origin the token was minted
+  // and transport-verified against, so forwarding its scheme+host makes the
+  // wrapped guard reconstruct the SAME origin — the `aud` survives the replay in
+  // both dev (http) and prod (any proxied https origin). Omitting them let the
+  // guard default the scheme to https and 401 a valid http-minted bearer.
+  const base = new URL(config.baseUrl);
+
+  const init: RequestInit = {
+    method: tool.method,
+    headers: {
+      accept: "application/json",
+      authorization: `Bearer ${config.bearer}`,
+      "x-forwarded-proto": base.protocol.replace(/:$/, ""),
+      "x-forwarded-host": base.host,
+      ...headers,
+    },
+  };
+  if (body !== undefined) {
+    (init.headers as Record<string, string>)["content-type"] = "application/json";
+    init.body = JSON.stringify(body);
+  }
+
+  const response = await doFetch(url.toString(), init);
+  const text = await response.text();
+  let parsed: unknown = text;
+  const contentType = response.headers.get("content-type") ?? "";
+  if (contentType.includes("application/json") && text) {
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      parsed = text;
+    }
+  }
+
+  return { status: response.status, ok: response.ok, body: parsed };
+}

package/src/index.ts

@@ -0,0 +1,48 @@
+/**
+ * @12-apps/mcp — app-agnostic MCP server core.
+ *
+ * Turn an OpenAPI document into MCP tools (one per operation) and dispatch each
+ * tool call by proxying to the endpoint with the caller's bearer token, so an
+ * agent inherits exactly the user's permissions. The consuming app supplies the
+ * spec, the base URL, and an AuthResolver, and binds the ToolRegistry to the MCP
+ * transport (mounted at `/api/mcp`).
+ */
+
+export * from "./types";
+export { generateTools } from "./openapi/generate";
+export { inlineSchemaRefs, UnsupportedSchemaError } from "./openapi/refs";
+export type {
+  OpenApiDocument,
+  OpenApiOperation,
+  OpenApiParameter,
+  OpenApiRequestBody,
+  OpenApiResponse,
+} from "./openapi/generate";
+export { dispatchTool, DispatchInputError } from "./dispatch/proxy";
+export {
+  createToolRegistry,
+  type ToolRegistry,
+  type RegistryOptions,
+  type McpToolDescriptor,
+  type McpToolResult,
+} from "./server/registry";
+export {
+  buildManifest,
+  serializeManifest,
+  type BuildManifestOptions,
+} from "./server/manifest";
+// OAuth discovery — both halves of the MCP auth story kept together so the
+// future `@12-apps/mcp` extraction inherits them as one surface:
+// RFC 9728 protected-resource metadata + RFC 8414 authorization-server metadata.
+export {
+  buildProtectedResourceMetadata,
+  bearerChallenge,
+  PROTECTED_RESOURCE_METADATA_PATH,
+  type ProtectedResourceMetadata,
+  type ProtectedResourceMetadataInput,
+} from "./auth/resource-metadata";
+export {
+  buildAuthorizationServerMetadata,
+  type AuthorizationServerMetadata,
+  type AuthorizationServerMetadataInput,
+} from "./auth/authorization-server-metadata";