@lovable.dev/mcp-js 0.13.0 → 0.15.0

package/README.md

@@ -49,7 +49,9 @@ That's the whole authoring surface. No imperative server construction, no route
 | `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 table shows the default `path: "/mcp"`. The REST companions co-locate under the parent of the configured `path`, so `mcpPlugin({ path: "/api/public/mcp" })` emits them at `/api/public/.mcp/list-tools` and `/api/public/.mcp/invoke-tool/<tool>` (file: `src/routes/api/public/[.mcp]/...`). Pass `restRoutes: false` to drop them.
+
+MCP (`POST <path>`, `/mcp` by default) is the public wire format clients speak directly. REST (the `.mcp/*` companions, co-located under the `path` parent) 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.
 
@@ -215,6 +217,34 @@ 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.
 
+## Usage metrics
+
+Each MCP server records per-invocation telemetry — tool name, JSON-RPC method, outcome (`ok` / `handler_error` / `transport_error`), and latency — and POSTs it in fire-and-forget batches as **OTLP/HTTP JSON logs**. No tool arguments or response payloads are ever captured. Emission is **on by default**, self-disables at runtime when `LOVABLE_API_KEY` is absent (so a local `vite dev` stays silent), and degrades silently — a failed flush never blocks or fails a tool call.
+
+Configure it on the MCP definition:
+
+```ts
+import { defineMcp } from "@lovable.dev/mcp-js";
+
+export default defineMcp({
+  name: "my-app-mcp",
+  // ...
+  tools: [],
+  metrics: {
+    endpoint: "https://your-collector.example.com/v1/logs",
+    headers: { authorization: "Bearer your-token" },
+  },
+});
+```
+
+| Use case | Config |
+| --- | --- |
+| **Default (recommended)** | Omit `metrics`, or `metrics: true` — batches to Lovable, authenticated with `LOVABLE_API_KEY` |
+| **Opt out entirely** | `metrics: false` |
+| **Self-hosted collector** | `metrics: { endpoint, headers? }` — your own OTLP/HTTP (JSON) endpoint |
+
+**Key scoping:** `LOVABLE_API_KEY` is read and sent (as the bearer) **only** for the default Lovable endpoint; a custom collector is reached with your own `headers` and never receives the workspace key. `headers` are baked into the build output, so source any token from your own build-time env. `content-type` is forced to `application/json` and can't be overridden.
+
 ## 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 bundles your MCP entry and its local imports into one self-contained Deno function (with esbuild) instead of emitting a tree of file-router routes. Third-party dependencies are left as `npm:` specifiers that Deno resolves at runtime, so no import map / `deno.json` is needed.

package/dist/{chunk-SIITHGUD.js → chunk-LWHVXXKQ.js}

@@ -1,5 +1,5 @@
 // package.json
-var version = "0.13.0";
+var version = "0.15.0";
 
 export {
   version

package/dist/{chunk-MA5H6PSF.js → chunk-P3F324UC.js}

@@ -41,6 +41,40 @@ var ToolContext = class {
   }
 };
 
+// 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";
+var METRICS_SAMPLE_RATE = 1;
+var METRICS_FLUSH_INTERVAL_MS = 5e3;
+var METRICS_MAX_BATCH_SIZE = 50;
+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,
+    sampleRate: METRICS_SAMPLE_RATE,
+    flushIntervalMs: METRICS_FLUSH_INTERVAL_MS,
+    maxBatchSize: METRICS_MAX_BATCH_SIZE
+  });
+}
+
 export {
+  DEFAULT_METRICS_ENDPOINT,
+  resolveMetricsConfig,
   ToolContext
 };

package/dist/{chunk-WLNT2FX7.js → chunk-RHDEW56Y.js}

@@ -1,6 +1,10 @@
+import {
+  createRecorderForRuntime,
+  nowMs
+} from "./chunk-XQSTN54Y.js";
 import {
   ToolContext
-} from "./chunk-MA5H6PSF.js";
+} from "./chunk-P3F324UC.js";
 import {
   corsPreflightResponse,
   createRequestAuthorizer,
@@ -14,22 +18,31 @@ import {
 // 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) {
+function adaptToolToSdkCallback(tool, auth, recorder) {
   return async (first) => {
     const args = tool.inputSchema ? first ?? {} : {};
+    const start = nowMs();
     let result;
     try {
       result = await tool.handler(args, new ToolContext(auth));
     } catch {
+      recorder.record({ tool: tool.name, method: "tools/call", outcome: "handler_error", durationMs: nowMs() - start });
       return { content: [{ type: "text", text: "tool execution failed" }], isError: true };
     }
     if (result == null) {
+      recorder.record({ tool: tool.name, method: "tools/call", outcome: "handler_error", durationMs: nowMs() - start });
       return { content: [{ type: "text", text: `tool "${tool.name}" returned no result` }], isError: true };
     }
+    recorder.record({
+      tool: tool.name,
+      method: "tools/call",
+      outcome: result.isError ? "tool_error" : "ok",
+      durationMs: nowMs() - start
+    });
     return { content: result.content ?? [], structuredContent: result.structuredContent, isError: result.isError };
   };
 }
-function createMcpProtocolHandler(mcp, options = {}) {
+function createMcpProtocolHandler(mcp, options = {}, recorder = createRecorderForRuntime(mcp)) {
   const authorizer = createRequestAuthorizer(mcp, options);
   const handle = async (request) => {
     const authResult = await authorizer.authorize(request);
@@ -50,7 +63,7 @@ function createMcpProtocolHandler(mcp, options = {}) {
             outputSchema: tool.outputSchema,
             annotations: tool.annotations
           },
-          adaptToolToSdkCallback(tool, authResult.auth)
+          adaptToolToSdkCallback(tool, authResult.auth, recorder)
         );
       }
       const transport = new WebStandardStreamableHTTPServerTransport({
@@ -59,6 +72,7 @@ function createMcpProtocolHandler(mcp, options = {}) {
       await server.connect(transport);
       return await transport.handleRequest(request);
     } catch (err) {
+      recorder.record({ tool: null, method: "transport", outcome: "transport_error", durationMs: 0 });
       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" } },

package/dist/{chunk-YWLMMDET.js → chunk-T2RED2TG.js}

@@ -1,6 +1,10 @@
+import {
+  createRecorderForRuntime,
+  nowMs
+} from "./chunk-XQSTN54Y.js";
 import {
   ToolContext
-} from "./chunk-MA5H6PSF.js";
+} from "./chunk-P3F324UC.js";
 import {
   JSON_HEADERS,
   assertRestResourceBinding,
@@ -24,7 +28,7 @@ function isEmptyArgs(value) {
     return false;
   return Object.keys(value).length === 0;
 }
-function createInvokeToolHandler(mcp, options = {}) {
+function createInvokeToolHandler(mcp, options = {}, recorder = createRecorderForRuntime(mcp)) {
   assertRestResourceBinding(mcp, options);
   const authorizer = createRequestAuthorizer(mcp, options);
   const handle = async (request, toolName) => {
@@ -80,20 +84,29 @@ function createInvokeToolHandler(mcp, options = {}) {
       });
     }
     let result;
+    const start = nowMs();
     try {
       result = await tool.handler(args, new ToolContext(authResult.auth));
     } catch {
+      recorder.record({ tool: tool.name, method: "tools/call", outcome: "handler_error", durationMs: nowMs() - start });
       return new Response(JSON.stringify({ error: "handler threw", tool: toolName }), {
         status: 500,
         headers: JSON_HEADERS
       });
     }
     if (result == null) {
+      recorder.record({ tool: tool.name, method: "tools/call", outcome: "handler_error", durationMs: nowMs() - start });
       return new Response(JSON.stringify({ error: `tool "${toolName}" returned no result` }), {
         status: 500,
         headers: JSON_HEADERS
       });
     }
+    recorder.record({
+      tool: tool.name,
+      method: "tools/call",
+      outcome: result.isError ? "tool_error" : "ok",
+      durationMs: nowMs() - start
+    });
     return Response.json({
       content: result.content ?? [],
       structuredContent: result.structuredContent,

package/dist/chunk-XQSTN54Y.js

@@ -0,0 +1,189 @@
+import {
+  DEFAULT_METRICS_ENDPOINT,
+  resolveMetricsConfig
+} from "./chunk-P3F324UC.js";
+import {
+  describeError,
+  log
+} from "./chunk-QC3DXQTH.js";
+import {
+  version
+} from "./chunk-LWHVXXKQ.js";
+
+// src/metrics/otlp.ts
+var SCOPE_NAME = "@lovable.dev/mcp-js";
+var EVENT_NAME = "mcp.tool.invocation";
+var SEVERITY_INFO = 9;
+function strAttr(key, value) {
+  return { key, value: { stringValue: value } };
+}
+function intAttr(key, value) {
+  return { key, value: { intValue: String(Math.round(value)) } };
+}
+function toLogRecord(rec) {
+  const attributes = [
+    strAttr("event.name", EVENT_NAME),
+    strAttr("mcp.method", rec.method),
+    strAttr("mcp.outcome", rec.outcome),
+    intAttr("mcp.duration_ms", rec.durationMs)
+  ];
+  if (rec.tool !== null)
+    attributes.push(strAttr("mcp.tool", rec.tool));
+  if (rec.reqBytes !== void 0)
+    attributes.push(intAttr("mcp.request_size_bytes", rec.reqBytes));
+  if (rec.resBytes !== void 0)
+    attributes.push(intAttr("mcp.response_size_bytes", rec.resBytes));
+  return {
+    timeUnixNano: rec.timeUnixNano,
+    observedTimeUnixNano: rec.timeUnixNano,
+    severityNumber: SEVERITY_INFO,
+    severityText: "INFO",
+    body: { stringValue: EVENT_NAME },
+    attributes
+  };
+}
+function buildLogsPayload(records, server) {
+  return JSON.stringify({
+    resourceLogs: [
+      {
+        resource: {
+          attributes: [
+            strAttr("service.name", server.name),
+            strAttr("service.version", server.version),
+            strAttr("telemetry.sdk.name", SCOPE_NAME),
+            strAttr("telemetry.sdk.version", version),
+            strAttr("telemetry.sdk.language", "webjs")
+          ]
+        },
+        scopeLogs: [
+          {
+            scope: { name: SCOPE_NAME, version },
+            logRecords: records.map(toLogRecord)
+          }
+        ]
+      }
+    ]
+  });
+}
+function nowUnixNano() {
+  return `${Date.now()}000000`;
+}
+
+// src/metrics/recorder.ts
+function nowMs() {
+  return typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
+}
+var NOOP_RECORDER = {
+  record() {
+  },
+  async flush() {
+  }
+};
+function createNoopRecorder() {
+  return NOOP_RECORDER;
+}
+function readRuntimeEnv(name) {
+  try {
+    const denoEnv = globalThis.Deno?.env;
+    const value = denoEnv?.get?.(name);
+    if (value)
+      return value;
+  } catch {
+  }
+  try {
+    if (typeof process !== "undefined") {
+      const value = process.env?.[name];
+      if (value)
+        return value;
+    }
+  } catch {
+  }
+  return void 0;
+}
+function probeWaitUntil() {
+  const fn = globalThis.EdgeRuntime?.waitUntil;
+  return typeof fn === "function" ? fn.bind(globalThis.EdgeRuntime) : void 0;
+}
+function createMetricsRecorder(ctx, deps = {}) {
+  const { config, server } = ctx;
+  if (!config.enabled)
+    return NOOP_RECORDER;
+  const doFetch = deps.fetch ?? globalThis.fetch;
+  if (!doFetch)
+    return NOOP_RECORDER;
+  const usesLovableEndpoint = config.endpoint === DEFAULT_METRICS_ENDPOINT;
+  const apiKey = usesLovableEndpoint ? (deps.getApiKey ?? (() => readRuntimeEnv(config.apiKeyEnvVar)))() : void 0;
+  if (usesLovableEndpoint && !apiKey) {
+    log.debug("metrics.disabled_no_api_key", { envVar: config.apiKeyEnvVar });
+    return NOOP_RECORDER;
+  }
+  const waitUntil = deps.waitUntil ?? probeWaitUntil();
+  const buffer = [];
+  let timer;
+  const schedule = (p) => {
+    if (waitUntil) {
+      try {
+        waitUntil(p);
+        return;
+      } catch {
+      }
+    }
+    void p.catch(() => {
+    });
+  };
+  const headers = {};
+  if (!usesLovableEndpoint) {
+    for (const [key, value] of Object.entries(config.headers)) {
+      if (key.toLowerCase() !== "content-type")
+        headers[key] = value;
+    }
+  }
+  headers["content-type"] = "application/json";
+  if (apiKey)
+    headers.authorization = `Bearer ${apiKey}`;
+  const flush = async () => {
+    if (buffer.length === 0)
+      return;
+    const records = buffer.splice(0, buffer.length);
+    try {
+      const res = await doFetch(config.endpoint, {
+        method: "POST",
+        headers,
+        body: buildLogsPayload(records, server),
+        keepalive: true
+      });
+      if (!res.ok)
+        log.debug("metrics.flush_rejected", { status: res.status });
+    } catch (err) {
+      log.debug("metrics.flush_failed", describeError(err));
+    }
+  };
+  const ensureTimer = () => {
+    if (timer !== void 0)
+      return;
+    timer = setInterval(() => schedule(flush()), config.flushIntervalMs);
+    timer.unref?.();
+  };
+  return {
+    record(ev) {
+      if (config.sampleRate < 1 && Math.random() >= config.sampleRate)
+        return;
+      buffer.push({ ...ev, timeUnixNano: nowUnixNano() });
+      ensureTimer();
+      if (buffer.length >= config.maxBatchSize)
+        schedule(flush());
+    },
+    flush
+  };
+}
+function createRecorderForRuntime(mcp) {
+  const config = resolveMetricsConfig(mcp.metrics);
+  if (!config.enabled)
+    return createNoopRecorder();
+  return createMetricsRecorder({ config, server: { name: mcp.name, version: mcp.version } });
+}
+
+export {
+  nowMs,
+  createRecorderForRuntime
+};

package/dist/cli/extract-manifest.cjs

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

package/dist/cli/extract-manifest.js

@@ -5,12 +5,12 @@ import {
 import "../chunk-G4XA7IJM.js";
 import "../chunk-QC3DXQTH.js";
 import "../chunk-6DXGZZA4.js";
-import {
-  version
-} from "../chunk-SIITHGUD.js";
 import {
   isFileMissing
 } from "../chunk-Y3ZFPEQH.js";
+import {
+  version
+} from "../chunk-LWHVXXKQ.js";
 
 // src/manifest/io.ts
 import { randomUUID } from "crypto";

package/dist/index.cjs

@@ -28,6 +28,38 @@ __export(src_exports, {
 });
 module.exports = __toCommonJS(src_exports);
 
+// 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";
+var METRICS_SAMPLE_RATE = 1;
+var METRICS_FLUSH_INTERVAL_MS = 5e3;
+var METRICS_MAX_BATCH_SIZE = 50;
+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,
+    sampleRate: METRICS_SAMPLE_RATE,
+    flushIntervalMs: METRICS_FLUSH_INTERVAL_MS,
+    maxBatchSize: METRICS_MAX_BATCH_SIZE
+  });
+}
+
 // src/core/url.ts
 function isLocalHTTPHost(hostname) {
   return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]";
@@ -202,6 +234,7 @@ function defineMcp(def) {
   assertUniqueNames(def);
   if (def.auth)
     assertOAuthConfig(def.auth);
+  resolveMetricsConfig(def.metrics);
   freezeAuth(def.auth);
   Object.freeze(def.tools);
   for (const tool of def.tools)

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { e as McpDefinitionInput, d as McpDefinition, Z as ZodRawShape, j as ToolDefinition, M as McpAuthConfig } from './types-BanzncFh.js';
-export { A as AudioContent, C as ContentAnnotations, a as ContentBlock, E as EmbeddedBlobResource, b as EmbeddedResource, c as EmbeddedTextResource, I as ImageContent, J as JwtClaims, R as ResourceLink, f as ResourceLinkIcon, T as TextContent, g as ToolAnnotations, h as ToolContent, i as ToolContext, k as ToolHandlerResult, l as ZodSchema } from './types-BanzncFh.js';
+import { e as McpDefinitionInput, d as McpDefinition, Z as ZodRawShape, l as ToolDefinition, M as McpAuthConfig } from './types-COY42xux.js';
+export { A as AudioContent, C as ContentAnnotations, a as ContentBlock, E as EmbeddedBlobResource, b as EmbeddedResource, c as EmbeddedTextResource, I as ImageContent, J as JwtClaims, f as MetricsConfig, g as MetricsOptions, R as ResourceLink, h as ResourceLinkIcon, T as TextContent, i as ToolAnnotations, j as ToolContent, k as ToolContext, m as ToolHandlerResult, n as ZodSchema } from './types-COY42xux.js';
 import 'zod';
 
 /**

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { e as McpDefinitionInput, d as McpDefinition, Z as ZodRawShape, j as ToolDefinition, M as McpAuthConfig } from './types-BanzncFh.js';
-export { A as AudioContent, C as ContentAnnotations, a as ContentBlock, E as EmbeddedBlobResource, b as EmbeddedResource, c as EmbeddedTextResource, I as ImageContent, J as JwtClaims, R as ResourceLink, f as ResourceLinkIcon, T as TextContent, g as ToolAnnotations, h as ToolContent, i as ToolContext, k as ToolHandlerResult, l as ZodSchema } from './types-BanzncFh.js';
+import { e as McpDefinitionInput, d as McpDefinition, Z as ZodRawShape, l as ToolDefinition, M as McpAuthConfig } from './types-COY42xux.js';
+export { A as AudioContent, C as ContentAnnotations, a as ContentBlock, E as EmbeddedBlobResource, b as EmbeddedResource, c as EmbeddedTextResource, I as ImageContent, J as JwtClaims, f as MetricsConfig, g as MetricsOptions, R as ResourceLink, h as ResourceLinkIcon, T as TextContent, i as ToolAnnotations, j as ToolContent, k as ToolContext, m as ToolHandlerResult, n as ZodSchema } from './types-COY42xux.js';
 import 'zod';
 
 /**

package/dist/index.js

@@ -1,6 +1,7 @@
 import {
-  ToolContext
-} from "./chunk-MA5H6PSF.js";
+  ToolContext,
+  resolveMetricsConfig
+} from "./chunk-P3F324UC.js";
 import {
   parseSafeUrl,
   setLogLevel
@@ -147,6 +148,7 @@ function defineMcp(def) {
   assertUniqueNames(def);
   if (def.auth)
     assertOAuthConfig(def.auth);
+  resolveMetricsConfig(def.metrics);
   freezeAuth(def.auth);
   Object.freeze(def.tools);
   for (const tool of def.tools)