@lovable.dev/mcp-js 0.9.4 → 0.10.0

package/README.internal.md

@@ -6,7 +6,7 @@ Architecture rationale, source layout, and dev scripts for contributors. The use
 
 - **`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.
+- **`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.
 
 ## Design decisions
@@ -143,6 +143,11 @@ src/
       handlers.ts                # TanStack route-ctx adapters
       vite.ts                    # mcpPlugin (route emission + stale-file cleanup; exposes McpPluginApi for the extractor)
       index.ts                   # barrel
+    supabase/
+      handler.ts                 # createSupabaseHandler (URL-suffix dispatcher to protocols/*)
+      emit.ts                    # syncSupabaseFunction (emits supabase/functions/<name>/{index.ts,deno.json})
+      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
@@ -153,6 +158,7 @@ tests/
   manifest/{extract,io,ssr-loader,run-extract}.test.ts  # stack-agnostic extractor (run-extract covers TanStack + Supabase)
   stacks/
     tanstack/{handlers,vite}.test.ts
+    supabase/{handler,emit,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
@@ -169,19 +175,20 @@ 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 test:integration:tanstack       # build + install tanstack example + vitest --project integration
+pnpm test:integration:tanstack:oauth # build + install OAuth example + vitest --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
+pnpm example:tanstack:install        # install example/tanstack deps (called by test:integration:tanstack)
+pnpm example:tanstack:oauth:install  # install example/tanstack-supabase-oauth deps
+pnpm example:tanstack:oauth:build    # production-build the OAuth example
+pnpm example:tanstack:oauth:smoke    # smoke a running OAuth example, optionally with MCP_ACCESS_TOKEN
+pnpm example:supabase:install        # install example/supabase deps
 ```
 
 `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.
+**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`).
 

package/README.md

@@ -215,6 +215,53 @@ LOVABLE_MCP_LOG_LEVEL=debug
 
 A `500` on an OAuth-protected route is always one of two causes, logged at `error`: an `OAuthConfigurationError` from issuer-metadata discovery or a JWKS *fetch* failure (`oauth.discovery.config_error` / `oauth.jwks.fetch_failed` → `auth.config_error`), or a transport-level fault in the MCP handler (`mcp.transport_error`). Auth outcomes are logged at `info`: a granted request as `oauth.verify.ok`, and a `401`/`403` as `auth.token_rejected` (with the `jose` reason) or `auth.no_bearer_token` — so a request rejected for insufficient scope shows both `oauth.verify.ok` and the `auth.token_rejected` that follows it.
 
+## Supabase Edge Functions
+
+Ship the same `defineMcp` server as a single Supabase Edge Function. Authoring is identical to the TanStack flow; only the build-time step differs — a different Vite plugin emits a single Deno function entry (plus a `deno.json` import map) instead of a tree of file-router routes.
+
+```ts
+// src/lib/mcp/index.ts — same as the TanStack flow
+import { auth, 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.",
+  auth: auth.oauth.issuer({
+    issuer: `${process.env.SUPABASE_URL!.replace(/\/+$/, "")}/auth/v1`,
+    acceptedAudiences: "authenticated",
+  }),
+  tools: [echoTool],
+});
+```
+
+```ts
+// vite.config.ts — Lovable Classic projects already run Vite for the
+// frontend, so the plugin is the natural authoring surface (the emitted
+// output is a Deno function, not a Vite-bundled file; Vite is just the
+// trigger). The export is named `mcpPlugin` in every stack — the import
+// path is what discriminates the TanStack and Supabase variants.
+import { defineConfig } from "vite";
+import { mcpPlugin } from "@lovable.dev/mcp-js/stacks/supabase/vite";
+
+export default defineConfig({ plugins: [mcpPlugin()] });
+```
+
+The plugin emits `supabase/functions/mcp/index.ts` and `supabase/functions/mcp/deno.json` on `configResolved`, re-emits on `buildStart`, and watches `src/lib/mcp/index.ts` for changes during `vite dev`. The emitted function calls `Deno.serve(createSupabaseHandler(mcp, { functionName: "mcp" }))`. The handler is one Web-Standard `Request → Response` that dispatches by URL suffix to the same protocol handlers the TanStack stack uses:
+
+| 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.
+
+Ownership: every emitted file carries a `// AUTO-GENERATED by @lovable.dev/mcp-js` banner. The plugin rewrites banner-tagged files in place and cleans up orphans; banner-less files (yours) are never touched. Delete the banner line to take ownership of a file. Deleting the `defineMcp` entry and re-running removes the SDK-owned function files.
+
 ## Subpath exports
 
 | Subpath                                 | Contents                                                                |
@@ -225,5 +272,7 @@ A `500` on an OAuth-protected route is always one of two causes, logged at `erro
 | `@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 |
+| `@lovable.dev/mcp-js/stacks/supabase/vite`     | `mcpPlugin` — the Vite plugin (Supabase variant; same name as TanStack's, picked by import path) |
 
-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.
+End users only need the root import (`@lovable.dev/mcp-js`). Generated route files import from `@lovable.dev/mcp-js/stacks/tanstack` (TanStack) or `@lovable.dev/mcp-js/stacks/supabase` (Supabase). The other subpaths are escape hatches for hand-wiring custom stacks against the protocol layer directly.

package/dist/chunk-4XJ2R3DD.js

@@ -0,0 +1,6 @@
+// package.json
+var version = "0.10.0";
+
+export {
+  version
+};

package/dist/{chunk-OXSSMKQE.js → chunk-DF3DD3KD.js}

@@ -5,7 +5,7 @@ import {
   corsPreflightResponse,
   createRequestAuthorizer,
   withCors
-} from "./chunk-YQBOGY7D.js";
+} from "./chunk-LAFJDJRY.js";
 import {
   describeError,
   log

package/dist/{chunk-YQBOGY7D.js → chunk-LAFJDJRY.js}

@@ -469,6 +469,7 @@ export {
   headResponse,
   methodNotAllowed,
   resolveProtectedResource,
+  assertResourcePathShape,
   oauthConfigurationErrorResponse,
   getOAuthRuntime,
   assertRestResourceBinding,

package/dist/{chunk-2RGXCDBU.js → chunk-PJXKJNSZ.js}

@@ -5,7 +5,7 @@ import {
   headResponse,
   methodNotAllowed,
   withCors
-} from "./chunk-YQBOGY7D.js";
+} from "./chunk-LAFJDJRY.js";
 
 // src/protocols/rest/list-tools.ts
 import { objectFromShape } from "@modelcontextprotocol/sdk/server/zod-compat.js";

package/dist/{chunk-6N7B7NZY.js → chunk-SZLSAGDF.js}

@@ -8,7 +8,7 @@ import {
   createRequestAuthorizer,
   methodNotAllowed,
   withCors
-} from "./chunk-YQBOGY7D.js";
+} from "./chunk-LAFJDJRY.js";
 
 // src/protocols/rest/invoke-tool.ts
 import { getParseErrorMessage, objectFromShape, safeParseAsync } from "@modelcontextprotocol/sdk/server/zod-compat.js";

package/dist/{chunk-4JO3BZQG.js → chunk-X7V2CL7C.js}

@@ -7,7 +7,7 @@ import {
   oauthConfigurationErrorResponse,
   resolveProtectedResource,
   withCors
-} from "./chunk-YQBOGY7D.js";
+} from "./chunk-LAFJDJRY.js";
 import {
   describeError,
   log

package/dist/chunk-XQWJN6DC.js

@@ -0,0 +1,14 @@
+// src/stacks/supabase/paths.ts
+var FUNCTIONS_MOUNT_PREFIX = "/functions/v1/";
+function assertFunctionName(value, label = "functionName") {
+  if (!/^[a-zA-Z0-9_-]+$/.test(value)) {
+    throw new Error(
+      `@lovable.dev/mcp-js: ${label} must be a single path segment matching [A-Za-z0-9_-], got ${JSON.stringify(value)}`
+    );
+  }
+}
+
+export {
+  FUNCTIONS_MOUNT_PREFIX,
+  assertFunctionName
+};

package/dist/cli/extract-manifest.cjs

@@ -13,7 +13,7 @@ function isFileMissing(err) {
 }
 
 // package.json
-var version = "0.9.4";
+var version = "0.10.0";
 
 // src/protocols/rest/list-tools.ts
 var import_zod_compat = require("@modelcontextprotocol/sdk/server/zod-compat.js");

package/dist/cli/extract-manifest.js

@@ -1,13 +1,16 @@
 #!/usr/bin/env node
 import {
   buildMcpListing
-} from "../chunk-2RGXCDBU.js";
-import "../chunk-YQBOGY7D.js";
+} from "../chunk-PJXKJNSZ.js";
+import "../chunk-LAFJDJRY.js";
 import "../chunk-QC3DXQTH.js";
+import "../chunk-6DXGZZA4.js";
+import {
+  version
+} from "../chunk-4XJ2R3DD.js";
 import {
   isFileMissing
 } from "../chunk-Y3ZFPEQH.js";
-import "../chunk-6DXGZZA4.js";
 
 // src/manifest/io.ts
 import { randomUUID } from "crypto";
@@ -15,9 +18,6 @@ import { lstatSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSy
 import { dirname, resolve } from "path";
 import { resolveConfig } from "vite";
 
-// package.json
-var version = "0.9.4";
-
 // src/manifest/extract.ts
 var MANIFEST_VERSION = 1;
 var MANIFEST_RELATIVE_PATH = ".lovable/mcp/manifest.json";

package/dist/io-D4srzRKc.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Shape every MCP Vite plugin exposes on its `api` so `runExtract` can read
+ * back the resolved entry path and the URL the stack mounts the MCP server at.
+ * TanStack sets `urlPath` to the configured route path (default `/mcp`);
+ * Supabase sets it to `/functions/v1/<functionName>` (the public mount under
+ * which the function and its companion routes live).
+ */
+interface McpPluginApi {
+    readonly mcpEntry: string;
+    readonly urlPath: string;
+}
+
+export type { McpPluginApi as M };

package/dist/protocols/mcp/index.js

@@ -1,8 +1,8 @@
 import {
   createMcpProtocolHandler
-} from "../../chunk-OXSSMKQE.js";
+} from "../../chunk-DF3DD3KD.js";
 import "../../chunk-MA5H6PSF.js";
-import "../../chunk-YQBOGY7D.js";
+import "../../chunk-LAFJDJRY.js";
 import "../../chunk-QC3DXQTH.js";
 import "../../chunk-6DXGZZA4.js";
 export {

package/dist/protocols/oauth-metadata.js

@@ -1,7 +1,7 @@
 import {
   createOAuthProtectedResourceMetadataHandler
-} from "../chunk-4JO3BZQG.js";
-import "../chunk-YQBOGY7D.js";
+} from "../chunk-X7V2CL7C.js";
+import "../chunk-LAFJDJRY.js";
 import "../chunk-QC3DXQTH.js";
 import "../chunk-6DXGZZA4.js";
 export {

package/dist/protocols/rest/index.js

@@ -1,11 +1,11 @@
 import {
   createInvokeToolHandler
-} from "../../chunk-6N7B7NZY.js";
-import "../../chunk-MA5H6PSF.js";
+} from "../../chunk-SZLSAGDF.js";
 import {
   createListToolsHandler
-} from "../../chunk-2RGXCDBU.js";
-import "../../chunk-YQBOGY7D.js";
+} from "../../chunk-PJXKJNSZ.js";
+import "../../chunk-MA5H6PSF.js";
+import "../../chunk-LAFJDJRY.js";
 import "../../chunk-QC3DXQTH.js";
 import "../../chunk-6DXGZZA4.js";
 export {