@lovable.dev/mcp-js 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lovable Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,386 @@
+# @lovable.dev/mcp-js
+
+Author MCP servers for Lovable apps. Declare tools with `defineTool`, register them with `defineMcp`, and a Vite plugin emits the framework-specific routes at build time (TanStack today, Supabase Edge Functions next).
+
+```ts
+// src/lib/mcp/tools/echo.ts
+import { defineTool } from "@lovable.dev/mcp-js";
+import { z } from "zod";
+
+export default defineTool({
+  name: "echo",
+  title: "Echo",
+  description: "Echo the input text back.",
+  inputSchema: { text: z.string().min(1) },
+  handler: ({ text }) => ({ content: [{ type: "text", text }] }),
+});
+```
+
+```ts
+// src/lib/mcp/index.ts
+import { defineMcp } from "@lovable.dev/mcp-js";
+import echoTool from "./tools/echo";
+
+export default defineMcp({
+  name: "my-app-mcp",
+  title: "My App MCP",
+  version: "0.1.0",
+  instructions: "Tools for interacting with My App. Use `echo` to verify connectivity.",
+  tools: [echoTool],
+});
+```
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { mcpPlugin } from "@lovable.dev/mcp-js/stacks/tanstack/vite";
+
+export default defineConfig({ plugins: [mcpPlugin()] });
+```
+
+That's the whole authoring surface. No imperative server construction, no route handlers, no JSON-RPC envelope, no transport instantiation — all wrapped.
+
+## What the plugin emits
+
+| URL                              | File                                       | Purpose                                  |
+| -------------------------------- | ------------------------------------------ | ---------------------------------------- |
+| `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 |
+
+MCP (`POST /mcp`) is the public wire format clients speak directly. REST (`/.mcp/list-tools`, `/.mcp/invoke-tool/<tool>`) 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 policy protects 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>`. CORS and rate limiting still belong at the app host or edge.
+
+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.
+
+## OAuth resource-server auth
+
+`@lovable.dev/mcp-js` can protect an app-hosted MCP server as an OAuth 2.1 resource server. The package does not implement `/authorize`, `/token`, client registration, refresh tokens, or consent UI; those stay with the authorization server (for today's Supabase-backed Lovable Cloud apps, Supabase Auth). The MCP runtime validates bearer JWTs, publishes RFC 9728 protected-resource metadata, returns `WWW-Authenticate: Bearer ... resource_metadata="..."` challenges, and passes verified claims to tools.
+
+Point the issuer at your OAuth/OIDC authorization server and anchor the accepted audience with either `resource` or `acceptedAudiences`:
+
+```ts
+// src/lib/mcp/index.ts
+import { auth, defineMcp } from "@lovable.dev/mcp-js";
+
+export default defineMcp({
+  name: "my-app-mcp",
+  title: "My App MCP",
+  version: "0.1.0",
+  instructions: "Tools for interacting with My App.",
+  auth: auth.oauth.issuer({
+    issuer: "https://auth.example.com",
+    resource: "https://my-app.example.com/mcp",
+    requiredScopes: ["mcp:tools"],
+  }),
+  tools: [],
+});
+```
+
+The `auth` namespace groups auth families; today it exposes `auth.oauth.issuer(...)`. It is exported from the package root (shown above), the canonical surface for app authors. `issuer` must be HTTPS (except localhost development URLs) and match the token `iss` exactly; the SDK discovers `jwks_uri` from the issuer's OAuth/OIDC metadata. The SDK reads no environment variables — pass values explicitly.
+
+### Supabase recipe
+
+For a Supabase-backed project, the issuer is the project's `<url>/auth/v1` and the accepted audience is Supabase's project-wide `authenticated` audience:
+
+```ts
+const supabaseUrl = process.env.SUPABASE_URL!.replace(/\/+$/, "");
+
+auth: auth.oauth.issuer({
+  issuer: `${supabaseUrl}/auth/v1`,
+  acceptedAudiences: "authenticated",
+}),
+```
+
+Supabase auth is **project-scoped**: Supabase access tokens use `aud: "authenticated"`, so the same delegated token verifies against every MCP server in that project. The binding is "an OAuth client of the project," not "this MCP server." Use `ctx.getClientId()`, `ctx.getUserId()`, and `ctx.getClaims()` for handler-level app/business checks — never authorize on the audience — and pass `ctx.getToken()` through to Supabase so RLS evaluates the token itself. Supabase tokens do not carry OAuth scopes today, so leave `requiredScopes` unset.
+
+To skip metadata discovery entirely, pin `jwksUri` to the issuer's JWKS endpoint. Verification then makes zero discovery probes; key rotation still works because the JWKS is fetched (and refreshed) on demand:
+
+```ts
+auth: auth.oauth.issuer({
+  issuer: `${supabaseUrl}/auth/v1`,
+  acceptedAudiences: "authenticated",
+  jwksUri: `${supabaseUrl}/auth/v1/.well-known/jwks.json`,
+}),
+```
+
+For a direct Supabase project, the relevant URLs look like this:
+
+| Supabase URL | Used by |
+| --- | --- |
+| `https://<project-ref>.supabase.co/auth/v1/.well-known/openid-configuration` | SDK: discovers `issuer` and `jwks_uri` |
+| `https://<project-ref>.supabase.co/auth/v1/.well-known/jwks.json` | SDK: verifies bearer JWT signatures |
+| `https://<project-ref>.supabase.co/auth/v1/oauth/authorize` | OAuth clients: start user authorization |
+| `https://<project-ref>.supabase.co/auth/v1/oauth/token` | OAuth clients: exchange/refresh tokens |
+
+The SDK only uses discovery + JWKS. It never calls the authorization or token endpoints.
+
+Tool handlers receive their input args plus a `ToolContext` as the second
+argument. The SDK constructs one per request from the verified token and passes
+it to the handler; helpers that need the auth take a `ToolContext` parameter, so
+the dependency is explicit in their signatures.
+
+```ts
+import type { ToolContext } from "@lovable.dev/mcp-js";
+
+handler: async ({ title }, ctx) => {
+  const userId = ctx.getUserId();  // token `sub`, or undefined when unauthenticated
+  // Apply app/business permissions here using ctx.getClaims() / ctx.getClientId().
+  // For Supabase RLS, pass ctx.getToken() through to Supabase.
+  return { content: [{ type: "text", text: `user=${userId}` }] };
+};
+```
+
+| `ToolContext` method | Returns |
+| --- | --- |
+| `isAuthenticated()` | `true` when the call carries a verified auth context. |
+| `getUserId()` | The token `sub` (subject) — the user id. |
+| `getUserEmail()` | Token `email` when present. |
+| `getClientId()` | OAuth `client_id`, falling back to the OIDC `azp` (authorized party) — the client binding handle, useful for authorization. |
+| `getScopes()` | The parsed OAuth `scope`s. |
+| `getIssuer()` | The verified token issuer. |
+| `getClaims()` | The full verified JWT claims — for app/business authorization on issuer-specific claims with no dedicated accessor. |
+| `getToken()` | The raw bearer — pass to downstream APIs (e.g. Supabase RLS); never return or log it. |
+
+Each returns `undefined` when the server is unauthenticated. `ToolContext` is a
+plain object passed by value — there is no ambient store, no `AsyncLocalStorage`,
+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.
+
+**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
+`structuredContent` — only the accessors above expose anything, and `getToken()` is
+the lone path to the bearer. Pass `getToken()` only into outbound `fetch`/client
+construction (e.g. calling Supabase on the user's behalf); never return it from a
+tool or write it to logs. A leaked token stays valid at the authorization server
+until it expires.
+
+Use an OAuth access token from the configured authorization server for MCP calls. Plain app-session JWTs, such as Supabase tokens from `signInWithPassword`, carry neither `client_id` nor `azp`; the SDK rejects them by default so copied browser sessions do not pass as delegated OAuth client tokens. Set `requireOAuthClientClaim: false` only when intentionally accepting those session tokens and relying on app checks plus downstream RLS via the forwarded bearer token.
+
+`auth.oauth.issuer(...)` fields:
+
+| Field | Meaning |
+| --- | --- |
+| `issuer` | OAuth/OIDC issuer URL. Must be HTTPS except localhost development URLs and must match the token `iss` exactly. Required. |
+| `resource` | Canonical protected-resource URL published in metadata. It also anchors the accepted audience unless `acceptedAudiences` is set. When omitted, the published resource is derived from the request origin plus the stack adapter's `resourcePath` and you must set `acceptedAudiences`; the metadata handler throws at construction if neither `resource` nor `resourcePath` is set. |
+| `acceptedAudiences` | Accepted JWT audience(s). Defaults to `resource` when that is set. One of `resource` or `acceptedAudiences` is required. |
+| `jwksUri` | JWKS URL override. If omitted, the runtime discovers `jwks_uri` from OAuth/OIDC metadata; setting it skips discovery entirely. |
+| `requiredScopes` | Required scopes. Advertised in metadata/challenges and enforced against the token `scope`. |
+| `requireOAuthClientClaim` | Defaults to `true`; rejects tokens carrying neither `client_id` nor the OIDC `azp` (authorized party) so copied app-session JWTs do not pass as OAuth client tokens. Supabase OAuth 2.1 server tokens carry `client_id` and issuers like Google/Keycloak/Entra use `azp`, so keep the default; only legacy `signInWithPassword` session tokens lack both and need `false`. |
+| `algorithms` | Accepted JWT signing algorithms. Defaults to asymmetric algorithms (`RS*`, `ES*`, `EdDSA`); set explicitly only for a narrower policy. |
+| `clockToleranceSeconds` | Allowed JWT clock skew for `exp`/`nbf` checks, in seconds. Defaults to `30`; max `300`. |
+| `resourceName`, `resourceDocumentation` | Optional metadata fields for MCP clients and humans. `resourceName` defaults to the MCP server `title`. |
+| `protectedResourceMetadataUrl` | Absolute HTTPS URL of an externally hosted RFC 9728 protected-resource metadata document. When set, the SDK advertises this URL in the 401 `WWW-Authenticate: resource_metadata` challenge and stops generating its own metadata — the `/.well-known/oauth-protected-resource` handler returns 404. Use it when the resource server already publishes its own PRM; you'll typically also pass `protectedResourceMetadataRoute: false` to the Vite plugin so the now-unused route isn't emitted. |
+
+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.
+
+## Subpath exports
+
+| Subpath                                 | Contents                                                                |
+| --------------------------------------- | ----------------------------------------------------------------------- |
+| `@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                                                         |
+
+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.

package/dist/authorize-DpTEIFvs.d.ts

@@ -0,0 +1,9 @@
+interface McpRuntimeOptions {
+    /**
+     * Public MCP protocol path. REST companion handlers pass this so OAuth
+     * resource/audience checks bind to `/mcp`, not internal `/.mcp/*` RPC URLs.
+     */
+    resourcePath?: string;
+}
+
+export type { McpRuntimeOptions as M };

package/dist/chunk-6DXGZZA4.js

@@ -0,0 +1,6 @@
+// src/auth/metadata-path.ts
+var OAUTH_PROTECTED_RESOURCE_METADATA_PATH = "/.well-known/oauth-protected-resource";
+
+export {
+  OAUTH_PROTECTED_RESOURCE_METADATA_PATH
+};

package/dist/chunk-DDF63QWG.js

@@ -0,0 +1,80 @@
+import {
+  JSON_HEADERS,
+  getOAuthRuntime,
+  headResponse,
+  methodNotAllowed,
+  oauthConfigurationErrorResponse,
+  resolveProtectedResource
+} from "./chunk-XEDRJFAR.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" }
+  });
+}
+async function buildProtectedResourceMetadata(mcp, auth, request, options, discovery) {
+  const issuer = await discovery.resolveIssuer();
+  const body = {
+    resource: resolveProtectedResource(auth, request, options),
+    authorization_servers: [issuer],
+    bearer_methods_supported: ["header"],
+    resource_name: auth.resourceName ?? mcp.title,
+    resource_documentation: auth.resourceDocumentation
+  };
+  if (auth.requiredScopes && auth.requiredScopes.length > 0)
+    body.scopes_supported = auth.requiredScopes;
+  return body;
+}
+function createOAuthProtectedResourceMetadataHandler(mcp, options = {}) {
+  const runtime = getOAuthRuntime(mcp, options);
+  if (runtime.kind === "configured" && runtime.auth.protectedResourceMetadataUrl === void 0 && runtime.auth.resource === void 0 && runtime.options.resourcePath === void 0) {
+    throw new Error(
+      `@lovable.dev/mcp-js: auth.resource or a resourcePath is required so the protected-resource metadata doesn't advertise the well-known URL as the resource`
+    );
+  }
+  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 !== "GET" && request.method !== "HEAD")
+      return withCors(methodNotAllowed("GET, HEAD, OPTIONS"));
+    const headers = {
+      ...JSON_HEADERS,
+      ...CORS_ORIGIN,
+      "Cache-Control": "public, max-age=300",
+      Vary: "Host"
+    };
+    try {
+      const metadata = await buildProtectedResourceMetadata(
+        mcp,
+        runtime.auth,
+        request,
+        runtime.options,
+        runtime.discovery
+      );
+      const response = Response.json(metadata, { headers });
+      return request.method === "HEAD" ? headResponse(response) : response;
+    } catch {
+      const response = withCors(oauthConfigurationErrorResponse());
+      return request.method === "HEAD" ? headResponse(response) : response;
+    }
+  };
+}
+
+export {
+  createOAuthProtectedResourceMetadataHandler
+};

package/dist/chunk-GLG5RZGE.js

@@ -0,0 +1,66 @@
+import {
+  ToolContext
+} from "./chunk-MA5H6PSF.js";
+import {
+  createRequestAuthorizer
+} from "./chunk-XEDRJFAR.js";
+
+// src/protocols/mcp/protocol.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+function adaptToolToSdkCallback(tool, auth) {
+  return async (first) => {
+    const args = tool.inputSchema ? first ?? {} : {};
+    let result;
+    try {
+      result = await tool.handler(args, new ToolContext(auth));
+    } catch {
+      return { content: [{ type: "text", text: "tool execution failed" }], isError: true };
+    }
+    if (result == null) {
+      return { content: [{ type: "text", text: `tool "${tool.name}" returned no result` }], isError: true };
+    }
+    return { content: result.content ?? [], structuredContent: result.structuredContent, isError: result.isError };
+  };
+}
+function createMcpProtocolHandler(mcp, options = {}) {
+  const authorizer = createRequestAuthorizer(mcp, options);
+  return async (request) => {
+    const authResult = await authorizer.authorize(request);
+    if (!authResult.ok)
+      return authResult.response;
+    try {
+      const server = new McpServer(
+        { name: mcp.name, version: mcp.version, title: mcp.title },
+        { instructions: mcp.instructions }
+      );
+      for (const tool of mcp.tools) {
+        server.registerTool(
+          tool.name,
+          {
+            title: tool.title,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            outputSchema: tool.outputSchema,
+            annotations: tool.annotations
+          },
+          adaptToolToSdkCallback(tool, authResult.auth)
+        );
+      }
+      const transport = new WebStandardStreamableHTTPServerTransport({
+        sessionIdGenerator: void 0
+      });
+      await server.connect(transport);
+      return await transport.handleRequest(request);
+    } catch {
+      return Response.json(
+        { jsonrpc: "2.0", id: null, error: { code: -32603, message: "internal error" } },
+        { status: 500 }
+      );
+    }
+  };
+}
+
+export {
+  createMcpProtocolHandler
+};

package/dist/chunk-MA5H6PSF.js

@@ -0,0 +1,46 @@
+// src/auth/context.ts
+var ToolContext = class {
+  #auth;
+  constructor(auth) {
+    this.#auth = auth;
+  }
+  /** Whether the in-flight tool call carries a verified auth context. */
+  isAuthenticated() {
+    return this.#auth !== void 0;
+  }
+  /** The verified bearer token, or `undefined` when unauthenticated. Pass it to downstream APIs; never return or log it. */
+  getToken() {
+    return this.#auth?.bearer.token;
+  }
+  /** The verified user id (the token `sub`), or `undefined`. */
+  getUserId() {
+    return this.#auth?.principal.sub;
+  }
+  /** The verified user email, or `undefined` when absent. */
+  getUserEmail() {
+    return this.#auth?.principal.email;
+  }
+  /** The verified OAuth `client_id`, or `undefined`. */
+  getClientId() {
+    return this.#auth?.principal.clientId;
+  }
+  /** The verified OAuth scopes, or `undefined` when unauthenticated. */
+  getScopes() {
+    return this.#auth?.principal.scopes;
+  }
+  /** The verified token issuer, or `undefined`. */
+  getIssuer() {
+    return this.#auth?.principal.issuer;
+  }
+  /**
+   * The full verified JWT claims, or `undefined`. Use this for app/business
+   * authorization on issuer-specific claims that have no dedicated accessor.
+   */
+  getClaims() {
+    return this.#auth?.principal.claims;
+  }
+};
+
+export {
+  ToolContext
+};