@lovable.dev/mcp-js 0.5.0 → 0.6.0

package/README.internal.md

@@ -0,0 +1,189 @@
+# @lovable.dev/mcp-js — internal notes
+
+Architecture rationale, source layout, and dev scripts for contributors. The user-facing docs are in [`README.md`](README.md); release rules and build-system constraints are in [`AGENTS.md`](AGENTS.md). Nothing in this file ships to npm — only `dist`, `package.json`, `README.md`, `LICENSE`, and `CHANGELOG.md` end up in the tarball.
+
+## Folder meaning
+
+- **`protocols/`** is the wire layer — one folder per externally observable HTTP surface. `protocols/mcp` is the public MCP-over-HTTP surface; `protocols/oauth-metadata` serves the RFC 9728 protected-resource metadata required to bootstrap protected MCP clients; `protocols/rest` is internal RPC for the upstream MCP proxy. Every backend wires both MCP and REST, plus the metadata endpoint when OAuth is configured.
+- **`auth/`** (unpublished) is the cross-cutting OAuth middleware — bearer verification, issuer/JWKS discovery, the `auth.oauth.*` config namespace. It depends only on `core/`; both `protocols/mcp` and `protocols/rest` depend on it for the shared bearer gate, so it isn't a wire-format peer of `mcp`/`rest` and doesn't live under `protocols/`.
+- **`stacks/`** is the framework integration: TanStack today; future entries (Supabase Edge Functions, classic Vite, …) live next to it under the same parent, forwarding to `protocols/{mcp,oauth-metadata,rest}` directly — protocol logic stays shared, only ctx unwrapping differs.
+
+## Design decisions
+
+### 1. Explicit `defineMcp({ tools })` over file-based discovery
+
+`defineTool` is a typed identity function. The user imports tools explicitly into `defineMcp({ tools: [...] })`. The Vite plugin scans nothing — it emits routes that read the user's array at runtime.
+
+Reasons:
+
+- **Implicit registration drifts silently.** Tool name + file name can disagree; duplicates only surface at runtime in `registerTool`.
+- **Refactoring is hostile.** Renaming a tool means renaming its file. Sub-directories require the plugin to recurse, and there's no clean convention for "implementation vs. helper" files.
+- **PR review can't grep the surface.** A reader can mentally check `tools: [echoTool, addTool]`; they cannot mentally check a directory scan.
+
+### 2. Build-time route emission via a Vite plugin
+
+TanStack's file-based router needs a route file on disk to register a URL. If we asked users to author the route file themselves, they'd own seven lines of plumbing that has to stay correct as the SDK's transport semantics evolve. Generating it lets us pin the wiring as a versioned package artifact — when the MCP SDK changes, the plugin emits a new template and every user picks it up on rebuild.
+
+This is the same insight that drives shipping an SDK instead of having the agent author the MCP runtime: bug fixes ship to all apps on the next build, not per-app.
+
+### 3. The `[.mcp]` URL prefix uses bracket escaping
+
+TanStack's file routing maps filenames to URLs and filters dot-prefixed entries as hidden — both directories (`src/routes/.mcp/...`) and flat files (`.mcp.list-tools.ts`). The escape is bracket-quoted literal segments: `[.mcp]/list-tools.ts` maps to `/.mcp/list-tools` and shows up in the generated route tree. The plugin emits at `src/routes/[.mcp]/list-tools.ts` and `src/routes/[.mcp]/invoke-tool/$tool.ts`.
+
+### 4. `invoke-tool/<tool>` instead of `<tool>` directly
+
+The `invoke-tool/` segment scopes the user-defined tool namespace, so future endpoints under `/.mcp/` (`list-tools`, `health`, `audit-log`, anything else added) can't collide with a user-defined tool named the same thing. Cheap upfront, breaking to add later.
+
+### 5. Dynamic tool resolution at runtime
+
+The dispatcher resolves the tool name against the live `mcp.tools` array on every request. From the caller's perspective `POST /.mcp/invoke-tool/echo` and `POST /.mcp/invoke-tool/add` look like separate endpoints; from the author's perspective the source of truth is one array. **Tool resolution is a per-request operation, not a per-build operation.**
+
+This is architectural foundation, not convenience. Resolution stays inside app code so it can grow:
+
+- **Per-user / per-scope tool visibility.** The lookup that maps `params.tool` to a handler can run *inside* app code, with access to the request's authenticated identity. An admin user might see `purge_workspace`; a regular user wouldn't see it in `list-tools` and would get a 404 from `invoke-tool`. Plan-tier gating, beta cohorts, feature flags, workspace roles — all want runtime context to decide what to expose.
+- **The build doesn't have user context.** Emitting per-tool files at build time would lock the tool catalog to the deploy. Dynamic resolution leaves that decision to the request lifecycle.
+- **The MCP and REST surfaces stay in sync automatically.** `tools/list` (over MCP) and `GET /.mcp/list-tools` (over REST) both read the same array. When per-user resolution lands, both surfaces filter through the same hook.
+
+`list-tools` stays a separate handler (not auto-injected into the dispatcher) because it's naturally a `GET` — distinct HTTP semantics from `invoke-tool`'s `POST`. The per-user filter will hook into both, but the HTTP shape stays clean.
+
+**Planned:** delegate the per-request tool-resolution step to app code via a hook (something like `resolveTools(ctx)` returning the subset of `mcp.tools` the caller can see). Until then, every authenticated caller sees the full array.
+
+### 6. Type-erased `AnyToolDefinition` at the array boundary
+
+`ToolDefinition<TInput>` is generic — the handler's args are inferred from `inputSchema`:
+
+```ts
+handler: TInput extends ZodRawShape
+  ? (args: ShapeOutput<TInput>) => ToolHandlerResult | Promise<...>
+  : () => ToolHandlerResult | Promise<...>;
+```
+
+This works per-tool at the `defineTool` call site. It breaks at the `defineMcp({ tools: [...] })` boundary because of **function-parameter contravariance**: a heterogeneous array of `ToolDefinition<{a}>` and `ToolDefinition<{b, c}>` can't collapse to one generic without rejecting at least one entry.
+
+`AnyToolDefinition` is the non-generic version used only at the array boundary, with `handler: (args: any) => ...`. `any` is bivariant in TypeScript, so any concrete handler assigns. Per-arg typing still happens inside `defineTool` — the only place it materially matters.
+
+### 7. Title, description, and instructions are required
+
+The MCP spec promoted `title` to a top-level field on `Tool` and `Server` in 2025-06-18+; we require it. We also require `description` on tools and `instructions` on servers because:
+
+- Both are read by LLMs as context for tool selection. A missing/templated description or instructions string produces agents that call the wrong tool or call none at all.
+- Optional prose fields encourage drift over time. Required-at-the-type-level enforces "intentional surface area" at PR-review time.
+- `instructions: ""` is the documented opt-out for servers that genuinely have nothing supplementary to say (single-purpose tools whose descriptions speak for themselves). Empty-string is intentional rather than accidental.
+
+The MCP spec's legacy `annotations.title` is omitted from our `ToolAnnotations` type — use the top-level `title` instead. Two locations for the same field encourage drift.
+
+### 8. Decoupled type surface from `@modelcontextprotocol/sdk`
+
+Two reasons:
+
+1. **`.d.ts` stability across SDK bumps.** The SDK's published type tree (`@modelcontextprotocol/sdk/types.js`) and its zod-compat shape generics have shipped breaking type-only changes between minor versions. Owning our own type re-declarations lets us bump the SDK's runtime without forcing every downstream consumer to re-type-check.
+2. **Optionality on the SDK itself.** If we ever swap or drop `@modelcontextprotocol/sdk` — different transport, in-house protocol implementation, a fork — consumers' code is the contract that matters, and it's typed against this package's surface, not the SDK's. The runtime hand-off can change without rippling through user code.
+
+The published `.d.ts` files import only from `zod` and `vite`. Three SDK concerns were re-implemented (or re-typed) locally:
+
+- **Content blocks and `ToolAnnotations`** — re-declared in `core/types.ts` to match the MCP wire format without depending on `@modelcontextprotocol/sdk/types.js`. The runtime still serializes via the SDK; only the type tree is owned.
+- **`ZodRawShape`, `ZodType`, `infer`** — sourced directly from `zod` (a peer dep). zod v3 and v4 both export all three at the top level; `ZodType` is non-deprecated in both versions with safe generic defaults. We re-export them from `core/types.ts` as `ZodRawShape` / `ZodSchema` / `ShapeOutput` (`ZodSchema` is a no-generic alias for `ZodType`). No dependency on `@modelcontextprotocol/sdk/server/zod-compat.js` types.
+- **`ContentBlock` union** — `TextContent | ImageContent | AudioContent | EmbeddedResource | ResourceLink`, structurally matching MCP's wire format. Consumers can type custom content (`return { content: [<ImageContent>, <TextContent>] }`) without referencing the SDK.
+
+The **runtime** still hands off to the MCP SDK — we still `import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"` and call `registerTool`, and we still use `objectFromShape` + `safeParseAsync` + `toJsonSchemaCompat` from the SDK's zod-compat module for REST input validation and JSON-Schema serialization. That's a runtime dependency, not a type-surface dependency.
+
+### 9. Stale-route cleanup on every regen
+
+The `GENERATED_BANNER` is the SDK's ownership token. Cleanup walks the whole `routesDir`, and any `.ts` file that carries the banner but is no longer in the current emit set gets unlinked. Catches two real cases:
+
+- **Plugin version upgrades** that move or rename a route. Without cleanup, a stale file keeps importing a symbol the package no longer exports and breaks the build.
+- **MCP entry removal.** Deleting `lib/mcp/index.ts` triggers the cleanup pass with an empty expected set; every banner-tagged file gets unlinked. Without this, the orphans still imported the deleted module and broke the build until removed by hand.
+
+Two consequences for user-authored files:
+
+- **Without the banner** (e.g., your own `src/routes/widgets.ts`): left alone. The banner is the only ownership signal, and it's 200+ idiosyncratic characters, so accidental collision is implausible.
+- **With the banner, anywhere under `routesDir`**: treated as SDK-owned and reclaimed if it isn't in the current emit set. To take ownership of such a file, delete the banner line — the plugin then leaves it alone. Conversely, a hand-authored file *at* an emit path *without* the banner makes `writeIfChanged` refuse with a build-time error — `refusing to overwrite user-authored route at <path>. Delete it or move it first.`
+
+## Layout
+
+```
+src/
+  index.ts                       # public entrypoint: defineTool/defineMcp, auth, ToolContext, public types
+  core/                          # framework-agnostic kernel; not a published subpath
+    define.ts                    # defineTool, defineMcp
+    types.ts                     # types (zod-sourced shape types, MCP wire types)
+    http.ts                      # Web-Standard Response helpers
+    url.ts                       # URL parsing/validation
+    validation.ts                # config assertions
+    promise.ts                   # cachedPromise (resolved-value cache)
+  auth/                          # cross-cutting OAuth middleware (unpublished); depends only on core/
+    config.ts                    # auth namespace: auth.oauth.issuer
+    authorize.ts                 # request authorizer, bearer parsing, challenges
+    verifier.ts                  # JWT verification and auth context construction
+    context.ts                   # ToolContext (verified auth passed to tool handlers)
+    claims.ts                    # JWT claim accessors (scope/string helpers)
+    discovery.ts                 # OAuth/OIDC metadata and JWKS URI discovery
+    resource.ts                  # protected-resource URL resolution
+    metadata-path.ts             # shared RFC 9728 metadata path constant
+    types.ts                     # auth config + context types
+  protocols/
+    oauth-metadata.ts            # createOAuthProtectedResourceMetadataHandler (RFC 9728 wire surface)
+    mcp/
+      protocol.ts                # createMcpProtocolHandler (Web-Standard)
+      index.ts                   # barrel
+    rest/
+      list-tools.ts              # createListToolsHandler (Web-Standard, GET)
+      invoke-tool.ts             # createInvokeToolHandler (Web-Standard, POST)
+      index.ts                   # barrel
+  stacks/
+    tanstack/
+      handlers.ts                # TanStack route-ctx adapters
+      vite.ts                    # mcpPlugin (route emission + stale-file cleanup)
+      index.ts                   # barrel
+tests/
+  core/{define,promise,url}.test.ts
+  auth/{claims,config,context,oauth}.test.ts  # OAuth config + bearer verification
+  protocols/
+    mcp/protocol.test.ts
+    rest/{list-tools,invoke-tool}.test.ts
+    parity.test.ts                   # REST↔MCP equivalence contract
+  stacks/
+    tanstack/{handlers,vite}.test.ts
+  integration/                       # boots an example app, hits live HTTP
+    global-setup.ts                  # spawns example/tanstack on :8080
+    tools.test.ts                    # non-OAuth example
+    oauth.test.ts                    # self-contained: mock issuer + OAuth example
+```
+
+## Scripts
+
+```bash
+pnpm format            # oxfmt --write src/ tests/
+pnpm format:check      # oxfmt --check src/ tests/
+pnpm lint              # format:check + oxlint (one command, both surfaces)
+pnpm lint:fix          # format + oxlint --fix
+pnpm typecheck         # tsgo --noEmit
+pnpm test              # vitest run --project unit  (fast, hermetic)
+pnpm test:watch        # vitest --project unit
+pnpm test:integration  # build + install example + vitest run --project integration
+pnpm test:integration:oauth # build + install OAuth example + vitest run --project integration-oauth
+pnpm build             # tsup → dist/{cjs,esm}/{index,protocols/*,stacks/*}
+pnpm pack:local        # build + npm pack into /tmp/lovable.dev-mcp-js-<version>.tgz
+pnpm example:install   # install example/tanstack deps (called by test:integration)
+pnpm example:oauth:install # install example/tanstack-supabase-oauth deps
+pnpm example:oauth:build   # production-build the OAuth example
+pnpm example:oauth:smoke   # smoke a running OAuth example, optionally with MCP_ACCESS_TOKEN
+```
+
+`lint` checks both formatting (oxfmt) and lint rules (oxlint) in one pass — the format check fails fast before the lint pass so you see the smaller diff first. `prepublishOnly` chains `clean → typecheck → test → build`; CI enforces `lint` separately.
+
+**Integration tests** live under `tests/integration/` and run against a live HTTP server. `pnpm test:integration` builds the SDK, installs `example/tanstack`, boots its dev server on port 8080 via a Vitest `globalSetup`, runs the suite, and tears the server down. If the server is already running at `MCP_BASE_URL` (default `http://localhost:8080`), the setup reuses it — useful when iterating on the suite. See `CHANGELOG.md` for version history.
+
+**OAuth integration test** (`tests/integration/oauth.test.ts`) is hermetic: `pnpm test:integration:oauth` builds + installs `example/tanstack-supabase-oauth`, then a self-contained `beforeAll` starts a mock RS256 issuer (JWKS + Supabase userinfo/PostgREST stubs), boots the example pointed at it on port 8081, signs a local test JWT, and asserts metadata, bearer challenges, and authorized REST + MCP calls. It runs in its own `integration-oauth` Vitest project (no shared `globalSetup`).
+
+**OAuth local loop** lives under `example/tanstack-supabase-oauth`. `pnpm example:oauth:dev` uses that example's checked-in `.env`, which points at the shared Lovable/Supabase test project; `pnpm example:oauth:smoke` verifies metadata/challenge behavior against a running example and, with `MCP_ACCESS_TOKEN`, authenticated calls.
+
+**Local-pack workflow** (for testing the SDK against a downstream consumer without publishing):
+
+```bash
+pnpm pack:local                              # → /tmp/lovable.dev-mcp-js-<version>.tgz
+cd path/to/your/app
+bun add /tmp/lovable.dev-mcp-js-<version>.tgz   # or `pnpm add`, `npm i`
+```
+
+Note: bun caches tarballs by absolute path. If you re-run `pack:local` without bumping the version, bun will re-extract from cache rather than picking up the new bytes. Bump `version` in `package.json` between iterations.

package/README.md

@@ -193,194 +193,4 @@ Use `auth.oauth.issuer(...)`, set `resource` or `acceptedAudiences` to anchor th
 | `@lovable.dev/mcp-js/stacks/tanstack`          | TanStack-route-ctx adapters (`createTanStack*Handler`)                  |
 | `@lovable.dev/mcp-js/stacks/tanstack/vite`     | The Vite plugin                                                         |
 
-The folders carry distinct meaning:
-
-- **`protocols/`** is the wire layer — one folder per externally observable HTTP surface. `protocols/mcp` is the public MCP-over-HTTP surface; `protocols/oauth-metadata` serves the RFC 9728 protected-resource metadata required to bootstrap protected MCP clients; `protocols/rest` is internal RPC for the upstream MCP proxy (see "What the plugin emits"). Every backend wires both MCP and REST, plus the metadata endpoint when OAuth is configured.
-- **`auth/`** (unpublished) is the cross-cutting OAuth middleware — bearer verification, issuer/JWKS discovery, the `auth.oauth.*` config namespace. It depends only on `core/`; both `protocols/mcp` and `protocols/rest` depend on it for the shared bearer gate, so it isn't a wire-format peer of `mcp`/`rest` and doesn't live under `protocols/`.
-- **`stacks/`** is the framework integration: TanStack today; future entries (Supabase Edge Functions, classic Vite, …) live next to it under the same parent.
-
-Generated route files import from `@lovable.dev/mcp-js/stacks/tanstack`. End users only need the root import. Future stacks (Supabase Edge, classic Vite, …) land under `stacks/` as siblings, forwarding to `protocols/{mcp,oauth-metadata,rest}` directly — protocol logic stays shared, only ctx unwrapping differs.
-
----
-
-## Design decisions
-
-### 1. Explicit `defineMcp({ tools })` over file-based discovery
-
-`defineTool` is a typed identity function. The user imports tools explicitly into `defineMcp({ tools: [...] })`. The Vite plugin scans nothing — it emits routes that read the user's array at runtime.
-
-Reasons:
-
-- **Implicit registration drifts silently.** Tool name + file name can disagree; duplicates only surface at runtime in `registerTool`.
-- **Refactoring is hostile.** Renaming a tool means renaming its file. Sub-directories require the plugin to recurse, and there's no clean convention for "implementation vs. helper" files.
-- **PR review can't grep the surface.** A reader can mentally check `tools: [echoTool, addTool]`; they cannot mentally check a directory scan.
-
-### 2. Build-time route emission via a Vite plugin
-
-TanStack's file-based router needs a route file on disk to register a URL. If we asked users to author the route file themselves, they'd own seven lines of plumbing that has to stay correct as the SDK's transport semantics evolve. Generating it lets us pin the wiring as a versioned package artifact — when the MCP SDK changes, the plugin emits a new template and every user picks it up on rebuild.
-
-This is the same insight that drives shipping an SDK instead of having the agent author the MCP runtime: bug fixes ship to all apps on the next build, not per-app.
-
-### 3. The `[.mcp]` URL prefix uses bracket escaping
-
-TanStack's file routing maps filenames to URLs and filters dot-prefixed entries as hidden — both directories (`src/routes/.mcp/...`) and flat files (`.mcp.list-tools.ts`). The escape is bracket-quoted literal segments: `[.mcp]/list-tools.ts` maps to `/.mcp/list-tools` and shows up in the generated route tree. The plugin emits at `src/routes/[.mcp]/list-tools.ts` and `src/routes/[.mcp]/invoke-tool/$tool.ts`.
-
-### 4. `invoke-tool/<tool>` instead of `<tool>` directly
-
-The `invoke-tool/` segment scopes the user-defined tool namespace, so future endpoints under `/.mcp/` (`list-tools`, `health`, `audit-log`, anything else added) can't collide with a user-defined tool named the same thing. Cheap upfront, breaking to add later.
-
-### 5. Dynamic tool resolution at runtime
-
-The dispatcher resolves the tool name against the live `mcp.tools` array on every request. From the caller's perspective `POST /.mcp/invoke-tool/echo` and `POST /.mcp/invoke-tool/add` look like separate endpoints; from the author's perspective the source of truth is one array. **Tool resolution is a per-request operation, not a per-build operation.**
-
-This is architectural foundation, not convenience. Resolution stays inside app code so it can grow:
-
-- **Per-user / per-scope tool visibility.** The lookup that maps `params.tool` to a handler can run *inside* app code, with access to the request's authenticated identity. An admin user might see `purge_workspace`; a regular user wouldn't see it in `list-tools` and would get a 404 from `invoke-tool`. Plan-tier gating, beta cohorts, feature flags, workspace roles — all want runtime context to decide what to expose.
-- **The build doesn't have user context.** Emitting per-tool files at build time would lock the tool catalog to the deploy. Dynamic resolution leaves that decision to the request lifecycle.
-- **The MCP and REST surfaces stay in sync automatically.** `tools/list` (over MCP) and `GET /.mcp/list-tools` (over REST) both read the same array. When per-user resolution lands, both surfaces filter through the same hook.
-
-`list-tools` stays a separate handler (not auto-injected into the dispatcher) because it's naturally a `GET` — distinct HTTP semantics from `invoke-tool`'s `POST`. The per-user filter will hook into both, but the HTTP shape stays clean.
-
-**Planned:** delegate the per-request tool-resolution step to app code via a hook (something like `resolveTools(ctx)` returning the subset of `mcp.tools` the caller can see). Until then, every authenticated caller sees the full array.
-
-### 6. Type-erased `AnyToolDefinition` at the array boundary
-
-`ToolDefinition<TInput>` is generic — the handler's args are inferred from `inputSchema`:
-
-```ts
-handler: TInput extends ZodRawShape
-  ? (args: ShapeOutput<TInput>) => ToolHandlerResult | Promise<...>
-  : () => ToolHandlerResult | Promise<...>;
-```
-
-This works per-tool at the `defineTool` call site. It breaks at the `defineMcp({ tools: [...] })` boundary because of **function-parameter contravariance**: a heterogeneous array of `ToolDefinition<{a}>` and `ToolDefinition<{b, c}>` can't collapse to one generic without rejecting at least one entry.
-
-`AnyToolDefinition` is the non-generic version used only at the array boundary, with `handler: (args: any) => ...`. `any` is bivariant in TypeScript, so any concrete handler assigns. Per-arg typing still happens inside `defineTool` — the only place it materially matters.
-
-### 7. Title, description, and instructions are required
-
-The MCP spec promoted `title` to a top-level field on `Tool` and `Server` in 2025-06-18+; we require it. We also require `description` on tools and `instructions` on servers because:
-
-- Both are read by LLMs as context for tool selection. A missing/templated description or instructions string produces agents that call the wrong tool or call none at all.
-- Optional prose fields encourage drift over time. Required-at-the-type-level enforces "intentional surface area" at PR-review time.
-- `instructions: ""` is the documented opt-out for servers that genuinely have nothing supplementary to say (single-purpose tools whose descriptions speak for themselves). Empty-string is intentional rather than accidental.
-
-The MCP spec's legacy `annotations.title` is omitted from our `ToolAnnotations` type — use the top-level `title` instead. Two locations for the same field encourage drift.
-
-### 8. Decoupled type surface from `@modelcontextprotocol/sdk`
-
-Two reasons:
-
-1. **`.d.ts` stability across SDK bumps.** The SDK's published type tree (`@modelcontextprotocol/sdk/types.js`) and its zod-compat shape generics have shipped breaking type-only changes between minor versions. Owning our own type re-declarations lets us bump the SDK's runtime without forcing every downstream consumer to re-type-check.
-2. **Optionality on the SDK itself.** If we ever swap or drop `@modelcontextprotocol/sdk` — different transport, in-house protocol implementation, a fork — consumers' code is the contract that matters, and it's typed against this package's surface, not the SDK's. The runtime hand-off can change without rippling through user code.
-
-The published `.d.ts` files import only from `zod` and `vite`. Three SDK concerns were re-implemented (or re-typed) locally:
-
-- **Content blocks and `ToolAnnotations`** — re-declared in `core/types.ts` to match the MCP wire format without depending on `@modelcontextprotocol/sdk/types.js`. The runtime still serializes via the SDK; only the type tree is owned.
-- **`ZodRawShape`, `ZodType`, `infer`** — sourced directly from `zod` (a peer dep). zod v3 and v4 both export all three at the top level; `ZodType` is non-deprecated in both versions with safe generic defaults. We re-export them from `core/types.ts` as `ZodRawShape` / `ZodSchema` / `ShapeOutput` (`ZodSchema` is a no-generic alias for `ZodType`). No dependency on `@modelcontextprotocol/sdk/server/zod-compat.js` types.
-- **`ContentBlock` union** — `TextContent | ImageContent | AudioContent | EmbeddedResource | ResourceLink`, structurally matching MCP's wire format. Consumers can type custom content (`return { content: [<ImageContent>, <TextContent>] }`) without referencing the SDK.
-
-The **runtime** still hands off to the MCP SDK — we still `import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"` and call `registerTool`, and we still use `objectFromShape` + `safeParseAsync` + `toJsonSchemaCompat` from the SDK's zod-compat module for REST input validation and JSON-Schema serialization. That's a runtime dependency, not a type-surface dependency.
-
-### 9. Stale-route cleanup on every regen
-
-The `GENERATED_BANNER` is the SDK's ownership token. Cleanup walks the whole `routesDir`, and any `.ts` file that carries the banner but is no longer in the current emit set gets unlinked. Catches two real cases:
-
-- **Plugin version upgrades** that move or rename a route. Without cleanup, a stale file keeps importing a symbol the package no longer exports and breaks the build.
-- **MCP entry removal.** Deleting `lib/mcp/index.ts` triggers the cleanup pass with an empty expected set; every banner-tagged file gets unlinked. Without this, the orphans still imported the deleted module and broke the build until removed by hand.
-
-Two consequences for user-authored files:
-
-- **Without the banner** (e.g., your own `src/routes/widgets.ts`): left alone. The banner is the only ownership signal, and it's 200+ idiosyncratic characters, so accidental collision is implausible.
-- **With the banner, anywhere under `routesDir`**: treated as SDK-owned and reclaimed if it isn't in the current emit set. To take ownership of such a file, delete the banner line — the plugin then leaves it alone. Conversely, a hand-authored file *at* an emit path *without* the banner makes `writeIfChanged` refuse with a build-time error — `refusing to overwrite user-authored route at <path>. Delete it or move it first.`
-
----
-
-## Layout
-
-```
-src/
-  index.ts                       # public entrypoint: defineTool/defineMcp, auth, ToolContext, public types
-  core/                          # framework-agnostic kernel; not a published subpath
-    define.ts                    # defineTool, defineMcp
-    types.ts                     # types (zod-sourced shape types, MCP wire types)
-    http.ts                      # Web-Standard Response helpers
-    url.ts                       # URL parsing/validation
-    validation.ts                # config assertions
-    promise.ts                   # cachedPromise (resolved-value cache)
-  auth/                          # cross-cutting OAuth middleware (unpublished); depends only on core/
-    config.ts                    # auth namespace: auth.oauth.issuer
-    authorize.ts                 # request authorizer, bearer parsing, challenges
-    verifier.ts                  # JWT verification and auth context construction
-    context.ts                   # ToolContext (verified auth passed to tool handlers)
-    claims.ts                    # JWT claim accessors (scope/string helpers)
-    discovery.ts                 # OAuth/OIDC metadata and JWKS URI discovery
-    resource.ts                  # protected-resource URL resolution
-    metadata-path.ts             # shared RFC 9728 metadata path constant
-    types.ts                     # auth config + context types
-  protocols/
-    oauth-metadata.ts            # createOAuthProtectedResourceMetadataHandler (RFC 9728 wire surface)
-    mcp/
-      protocol.ts                # createMcpProtocolHandler (Web-Standard)
-      index.ts                   # barrel
-    rest/
-      list-tools.ts              # createListToolsHandler (Web-Standard, GET)
-      invoke-tool.ts             # createInvokeToolHandler (Web-Standard, POST)
-      index.ts                   # barrel
-  stacks/
-    tanstack/
-      handlers.ts                # TanStack route-ctx adapters
-      vite.ts                    # mcpPlugin (route emission + stale-file cleanup)
-      index.ts                   # barrel
-tests/
-  core/{define,promise,url}.test.ts
-  auth/{claims,config,context,oauth}.test.ts  # OAuth config + bearer verification
-  protocols/
-    mcp/protocol.test.ts
-    rest/{list-tools,invoke-tool}.test.ts
-    parity.test.ts                   # REST↔MCP equivalence contract
-  stacks/
-    tanstack/{handlers,vite}.test.ts
-  integration/                       # boots an example app, hits live HTTP
-    global-setup.ts                  # spawns example/tanstack on :8080
-    tools.test.ts                    # non-OAuth example
-    oauth.test.ts                    # self-contained: mock issuer + OAuth example
-```
-
-## Scripts
-
-```bash
-pnpm format            # oxfmt --write src/ tests/
-pnpm format:check      # oxfmt --check src/ tests/
-pnpm lint              # format:check + oxlint (one command, both surfaces)
-pnpm lint:fix          # format + oxlint --fix
-pnpm typecheck         # tsgo --noEmit
-pnpm test              # vitest run --project unit  (fast, hermetic)
-pnpm test:watch        # vitest --project unit
-pnpm test:integration  # build + install example + vitest run --project integration
-pnpm test:integration:oauth # build + install OAuth example + vitest run --project integration-oauth
-pnpm build             # tsup → dist/{cjs,esm}/{index,protocols/*,stacks/*}
-pnpm pack:local        # build + npm pack into /tmp/lovable.dev-mcp-js-<version>.tgz
-pnpm example:install   # install example/tanstack deps (called by test:integration)
-pnpm example:oauth:install # install example/tanstack-supabase-oauth deps
-pnpm example:oauth:build   # production-build the OAuth example
-pnpm example:oauth:smoke   # smoke a running OAuth example, optionally with MCP_ACCESS_TOKEN
-```
-
-`lint` checks both formatting (oxfmt) and lint rules (oxlint) in one pass — the format check fails fast before the lint pass so you see the smaller diff first. `prepublishOnly` chains `clean → typecheck → test → build`; CI enforces `lint` separately.
-
-**Integration tests** live under `tests/integration/` and run against a live HTTP server. `pnpm test:integration` builds the SDK, installs `example/tanstack`, boots its dev server on port 8080 via a Vitest `globalSetup`, runs the suite, and tears the server down. If the server is already running at `MCP_BASE_URL` (default `http://localhost:8080`), the setup reuses it — useful when iterating on the suite. See `CHANGELOG.md` for version history.
-
-**OAuth integration test** (`tests/integration/oauth.test.ts`) is hermetic: `pnpm test:integration:oauth` builds + installs `example/tanstack-supabase-oauth`, then a self-contained `beforeAll` starts a mock RS256 issuer (JWKS + Supabase userinfo/PostgREST stubs), boots the example pointed at it on port 8081, signs a local test JWT, and asserts metadata, bearer challenges, and authorized REST + MCP calls. It runs in its own `integration-oauth` Vitest project (no shared `globalSetup`).
-
-**OAuth local loop** lives under `example/tanstack-supabase-oauth`. `pnpm example:oauth:dev` uses that example's checked-in `.env`, which points at the shared Lovable/Supabase test project; `pnpm example:oauth:smoke` verifies metadata/challenge behavior against a running example and, with `MCP_ACCESS_TOKEN`, authenticated calls.
-
-**Local-pack workflow** (for testing the SDK against a downstream consumer without publishing):
-
-```bash
-pnpm pack:local                              # → /tmp/lovable.dev-mcp-js-<version>.tgz
-cd path/to/your/app
-bun add /tmp/lovable.dev-mcp-js-<version>.tgz   # or `pnpm add`, `npm i`
-```
-
-Note: bun caches tarballs by absolute path. If you re-run `pack:local` without bumping the version, bun will re-extract from cache rather than picking up the new bytes. Bump `version` in `package.json` between iterations.
+End users only need the root import (`@lovable.dev/mcp-js`). Generated route files import from `@lovable.dev/mcp-js/stacks/tanstack`. The other subpaths are escape hatches for hand-wiring custom stacks against the protocol layer directly.

package/dist/{chunk-DDF63QWG.js → chunk-K2T4WTKX.js}

@@ -1,25 +1,24 @@
 import {
   JSON_HEADERS,
+  corsPreflightResponse,
   getOAuthRuntime,
   headResponse,
   methodNotAllowed,
   oauthConfigurationErrorResponse,
-  resolveProtectedResource
-} from "./chunk-XEDRJFAR.js";
+  resolveProtectedResource,
+  withCors
+} from "./chunk-ZKKLOL2C.js";
 
 // src/protocols/oauth-metadata.ts
-var CORS_ORIGIN = { "Access-Control-Allow-Origin": "*" };
-function withCors(response) {
-  response.headers.set("Access-Control-Allow-Origin", "*");
-  return response;
-}
 function notFound() {
-  return new Response(JSON.stringify({ error: "not found" }), {
-    status: 404,
-    // `no-store` so a 404 (OAuth unconfigured) isn't heuristically cached and
-    // then served past a later deploy that enables OAuth and starts returning 200.
-    headers: { ...JSON_HEADERS, ...CORS_ORIGIN, "Cache-Control": "no-store" }
-  });
+  return withCors(
+    new Response(JSON.stringify({ error: "not found" }), {
+      status: 404,
+      // `no-store` so a 404 (OAuth unconfigured) isn't heuristically cached and
+      // then served past a later deploy that enables OAuth and starts returning 200.
+      headers: { ...JSON_HEADERS, "Cache-Control": "no-store" }
+    })
+  );
 }
 async function buildProtectedResourceMetadata(mcp, auth, request, options, discovery) {
   const issuer = await discovery.resolveIssuer();
@@ -44,17 +43,12 @@ function createOAuthProtectedResourceMetadataHandler(mcp, options = {}) {
   return async (request) => {
     if (runtime.kind !== "configured" || runtime.auth.protectedResourceMetadataUrl !== void 0)
       return notFound();
-    if (request.method === "OPTIONS") {
-      return new Response(null, {
-        status: 204,
-        headers: { ...CORS_ORIGIN, "Access-Control-Allow-Methods": "GET, HEAD, OPTIONS" }
-      });
-    }
+    if (request.method === "OPTIONS")
+      return corsPreflightResponse("GET, HEAD, OPTIONS");
     if (request.method !== "GET" && request.method !== "HEAD")
       return withCors(methodNotAllowed("GET, HEAD, OPTIONS"));
     const headers = {
       ...JSON_HEADERS,
-      ...CORS_ORIGIN,
       "Cache-Control": "public, max-age=300",
       Vary: "Host"
     };
@@ -66,7 +60,7 @@ function createOAuthProtectedResourceMetadataHandler(mcp, options = {}) {
         runtime.options,
         runtime.discovery
       );
-      const response = Response.json(metadata, { headers });
+      const response = withCors(Response.json(metadata, { headers }));
       return request.method === "HEAD" ? headResponse(response) : response;
     } catch {
       const response = withCors(oauthConfigurationErrorResponse());

package/dist/{chunk-GLG5RZGE.js → chunk-NJ5WBRYI.js}

@@ -2,8 +2,10 @@ import {
   ToolContext
 } from "./chunk-MA5H6PSF.js";
 import {
-  createRequestAuthorizer
-} from "./chunk-XEDRJFAR.js";
+  corsPreflightResponse,
+  createRequestAuthorizer,
+  withCors
+} from "./chunk-ZKKLOL2C.js";
 
 // src/protocols/mcp/protocol.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -25,7 +27,7 @@ function adaptToolToSdkCallback(tool, auth) {
 }
 function createMcpProtocolHandler(mcp, options = {}) {
   const authorizer = createRequestAuthorizer(mcp, options);
-  return async (request) => {
+  const handle = async (request) => {
     const authResult = await authorizer.authorize(request);
     if (!authResult.ok)
       return authResult.response;
@@ -59,6 +61,11 @@ function createMcpProtocolHandler(mcp, options = {}) {
       );
     }
   };
+  return async (request) => {
+    if (request.method === "OPTIONS")
+      return corsPreflightResponse("GET, POST, DELETE, OPTIONS");
+    return withCors(await handle(request));
+  };
 }
 
 export {

package/dist/{chunk-VD6CS7Y6.js → chunk-SYI32IRK.js}

@@ -4,10 +4,12 @@ import {
 import {
   JSON_HEADERS,
   assertRestResourceBinding,
+  corsPreflightResponse,
   createRequestAuthorizer,
   headResponse,
-  methodNotAllowed
-} from "./chunk-XEDRJFAR.js";
+  methodNotAllowed,
+  withCors
+} from "./chunk-ZKKLOL2C.js";
 
 // src/protocols/rest/list-tools.ts
 import { objectFromShape } from "@modelcontextprotocol/sdk/server/zod-compat.js";
@@ -24,12 +26,12 @@ function shapeToJsonSchema(shape) {
 function createListToolsHandler(mcp, options = {}) {
   assertRestResourceBinding(mcp, options);
   const authorizer = createRequestAuthorizer(mcp, options);
-  return async (request) => {
+  const handle = async (request) => {
     const authResult = await authorizer.authorize(request);
     if (!authResult.ok)
       return authResult.response;
     if (request.method !== "GET" && request.method !== "HEAD")
-      return methodNotAllowed("GET, HEAD");
+      return methodNotAllowed("GET, HEAD, OPTIONS");
     const body = {
       server: { name: mcp.name, version: mcp.version, title: mcp.title },
       tools: mcp.tools.map((tool) => ({
@@ -44,6 +46,11 @@ function createListToolsHandler(mcp, options = {}) {
     const response = Response.json(body);
     return request.method === "HEAD" ? headResponse(response) : response;
   };
+  return async (request) => {
+    if (request.method === "OPTIONS")
+      return corsPreflightResponse("GET, HEAD, OPTIONS");
+    return withCors(await handle(request));
+  };
 }
 
 // src/protocols/rest/invoke-tool.ts
@@ -63,12 +70,12 @@ function isEmptyArgs(value) {
 function createInvokeToolHandler(mcp, options = {}) {
   assertRestResourceBinding(mcp, options);
   const authorizer = createRequestAuthorizer(mcp, options);
-  return async (request, toolName) => {
+  const handle = async (request, toolName) => {
     const authResult = await authorizer.authorize(request);
     if (!authResult.ok)
       return authResult.response;
     if (request.method !== "POST")
-      return methodNotAllowed("POST");
+      return methodNotAllowed("POST, OPTIONS");
     const tool = mcp.tools.find((t) => t.name === toolName);
     if (!tool) {
       return new Response(JSON.stringify({ error: `unknown tool: ${safeReflectName(toolName)}` }), {
@@ -136,6 +143,11 @@ function createInvokeToolHandler(mcp, options = {}) {
       isError: result.isError
     });
   };
+  return async (request, toolName) => {
+    if (request.method === "OPTIONS")
+      return corsPreflightResponse("POST, OPTIONS");
+    return withCors(await handle(request, toolName));
+  };
 }
 
 export {

package/dist/{chunk-XEDRJFAR.js → chunk-ZKKLOL2C.js}

@@ -359,6 +359,26 @@ function createRequestAuthorizer(mcp, options = {}) {
   };
 }
 
+// src/core/cors.ts
+var EXPOSE_HEADERS = "WWW-Authenticate, Mcp-Session-Id, Mcp-Protocol-Version";
+var ALLOW_HEADERS = "Authorization, Content-Type, Mcp-Session-Id, Mcp-Protocol-Version, Last-Event-ID";
+function withCors(response) {
+  response.headers.set("Access-Control-Allow-Origin", "*");
+  response.headers.set("Access-Control-Expose-Headers", EXPOSE_HEADERS);
+  return response;
+}
+function corsPreflightResponse(allowMethods) {
+  return new Response(null, {
+    status: 204,
+    headers: {
+      "Access-Control-Allow-Origin": "*",
+      "Access-Control-Allow-Methods": allowMethods,
+      "Access-Control-Allow-Headers": ALLOW_HEADERS,
+      "Access-Control-Max-Age": "86400"
+    }
+  });
+}
+
 export {
   JSON_HEADERS,
   headResponse,
@@ -367,5 +387,7 @@ export {
   oauthConfigurationErrorResponse,
   getOAuthRuntime,
   assertRestResourceBinding,
-  createRequestAuthorizer
+  createRequestAuthorizer,
+  withCors,
+  corsPreflightResponse
 };

package/dist/protocols/mcp/index.cjs

@@ -446,6 +446,26 @@ var ToolContext = class {
   }
 };
 
+// src/core/cors.ts
+var EXPOSE_HEADERS = "WWW-Authenticate, Mcp-Session-Id, Mcp-Protocol-Version";
+var ALLOW_HEADERS = "Authorization, Content-Type, Mcp-Session-Id, Mcp-Protocol-Version, Last-Event-ID";
+function withCors(response) {
+  response.headers.set("Access-Control-Allow-Origin", "*");
+  response.headers.set("Access-Control-Expose-Headers", EXPOSE_HEADERS);
+  return response;
+}
+function corsPreflightResponse(allowMethods) {
+  return new Response(null, {
+    status: 204,
+    headers: {
+      "Access-Control-Allow-Origin": "*",
+      "Access-Control-Allow-Methods": allowMethods,
+      "Access-Control-Allow-Headers": ALLOW_HEADERS,
+      "Access-Control-Max-Age": "86400"
+    }
+  });
+}
+
 // src/protocols/mcp/protocol.ts
 function adaptToolToSdkCallback(tool, auth) {
   return async (first) => {
@@ -464,7 +484,7 @@ function adaptToolToSdkCallback(tool, auth) {
 }
 function createMcpProtocolHandler(mcp, options = {}) {
   const authorizer = createRequestAuthorizer(mcp, options);
-  return async (request) => {
+  const handle = async (request) => {
     const authResult = await authorizer.authorize(request);
     if (!authResult.ok)
       return authResult.response;
@@ -498,6 +518,11 @@ function createMcpProtocolHandler(mcp, options = {}) {
       );
     }
   };
+  return async (request) => {
+    if (request.method === "OPTIONS")
+      return corsPreflightResponse("GET, POST, DELETE, OPTIONS");
+    return withCors(await handle(request));
+  };
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/protocols/mcp/index.js

@@ -1,8 +1,8 @@
 import {
   createMcpProtocolHandler
-} from "../../chunk-GLG5RZGE.js";
+} from "../../chunk-NJ5WBRYI.js";
 import "../../chunk-MA5H6PSF.js";
-import "../../chunk-XEDRJFAR.js";
+import "../../chunk-ZKKLOL2C.js";
 import "../../chunk-QA3FWDUV.js";
 import "../../chunk-6DXGZZA4.js";
 export {

package/dist/protocols/oauth-metadata.cjs

@@ -317,20 +317,37 @@ function getOAuthRuntime(mcp, options = {}) {
   };
 }
 
-// src/protocols/oauth-metadata.ts
-var CORS_ORIGIN = { "Access-Control-Allow-Origin": "*" };
+// src/core/cors.ts
+var EXPOSE_HEADERS = "WWW-Authenticate, Mcp-Session-Id, Mcp-Protocol-Version";
+var ALLOW_HEADERS = "Authorization, Content-Type, Mcp-Session-Id, Mcp-Protocol-Version, Last-Event-ID";
 function withCors(response) {
   response.headers.set("Access-Control-Allow-Origin", "*");
+  response.headers.set("Access-Control-Expose-Headers", EXPOSE_HEADERS);
   return response;
 }
-function notFound() {
-  return new Response(JSON.stringify({ error: "not found" }), {
-    status: 404,
-    // `no-store` so a 404 (OAuth unconfigured) isn't heuristically cached and
-    // then served past a later deploy that enables OAuth and starts returning 200.
-    headers: { ...JSON_HEADERS, ...CORS_ORIGIN, "Cache-Control": "no-store" }
+function corsPreflightResponse(allowMethods) {
+  return new Response(null, {
+    status: 204,
+    headers: {
+      "Access-Control-Allow-Origin": "*",
+      "Access-Control-Allow-Methods": allowMethods,
+      "Access-Control-Allow-Headers": ALLOW_HEADERS,
+      "Access-Control-Max-Age": "86400"
+    }
   });
 }
+
+// src/protocols/oauth-metadata.ts
+function notFound() {
+  return withCors(
+    new Response(JSON.stringify({ error: "not found" }), {
+      status: 404,
+      // `no-store` so a 404 (OAuth unconfigured) isn't heuristically cached and
+      // then served past a later deploy that enables OAuth and starts returning 200.
+      headers: { ...JSON_HEADERS, "Cache-Control": "no-store" }
+    })
+  );
+}
 async function buildProtectedResourceMetadata(mcp, auth, request, options, discovery) {
   const issuer = await discovery.resolveIssuer();
   const body = {
@@ -354,17 +371,12 @@ function createOAuthProtectedResourceMetadataHandler(mcp, options = {}) {
   return async (request) => {
     if (runtime.kind !== "configured" || runtime.auth.protectedResourceMetadataUrl !== void 0)
       return notFound();
-    if (request.method === "OPTIONS") {
-      return new Response(null, {
-        status: 204,
-        headers: { ...CORS_ORIGIN, "Access-Control-Allow-Methods": "GET, HEAD, OPTIONS" }
-      });
-    }
+    if (request.method === "OPTIONS")
+      return corsPreflightResponse("GET, HEAD, OPTIONS");
     if (request.method !== "GET" && request.method !== "HEAD")
       return withCors(methodNotAllowed("GET, HEAD, OPTIONS"));
     const headers = {
       ...JSON_HEADERS,
-      ...CORS_ORIGIN,
       "Cache-Control": "public, max-age=300",
       Vary: "Host"
     };
@@ -376,7 +388,7 @@ function createOAuthProtectedResourceMetadataHandler(mcp, options = {}) {
         runtime.options,
         runtime.discovery
       );
-      const response = Response.json(metadata, { headers });
+      const response = withCors(Response.json(metadata, { headers }));
       return request.method === "HEAD" ? headResponse(response) : response;
     } catch {
       const response = withCors(oauthConfigurationErrorResponse());

package/dist/protocols/oauth-metadata.js

@@ -1,7 +1,7 @@
 import {
   createOAuthProtectedResourceMetadataHandler
-} from "../chunk-DDF63QWG.js";
-import "../chunk-XEDRJFAR.js";
+} from "../chunk-K2T4WTKX.js";
+import "../chunk-ZKKLOL2C.js";
 import "../chunk-QA3FWDUV.js";
 import "../chunk-6DXGZZA4.js";
 export {

package/dist/protocols/rest/index.cjs

@@ -421,6 +421,26 @@ function createRequestAuthorizer(mcp, options = {}) {
   };
 }
 
+// src/core/cors.ts
+var EXPOSE_HEADERS = "WWW-Authenticate, Mcp-Session-Id, Mcp-Protocol-Version";
+var ALLOW_HEADERS = "Authorization, Content-Type, Mcp-Session-Id, Mcp-Protocol-Version, Last-Event-ID";
+function withCors(response) {
+  response.headers.set("Access-Control-Allow-Origin", "*");
+  response.headers.set("Access-Control-Expose-Headers", EXPOSE_HEADERS);
+  return response;
+}
+function corsPreflightResponse(allowMethods) {
+  return new Response(null, {
+    status: 204,
+    headers: {
+      "Access-Control-Allow-Origin": "*",
+      "Access-Control-Allow-Methods": allowMethods,
+      "Access-Control-Allow-Headers": ALLOW_HEADERS,
+      "Access-Control-Max-Age": "86400"
+    }
+  });
+}
+
 // src/protocols/rest/list-tools.ts
 function shapeToJsonSchema(shape) {
   if (!shape)
@@ -434,12 +454,12 @@ function shapeToJsonSchema(shape) {
 function createListToolsHandler(mcp, options = {}) {
   assertRestResourceBinding(mcp, options);
   const authorizer = createRequestAuthorizer(mcp, options);
-  return async (request) => {
+  const handle = async (request) => {
     const authResult = await authorizer.authorize(request);
     if (!authResult.ok)
       return authResult.response;
     if (request.method !== "GET" && request.method !== "HEAD")
-      return methodNotAllowed("GET, HEAD");
+      return methodNotAllowed("GET, HEAD, OPTIONS");
     const body = {
       server: { name: mcp.name, version: mcp.version, title: mcp.title },
       tools: mcp.tools.map((tool) => ({
@@ -454,6 +474,11 @@ function createListToolsHandler(mcp, options = {}) {
     const response = Response.json(body);
     return request.method === "HEAD" ? headResponse(response) : response;
   };
+  return async (request) => {
+    if (request.method === "OPTIONS")
+      return corsPreflightResponse("GET, HEAD, OPTIONS");
+    return withCors(await handle(request));
+  };
 }
 
 // src/protocols/rest/invoke-tool.ts
@@ -518,12 +543,12 @@ function isEmptyArgs(value) {
 function createInvokeToolHandler(mcp, options = {}) {
   assertRestResourceBinding(mcp, options);
   const authorizer = createRequestAuthorizer(mcp, options);
-  return async (request, toolName) => {
+  const handle = async (request, toolName) => {
     const authResult = await authorizer.authorize(request);
     if (!authResult.ok)
       return authResult.response;
     if (request.method !== "POST")
-      return methodNotAllowed("POST");
+      return methodNotAllowed("POST, OPTIONS");
     const tool = mcp.tools.find((t) => t.name === toolName);
     if (!tool) {
       return new Response(JSON.stringify({ error: `unknown tool: ${safeReflectName(toolName)}` }), {
@@ -591,6 +616,11 @@ function createInvokeToolHandler(mcp, options = {}) {
       isError: result.isError
     });
   };
+  return async (request, toolName) => {
+    if (request.method === "OPTIONS")
+      return corsPreflightResponse("POST, OPTIONS");
+    return withCors(await handle(request, toolName));
+  };
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/protocols/rest/index.js

@@ -1,9 +1,9 @@
 import {
   createInvokeToolHandler,
   createListToolsHandler
-} from "../../chunk-VD6CS7Y6.js";
+} from "../../chunk-SYI32IRK.js";
 import "../../chunk-MA5H6PSF.js";
-import "../../chunk-XEDRJFAR.js";
+import "../../chunk-ZKKLOL2C.js";
 import "../../chunk-QA3FWDUV.js";
 import "../../chunk-6DXGZZA4.js";
 export {

package/dist/stacks/tanstack/index.cjs

@@ -466,6 +466,26 @@ var ToolContext = class {
   }
 };
 
+// src/core/cors.ts
+var EXPOSE_HEADERS = "WWW-Authenticate, Mcp-Session-Id, Mcp-Protocol-Version";
+var ALLOW_HEADERS = "Authorization, Content-Type, Mcp-Session-Id, Mcp-Protocol-Version, Last-Event-ID";
+function withCors(response) {
+  response.headers.set("Access-Control-Allow-Origin", "*");
+  response.headers.set("Access-Control-Expose-Headers", EXPOSE_HEADERS);
+  return response;
+}
+function corsPreflightResponse(allowMethods) {
+  return new Response(null, {
+    status: 204,
+    headers: {
+      "Access-Control-Allow-Origin": "*",
+      "Access-Control-Allow-Methods": allowMethods,
+      "Access-Control-Allow-Headers": ALLOW_HEADERS,
+      "Access-Control-Max-Age": "86400"
+    }
+  });
+}
+
 // src/protocols/mcp/protocol.ts
 function adaptToolToSdkCallback(tool, auth) {
   return async (first) => {
@@ -484,7 +504,7 @@ function adaptToolToSdkCallback(tool, auth) {
 }
 function createMcpProtocolHandler(mcp, options = {}) {
   const authorizer = createRequestAuthorizer(mcp, options);
-  return async (request) => {
+  const handle = async (request) => {
     const authResult = await authorizer.authorize(request);
     if (!authResult.ok)
       return authResult.response;
@@ -518,21 +538,23 @@ function createMcpProtocolHandler(mcp, options = {}) {
       );
     }
   };
+  return async (request) => {
+    if (request.method === "OPTIONS")
+      return corsPreflightResponse("GET, POST, DELETE, OPTIONS");
+    return withCors(await handle(request));
+  };
 }
 
 // src/protocols/oauth-metadata.ts
-var CORS_ORIGIN = { "Access-Control-Allow-Origin": "*" };
-function withCors(response) {
-  response.headers.set("Access-Control-Allow-Origin", "*");
-  return response;
-}
 function notFound() {
-  return new Response(JSON.stringify({ error: "not found" }), {
-    status: 404,
-    // `no-store` so a 404 (OAuth unconfigured) isn't heuristically cached and
-    // then served past a later deploy that enables OAuth and starts returning 200.
-    headers: { ...JSON_HEADERS, ...CORS_ORIGIN, "Cache-Control": "no-store" }
-  });
+  return withCors(
+    new Response(JSON.stringify({ error: "not found" }), {
+      status: 404,
+      // `no-store` so a 404 (OAuth unconfigured) isn't heuristically cached and
+      // then served past a later deploy that enables OAuth and starts returning 200.
+      headers: { ...JSON_HEADERS, "Cache-Control": "no-store" }
+    })
+  );
 }
 async function buildProtectedResourceMetadata(mcp, auth, request, options, discovery) {
   const issuer = await discovery.resolveIssuer();
@@ -557,17 +579,12 @@ function createOAuthProtectedResourceMetadataHandler(mcp, options = {}) {
   return async (request) => {
     if (runtime.kind !== "configured" || runtime.auth.protectedResourceMetadataUrl !== void 0)
       return notFound();
-    if (request.method === "OPTIONS") {
-      return new Response(null, {
-        status: 204,
-        headers: { ...CORS_ORIGIN, "Access-Control-Allow-Methods": "GET, HEAD, OPTIONS" }
-      });
-    }
+    if (request.method === "OPTIONS")
+      return corsPreflightResponse("GET, HEAD, OPTIONS");
     if (request.method !== "GET" && request.method !== "HEAD")
       return withCors(methodNotAllowed("GET, HEAD, OPTIONS"));
     const headers = {
       ...JSON_HEADERS,
-      ...CORS_ORIGIN,
       "Cache-Control": "public, max-age=300",
       Vary: "Host"
     };
@@ -579,7 +596,7 @@ function createOAuthProtectedResourceMetadataHandler(mcp, options = {}) {
         runtime.options,
         runtime.discovery
       );
-      const response = Response.json(metadata, { headers });
+      const response = withCors(Response.json(metadata, { headers }));
       return request.method === "HEAD" ? headResponse(response) : response;
     } catch {
       const response = withCors(oauthConfigurationErrorResponse());
@@ -603,12 +620,12 @@ function shapeToJsonSchema(shape) {
 function createListToolsHandler(mcp, options = {}) {
   assertRestResourceBinding(mcp, options);
   const authorizer = createRequestAuthorizer(mcp, options);
-  return async (request) => {
+  const handle = async (request) => {
     const authResult = await authorizer.authorize(request);
     if (!authResult.ok)
       return authResult.response;
     if (request.method !== "GET" && request.method !== "HEAD")
-      return methodNotAllowed("GET, HEAD");
+      return methodNotAllowed("GET, HEAD, OPTIONS");
     const body = {
       server: { name: mcp.name, version: mcp.version, title: mcp.title },
       tools: mcp.tools.map((tool) => ({
@@ -623,6 +640,11 @@ function createListToolsHandler(mcp, options = {}) {
     const response = Response.json(body);
     return request.method === "HEAD" ? headResponse(response) : response;
   };
+  return async (request) => {
+    if (request.method === "OPTIONS")
+      return corsPreflightResponse("GET, HEAD, OPTIONS");
+    return withCors(await handle(request));
+  };
 }
 
 // src/protocols/rest/invoke-tool.ts
@@ -642,12 +664,12 @@ function isEmptyArgs(value) {
 function createInvokeToolHandler(mcp, options = {}) {
   assertRestResourceBinding(mcp, options);
   const authorizer = createRequestAuthorizer(mcp, options);
-  return async (request, toolName) => {
+  const handle = async (request, toolName) => {
     const authResult = await authorizer.authorize(request);
     if (!authResult.ok)
       return authResult.response;
     if (request.method !== "POST")
-      return methodNotAllowed("POST");
+      return methodNotAllowed("POST, OPTIONS");
     const tool = mcp.tools.find((t) => t.name === toolName);
     if (!tool) {
       return new Response(JSON.stringify({ error: `unknown tool: ${safeReflectName(toolName)}` }), {
@@ -715,6 +737,11 @@ function createInvokeToolHandler(mcp, options = {}) {
       isError: result.isError
     });
   };
+  return async (request, toolName) => {
+    if (request.method === "OPTIONS")
+      return corsPreflightResponse("POST, OPTIONS");
+    return withCors(await handle(request, toolName));
+  };
 }
 
 // src/stacks/tanstack/handlers.ts

package/dist/stacks/tanstack/index.js

@@ -1,15 +1,15 @@
 import {
   createMcpProtocolHandler
-} from "../../chunk-GLG5RZGE.js";
+} from "../../chunk-NJ5WBRYI.js";
 import {
   createOAuthProtectedResourceMetadataHandler
-} from "../../chunk-DDF63QWG.js";
+} from "../../chunk-K2T4WTKX.js";
 import {
   createInvokeToolHandler,
   createListToolsHandler
-} from "../../chunk-VD6CS7Y6.js";
+} from "../../chunk-SYI32IRK.js";
 import "../../chunk-MA5H6PSF.js";
-import "../../chunk-XEDRJFAR.js";
+import "../../chunk-ZKKLOL2C.js";
 import "../../chunk-QA3FWDUV.js";
 import "../../chunk-6DXGZZA4.js";
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lovable.dev/mcp-js",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Author MCP servers for Lovable apps. Declare tools with defineTool, register them in defineMcp, and the framework adapter (TanStack today, Supabase Edge Functions next) emits the route(s) at build time.",
   "type": "module",
   "repository": {