@lovable.dev/mcp-js 0.6.0 → 0.7.0

package/README.md

@@ -182,6 +182,27 @@ The request-derived `resource` default trusts the incoming `Host` to name this s
 
 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.
 
+## Debug logging
+
+The runtime is silent by default. Raise the log level to trace OAuth discovery, JWKS resolution, and token verification when a deployed MCP server returns `401`/`500` and you need to see why. Logs go to `console` (so they land in your platform's function logs) and **never include the bearer token, full claims, or PII** — only non-secret fields such as the JWT header `alg`/`kid`, `issuer`, `jwks_uri`, the token `sub`/`client_id`/`scopes`, and `jose` error codes.
+
+Enable it either way:
+
+```ts
+// Programmatic — works on every runtime, including Workers that pass env via bindings.
+import { setLogLevel } from "@lovable.dev/mcp-js";
+setLogLevel("debug"); // "silent" | "error" | "warn" | "info" | "debug"
+```
+
+```bash
+# Or via env var, read once at startup. Node/Deno only: it reads `process.env`,
+# which is absent on a deployed Cloudflare Worker (env arrives via bindings), so
+# the var is silently ignored there — use `setLogLevel()` on Workers.
+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.
+
 ## Subpath exports
 
 | Subpath                                 | Contents                                                                |

package/dist/{chunk-SYI32IRK.js → chunk-53M2X7FU.js}

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

package/dist/{chunk-K2T4WTKX.js → chunk-722HKLIU.js}

@@ -7,7 +7,11 @@ import {
   oauthConfigurationErrorResponse,
   resolveProtectedResource,
   withCors
-} from "./chunk-ZKKLOL2C.js";
+} from "./chunk-NTXHOUK6.js";
+import {
+  describeError,
+  log
+} from "./chunk-QC3DXQTH.js";
 
 // src/protocols/oauth-metadata.ts
 function notFound() {
@@ -62,7 +66,8 @@ function createOAuthProtectedResourceMetadataHandler(mcp, options = {}) {
       );
       const response = withCors(Response.json(metadata, { headers }));
       return request.method === "HEAD" ? headResponse(response) : response;
-    } catch {
+    } catch (err) {
+      log.error("oauth.metadata.config_error", { ...describeError(err), outcome: "500 oauth configuration error" });
       const response = withCors(oauthConfigurationErrorResponse());
       return request.method === "HEAD" ? headResponse(response) : response;
     }

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

@@ -5,7 +5,11 @@ import {
   corsPreflightResponse,
   createRequestAuthorizer,
   withCors
-} from "./chunk-ZKKLOL2C.js";
+} from "./chunk-NTXHOUK6.js";
+import {
+  describeError,
+  log
+} from "./chunk-QC3DXQTH.js";
 
 // src/protocols/mcp/protocol.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -54,7 +58,8 @@ function createMcpProtocolHandler(mcp, options = {}) {
       });
       await server.connect(transport);
       return await transport.handleRequest(request);
-    } catch {
+    } catch (err) {
+      log.error("mcp.transport_error", { ...describeError(err), outcome: "500 internal error" });
       return Response.json(
         { jsonrpc: "2.0", id: null, error: { code: -32603, message: "internal error" } },
         { status: 500 }

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

@@ -1,7 +1,9 @@
 import {
+  describeError,
+  log,
   parseSafeUrl,
   trimTrailingSlash
-} from "./chunk-QA3FWDUV.js";
+} from "./chunk-QC3DXQTH.js";
 import {
   OAUTH_PROTECTED_RESOURCE_METADATA_PATH
 } from "./chunk-6DXGZZA4.js";
@@ -43,16 +45,29 @@ function resolveResourcePath(resourcePath, request) {
 }
 
 // src/core/promise.ts
-function cachedPromise(load) {
+function cachedPromise(load, label) {
   let settled = false;
   let value;
   return async () => {
-    if (settled)
+    if (settled) {
+      if (label)
+        log.debug(`${label}.cache_hit`);
       return value;
-    const loaded = await load();
-    settled = true;
-    value = loaded;
-    return loaded;
+    }
+    if (label)
+      log.debug(`${label}.load_start`);
+    try {
+      const loaded = await load();
+      settled = true;
+      value = loaded;
+      if (label)
+        log.debug(`${label}.settled`);
+      return loaded;
+    } catch (err) {
+      if (label)
+        log.debug(`${label}.load_failed`, describeError(err));
+      throw err;
+    }
   };
 }
 
@@ -92,13 +107,16 @@ async function fetchFirstValidOAuthServerMetadata(metadataUrls, expectedIssuer)
     try {
       return await fetchOAuthServerMetadata(url, expectedIssuer);
     } catch (err) {
+      log.debug("oauth.discovery.attempt_failed", { url, ...describeError(err) });
       errors.push(`${url}: ${err instanceof Error ? err.message : String(err)}`);
     }
   }
+  log.error("oauth.discovery.exhausted", { expectedIssuer, urlsTried: metadataUrls, errors });
   throw new Error(`failed to discover OAuth server metadata (${errors.join("; ")})`);
 }
 async function fetchOAuthServerMetadata(url, expectedIssuer) {
-  const response = await fetch(url, { signal: AbortSignal.timeout(METADATA_FETCH_TIMEOUT_MS), redirect: "error" });
+  log.debug("oauth.discovery.fetch", { url });
+  const response = await fetch(url, { signal: AbortSignal.timeout(METADATA_FETCH_TIMEOUT_MS), redirect: "manual" });
   if (!response.ok) {
     throw new Error(String(response.status));
   }
@@ -108,6 +126,7 @@ async function fetchOAuthServerMetadata(url, expectedIssuer) {
   }
   parseSafeUrl("discovered issuer", json.issuer);
   if (trimTrailingSlash(json.issuer) !== expectedIssuer) {
+    log.warn("oauth.discovery.issuer_mismatch", { url, expectedIssuer, published: json.issuer });
     throw new Error("issuer mismatch");
   }
   if (typeof json.jwks_uri !== "string") {
@@ -120,6 +139,11 @@ async function fetchIssuerOAuthServerMetadata(issuer) {
   try {
     return await fetchFirstValidOAuthServerMetadata(oauthMetadataUrlsForIssuer(issuer), issuer);
   } catch (err) {
+    log.error("oauth.discovery.config_error", {
+      issuer,
+      ...describeError(err),
+      outcome: "500 oauth configuration error"
+    });
     throw new OAuthConfigurationError(
       `OAuth issuer discovery failed: ${err instanceof Error ? err.message : String(err)}`
     );
@@ -127,15 +151,26 @@ async function fetchIssuerOAuthServerMetadata(issuer) {
 }
 function createOAuthDiscoveryResolver(auth) {
   const configuredIssuer = trimTrailingSlash(auth.issuer);
-  const oauthServerMetadata = cachedPromise(() => fetchIssuerOAuthServerMetadata(configuredIssuer));
+  const oauthServerMetadata = cachedPromise(
+    () => fetchIssuerOAuthServerMetadata(configuredIssuer),
+    "oauth.discovery.metadata"
+  );
   return {
     resolveIssuer: async () => configuredIssuer,
-    resolveJwksUri: async () => auth.jwksUri ?? (await oauthServerMetadata()).jwks_uri
+    resolveJwksUri: async () => {
+      if (auth.jwksUri) {
+        log.debug("oauth.jwks.resolved", { jwksUri: auth.jwksUri, source: "configured" });
+        return auth.jwksUri;
+      }
+      const jwksUri = (await oauthServerMetadata()).jwks_uri;
+      log.debug("oauth.jwks.resolved", { jwksUri, source: "discovered" });
+      return jwksUri;
+    }
   };
 }
 
 // src/auth/verifier.ts
-import { createRemoteJWKSet, errors as joseErrors, jwtVerify } from "jose";
+import { createRemoteJWKSet, decodeProtectedHeader, errors as joseErrors, jwtVerify } from "jose";
 
 // src/auth/claims.ts
 function readString(value) {
@@ -166,6 +201,14 @@ var OAuthTokenError = class extends Error {
 function resolveAcceptedAudiences(auth, resource) {
   return auth.acceptedAudiences ?? [resource];
 }
+function tokenHeaderFields(token) {
+  try {
+    const header = decodeProtectedHeader(token);
+    return { jwtAlg: header.alg, jwtKid: header.kid, tokenLength: token.length };
+  } catch {
+    return { tokenLength: token.length };
+  }
+}
 function isJwksFetchFailure(err) {
   if (err instanceof joseErrors.JWKSTimeout || err instanceof joseErrors.JWKSInvalid)
     return true;
@@ -187,19 +230,23 @@ async function verifyJwtClaims(token, keySet, issuer, audience, auth) {
     return payload;
   } catch (err) {
     if (isJwksFetchFailure(err)) {
+      log.error("oauth.jwks.fetch_failed", { ...describeError(err), outcome: "500 oauth configuration error" });
       throw new OAuthConfigurationError(`JWKS fetch failed: ${err instanceof Error ? err.message : String(err)}`);
     }
+    log.debug("oauth.verify.rejected", { ...describeError(err), outcome: "401 invalid_token" });
     throw err;
   }
 }
 function assertNonEmptySubject(claims) {
   const sub = claims["sub"];
   if (typeof sub !== "string" || sub.trim() === "") {
+    log.debug("oauth.verify.bad_subject", { subType: typeof sub });
     throw new OAuthTokenError(401, "invalid_token", "token subject claim must be a non-empty string");
   }
 }
 function assertOAuthClientClaim(auth, clientId) {
   if (auth.requireOAuthClientClaim !== false && !clientId) {
+    log.debug("oauth.verify.missing_client_claim", { outcome: "401 invalid_token" });
     throw new OAuthTokenError(401, "invalid_token", "OAuth client claim is required");
   }
 }
@@ -224,17 +271,23 @@ function buildMcpAuthContext(args) {
   };
 }
 function createOAuthTokenVerifier(auth, discovery) {
-  const loadRemoteJwksKeySet = cachedPromise(
-    () => discovery.resolveJwksUri().then((jwksURI) => createRemoteJWKSet(new URL(jwksURI)))
-  );
   return async (token, request, options) => {
     const resource = resolveProtectedResource(auth, request, options);
     const issuer = await discovery.resolveIssuer();
     const acceptedAudiences = resolveAcceptedAudiences(auth, resource);
-    const claims = await verifyJwtClaims(token, await loadRemoteJwksKeySet(), issuer, acceptedAudiences, auth);
+    log.debug("oauth.verify.start", { issuer, acceptedAudiences, resource, ...tokenHeaderFields(token) });
+    const jwksUri = await discovery.resolveJwksUri();
+    log.debug("oauth.jwks.keyset_created", { jwksUri });
+    const keySet = createRemoteJWKSet(new URL(jwksUri));
+    const claims = await verifyJwtClaims(token, keySet, issuer, acceptedAudiences, auth);
     assertNonEmptySubject(claims);
     const context = buildMcpAuthContext({ token, claims, issuer, resource, acceptedAudiences });
     assertOAuthClientClaim(auth, context.principal.clientId);
+    log.info("oauth.verify.ok", {
+      sub: context.principal.sub,
+      clientId: context.principal.clientId,
+      scopes: context.principal.scopes
+    });
     return context;
   };
 }
@@ -334,22 +387,27 @@ function createRequestAuthorizer(mcp, options = {}) {
       if (runtime.kind === "unconfigured")
         return { ok: true };
       const token = parseBearerToken(request);
-      if (!token)
+      if (!token) {
+        log.info("auth.no_bearer_token", { outcome: "401" });
         return { ok: false, response: challengeResponse(runtime.auth, request, 401) };
+      }
       try {
         const auth = await runtime.verify(token, request, runtime.options);
         assertRequiredScopes(runtime.auth, auth);
         return { ok: true, auth };
       } catch (err) {
         if (err instanceof OAuthConfigurationError) {
+          log.error("auth.config_error", { ...describeError(err), outcome: "500" });
           return { ok: false, response: oauthConfigurationErrorResponse() };
         }
         if (err instanceof OAuthTokenError) {
+          log.info("auth.token_rejected", { status: err.status, oauthError: err.oauthError });
           return {
             ok: false,
             response: challengeResponse(runtime.auth, request, err.status, err.oauthError, err.message)
           };
         }
+        log.error("auth.unexpected_error", { ...describeError(err), outcome: "401" });
         return {
           ok: false,
           response: challengeResponse(runtime.auth, request, 401, "invalid_token", "Invalid access token")

package/dist/chunk-QC3DXQTH.js

@@ -0,0 +1,87 @@
+// src/core/logger.ts
+var LEVEL_RANK = { silent: 0, error: 1, warn: 2, info: 3, debug: 4 };
+function isLogLevel(value) {
+  return typeof value === "string" && value in LEVEL_RANK;
+}
+function readEnvLevel() {
+  try {
+    const raw = typeof process !== "undefined" ? process.env?.["LOVABLE_MCP_LOG_LEVEL"] : void 0;
+    const normalized = raw?.trim().toLowerCase();
+    return isLogLevel(normalized) ? normalized : void 0;
+  } catch {
+    return void 0;
+  }
+}
+var currentLevel = readEnvLevel() ?? "silent";
+function setLogLevel(level) {
+  currentLevel = level;
+}
+function enabled(level) {
+  return LEVEL_RANK[level] <= LEVEL_RANK[currentLevel];
+}
+function emit(level, method, event, fields) {
+  if (!enabled(level))
+    return;
+  const message = `[mcp-js] ${event}`;
+  if (fields)
+    console[method](message, fields);
+  else
+    console[method](message);
+}
+var log = {
+  error: (event, fields) => emit("error", "error", event, fields),
+  warn: (event, fields) => emit("warn", "warn", event, fields),
+  info: (event, fields) => emit("info", "info", event, fields),
+  debug: (event, fields) => emit("debug", "debug", event, fields)
+};
+function describeError(err) {
+  if (err instanceof Error) {
+    const code = err.code;
+    return { name: err.name, message: err.message, ...typeof code === "string" ? { code } : {} };
+  }
+  return { value: String(err) };
+}
+
+// src/core/url.ts
+function trimTrailingSlash(value) {
+  return value.replace(/\/+$/, "");
+}
+function isLocalHTTPHost(hostname) {
+  return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]";
+}
+function urlSafetyProblem(url) {
+  const isAllowedHTTP = url.protocol === "http:" && isLocalHTTPHost(url.hostname);
+  if (url.protocol !== "https:" && !isAllowedHTTP) {
+    return "must use https://, except localhost development URLs";
+  }
+  if (url.username || url.password) {
+    return "must not include credentials";
+  }
+  if (url.search || url.hash) {
+    return "must not include query or fragment";
+  }
+  return void 0;
+}
+
+// src/core/validation.ts
+function parseSafeUrl(subject, raw, ErrorClass = Error) {
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new ErrorClass(`${subject} must be an absolute URL`);
+  }
+  const problem = urlSafetyProblem(url);
+  if (problem) {
+    throw new ErrorClass(`${subject} ${problem}`);
+  }
+  return url;
+}
+
+export {
+  trimTrailingSlash,
+  parseSafeUrl,
+  setLogLevel,
+  log,
+  describeError
+};

package/dist/index.cjs

@@ -23,7 +23,8 @@ __export(src_exports, {
   ToolContext: () => ToolContext,
   auth: () => auth,
   defineMcp: () => defineMcp,
-  defineTool: () => defineTool
+  defineTool: () => defineTool,
+  setLogLevel: () => setLogLevel
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -262,10 +263,30 @@ var ToolContext = class {
     return this.#auth?.principal.claims;
   }
 };
+
+// src/core/logger.ts
+var LEVEL_RANK = { silent: 0, error: 1, warn: 2, info: 3, debug: 4 };
+function isLogLevel(value) {
+  return typeof value === "string" && value in LEVEL_RANK;
+}
+function readEnvLevel() {
+  try {
+    const raw = typeof process !== "undefined" ? process.env?.["LOVABLE_MCP_LOG_LEVEL"] : void 0;
+    const normalized = raw?.trim().toLowerCase();
+    return isLogLevel(normalized) ? normalized : void 0;
+  } catch {
+    return void 0;
+  }
+}
+var currentLevel = readEnvLevel() ?? "silent";
+function setLogLevel(level) {
+  currentLevel = level;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ToolContext,
   auth,
   defineMcp,
-  defineTool
+  defineTool,
+  setLogLevel
 });

package/dist/index.d.cts

@@ -53,4 +53,12 @@ declare const auth: Readonly<{
     }>;
 }>;
 
-export { type IssuerOAuthOptions, McpDefinitionInput, ToolDefinition, ZodRawShape, auth, defineMcp, defineTool };
+type LogLevel = "silent" | "error" | "warn" | "info" | "debug";
+/**
+ * Set the runtime log level programmatically. Use this when the deployment can't
+ * surface `LOVABLE_MCP_LOG_LEVEL` to the package (e.g. a Cloudflare Worker that
+ * passes vars via bindings): call `setLogLevel("debug")` once at server startup.
+ */
+declare function setLogLevel(level: LogLevel): void;
+
+export { type IssuerOAuthOptions, type LogLevel, McpDefinitionInput, ToolDefinition, ZodRawShape, auth, defineMcp, defineTool, setLogLevel };

package/dist/index.d.ts

@@ -53,4 +53,12 @@ declare const auth: Readonly<{
     }>;
 }>;
 
-export { type IssuerOAuthOptions, McpDefinitionInput, ToolDefinition, ZodRawShape, auth, defineMcp, defineTool };
+type LogLevel = "silent" | "error" | "warn" | "info" | "debug";
+/**
+ * Set the runtime log level programmatically. Use this when the deployment can't
+ * surface `LOVABLE_MCP_LOG_LEVEL` to the package (e.g. a Cloudflare Worker that
+ * passes vars via bindings): call `setLogLevel("debug")` once at server startup.
+ */
+declare function setLogLevel(level: LogLevel): void;
+
+export { type IssuerOAuthOptions, type LogLevel, McpDefinitionInput, ToolDefinition, ZodRawShape, auth, defineMcp, defineTool, setLogLevel };

package/dist/index.js

@@ -2,8 +2,9 @@ import {
   ToolContext
 } from "./chunk-MA5H6PSF.js";
 import {
-  parseSafeUrl
-} from "./chunk-QA3FWDUV.js";
+  parseSafeUrl,
+  setLogLevel
+} from "./chunk-QC3DXQTH.js";
 
 // src/core/define.ts
 function assertUniqueNames(mcp) {
@@ -168,5 +169,6 @@ export {
   ToolContext,
   auth,
   defineMcp,
-  defineTool
+  defineTool,
+  setLogLevel
 };