@lovable.dev/mcp-js 2.1.0 → 2.2.0-rc.0

package/README.md

@@ -53,6 +53,87 @@ MCP (`POST <path>`, `/mcp` by default) is the wire format clients speak directly
 
 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.
 
+## Caller-dependent tool catalogs
+
+Use a request context only when authenticated callers must see different tool
+names. Bind its type once and export the resulting helper for tool files:
+
+```ts
+// src/lib/mcp/context.ts
+import { defineTool } from "@lovable.dev/mcp-js";
+
+export interface AppContext {
+  readonly plan: "free" | "pro";
+}
+
+export const defineAppTool = defineTool.withAppContext<AppContext>();
+```
+
+Create the app context from verified auth when an operation needs it, then
+register every tool in the build-time union:
+
+```ts
+import { auth, defineMcp } from "@lovable.dev/mcp-js";
+import type { AppContext } from "./context";
+import exportDataTool from "./tools/export-data";
+
+export default defineMcp<AppContext>({
+  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",
+  }),
+  createAppContext: async ({ auth, signal }) => ({
+    // Unknown callers get the least-privilege catalog; only a failed lookup throws.
+    plan: (await loadPlan(auth.getUserId(), signal)) ?? "free",
+  }),
+  tools: [exportDataTool],
+});
+```
+
+Define conditional tools with the bound helper. The predicate is synchronous
+and intentionally receives only `appContext`; handlers receive the same value
+on `ctx.appContext`. Keep predicates pure: do not mutate `appContext` or depend
+on tool evaluation order.
+
+```ts
+import { defineAppTool } from "../context";
+
+export default defineAppTool({
+  name: "export_data",
+  title: "Export data",
+  description: "Export the caller's data.",
+  enabled: ({ appContext }) => appContext.plan === "pro",
+  handler: async (_args, ctx) => {
+    const token = ctx.getToken();
+    if (!token) throw new Error("Authenticated caller required");
+    await exportDataForCaller(token, ctx.signal);
+    return { content: [{ type: "text", text: "Export ready." }] };
+  },
+});
+```
+
+The SDK runs `createAppContext` once per request: for `tools/list` when any tool
+has `enabled`, and for a call to a conditional or app-context tool. Plain static
+tool calls, discovery, and ping skip it. A throw from the factory or a predicate
+fails the whole request with a redacted 500, including `tools/list`, so return a
+least-privilege context for callers who lack access and throw only when the
+lookup itself fails. Disabled tools are omitted from
+`tools/list`; direct calls receive the standard unknown-tool error. `enabled`
+gates discovery and dispatch, but the operation must still authorize current
+permissions in its app service or database. Repeating the predicate against the
+same `ctx.appContext` is not a fresh authorization check.
+
+Modern responses advertise caching policy to clients: static catalogs are
+`public` for 24 hours; catalogs containing any `enabled` predicate are `private`
+for 12 hours. `private` means a client must not reuse the result across auth
+contexts; it does not itself enforce endpoint access. The publish manifest
+always contains the complete tool union and marks predicate-bearing entries as
+`conditional`, so Lovable can review and display the full API surface.
+
 `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 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.
@@ -63,7 +144,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 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.
+`.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 complete build-time tool catalog (`name`/`title`/`description`/`annotations`, JSON-Schema `inputSchema`/`outputSchema`, and `conditional: true` for tools with an `enabled` predicate). It's produced by loading the entry and reading the catalog off the `defineMcp` result, so it includes tools built programmatically (spreads, computed names, tools from npm) even when a live caller's `tools/list` narrows the catalog. **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:
 
@@ -135,21 +216,29 @@ The SDK only uses discovery + JWKS. It never calls the authorization or token en
 
 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.
+it to the handler. `ToolContext` extends `AuthContext`, which is also what
+`createAppContext` receives as `auth`; helpers that need the auth should take an
+`AuthContext` parameter so both call sites can share them.
 
 ```ts
-import type { ToolContext } from "@lovable.dev/mcp-js";
+import type { AuthContext } from "@lovable.dev/mcp-js";
+
+// Usable from tool handlers (`ctx`) and from `createAppContext` (`auth`).
+function requireUserId(auth: AuthContext): string {
+  const userId = auth.getUserId(); // token `sub`, or undefined when unauthenticated
+  if (!userId) throw new Error("Authenticated caller required");
+  return userId;
+}
 
 handler: async ({ title }, ctx) => {
-  const userId = ctx.getUserId();  // token `sub`, or undefined when unauthenticated
+  const userId = requireUserId(ctx);
   // 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 |
+| `AuthContext` method (inherited by `ToolContext`) | Returns |
 | --- | --- |
 | `isAuthenticated()` | `true` when the call carries a verified auth context. |
 | `getUserId()` | The token `sub` (subject) — the user id. |
@@ -257,11 +346,11 @@ setLogLevel("debug"); // "silent" | "error" | "warn" | "info" | "debug"
 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`, a request with no parseable bearer as `auth.no_bearer_token`, and a rejected token as `auth.token_rejected` (a `jose` rejection such as an expired token carries the `jose` error name and code; the full reason appears at `debug` as `oauth.verify.rejected`) — so a request rejected for insufficient scope shows both `oauth.verify.ok` and the `auth.token_rejected` that follows it. A sustained flood of `auth.token_rejected` whose `code` is `ERR_JOSE_NOT_SUPPORTED` or `ERR_JOSE_ALG_NOT_ALLOWED` (rather than `ERR_JWT_EXPIRED`) points at server-side key or algorithm configuration, not client error.
+A `500` on an OAuth-protected route is always one of three 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`), a throw from the app's own `createAppContext` or an `enabled` predicate (`mcp.app_context_error`, carrying that error's name and message), 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`, a request with no parseable bearer as `auth.no_bearer_token`, and a rejected token as `auth.token_rejected` (a `jose` rejection such as an expired token carries the `jose` error name and code; the full reason appears at `debug` as `oauth.verify.rejected`) — so a request rejected for insufficient scope shows both `oauth.verify.ok` and the `auth.token_rejected` that follows it. A sustained flood of `auth.token_rejected` whose `code` is `ERR_JOSE_NOT_SUPPORTED` or `ERR_JOSE_ALG_NOT_ALLOWED` (rather than `ERR_JWT_EXPIRED`) points at server-side key or algorithm configuration, not client error.
 
 ## Usage metrics
 
-Each MCP server records per-invocation telemetry — tool name, JSON-RPC method, outcome, latency, request and response sizes when available, and the verified token `sub` for authenticated calls — 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. The bearer token, full claims, tool arguments, and response payloads are never 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, latency, request and response sizes when available, and the verified token `sub` for authenticated calls — 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`), `app_context_error` for a request failed by a throwing `createAppContext` or `enabled`, 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. The bearer token, full claims, tool arguments, and response payloads are never 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:
 

package/dist/{authorize-CzyL7nmF.d.cts → authorize-BmYO5_-I.d.cts}

@@ -1,4 +1,4 @@
-import "./types-B3_lX-L1.cjs";
+import "./types-BCKyT2wb.cjs";
 //#region src/metrics/recorder.d.ts
 type ScheduleBackground = (task: Promise<unknown>) => void;
 //#endregion

package/dist/{authorize-Drz_eJ7O.d.ts → authorize-d9-8n9u3.d.ts}

@@ -1,4 +1,4 @@
-import "./types-B3_lX-L1.js";
+import "./types-BCKyT2wb.js";
 //#region src/metrics/recorder.d.ts
 type ScheduleBackground = (task: Promise<unknown>) => void;
 //#endregion

package/dist/{base-COwtdWE8.d.ts → base-BAxrhVjq.d.ts}

@@ -1,6 +1,6 @@
-import { E as McpProtocolEra } from "./types-B3_lX-L1.js";
+import { j as McpProtocolEra } from "./types-BCKyT2wb.js";
 //#region src/metrics/impl/base.d.ts
-type InvocationOutcome = "ok" | "tool_error" | "handler_error" | "transport_error" | "auth_challenge" | "origin_rejected" | "auth_discovery_config_error" | "auth_discovery_unreachable" | "auth_jwks_config_error" | "auth_jwks_unreachable";
+type InvocationOutcome = "ok" | "tool_error" | "handler_error" | "transport_error" | "app_context_error" | "auth_challenge" | "origin_rejected" | "auth_discovery_config_error" | "auth_discovery_unreachable" | "auth_jwks_config_error" | "auth_jwks_unreachable";
 /** One recorded MCP call. Carries no arguments or response payloads — only the
  *  tool name, the JSON-RPC method, the result class, timing, and byte sizes.
  *  `errorText` is the sole exception: it is logged locally for debugging and

package/dist/{base-DD4MCXZ6.d.cts → base-Bmw6Wrb-.d.cts}

@@ -1,6 +1,6 @@
-import { E as McpProtocolEra } from "./types-B3_lX-L1.cjs";
+import { j as McpProtocolEra } from "./types-BCKyT2wb.cjs";
 //#region src/metrics/impl/base.d.ts
-type InvocationOutcome = "ok" | "tool_error" | "handler_error" | "transport_error" | "auth_challenge" | "origin_rejected" | "auth_discovery_config_error" | "auth_discovery_unreachable" | "auth_jwks_config_error" | "auth_jwks_unreachable";
+type InvocationOutcome = "ok" | "tool_error" | "handler_error" | "transport_error" | "app_context_error" | "auth_challenge" | "origin_rejected" | "auth_discovery_config_error" | "auth_discovery_unreachable" | "auth_jwks_config_error" | "auth_jwks_unreachable";
 /** One recorded MCP call. Carries no arguments or response payloads — only the
  *  tool name, the JSON-RPC method, the result class, timing, and byte sizes.
  *  `errorText` is the sole exception: it is logged locally for debugging and

package/dist/cli/extract-manifest.cjs

@@ -4,7 +4,7 @@ const projectRoot = process.argv[2] ?? process.cwd();
 import("zod/v3").catch((err) => {
 	const message = err instanceof Error ? err.message : String(err);
 	throw new Error(`@lovable.dev/mcp-js requires zod ^3.25 or ^4.0 to extract MCP schemas. Verify the project's zod dependency and package resolution, then try again. Underlying error: ${message}`);
-}).then(() => Promise.resolve().then(() => require("../io-DZD6xmJQ.cjs"))).then(({ runExtract }) => runExtract(projectRoot)).catch((err) => {
+}).then(() => Promise.resolve().then(() => require("../io-DaqblVaG.cjs"))).then(({ runExtract }) => runExtract(projectRoot)).catch((err) => {
 	console.error(err instanceof Error ? err.message : String(err));
 	process.exit(1);
 });

package/dist/cli/extract-manifest.js

@@ -4,7 +4,7 @@ const projectRoot = process.argv[2] ?? process.cwd();
 import("zod/v3").catch((err) => {
 	const message = err instanceof Error ? err.message : String(err);
 	throw new Error(`@lovable.dev/mcp-js requires zod ^3.25 or ^4.0 to extract MCP schemas. Verify the project's zod dependency and package resolution, then try again. Underlying error: ${message}`);
-}).then(() => import("../io-DG83CLKx.js")).then(({ runExtract }) => runExtract(projectRoot)).catch((err) => {
+}).then(() => import("../io-DD8wjGjd.js")).then(({ runExtract }) => runExtract(projectRoot)).catch((err) => {
 	console.error(err instanceof Error ? err.message : String(err));
 	process.exit(1);
 });

package/dist/{cors-BaRKDl4r.js → cors-BfacizN-.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-BNFIhH0F.js";
+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-CpLgYbCG.js";
+import { t as version } from "./package-cPx-zYIb.js";
 import "./metadata-path-CAkNcfyY.js";
 import { createLocalJWKSet, decodeProtectedHeader, errors, jwtVerify } from "jose";
 //#region src/core/http.ts

package/dist/{cors-D-X0aP4O.cjs → cors-Dm9Yn8E5.cjs}

@@ -1,5 +1,5 @@
-const require_logger = require("./logger-CN1q-KNn.cjs");
-const require_package = require("./package-CFVl3oIe.cjs");
+const require_logger = require("./logger-C-Hdu57K.cjs");
+const require_package = require("./package-hWM0Ru0w.cjs");
 require("./metadata-path-zd7NSNoa.cjs");
 let jose = require("jose");
 //#region src/core/http.ts

package/dist/errors-CpTdzogX.cjs

@@ -0,0 +1,308 @@
+const require_logger = require("./logger-C-Hdu57K.cjs");
+const require_schema = require("./schema-D3vClxb7.cjs");
+//#region src/core/define.ts
+function toolRequiresAppContext(tool) {
+	return "requiresAppContext" in tool && tool.requiresAppContext === true;
+}
+function assertUniqueNames(mcp) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const tool of mcp.tools) {
+		if (seen.has(tool.name)) throw new Error(`@lovable.dev/mcp-js: duplicate tool name "${tool.name}"`);
+		seen.add(tool.name);
+	}
+}
+function assertAppContextConfiguration(mcp) {
+	if (mcp.createAppContext && !mcp.auth) throw new Error(`@lovable.dev/mcp-js: createAppContext requires auth`);
+	if (!mcp.createAppContext && mcp.tools.some((tool) => tool.enabled || toolRequiresAppContext(tool))) throw new Error(`@lovable.dev/mcp-js: app-context or conditional tools require createAppContext`);
+}
+function assertNonEmptyString(label, value) {
+	if (value.trim() === "") throw new Error(`@lovable.dev/mcp-js: ${label} must not be empty`);
+	if (value !== value.trim()) throw new Error(`@lovable.dev/mcp-js: ${label} must not have leading or trailing whitespace`);
+}
+function assertHttpsUrlField(name, value) {
+	assertNonEmptyString(`auth.${name}`, value);
+	require_logger.parseSafeUrl(`@lovable.dev/mcp-js: auth.${name}`, value);
+}
+function assertScope(scope) {
+	if (scope.trim() === "" || /\s/.test(scope)) throw new Error(`@lovable.dev/mcp-js: OAuth scopes must be non-empty space-free tokens`);
+}
+function assertJwtAlgorithm(algorithm) {
+	if (algorithm.trim() === "" || /\s/.test(algorithm)) throw new Error(`@lovable.dev/mcp-js: auth.algorithms must contain non-empty space-free tokens`);
+	if (/^HS\d+$/i.test(algorithm) || algorithm.toLowerCase() === "none") throw new Error(`@lovable.dev/mcp-js: auth.algorithms cannot include "${algorithm}"; this verifier is JWKS-only`);
+}
+const MAX_CLOCK_TOLERANCE_SECONDS = 300;
+function assertClockToleranceSeconds(value) {
+	if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > MAX_CLOCK_TOLERANCE_SECONDS) throw new Error(`@lovable.dev/mcp-js: auth.clockToleranceSeconds must be a non-negative number of seconds no greater than ${MAX_CLOCK_TOLERANCE_SECONDS}`);
+}
+function assertOAuthConfig(auth) {
+	if (auth.type !== "oauth") {
+		const authType = String(auth.type);
+		throw new Error(`@lovable.dev/mcp-js: unsupported auth type "${authType}"`);
+	}
+	if (auth.issuer === void 0) throw new Error(`@lovable.dev/mcp-js: auth.issuer is required`);
+	assertHttpsUrlField("issuer", auth.issuer);
+	if (auth.jwksUri !== void 0) assertHttpsUrlField("jwksUri", auth.jwksUri);
+	if (auth.resource !== void 0) assertHttpsUrlField("resource", auth.resource);
+	if (auth.resourceName !== void 0) assertNonEmptyString("auth.resourceName", auth.resourceName);
+	if (auth.resourceDocumentation !== void 0) assertHttpsUrlField("resourceDocumentation", auth.resourceDocumentation);
+	if (auth.protectedResourceMetadataUrl !== void 0) assertHttpsUrlField("protectedResourceMetadataUrl", auth.protectedResourceMetadataUrl);
+	if (auth.acceptedAudiences !== void 0) {
+		if (!Array.isArray(auth.acceptedAudiences)) throw new Error(`@lovable.dev/mcp-js: auth.acceptedAudiences must be an array`);
+		if (auth.acceptedAudiences.length === 0) throw new Error(`@lovable.dev/mcp-js: auth.acceptedAudiences must not be empty`);
+		for (const audience of auth.acceptedAudiences) {
+			if (typeof audience !== "string") throw new Error(`@lovable.dev/mcp-js: auth.acceptedAudiences must contain strings`);
+			assertNonEmptyString("auth.acceptedAudiences", audience);
+			if (require_logger.trimTrailingSlash(audience) === "") throw new Error(`@lovable.dev/mcp-js: auth.acceptedAudiences entries must not be only slashes`);
+		}
+	}
+	if (auth.requireOAuthClientClaim !== void 0 && typeof auth.requireOAuthClientClaim !== "boolean") throw new Error(`@lovable.dev/mcp-js: auth.requireOAuthClientClaim must be a boolean`);
+	if (auth.acceptResourceClaim !== void 0 && typeof auth.acceptResourceClaim !== "boolean") throw new Error(`@lovable.dev/mcp-js: auth.acceptResourceClaim must be a boolean`);
+	if (auth.requiredScopes !== void 0) {
+		if (!Array.isArray(auth.requiredScopes)) throw new Error(`@lovable.dev/mcp-js: auth.requiredScopes must be an array`);
+		for (const scope of auth.requiredScopes) assertScope(scope);
+	}
+	if (auth.algorithms !== void 0) {
+		if (!Array.isArray(auth.algorithms)) throw new Error(`@lovable.dev/mcp-js: auth.algorithms must be an array`);
+		if (auth.algorithms.length === 0) throw new Error(`@lovable.dev/mcp-js: auth.algorithms must not be empty`);
+		for (const algorithm of auth.algorithms) assertJwtAlgorithm(algorithm);
+	}
+	if (auth.accessTokenTyp !== void 0) {
+		if (!Array.isArray(auth.accessTokenTyp)) throw new Error(`@lovable.dev/mcp-js: auth.accessTokenTyp must be an array`);
+		if (auth.accessTokenTyp.length === 0) throw new Error(`@lovable.dev/mcp-js: auth.accessTokenTyp must not be empty`);
+		for (const typ of auth.accessTokenTyp) {
+			if (typeof typ !== "string") throw new Error(`@lovable.dev/mcp-js: auth.accessTokenTyp must contain strings`);
+			assertNonEmptyString("auth.accessTokenTyp", typ);
+		}
+	}
+	if (auth.clockToleranceSeconds !== void 0) assertClockToleranceSeconds(auth.clockToleranceSeconds);
+	if (auth.resource === void 0 && auth.acceptedAudiences === void 0) throw new Error(`@lovable.dev/mcp-js: auth.resource or auth.acceptedAudiences is required`);
+}
+function freezeAuth(auth) {
+	if (!auth) return;
+	if (auth.acceptedAudiences) Object.freeze(auth.acceptedAudiences);
+	if (auth.requiredScopes) Object.freeze(auth.requiredScopes);
+	if (auth.algorithms) Object.freeze(auth.algorithms);
+	if (auth.accessTokenTyp) Object.freeze(auth.accessTokenTyp);
+	Object.freeze(auth);
+}
+function assertAllowedOrigins(allowedOrigins) {
+	if (allowedOrigins === void 0 || allowedOrigins === "any") return;
+	if (!Array.isArray(allowedOrigins)) throw new Error(`@lovable.dev/mcp-js: allowedOrigins must be "any" or an array of exact origins`);
+	for (const origin of allowedOrigins) {
+		if (typeof origin !== "string") throw new Error(`@lovable.dev/mcp-js: allowedOrigins must contain strings`);
+		let parsed;
+		try {
+			parsed = new URL(origin);
+		} catch {
+			throw new Error(`@lovable.dev/mcp-js: allowedOrigins must contain valid exact origins`);
+		}
+		if (parsed.protocol !== "http:" && parsed.protocol !== "https:" || parsed.origin !== origin) throw new Error(`@lovable.dev/mcp-js: allowedOrigins entry "${origin}" must be an exact http(s) origin without a path, query, fragment, or trailing slash`);
+	}
+}
+function assertToolSchemas(mcp) {
+	for (const tool of mcp.tools) for (const [name, definition, strategy] of [[
+		"inputSchema",
+		tool.inputSchema,
+		"input"
+	], [
+		"outputSchema",
+		tool.outputSchema,
+		"output"
+	]]) {
+		if (!definition) continue;
+		try {
+			require_schema.jsonSchemaFromDefinition(definition, strategy);
+		} catch (error) {
+			const detail = error instanceof Error ? `: ${error.message}` : "";
+			throw new Error(`@lovable.dev/mcp-js: tool "${tool.name}" ${name} cannot be represented as JSON Schema${detail}`);
+		}
+	}
+}
+const defineStaticTool = (def) => def;
+const defineTool = Object.assign(defineStaticTool, { withAppContext: () => (def) => {
+	return {
+		...def,
+		requiresAppContext: true
+	};
+} });
+/**
+* Declare the MCP server. `export default` the result from your MCP
+* entrypoint (default `lib/mcp/index.ts`); the Vite plugin reads it to
+* emit the framework-specific route(s) at build time.
+*/
+function defineMcp(def) {
+	assertNonEmptyString("name", def.name);
+	assertNonEmptyString("title", def.title);
+	assertNonEmptyString("version", def.version);
+	assertUniqueNames(def);
+	assertAppContextConfiguration(def);
+	if (def.auth) assertOAuthConfig(def.auth);
+	assertAllowedOrigins(def.allowedOrigins);
+	assertToolSchemas(def);
+	require_logger.resolveMetricsConfig(def.metrics);
+	freezeAuth(def.auth);
+	if (Array.isArray(def.allowedOrigins)) Object.freeze(def.allowedOrigins);
+	Object.freeze(def.tools);
+	for (const tool of def.tools) Object.freeze(tool);
+	return def;
+}
+//#endregion
+//#region src/auth/context.ts
+const NEVER_ABORTED = new AbortController().signal;
+/** Verified caller identity exposed to the app-context factory.
+* `getToken()` is the sole bearer escape hatch. */
+var AuthContext = 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;
+	}
+};
+/** The per-request context passed to every tool handler as its second argument. */
+var ToolContext = class extends AuthContext {
+	#appContext;
+	#signal;
+	#client;
+	#sendProgress;
+	constructor(auth, request = {}, appContext) {
+		super(auth);
+		this.#appContext = appContext;
+		this.#signal = request.signal ?? NEVER_ABORTED;
+		this.#client = request.client ?? { protocol: "legacy" };
+		this.#sendProgress = request.sendProgress;
+	}
+	/** App-defined context created for this tool call. */
+	get appContext() {
+		return this.#appContext;
+	}
+	/** 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);
+	}
+};
+//#endregion
+//#region src/core/errors.ts
+const TOOL_ERROR_BRAND = Symbol.for("@lovable.dev/mcp-js/tool-error");
+/** Error whose message is meant for the remote MCP caller; thrown from a handler
+*  it becomes an `isError` result carrying exactly `message`. */
+var ToolError = class extends Error {
+	constructor(message, options) {
+		super(message, options);
+		this.name = "ToolError";
+		Object.defineProperty(this, TOOL_ERROR_BRAND, { value: true });
+	}
+};
+function isToolError(err) {
+	return err instanceof Error && Object.getOwnPropertyDescriptor(err, TOOL_ERROR_BRAND)?.value === true;
+}
+/** The caller-visible message of a thrown ToolError, or undefined for anything
+*  else — including when inspecting the value itself throws (fail closed). */
+function resolveToolErrorMessage(err) {
+	try {
+		return isToolError(err) ? String(err.message) : void 0;
+	} catch {
+		return;
+	}
+}
+const MAX_ERROR_SUMMARY = 500;
+/** Bounded name+message line for local logs; never for wire responses. */
+function errorSummary(err) {
+	try {
+		const text = err instanceof Error ? `${err.name}: ${err.message}` : String(err);
+		return text.length > MAX_ERROR_SUMMARY ? `${text.slice(0, MAX_ERROR_SUMMARY)}…` : text;
+	} catch {
+		return "unprintable error";
+	}
+}
+//#endregion
+Object.defineProperty(exports, "AuthContext", {
+	enumerable: true,
+	get: function() {
+		return AuthContext;
+	}
+});
+Object.defineProperty(exports, "ToolContext", {
+	enumerable: true,
+	get: function() {
+		return ToolContext;
+	}
+});
+Object.defineProperty(exports, "ToolError", {
+	enumerable: true,
+	get: function() {
+		return ToolError;
+	}
+});
+Object.defineProperty(exports, "defineMcp", {
+	enumerable: true,
+	get: function() {
+		return defineMcp;
+	}
+});
+Object.defineProperty(exports, "defineTool", {
+	enumerable: true,
+	get: function() {
+		return defineTool;
+	}
+});
+Object.defineProperty(exports, "errorSummary", {
+	enumerable: true,
+	get: function() {
+		return errorSummary;
+	}
+});
+Object.defineProperty(exports, "resolveToolErrorMessage", {
+	enumerable: true,
+	get: function() {
+		return resolveToolErrorMessage;
+	}
+});
+Object.defineProperty(exports, "toolRequiresAppContext", {
+	enumerable: true,
+	get: function() {
+		return toolRequiresAppContext;
+	}
+});