@lovable.dev/mcp-js 0.29.0-rc.1 → 0.29.0-rc.2

package/README.internal.md

@@ -4,10 +4,10 @@ Architecture rationale, source layout, and dev scripts for contributors. The use
 
 ## 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. Two are published: `stacks/tanstack/` (file-router routes emitted by a Vite plugin) and `stacks/supabase/` (a single Deno-served function with URL-suffix dispatch, emitted by the Supabase Vite plugin). Future entries (classic Vite, Cloudflare Workers, …) live alongside them. Each stack forwards to `protocols/{mcp,oauth-metadata,rest}` directly — protocol logic stays shared, only ctx unwrapping and route emission differ.
-- **`manifest/`** is the stack-agnostic snapshot writer. `lovable-mcp-extract-manifest` is one CLI for every stack: it asks Vite for the resolved config, finds any plugin whose name matches `@lovable.dev/mcp-js*`, and reads `mcpEntry` + `urlPath` off its `api`. TanStack publishes its configured route path (`/mcp`); Supabase publishes `/functions/v1/<functionName>`. The projection (`extract.ts`) is pure and shares `buildMcpListing` with the live `GET /.mcp/list-tools` route so the committed manifest and the served catalog can't drift.
+- **`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/gate.ts` is the shared CORS → auth → method gate both surfaces run behind.
+- **`auth/`** (unpublished) is the cross-cutting OAuth middleware — bearer verification, issuer/JWKS discovery, the `auth.oauth.*` config namespace. It depends only on `core/`; `protocols/mcp` depends on it for the bearer gate, so it isn't a wire-format peer of `mcp` and doesn't live under `protocols/`.
+- **`stacks/`** is the framework integration. Two are published: `stacks/tanstack/` (file-router routes emitted by a Vite plugin) and `stacks/supabase/` (a single Deno-served function with URL-suffix dispatch, emitted by the Supabase Vite plugin). Future entries (classic Vite, Cloudflare Workers, …) live alongside them. Each stack forwards to `protocols/{mcp,oauth-metadata}` directly — protocol logic stays shared, only ctx unwrapping and route emission differ.
+- **`manifest/`** is the stack-agnostic snapshot writer. `lovable-mcp-extract-manifest` is one CLI for every stack: it asks Vite for the resolved config, finds any plugin whose name matches `@lovable.dev/mcp-js*`, and reads `mcpEntry` + `urlPath` off its `api`. TanStack publishes its configured route path (`/mcp`); Supabase publishes `/functions/v1/<functionName>`. The projection (`extract.ts` + `listing.ts`) is pure and derives from the same `defineMcp` definition the live `tools/list` serves, so the committed manifest and the served catalog can't drift.
 
 ## Design decisions
 
@@ -27,29 +27,22 @@ TanStack's file-based router needs a route file on disk to register a URL. If we
 
 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
+### 3. Dot-prefixed URL paths use 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`.
+TanStack's file routing maps filenames to URLs and filters dot-prefixed entries as hidden. The escape is bracket-quoted literal segments: the OAuth metadata route is emitted at `src/routes/[.well-known]/oauth-protected-resource.ts`, which maps to `/.well-known/oauth-protected-resource` and shows up in the generated route tree.
 
-### 4. `invoke-tool/<tool>` instead of `<tool>` directly
+### 4. Dynamic tool resolution at runtime
 
-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.**
+Every request builds a fresh `McpServer` from the live `mcp.tools` array; the source of truth is one array. **Tool registration 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.
+- **Per-user / per-scope tool visibility.** Registration runs *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 `tools/list` and couldn't call it. 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.** Baking the catalog in at build time would lock it to the deploy. Per-request registration leaves that decision to the request lifecycle.
 
 **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
+### 5. Type-erased `AnyToolDefinition` at the array boundary
 
 `ToolDefinition<TInput>` is generic — the handler's args are inferred from `inputSchema`:
 
@@ -63,7 +56,7 @@ This works per-tool at the `defineTool` call site. It breaks at the `defineMcp({
 
 `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
+### 6. 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:
 
@@ -73,7 +66,7 @@ The MCP spec promoted `title` to a top-level field on `Tool` and `Server` in 202
 
 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`
+### 7. Decoupled type surface from `@modelcontextprotocol/sdk`
 
 Two reasons:
 
@@ -86,9 +79,9 @@ The published `.d.ts` files import only from `zod` and `vite`. Three SDK concern
 - **`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.
+The **runtime** still hands off to the MCP SDKs — `createMcpHandler` + `McpServer` come from `@modelcontextprotocol/server` (v2), and `objectFromShape` + `safeParseAsync` + `toJsonSchemaCompat` come from `@modelcontextprotocol/sdk`'s zod-compat modules for input validation and JSON-Schema serialization. Those are runtime dependencies, not type-surface dependencies.
 
-### 9. Stale-route cleanup on every regen
+### 8. 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:
 
@@ -123,17 +116,16 @@ src/
     resource.ts                  # protected-resource URL resolution
     metadata-path.ts             # shared RFC 9728 metadata path constant
     types.ts                     # auth config + context types
+  metrics/                       # OTLP metrics recorder (unpublished); config, recorder, exporters under impl/
   protocols/
+    gate.ts                      # shared CORS → auth → method gate
     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
   manifest/                      # stack-agnostic manifest extraction (TanStack + Supabase both feed it)
     extract.ts                   # project a defineMcp result to the manifest (types + manifestFromDefinition)
+    listing.ts                   # buildMcpListing: the tool-catalog projection embedded in the manifest
     io.ts                        # runExtract/syncManifest: read any @lovable.dev/mcp-js* plugin's api + write .lovable/mcp/manifest.json
     ssr-loader.ts                # produceViaSsr: load the entry via a throwaway Vite SSR server
   cli/
@@ -149,12 +141,11 @@ src/
       vite.ts                    # mcpPlugin (Vite-lifecycle trigger; exposes McpPluginApi with urlPath=/functions/v1/<functionName>)
       index.ts                   # barrel
 tests/
-  core/{define,promise,url}.test.ts
-  auth/{claims,config,context,oauth}.test.ts  # OAuth config + bearer verification
+  core/{content,cors,define,errors,forwarded,logger,promise,supabase-config,url}.test.ts
+  auth/{claims,config,context,oauth,oauth-fallback,oauth-logging,oauth-metrics}.test.ts  # OAuth config + bearer verification
+  metrics/{config,dispatch,otlp,recorder}.test.ts
   protocols/
     mcp/protocol.test.ts
-    rest/{list-tools,invoke-tool}.test.ts
-    parity.test.ts                   # REST↔MCP equivalence contract
   manifest/{extract,io,ssr-loader,run-extract}.test.ts  # stack-agnostic extractor (run-extract covers TanStack + Supabase)
   stacks/
     tanstack/{handlers,vite}.test.ts
@@ -191,7 +182,7 @@ pnpm example:supabase:install        # install example/supabase deps
 
 **Integration tests** live under `tests/integration/` and run against a live HTTP server. `pnpm test:integration:tanstack` 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 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 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.
 

package/README.md

@@ -46,18 +46,16 @@ That's the whole authoring surface. No imperative server construction, no route
 | -------------------------------- | ------------------------------------------ | ---------------------------------------- |
 | `POST /mcp`                      | `src/routes/mcp.ts`                        | Full MCP streamable-HTTP protocol        |
 | `GET /.well-known/oauth-protected-resource` | `src/routes/[.well-known]/oauth-protected-resource.ts` | OAuth protected-resource metadata |
-| `GET /.mcp/list-tools`           | `src/routes/[.mcp]/list-tools.ts`          | Tool catalog with JSON Schemas           |
-| `POST /.mcp/invoke-tool/<tool>`  | `src/routes/[.mcp]/invoke-tool/$tool.ts`   | REST dispatcher; one handler call per tool |
 
-The table shows the default `path: "/mcp"`. The REST companions co-locate under the parent of the configured `path`, so `mcpPlugin({ path: "/api/public/mcp" })` emits them at `/api/public/.mcp/list-tools` and `/api/public/.mcp/invoke-tool/<tool>` (file: `src/routes/api/public/[.mcp]/...`). Pass `restRoutes: false` to drop them.
+The table shows the default `path: "/mcp"`; `mcpPlugin({ path: "/api/public/mcp" })` moves the MCP route accordingly.
 
-MCP (`POST <path>`, `/mcp` by default) is the public wire format clients speak directly. REST (the `.mcp/*` companions, co-located under the `path` parent) is internal RPC — only an upstream MCP proxy calls it; never a browser or a hand-rolled client. All runtime routes import the same `defineMcp` result, so they stay in sync on which tools exist and which auth and browser-origin policies protect them. If `defineMcp({ auth: ... })` is omitted, the handlers stay unauthenticated; if OAuth auth is configured, MCP and REST both require the proxy/client to pass `Authorization: Bearer <token>`. Rate limiting belongs at the app host or edge.
+MCP (`POST <path>`, `/mcp` by default) is the wire format clients speak directly. All runtime routes import the same `defineMcp` result, so they stay in sync on which tools exist and which auth and browser-origin policies protect them. If `defineMcp({ auth: ... })` is omitted, the handlers stay unauthenticated; if OAuth auth is configured, clients must pass `Authorization: Bearer <token>`. Rate limiting belongs at the app host or edge.
 
 The MCP endpoint supports both protocol eras on one URL. Finalized `2026-07-28` clients send the version, client capabilities, and mirrored HTTP headers on every request; the server returns typed results plus cache metadata on discovery and list responses without initialization or protocol sessions. Initialization-era clients continue through a stateless compatibility path: `initialize`, `tools/list`, and `tools/call` work as independent requests, and the endpoint never mints `Mcp-Session-Id`. `GET` and `DELETE` return `405` because there is no standalone stream or session to manage.
 
 `outputSchema` accepts either the existing object-shape shorthand (`{ value: z.string() }`) or a JSON-Schema-representable Zod schema such as `z.array(z.string())`; `structuredContent` may be any JSON value. The server returns the schema's parsed output, so coercions are reflected in the result; transforms with no truthful JSON Schema are rejected when `defineMcp` runs. Modern clients receive the natural schema and value. The compatibility path wraps non-object schemas and values under `result` for initialization-era clients whose wire format requires an object root.
 
-Browser-origin checks apply to the MCP, REST companion, and OAuth metadata routes before authentication. Omit `allowedOrigins` to allow requests with no `Origin` header (Go, desktop, CLI, and server clients) plus same-origin browser requests. Set `allowedOrigins: ["https://client.example.com"]` for exact additional origins, or `allowedOrigins: "any"` to intentionally restore wildcard CORS. Exact and same origins are reflected with `Vary: Origin`; other browser origins receive `403` without an OAuth challenge. Reverse-proxy adapters compare against the effective public origin after applying only their configured trusted forwarded headers.
+Browser-origin checks apply to the MCP and OAuth metadata routes before authentication. Omit `allowedOrigins` to allow requests with no `Origin` header (Go, desktop, CLI, and server clients) plus same-origin browser requests. Set `allowedOrigins: ["https://client.example.com"]` for exact additional origins, or `allowedOrigins: "any"` to intentionally restore wildcard CORS. Exact and same origins are reflected with `Vary: Origin`; other browser origins receive `403` without an OAuth challenge. Reverse-proxy adapters compare against the effective public origin after applying only their configured trusted forwarded headers.
 
 The OAuth metadata route is emitted by default and returns `404` until OAuth auth is configured. Disable it with `mcpPlugin({ protectedResourceMetadataRoute: false })` only if the app owns `/.well-known/oauth-protected-resource` itself.
 
@@ -65,7 +63,7 @@ To serve the metadata from a different path — e.g. a workspace-private project
 
 ### `.lovable/mcp/manifest.json`
 
-`.lovable/mcp/manifest.json` is a snapshot the Lovable platform reads to register the MCP server. Envelope fields: `version` (manifest schema version), `sdk_version` (the `@lovable.dev/mcp-js` release that wrote the snapshot), `path`, and `auth`. `auth` is the server's auth configuration, lifted into the envelope (not into `mcp`): `{ "type": "none" }`, or `{ "type": "oauth", ... }` mirroring the `defineMcp({ auth })` config (snake_case — `issuer`, `accepted_audiences`, `required_scopes`, `resource`, …). The `mcp` field is **exactly the `GET /.mcp/list-tools` body** — `server` plus the tool catalog (`name`/`title`/`description`/`annotations` and JSON-Schema `inputSchema`/`outputSchema`) — so the committed snapshot can't drift from what the live route serves. It's produced by loading the entry and reading the catalog off the `defineMcp` result, so the manifest reflects exactly what the server exposes, including tools built programmatically (spreads, computed names, tools from npm). **The `lovable-mcp-extract-manifest` CLI writes it** (loading the entry through Vite's SSR module loader, so it works under Node/Bun), and removes it when the entry is deleted. The Lovable platform runs the CLI in its commit pipeline; the Vite plugin only generates routes. Commit it: the platform reads the committed file.
+`.lovable/mcp/manifest.json` is a snapshot the Lovable platform reads to register the MCP server. Envelope fields: `version` (manifest schema version), `sdk_version` (the `@lovable.dev/mcp-js` release that wrote the snapshot), `path`, and `auth`. `auth` is the server's auth configuration, lifted into the envelope (not into `mcp`): `{ "type": "none" }`, or `{ "type": "oauth", ... }` mirroring the `defineMcp({ auth })` config (snake_case — `issuer`, `accepted_audiences`, `required_scopes`, `resource`, …). The `mcp` field is the server listing — `server` plus the tool catalog (`name`/`title`/`description`/`annotations` and JSON-Schema `inputSchema`/`outputSchema`) — the same projection the live MCP endpoint serves from `tools/list`. It's produced by loading the entry and reading the catalog off the `defineMcp` result, so the manifest reflects exactly what the server exposes, including tools built programmatically (spreads, computed names, tools from npm). **The `lovable-mcp-extract-manifest` CLI writes it** (loading the entry through Vite's SSR module loader, so it works under Node/Bun), and removes it when the entry is deleted. The Lovable platform runs the CLI in its commit pipeline; the Vite plugin only generates routes. Commit it: the platform reads the committed file.
 
 Three caveats:
 
@@ -168,6 +166,23 @@ and no `node:async_hooks` dependency, so it works on any runtime and is safe
 under concurrency by construction. A handler that hands `ctx` to deferred work (a
 detached timer, an un-awaited promise) keeps full access to it.
 
+Beyond auth, `ToolContext` carries the per-request runtime surface:
+
+| Member | Purpose |
+| --- | --- |
+| `signal` | An `AbortSignal` that aborts when the client cancels the request or disconnects. Pass it to `fetch` and other cancelable APIs, or check `signal.aborted` between steps of long work. |
+| `client` | What the calling client declared about itself (`McpClientInfo`): `protocol` (`"2026-07-28"` or `"legacy"`), and for modern requests the envelope's `info`, `capabilities`, and `extensions`. Unverified client input — use it to adapt output, never to authorize. |
+| `progress(update)` | Sends a `notifications/progress` frame (`{ progress, total?, message? }`) for long-running tools. A no-op unless the client requested progress by sending `_meta.progressToken`; safe to call unconditionally. |
+
+```ts
+handler: async ({ url }, ctx) => {
+  await ctx.progress({ progress: 0, total: 2, message: "fetching" });
+  const res = await fetch(url, { signal: ctx.signal });
+  await ctx.progress({ progress: 1, total: 2, message: "processing" });
+  return { content: [{ type: "text", text: await res.text() }] };
+};
+```
+
 **Security contract for the bearer token.** `getToken()` is the only way to read
 the raw token. `ToolContext` holds the verified context in a private field, so the
 credential can't be read off the instance via `JSON.stringify`, object spread, or
@@ -177,7 +192,7 @@ construction (e.g. calling Supabase on the user's behalf); never return it from
 tool or write it to logs. A leaked token stays valid at the authorization server
 until it expires.
 
-**Caller-visible errors.** Throwing `ToolError` from a handler returns an `isError` result carrying exactly its message, on both the MCP and REST surfaces — the same shape as returning `{ isError: true, content: [...] }`. Any other exception is redacted to a generic failure on the wire; its name and message appear only in the server's local `tool.invoked` log line (`errorText`), never in telemetry.
+**Caller-visible errors.** Throwing `ToolError` from a handler returns an `isError` result carrying exactly its message — the same shape as returning `{ isError: true, content: [...] }`. Any other exception is redacted to a generic failure on the wire; its name and message appear only in the server's local `tool.invoked` log line (`errorText`), never in telemetry.
 
 ```ts
 import { ToolError } from "@lovable.dev/mcp-js";
@@ -209,8 +224,6 @@ Use an OAuth access token from the configured authorization server for MCP calls
 
 Protected-resource metadata is derived from the same config. When `resource` is omitted, the published resource is the incoming request origin plus the MCP route path the stack adapter supplies as `resourcePath` (for example, `https://my-app.lovable.app/mcp`); `authorization_servers` is the configured issuer, and `resource_name` is `defineMcp({ title })` unless `resourceName` overrides it. Because the metadata endpoint is served from `/.well-known/...`, it can't infer the resource from its own path — the handler throws at construction when neither `resource` nor `resourcePath` is set (the generated TanStack routes always pass `resourcePath`). For Supabase auth, this metadata still names the MCP resource even though Supabase JWTs use the project audience `"authenticated"`.
 
-Stack adapters must pass the public MCP route as `resourcePath` when they also expose REST companion routes. The REST companion handlers (`createInvokeToolHandler`, `createListToolsHandler`) throw at construction unless `resource` or `resourcePath` is set, so `principal.resource` binds to `/mcp` rather than leaking the internal `/.mcp/*` RPC path it was reached through. The generated TanStack routes already pass it.
-
 The request-derived `resource` default trusts the incoming `Host` to name this server's origin. Because a config always sets `acceptedAudiences` (Supabase: `"authenticated"`) or `resource`, this default only names the advertised protected-resource metadata, never the accepted JWT audience. A platform that terminates TLS and sets `Host` from the verified domain (Lovable Cloud) makes this safe. Deployments fronted by a proxy that forwards an attacker-controlled `Host` should pin `resource` to the canonical URL so a spoofed host cannot shift the advertised metadata URL.
 
 Use `auth.oauth.issuer(...)`, set `resource` or `acceptedAudiences` to anchor the accepted audience, and optionally set `jwksUri` and `requiredScopes`. For Supabase project auth, set `acceptedAudiences: "authenticated"`, keep app/business checks in app code, and forward `ctx.getToken()` to Supabase for RLS-backed data access.
@@ -238,7 +251,7 @@ A `500` on an OAuth-protected route is always one of two causes, logged at `erro
 
 ## Usage metrics
 
-Each MCP server records per-invocation telemetry — tool name, JSON-RPC method, outcome, and latency — as **OTLP/HTTP JSON logs**, one awaited POST per record, bounded by a 3-second timeout; a failed or slow POST is logged (`metrics.failed`) and swallowed, never failing the request. Outcomes cover tool results (`ok`, `tool_error`, `handler_error`, `transport_error`) and the authorization gate: `auth_challenge` for an unauthenticated request answered with the `401` challenge (so probe traffic produces records), and the `auth_*` discovery/JWKS failure outcomes. No tool arguments or response payloads are ever captured. Emission is **on by default** and self-disables at runtime when `LOVABLE_API_KEY` is absent: records are dropped and one `metrics.disabled_no_api_key` warning is logged per process, so a local `vite dev` stays quiet. With `metrics: false` the recorder never runs — on Deno and Cloudflare Workers that also means `LOVABLE_MCP_LOG_LEVEL` is never applied (use `setLogLevel()` instead).
+Each MCP server records per-invocation telemetry — tool name, JSON-RPC method, outcome, and latency — as **OTLP/HTTP JSON logs**, one awaited POST per record, bounded by a 3-second timeout; a failed or slow POST is logged (`metrics.failed`) and swallowed, never failing the request. Outcomes cover tool results (`ok`, `tool_error`, `handler_error`, `transport_error`), the authorization gate — `auth_challenge` for an unauthenticated request answered with the `401` challenge (so probe traffic produces records), and the `auth_*` discovery/JWKS failure outcomes — and `origin_rejected` for a request refused `403` by the origin policy. Tool-call records also carry the protocol era (`mcp.protocol`: `2026-07-28` or `legacy`); records emitted before protocol classification (auth challenges, transport errors, origin rejections) have no protocol attribute. No tool arguments or response payloads are ever captured. Emission is **on by default** and self-disables at runtime when `LOVABLE_API_KEY` is absent: records are dropped and one `metrics.disabled_no_api_key` warning is logged per process, so a local `vite dev` stays quiet. With `metrics: false` the recorder never runs — on Deno and Cloudflare Workers that also means `LOVABLE_MCP_LOG_LEVEL` is never applied (use `setLogLevel()` instead).
 
 Configure it on the MCP definition:
 
@@ -303,8 +316,6 @@ The plugin bundles `src/lib/mcp/index.ts` (and the tool files it imports) into `
 | URL suffix | Target |
 | --- | --- |
 | (root) | MCP streamable-HTTP protocol |
-| `/.mcp/list-tools` | REST tool catalog |
-| `/.mcp/invoke-tool/<tool>` | REST tool dispatcher |
 | `/.well-known/oauth-protected-resource` | RFC 9728 metadata |
 
 In production the function is mounted at `https://<project-ref>.supabase.co/functions/v1/mcp` and the dispatcher binds the OAuth `resource` to that URL via `functionName`. Locally, run `supabase functions serve mcp --no-verify-jwt` so Supabase's edge-runtime doesn't 401 before the SDK's OAuth verifier sees the bearer.
@@ -318,7 +329,6 @@ Ownership: the emitted `index.ts` carries a `// AUTO-GENERATED by @lovable.dev/m
 | `@lovable.dev/mcp-js`                       | `defineTool`, `defineMcp`, public types                                 |
 | `@lovable.dev/mcp-js/protocols/mcp`            | `createMcpProtocolHandler` — Web-Standard MCP-over-HTTP                 |
 | `@lovable.dev/mcp-js/protocols/oauth-metadata` | `createOAuthProtectedResourceMetadataHandler` (the `auth` namespace lives at the root) |
-| `@lovable.dev/mcp-js/protocols/rest`           | `createListToolsHandler`, `createInvokeToolHandler` — Web-Standard      |
 | `@lovable.dev/mcp-js/stacks/tanstack`          | TanStack-route-ctx adapters (`createTanStack*Handler`)                  |
 | `@lovable.dev/mcp-js/stacks/tanstack/vite`     | The Vite plugin                                                         |
 | `@lovable.dev/mcp-js/stacks/supabase`          | `createSupabaseHandler` — Web-Standard Supabase Edge Function dispatcher |

package/dist/{authorize-BjNE3LPr.d.ts → authorize-Bpz8oxjF.d.ts}

@@ -1,10 +1,7 @@
-import "./types-D1cgsnPu.js";
+import "./types-DnGEKnvI.js";
 //#region src/auth/authorize.d.ts
 interface McpRuntimeOptions {
-  /**
-   * Public MCP protocol path. REST companion handlers pass this so OAuth
-   * resource/audience checks bind to `/mcp`, not internal `/.mcp/*` RPC URLs.
-   */
+  /** Public MCP path OAuth resource/audience checks bind to when it differs from the request path. */
   resourcePath?: string;
   /**
    * Host-relative path of the SDK-served protected-resource metadata document.

package/dist/{authorize-BzZFS0zi.d.cts → authorize-Cqr7Jps0.d.cts}

@@ -1,10 +1,7 @@
-import "./types-D1cgsnPu.cjs";
+import "./types-DnGEKnvI.cjs";
 //#region src/auth/authorize.d.ts
 interface McpRuntimeOptions {
-  /**
-   * Public MCP protocol path. REST companion handlers pass this so OAuth
-   * resource/audience checks bind to `/mcp`, not internal `/.mcp/*` RPC URLs.
-   */
+  /** Public MCP path OAuth resource/audience checks bind to when it differs from the request path. */
   resourcePath?: string;
   /**
    * Host-relative path of the SDK-served protected-resource metadata document.

package/dist/cli/extract-manifest.cjs

@@ -1,11 +1,33 @@
 #!/usr/bin/env node
-const require_package = require("../package-ClCIqol1.cjs");
-const require_list_tools = require("../list-tools-DES10avA.cjs");
+const require_schema = require("../schema-D3vClxb7.cjs");
+const require_package = require("../package-DNSwCau1.cjs");
 const require_fs_errors = require("../fs-errors-CWNzOV75.cjs");
 let node_fs = require("node:fs");
 let node_path = require("node:path");
 let vite = require("vite");
 let node_crypto = require("node:crypto");
+//#region src/manifest/listing.ts
+function schemaToJsonSchema(definition, pipeStrategy) {
+	if (!definition) return null;
+	return require_schema.jsonSchemaFromDefinition(definition, pipeStrategy);
+}
+function buildMcpListing(mcp) {
+	return {
+		server: {
+			name: mcp.name,
+			version: mcp.version,
+			title: mcp.title
+		},
+		tools: mcp.tools.map((tool) => ({
+			name: tool.name,
+			title: tool.title,
+			description: tool.description,
+			annotations: tool.annotations,
+			inputSchema: schemaToJsonSchema(tool.inputSchema, "input"),
+			outputSchema: schemaToJsonSchema(tool.outputSchema, "output")
+		}))
+	};
+}
 const MANIFEST_RELATIVE_PATH = ".lovable/mcp/manifest.json";
 function manifestAuth(auth) {
 	if (!auth) return { type: "none" };
@@ -45,7 +67,7 @@ function manifestFromDefinition(definition, urlPath, source = "the MCP entry") {
 		sdk_version: require_package.version,
 		path: urlPath,
 		auth: manifestAuth(def.auth),
-		mcp: require_list_tools.buildMcpListing(def)
+		mcp: buildMcpListing(def)
 	};
 }
 //#endregion

package/dist/cli/extract-manifest.js

@@ -1,11 +1,33 @@
 #!/usr/bin/env node
-import { t as version } from "../package-BI5r4uGM.js";
-import { t as buildMcpListing } from "../list-tools-C1OiTDR9.js";
+import { t as jsonSchemaFromDefinition } from "../schema-CW1jKvio.js";
+import { t as version } from "../package-CYA-5C24.js";
 import { t as isFileMissing } from "../fs-errors-PA2t1TIp.js";
 import { lstatSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { createServer, resolveConfig } from "vite";
 import { randomUUID } from "node:crypto";
+//#region src/manifest/listing.ts
+function schemaToJsonSchema(definition, pipeStrategy) {
+	if (!definition) return null;
+	return jsonSchemaFromDefinition(definition, pipeStrategy);
+}
+function buildMcpListing(mcp) {
+	return {
+		server: {
+			name: mcp.name,
+			version: mcp.version,
+			title: mcp.title
+		},
+		tools: mcp.tools.map((tool) => ({
+			name: tool.name,
+			title: tool.title,
+			description: tool.description,
+			annotations: tool.annotations,
+			inputSchema: schemaToJsonSchema(tool.inputSchema, "input"),
+			outputSchema: schemaToJsonSchema(tool.outputSchema, "output")
+		}))
+	};
+}
 const MANIFEST_RELATIVE_PATH = ".lovable/mcp/manifest.json";
 function manifestAuth(auth) {
 	if (!auth) return { type: "none" };

package/dist/{cors-BDTQQJE2.js → cors-C_VffY86.js}

@@ -1,5 +1,5 @@
 import { i as log, n as applyLogLevelFromEnv, o as parseSafeUrl, r as describeError, s as trimTrailingSlash, t as LOG_LEVEL_ENV_VAR, u as resolveMetricsConfig } from "./logger-Ctv5xUSD.js";
-import { t as version } from "./package-BI5r4uGM.js";
+import { t as version } from "./package-CYA-5C24.js";
 import "./metadata-path-CAkNcfyY.js";
 import { createLocalJWKSet, decodeProtectedHeader, errors, jwtVerify } from "jose";
 //#region src/core/http.ts
@@ -827,17 +827,6 @@ function getOAuthRuntime(mcp, options = {}) {
 		options: stableOptions
 	};
 }
-/**
-* REST companion routes (`/.mcp/list-tools`, `/.mcp/invoke-tool/*`) are internal
-* RPC the main MCP server calls, so their own request path must never become the
-* advertised resource. Require `auth.resource` or a `resourcePath` so the bound
-* `principal.resource` is the public MCP route, not the internal `/.mcp/*` path.
-* The MCP protocol handler is exempt: its own path is the public resource.
-*/
-function assertRestResourceBinding(mcp, options = {}) {
-	const auth = mcp.auth?.type === "oauth" ? mcp.auth : void 0;
-	if (auth && auth.resource === void 0 && options.resourcePath === void 0) throw new Error(`@lovable.dev/mcp-js: REST companion handlers require auth.resource or a resourcePath so principal.resource binds to the public MCP route, not the internal /.mcp/* request path`);
-}
 function missingRequiredScopes(auth, scopes) {
 	const requiredScopes = auth.requiredScopes ?? [];
 	if (requiredScopes.length === 0) return [];
@@ -942,7 +931,15 @@ function createRequestAuthorizer(mcp, options = {}) {
 //#endregion
 //#region src/core/cors.ts
 const EXPOSE_HEADERS = "WWW-Authenticate, MCP-Protocol-Version, Mcp-Session-Id";
-const ALLOW_HEADERS = "Authorization, Content-Type, MCP-Protocol-Version, Mcp-Method, Mcp-Name, Mcp-Session-Id, Last-Event-ID";
+const ALLOW_HEADERS = [
+	"Authorization",
+	"Content-Type",
+	"MCP-Protocol-Version",
+	"Mcp-Method",
+	"Mcp-Name",
+	"Mcp-Session-Id",
+	"Last-Event-ID"
+];
 const MCP_PARAM_HEADER = /^mcp-param-[!#$%&'*+.^_`|~0-9A-Za-z-]+$/i;
 function appendVary(headers, value) {
 	const values = new Set((headers.get("Vary") ?? "").split(",").map((entry) => entry.trim()).filter(Boolean));
@@ -958,7 +955,7 @@ function addCorsHeaders(response, allowedOrigin, variesByOrigin) {
 	return response;
 }
 function allowedRequestHeaders(request) {
-	const allowed = new Map(ALLOW_HEADERS.split(", ").map((header) => [header.toLowerCase(), header]));
+	const allowed = new Map(ALLOW_HEADERS.map((header) => [header.toLowerCase(), header]));
 	for (const header of (request.headers.get("Access-Control-Request-Headers") ?? "").split(",")) {
 		const normalized = header.trim();
 		if (MCP_PARAM_HEADER.test(normalized)) allowed.set(normalized.toLowerCase(), normalized);
@@ -968,12 +965,8 @@ function allowedRequestHeaders(request) {
 function evaluateCors(request, allowedOrigins) {
 	const origin = request.headers.get("Origin");
 	const allowAny = allowedOrigins === "any";
-	let allowedOrigin;
-	if (allowAny) allowedOrigin = "*";
-	else if (origin === null) allowedOrigin = void 0;
-	else if (origin === new URL(request.url).origin || allowedOrigins?.includes(origin)) allowedOrigin = origin;
-	else allowedOrigin = null;
-	if (allowedOrigin === null) {
+	const originAllowed = origin === null || origin === new URL(request.url).origin || allowedOrigins?.includes(origin) === true;
+	if (!allowAny && !originAllowed) {
 		const response = Response.json({ error: "origin not allowed" }, {
 			status: 403,
 			headers: { "Cache-Control": "no-store" }
@@ -984,6 +977,7 @@ function evaluateCors(request, allowedOrigins) {
 			response
 		};
 	}
+	const allowedOrigin = allowAny ? "*" : origin ?? void 0;
 	return {
 		ok: true,
 		withHeaders: (response) => addCorsHeaders(response, allowedOrigin, !allowAny),
@@ -1003,4 +997,4 @@ function evaluateCors(request, allowedOrigins) {
 	};
 }
 //#endregion
-export { oauthConfigurationErrorResponse as a, createRecorderForRuntime as c, JSON_HEADERS as d, finalizeWireResponse as f, getOAuthRuntime as i, createNoopRecorder as l, assertRestResourceBinding as n, assertResourcePathShape as o, methodNotAllowed as p, createRequestAuthorizer as r, resolveProtectedResource as s, evaluateCors as t, nowMs as u };
+export { assertResourcePathShape as a, createNoopRecorder as c, finalizeWireResponse as d, methodNotAllowed as f, oauthConfigurationErrorResponse as i, nowMs as l, createRequestAuthorizer as n, resolveProtectedResource as o, getOAuthRuntime as r, createRecorderForRuntime as s, evaluateCors as t, JSON_HEADERS as u };

package/dist/{cors-BRv5KXKQ.cjs → cors-DNzLB6qa.cjs}

@@ -1,5 +1,5 @@
 const require_logger = require("./logger-CN1q-KNn.cjs");
-const require_package = require("./package-ClCIqol1.cjs");
+const require_package = require("./package-DNSwCau1.cjs");
 require("./metadata-path-zd7NSNoa.cjs");
 let jose = require("jose");
 //#region src/core/http.ts
@@ -827,17 +827,6 @@ function getOAuthRuntime(mcp, options = {}) {
 		options: stableOptions
 	};
 }
-/**
-* REST companion routes (`/.mcp/list-tools`, `/.mcp/invoke-tool/*`) are internal
-* RPC the main MCP server calls, so their own request path must never become the
-* advertised resource. Require `auth.resource` or a `resourcePath` so the bound
-* `principal.resource` is the public MCP route, not the internal `/.mcp/*` path.
-* The MCP protocol handler is exempt: its own path is the public resource.
-*/
-function assertRestResourceBinding(mcp, options = {}) {
-	const auth = mcp.auth?.type === "oauth" ? mcp.auth : void 0;
-	if (auth && auth.resource === void 0 && options.resourcePath === void 0) throw new Error(`@lovable.dev/mcp-js: REST companion handlers require auth.resource or a resourcePath so principal.resource binds to the public MCP route, not the internal /.mcp/* request path`);
-}
 function missingRequiredScopes(auth, scopes) {
 	const requiredScopes = auth.requiredScopes ?? [];
 	if (requiredScopes.length === 0) return [];
@@ -942,7 +931,15 @@ function createRequestAuthorizer(mcp, options = {}) {
 //#endregion
 //#region src/core/cors.ts
 const EXPOSE_HEADERS = "WWW-Authenticate, MCP-Protocol-Version, Mcp-Session-Id";
-const ALLOW_HEADERS = "Authorization, Content-Type, MCP-Protocol-Version, Mcp-Method, Mcp-Name, Mcp-Session-Id, Last-Event-ID";
+const ALLOW_HEADERS = [
+	"Authorization",
+	"Content-Type",
+	"MCP-Protocol-Version",
+	"Mcp-Method",
+	"Mcp-Name",
+	"Mcp-Session-Id",
+	"Last-Event-ID"
+];
 const MCP_PARAM_HEADER = /^mcp-param-[!#$%&'*+.^_`|~0-9A-Za-z-]+$/i;
 function appendVary(headers, value) {
 	const values = new Set((headers.get("Vary") ?? "").split(",").map((entry) => entry.trim()).filter(Boolean));
@@ -958,7 +955,7 @@ function addCorsHeaders(response, allowedOrigin, variesByOrigin) {
 	return response;
 }
 function allowedRequestHeaders(request) {
-	const allowed = new Map(ALLOW_HEADERS.split(", ").map((header) => [header.toLowerCase(), header]));
+	const allowed = new Map(ALLOW_HEADERS.map((header) => [header.toLowerCase(), header]));
 	for (const header of (request.headers.get("Access-Control-Request-Headers") ?? "").split(",")) {
 		const normalized = header.trim();
 		if (MCP_PARAM_HEADER.test(normalized)) allowed.set(normalized.toLowerCase(), normalized);
@@ -968,12 +965,8 @@ function allowedRequestHeaders(request) {
 function evaluateCors(request, allowedOrigins) {
 	const origin = request.headers.get("Origin");
 	const allowAny = allowedOrigins === "any";
-	let allowedOrigin;
-	if (allowAny) allowedOrigin = "*";
-	else if (origin === null) allowedOrigin = void 0;
-	else if (origin === new URL(request.url).origin || allowedOrigins?.includes(origin)) allowedOrigin = origin;
-	else allowedOrigin = null;
-	if (allowedOrigin === null) {
+	const originAllowed = origin === null || origin === new URL(request.url).origin || allowedOrigins?.includes(origin) === true;
+	if (!allowAny && !originAllowed) {
 		const response = Response.json({ error: "origin not allowed" }, {
 			status: 403,
 			headers: { "Cache-Control": "no-store" }
@@ -984,6 +977,7 @@ function evaluateCors(request, allowedOrigins) {
 			response
 		};
 	}
+	const allowedOrigin = allowAny ? "*" : origin ?? void 0;
 	return {
 		ok: true,
 		withHeaders: (response) => addCorsHeaders(response, allowedOrigin, !allowAny),
@@ -1015,12 +1009,6 @@ Object.defineProperty(exports, "assertResourcePathShape", {
 		return assertResourcePathShape;
 	}
 });
-Object.defineProperty(exports, "assertRestResourceBinding", {
-	enumerable: true,
-	get: function() {
-		return assertRestResourceBinding;
-	}
-});
 Object.defineProperty(exports, "createNoopRecorder", {
 	enumerable: true,
 	get: function() {

package/dist/{errors-DSe96Ffd.js → errors-Bwd1L0Rf.js}

@@ -1,15 +1,30 @@
 //#region src/auth/context.ts
-/**
-* The auth surface passed to every tool handler as its second argument. It wraps
-* the verified per-request auth context in a private field, so the context — and
-* the bearer token inside it — can't be read, enumerated, spread, or
-* `JSON.stringify`'d off the instance; the accessors below are the only way out.
-* `getToken()` is the single intentional escape hatch for the raw bearer.
-*/
+const NEVER_ABORTED = new AbortController().signal;
+/** The per-request context passed to every tool handler as its second argument. The
+* auth context lives in a private field so the accessors are the only way out; `getToken()` is the sole bearer escape hatch. */
 var ToolContext = class {
 	#auth;
-	constructor(auth) {
+	#signal;
+	#client;
+	#sendProgress;
+	constructor(auth, request = {}) {
 		this.#auth = auth;
+		this.#signal = request.signal ?? NEVER_ABORTED;
+		this.#client = request.client ?? { protocol: "legacy" };
+		this.#sendProgress = request.sendProgress;
+	}
+	/** Aborts when the client cancels the request or disconnects. */
+	get signal() {
+		return this.#signal;
+	}
+	/** What the client declared about itself on this request. Unverified input. */
+	get client() {
+		return this.#client;
+	}
+	/** Send a progress notification for this call. A no-op when the client
+	* didn't request progress (no `progressToken` on the request). */
+	async progress(update) {
+		await this.#sendProgress?.(update);
 	}
 	/** Whether the in-flight tool call carries a verified auth context. */
 	isAuthenticated() {

package/dist/{errors-CN6Da8iz.cjs → errors-Cr95rSkB.cjs}

@@ -1,15 +1,30 @@
 //#region src/auth/context.ts
-/**
-* The auth surface passed to every tool handler as its second argument. It wraps
-* the verified per-request auth context in a private field, so the context — and
-* the bearer token inside it — can't be read, enumerated, spread, or
-* `JSON.stringify`'d off the instance; the accessors below are the only way out.
-* `getToken()` is the single intentional escape hatch for the raw bearer.
-*/
+const NEVER_ABORTED = new AbortController().signal;
+/** The per-request context passed to every tool handler as its second argument. The
+* auth context lives in a private field so the accessors are the only way out; `getToken()` is the sole bearer escape hatch. */
 var ToolContext = class {
 	#auth;
-	constructor(auth) {
+	#signal;
+	#client;
+	#sendProgress;
+	constructor(auth, request = {}) {
 		this.#auth = auth;
+		this.#signal = request.signal ?? NEVER_ABORTED;
+		this.#client = request.client ?? { protocol: "legacy" };
+		this.#sendProgress = request.sendProgress;
+	}
+	/** Aborts when the client cancels the request or disconnects. */
+	get signal() {
+		return this.#signal;
+	}
+	/** What the client declared about itself on this request. Unverified input. */
+	get client() {
+		return this.#client;
+	}
+	/** Send a progress notification for this call. A no-op when the client
+	* didn't request progress (no `progressToken` on the request). */
+	async progress(update) {
+		await this.#sendProgress?.(update);
 	}
 	/** Whether the in-flight tool call carries a verified auth context. */
 	isAuthenticated() {

package/dist/index.cjs

@@ -1,7 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_logger = require("./logger-CN1q-KNn.cjs");
 const require_schema = require("./schema-D3vClxb7.cjs");
-const require_errors = require("./errors-CN6Da8iz.cjs");
+const require_errors = require("./errors-Cr95rSkB.cjs");
 //#region src/core/define.ts
 function assertUniqueNames(mcp) {
 	const seen = /* @__PURE__ */ new Set();