@lovable.dev/mcp-js 0.14.0 → 0.15.0

package/dist/stacks/tanstack/index.cjs

@@ -649,23 +649,240 @@ function corsPreflightResponse(allowMethods) {
   });
 }
 
+// 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
+  });
+}
+
+// package.json
+var version = "0.15.0";
+
+// 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 } });
+}
+
 // src/protocols/mcp/protocol.ts
-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);
@@ -686,7 +903,7 @@ function createMcpProtocolHandler(mcp, options = {}) {
             outputSchema: tool.outputSchema,
             annotations: tool.annotations
           },
-          adaptToolToSdkCallback(tool, authResult.auth)
+          adaptToolToSdkCallback(tool, authResult.auth, recorder)
         );
       }
       const transport = new import_webStandardStreamableHttp.WebStandardStreamableHTTPServerTransport({
@@ -695,6 +912,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" } },
@@ -828,7 +1046,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) => {
@@ -884,20 +1102,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/stacks/tanstack/index.d.cts

@@ -1,5 +1,5 @@
 import { M as McpRuntimeOptions } from '../../authorize-BMeXd_Sh.js';
-import { d as McpDefinition } from '../../types-BanzncFh.js';
+import { d as McpDefinition } from '../../types-COY42xux.js';
 import 'zod';
 
 interface TanStackRouteCtx {

package/dist/stacks/tanstack/index.d.ts

@@ -1,5 +1,5 @@
 import { M as McpRuntimeOptions } from '../../authorize-BMeXd_Sh.js';
-import { d as McpDefinition } from '../../types-BanzncFh.js';
+import { d as McpDefinition } from '../../types-COY42xux.js';
 import 'zod';
 
 interface TanStackRouteCtx {

package/dist/stacks/tanstack/index.js

@@ -3,20 +3,22 @@ import {
 } from "../../chunk-UQK5UO6C.js";
 import {
   createMcpProtocolHandler
-} from "../../chunk-WLNT2FX7.js";
+} from "../../chunk-RHDEW56Y.js";
 import {
   createOAuthProtectedResourceMetadataHandler
 } from "../../chunk-QDKOF4UF.js";
 import {
   createInvokeToolHandler
-} from "../../chunk-YWLMMDET.js";
+} from "../../chunk-T2RED2TG.js";
 import {
   createListToolsHandler
 } from "../../chunk-VNRQPA4K.js";
-import "../../chunk-MA5H6PSF.js";
+import "../../chunk-XQSTN54Y.js";
+import "../../chunk-P3F324UC.js";
 import "../../chunk-G4XA7IJM.js";
 import "../../chunk-QC3DXQTH.js";
 import "../../chunk-6DXGZZA4.js";
+import "../../chunk-LWHVXXKQ.js";
 
 // src/stacks/tanstack/handlers.ts
 function forwarded(request, options) {

package/dist/{types-BanzncFh.d.ts → types-COY42xux.d.ts}

@@ -105,6 +105,29 @@ declare class ToolContext {
     getClaims(): JwtClaims | undefined;
 }
 
+/**
+ * Usage-metrics options. Pass a boolean to the Vite plugins for the common
+ * on/off case, or this object to override the ingest endpoint (e.g. to
+ * self-host the collector outside Lovable).
+ */
+interface MetricsOptions {
+    /** Master switch. Default `true`; metrics still self-disable at runtime when
+     *  the API key env var is absent. */
+    enabled?: boolean;
+    /** OTLP/HTTP (JSON) logs URL to POST batches to — the default Lovable route or
+     *  any OTLP collector. Must be an absolute http(s) URL.
+     *  @default "https://api.lovable.dev/v1/app-mcp-usage" */
+    endpoint?: string;
+    /** Extra request headers — e.g. the auth token for a private OTLP collector.
+     *  Sent verbatim with every batch (and baked into the build output, so source
+     *  your own build-time env for secrets). Ignored for the default Lovable
+     *  endpoint, which authenticates with `LOVABLE_API_KEY` instead. `content-type`
+     *  cannot be overridden (OTLP/HTTP JSON requires `application/json`). */
+    headers?: Record<string, string>;
+}
+/** Either the bare on/off toggle or the full options object. */
+type MetricsConfig = boolean | MetricsOptions;
+
 /**
  * Any zod schema. Aliased to zod's `ZodType` (no generics) — non-deprecated
  * in both v3 and v4. Use this when you need to type an individual schema;
@@ -273,10 +296,16 @@ interface McpDefinitionInput {
      */
     readonly instructions: string;
     readonly tools: readonly AnyToolDefinition[];
+    /**
+     * Usage-metrics emission (runtime telemetry), on by default. `false` opts out;
+     * `{ endpoint, headers }` sends to your own OTLP collector. Self-disables at
+     * runtime without `LOVABLE_API_KEY` on the default Lovable endpoint.
+     */
+    readonly metrics?: MetricsConfig;
 }
 declare const McpDefinitionBrand: unique symbol;
 type McpDefinition = McpDefinitionInput & {
     readonly [McpDefinitionBrand]: never;
 };
 
-export { type AudioContent as A, type ContentAnnotations as C, type EmbeddedBlobResource as E, type ImageContent as I, type JwtClaims as J, type McpAuthConfig as M, type ResourceLink as R, type TextContent as T, type ZodRawShape as Z, type ContentBlock as a, type EmbeddedResource as b, type EmbeddedTextResource as c, type McpDefinition as d, type McpDefinitionInput as e, type ResourceLinkIcon as f, type ToolAnnotations as g, type ToolContent as h, ToolContext as i, type ToolDefinition as j, type ToolHandlerResult as k, type ZodSchema as l };
+export { type AudioContent as A, type ContentAnnotations as C, type EmbeddedBlobResource as E, type ImageContent as I, type JwtClaims as J, type McpAuthConfig as M, type ResourceLink as R, type TextContent as T, type ZodRawShape as Z, type ContentBlock as a, type EmbeddedResource as b, type EmbeddedTextResource as c, type McpDefinition as d, type McpDefinitionInput as e, type MetricsConfig as f, type MetricsOptions as g, type ResourceLinkIcon as h, type ToolAnnotations as i, type ToolContent as j, ToolContext as k, type ToolDefinition as l, type ToolHandlerResult as m, type ZodSchema as n };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lovable.dev/mcp-js",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Author MCP servers for Lovable apps. Declare tools with defineTool, register them in defineMcp, and a framework adapter (TanStack or Supabase Edge Functions) emits the route(s) at build time.",
   "type": "module",
   "repository": {