@lovable.dev/mcp-js 0.21.1-rc.1 → 0.22.0

package/dist/authorize-BMeXd_Sh.d.ts

@@ -0,0 +1,25 @@
+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;
+    /**
+     * Host-relative path of the SDK-served protected-resource metadata document.
+     * The Vite plugin injects it into every emitted handler when it generates the
+     * PRM route, so the 401 challenge advertises the same path the route serves.
+     * Its presence is the signal that the SDK owns the PRM document, so it is
+     * mutually exclusive with `auth.protectedResourceMetadataUrl` (which points at
+     * an externally hosted document). Defaults to the well-known path when absent.
+     */
+    metadataPath?: string;
+    /**
+     * Derive the request origin (and thus the advertised `resource`/metadata URLs)
+     * from `X-Forwarded-Host` rather than the rewritten `Host`. Stack adapters read
+     * this before invoking the handler, so the OAuth runtime never sees it; safe
+     * only behind a proxy that overwrites the header (see `core/forwarded.ts`).
+     */
+    trustForwardedHost?: boolean;
+}
+
+export type { McpRuntimeOptions as M };

package/dist/base-CM-KCpp6.d.ts

@@ -0,0 +1,28 @@
+type InvocationOutcome = "ok" | "tool_error" | "handler_error" | "transport_error" | "auth_config_error";
+/** 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
+ *  deliberately never included in the OTLP payload (see `emit` / `buildLogsPayload`). */
+interface InvocationRecord {
+    /** Tool name for `tools/call`; `null` for list/initialize, transport faults, and auth-config failures. */
+    tool: string | null;
+    /** JSON-RPC method, e.g. `tools/call`; `authorize` for auth-config failures. */
+    method: string;
+    outcome: InvocationOutcome;
+    durationMs: number;
+    reqBytes?: number;
+    resBytes?: number;
+    /** The app end-user that made the call (the access token `sub`), or
+     *  `undefined` when the request is unauthenticated. Not a Lovable identity. */
+    endUserId?: string;
+    /** The `tool_error` message (text content of an `isError` result). Local log
+     *  only — never sent to the collector, so it stays on-box for the operator. */
+    errorText?: string;
+}
+/** A per-request telemetry recorder. `emit` logs the invocation and sends it as a
+ *  single OTLP POST, awaited so it lands before the request ends. */
+interface MetricsRecorder {
+    emit(ev: InvocationRecord): Promise<void>;
+}
+
+export type { MetricsRecorder as M };

package/dist/chunk-4EHZUUS5.js

@@ -0,0 +1,141 @@
+import {
+  extractTextContent
+} from "./chunk-6QFZYYUV.js";
+import {
+  ToolContext
+} from "./chunk-MA5H6PSF.js";
+import {
+  JSON_HEADERS,
+  assertRestResourceBinding,
+  corsPreflightResponse,
+  createNoopRecorder,
+  createRequestAuthorizer,
+  methodNotAllowed,
+  nowMs,
+  withCors
+} from "./chunk-RK62EMPY.js";
+
+// src/protocols/rest/invoke-tool.ts
+import { getParseErrorMessage, objectFromShape, safeParseAsync } from "@modelcontextprotocol/sdk/server/zod-compat.js";
+var MAX_REFLECTED_TOOL_NAME = 256;
+function safeReflectName(name) {
+  const text = String(name);
+  return text.length > MAX_REFLECTED_TOOL_NAME ? `${text.slice(0, MAX_REFLECTED_TOOL_NAME)}\u2026` : text;
+}
+function isEmptyArgs(value) {
+  if (value == null)
+    return true;
+  if (typeof value !== "object" || Array.isArray(value))
+    return false;
+  return Object.keys(value).length === 0;
+}
+function createInvokeToolHandler(mcp, options = {}) {
+  assertRestResourceBinding(mcp, options);
+  const authorizer = createRequestAuthorizer(mcp, options);
+  const handle = async (request, toolName, recorder) => {
+    const authResult = await authorizer.authorize(request, recorder);
+    if (!authResult.ok)
+      return authResult.response;
+    const endUserId = authResult.auth?.principal.sub;
+    if (request.method !== "POST")
+      return methodNotAllowed("POST, OPTIONS");
+    const tool = mcp.tools.find((t) => t.name === toolName);
+    if (!tool) {
+      return new Response(JSON.stringify({ error: `unknown tool: ${safeReflectName(toolName)}` }), {
+        status: 404,
+        headers: JSON_HEADERS
+      });
+    }
+    let rawArgs = {};
+    const text = await request.text();
+    if (text) {
+      try {
+        rawArgs = JSON.parse(text);
+      } catch {
+        return new Response(JSON.stringify({ error: "invalid JSON body" }), {
+          status: 400,
+          headers: JSON_HEADERS
+        });
+      }
+    }
+    let args = rawArgs;
+    if (tool.inputSchema) {
+      try {
+        const schema = objectFromShape(tool.inputSchema);
+        const parsed = await safeParseAsync(schema, rawArgs);
+        if (!parsed.success) {
+          return new Response(
+            JSON.stringify({
+              error: "validation failed",
+              details: getParseErrorMessage(parsed.error)
+            }),
+            { status: 400, headers: JSON_HEADERS }
+          );
+        }
+        args = parsed.data;
+      } catch {
+        return new Response(JSON.stringify({ error: "schema error", tool: toolName }), {
+          status: 500,
+          headers: JSON_HEADERS
+        });
+      }
+    } else if (!isEmptyArgs(rawArgs)) {
+      return new Response(JSON.stringify({ error: "tool has no inputSchema; expected empty body" }), {
+        status: 400,
+        headers: JSON_HEADERS
+      });
+    }
+    let result;
+    const start = nowMs();
+    try {
+      result = await tool.handler(args, new ToolContext(authResult.auth));
+    } catch {
+      await recorder.emit({
+        tool: tool.name,
+        method: "tools/call",
+        outcome: "handler_error",
+        durationMs: nowMs() - start,
+        endUserId
+      });
+      return new Response(JSON.stringify({ error: "handler threw", tool: toolName }), {
+        status: 500,
+        headers: JSON_HEADERS
+      });
+    }
+    if (result == null) {
+      await recorder.emit({
+        tool: tool.name,
+        method: "tools/call",
+        outcome: "handler_error",
+        durationMs: nowMs() - start,
+        endUserId
+      });
+      return new Response(JSON.stringify({ error: `tool "${toolName}" returned no result` }), {
+        status: 500,
+        headers: JSON_HEADERS
+      });
+    }
+    await recorder.emit({
+      tool: tool.name,
+      method: "tools/call",
+      outcome: result.isError ? "tool_error" : "ok",
+      durationMs: nowMs() - start,
+      errorText: result.isError ? extractTextContent(result.content) : void 0,
+      endUserId
+    });
+    return Response.json({
+      content: result.content ?? [],
+      structuredContent: result.structuredContent,
+      isError: result.isError
+    });
+  };
+  return async (request, toolName, recorder = createNoopRecorder()) => {
+    if (request.method === "OPTIONS")
+      return corsPreflightResponse("POST, OPTIONS");
+    return withCors(await handle(request, toolName, recorder));
+  };
+}
+
+export {
+  createInvokeToolHandler
+};

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-6KNM7RGD.js

@@ -0,0 +1,79 @@
+import {
+  JSON_HEADERS,
+  corsPreflightResponse,
+  getOAuthRuntime,
+  headResponse,
+  methodNotAllowed,
+  oauthConfigurationErrorResponse,
+  resolveProtectedResource,
+  withCors
+} from "./chunk-RK62EMPY.js";
+import {
+  describeError,
+  log
+} from "./chunk-H37EB22A.js";
+
+// src/protocols/oauth-metadata.ts
+function notFound() {
+  return withCors(
+    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, "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 corsPreflightResponse("GET, HEAD, OPTIONS");
+    if (request.method !== "GET" && request.method !== "HEAD")
+      return withCors(methodNotAllowed("GET, HEAD, OPTIONS"));
+    const headers = {
+      ...JSON_HEADERS,
+      "Cache-Control": "public, max-age=300",
+      Vary: "Host"
+    };
+    try {
+      const metadata = await buildProtectedResourceMetadata(
+        mcp,
+        runtime.auth,
+        request,
+        runtime.options,
+        runtime.discovery
+      );
+      const response = withCors(Response.json(metadata, { headers }));
+      return request.method === "HEAD" ? headResponse(response) : response;
+    } 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;
+    }
+  };
+}
+
+export {
+  createOAuthProtectedResourceMetadataHandler
+};

package/dist/chunk-6QFZYYUV.js

@@ -0,0 +1,11 @@
+// src/core/content.ts
+function extractTextContent(content) {
+  if (!content)
+    return void 0;
+  const text = content.filter((block) => block.type === "text").map((block) => block.text).join("\n").trim();
+  return text.length > 0 ? text : void 0;
+}
+
+export {
+  extractTextContent
+};

package/dist/chunk-EOFPMSND.js

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

package/dist/chunk-H37EB22A.js

@@ -0,0 +1,125 @@
+// 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;
+}
+var LOG_LEVEL_ENV_VAR = "LOVABLE_MCP_LOG_LEVEL";
+function readEnvLevel() {
+  try {
+    const raw = typeof process !== "undefined" ? process.env?.[LOG_LEVEL_ENV_VAR] : void 0;
+    const normalized = raw?.trim().toLowerCase();
+    return isLogLevel(normalized) ? normalized : void 0;
+  } catch {
+    return void 0;
+  }
+}
+var currentLevel = readEnvLevel() ?? "debug";
+function setLogLevel(level) {
+  currentLevel = level;
+}
+function parseLogLevel(raw) {
+  const normalized = raw?.trim().toLowerCase();
+  return isLogLevel(normalized) ? normalized : void 0;
+}
+function applyLogLevelFromEnv(raw) {
+  setLogLevel(parseLogLevel(raw) ?? "debug");
+}
+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/metrics/config.ts
+var DEFAULT_METRICS_ENDPOINT = "https://api.lovable.dev/v1/app-mcp-usage";
+var METRICS_API_KEY_ENV_VAR = "LOVABLE_API_KEY";
+function assertMetricsEndpoint(endpoint) {
+  let url;
+  try {
+    url = new URL(endpoint);
+  } catch {
+    throw new Error(`@lovable.dev/mcp-js: metrics.endpoint must be an absolute URL, got ${JSON.stringify(endpoint)}`);
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") {
+    throw new Error(`@lovable.dev/mcp-js: metrics.endpoint must be http(s), got ${JSON.stringify(endpoint)}`);
+  }
+}
+function resolveMetricsConfig(config = true) {
+  const options = typeof config === "boolean" ? { enabled: config } : config;
+  const endpoint = options.endpoint ?? DEFAULT_METRICS_ENDPOINT;
+  assertMetricsEndpoint(endpoint);
+  return Object.freeze({
+    enabled: options.enabled ?? true,
+    endpoint,
+    headers: options.headers ?? {},
+    apiKeyEnvVar: METRICS_API_KEY_ENV_VAR
+  });
+}
+
+// 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 {
+  DEFAULT_METRICS_ENDPOINT,
+  resolveMetricsConfig,
+  trimTrailingSlash,
+  parseSafeUrl,
+  LOG_LEVEL_ENV_VAR,
+  setLogLevel,
+  applyLogLevelFromEnv,
+  log,
+  describeError
+};

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
+};

package/dist/chunk-P43FIUMZ.js

@@ -0,0 +1,114 @@
+import {
+  extractTextContent
+} from "./chunk-6QFZYYUV.js";
+import {
+  ToolContext
+} from "./chunk-MA5H6PSF.js";
+import {
+  corsPreflightResponse,
+  createNoopRecorder,
+  createRequestAuthorizer,
+  nowMs,
+  withCors
+} from "./chunk-RK62EMPY.js";
+import {
+  describeError,
+  log
+} from "./chunk-H37EB22A.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, recorder) {
+  const endUserId = auth?.principal.sub;
+  return async (first) => {
+    const args = tool.inputSchema ? first ?? {} : {};
+    const start = nowMs();
+    let result;
+    try {
+      result = await tool.handler(args, new ToolContext(auth));
+    } catch {
+      await recorder.emit({
+        tool: tool.name,
+        method: "tools/call",
+        outcome: "handler_error",
+        durationMs: nowMs() - start,
+        endUserId
+      });
+      return { content: [{ type: "text", text: "tool execution failed" }], isError: true };
+    }
+    if (result == null) {
+      await recorder.emit({
+        tool: tool.name,
+        method: "tools/call",
+        outcome: "handler_error",
+        durationMs: nowMs() - start,
+        endUserId
+      });
+      return { content: [{ type: "text", text: `tool "${tool.name}" returned no result` }], isError: true };
+    }
+    await recorder.emit({
+      tool: tool.name,
+      method: "tools/call",
+      outcome: result.isError ? "tool_error" : "ok",
+      durationMs: nowMs() - start,
+      errorText: result.isError ? extractTextContent(result.content) : void 0,
+      endUserId
+    });
+    return { content: result.content ?? [], structuredContent: result.structuredContent, isError: result.isError };
+  };
+}
+function createMcpProtocolHandler(mcp, options = {}) {
+  const authorizer = createRequestAuthorizer(mcp, options);
+  const handle = async (request, recorder) => {
+    const authResult = await authorizer.authorize(request, recorder);
+    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, recorder)
+        );
+      }
+      const transport = new WebStandardStreamableHTTPServerTransport({
+        sessionIdGenerator: void 0
+      });
+      await server.connect(transport);
+      return await transport.handleRequest(request);
+    } catch (err) {
+      await recorder.emit({
+        tool: null,
+        method: "transport",
+        outcome: "transport_error",
+        durationMs: 0,
+        endUserId: authResult.auth?.principal.sub
+      });
+      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 }
+      );
+    }
+  };
+  return async (request, recorder = createNoopRecorder()) => {
+    if (request.method === "OPTIONS")
+      return corsPreflightResponse("GET, POST, DELETE, OPTIONS");
+    return withCors(await handle(request, recorder));
+  };
+}
+
+export {
+  createMcpProtocolHandler
+};