@lovable.dev/mcp-js 0.25.0 → 0.26.0

package/README.internal.md

@@ -1,6 +1,6 @@
 # @lovable.dev/mcp-js — internal notes
 
-Architecture rationale, source layout, and dev scripts for contributors. The user-facing docs are in [`README.md`](README.md); release rules and build-system constraints are in [`AGENTS.md`](AGENTS.md). Nothing in this file ships to npm — only `dist`, `package.json`, `README.md`, `LICENSE`, and `CHANGELOG.md` end up in the tarball.
+Architecture rationale, source layout, and dev scripts for contributors. The user-facing docs are in [`README.md`](README.md); release rules and build-system constraints are in [`AGENTS.md`](AGENTS.md). The tarball carries `dist`, `package.json`, `LICENSE`, `CHANGELOG.md`, and every root `README*` (npm force-includes them, this file included) — no source, tests, or examples.
 
 ## Folder meaning
 
@@ -159,6 +159,7 @@ tests/
   stacks/
     tanstack/{handlers,vite}.test.ts
     supabase/{handler,emit,vite}.test.ts
+    supabase/authoring-template.test.ts  # executes the App MCP authoring guides' factory (reads go/api/**, needs a monorepo checkout)
   integration/                       # boots an example app, hits live HTTP
     global-setup.ts                  # spawns example/tanstack on :8080
     tools.test.ts                    # non-OAuth example
@@ -173,7 +174,7 @@ pnpm format:check      # oxfmt --check src/ tests/
 pnpm lint              # format:check + oxlint (one command, both surfaces)
 pnpm lint:fix          # format + oxlint --fix
 pnpm typecheck         # tsgo --noEmit
-pnpm test              # vitest run --project unit  (fast, hermetic)
+pnpm test              # vitest run --project unit  (fast; needs the monorepo checkout — authoring-template.test.ts reads go/api/**)
 pnpm test:watch        # vitest --project unit
 pnpm test:integration:tanstack       # build + install tanstack example + vitest --project integration
 pnpm test:integration:tanstack:oauth # build + install OAuth example + vitest --project integration-oauth

package/README.md

@@ -171,6 +171,18 @@ construction (e.g. calling Supabase on the user's behalf); never return it from
 tool or write it to logs. A leaked token stays valid at the authorization server
 until it expires.
 
+**Caller-visible errors.** Throwing `ToolError` from a handler returns an `isError` result carrying exactly its message, on both the MCP and REST surfaces — the same shape as returning `{ isError: true, content: [...] }`. Any other exception is redacted to a generic failure on the wire; its name and message appear only in the server's local `tool.invoked` log line (`errorText`), never in telemetry.
+
+```ts
+import { ToolError } from "@lovable.dev/mcp-js";
+
+handler: async ({ id }, ctx) => {
+  const row = await findBook(ctx, id);
+  if (!row) throw new ToolError(`book ${id} not found`);
+  return { content: [{ type: "text", text: JSON.stringify(row) }] };
+};
+```
+
 Use an OAuth access token from the configured authorization server for MCP calls. Plain app-session JWTs, such as Supabase tokens from `signInWithPassword`, carry neither `client_id` nor `azp`; the SDK rejects them by default so copied browser sessions do not pass as delegated OAuth client tokens. Set `requireOAuthClientClaim: false` only when intentionally accepting those session tokens and relying on app checks plus downstream RLS via the forwarded bearer token.
 
 `auth.oauth.issuer(...)` fields:

package/dist/{base-D-dYxK8t.d.cts → base-CReh7d3E.d.cts}

@@ -16,8 +16,8 @@ interface InvocationRecord {
   /** 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. */
+  /** Caller-visible `isError` text (`tool_error`) or a bounded internal-exception
+   *  summary (`handler_error`). Local log only — never sent to the collector. */
   errorText?: string;
 }
 /** A per-request telemetry recorder. `emit` logs the invocation and sends it as a

package/dist/{base-D-dYxK8t.d.ts → base-CReh7d3E.d.ts}

@@ -16,8 +16,8 @@ interface InvocationRecord {
   /** 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. */
+  /** Caller-visible `isError` text (`tool_error`) or a bounded internal-exception
+   *  summary (`handler_error`). Local log only — never sent to the collector. */
   errorText?: string;
 }
 /** A per-request telemetry recorder. `emit` logs the invocation and sends it as a

package/dist/cli/extract-manifest.cjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-const require_package = require("../package-Wvf1u2OZ.cjs");
-const require_list_tools = require("../list-tools-DBidJV3L.cjs");
+const require_package = require("../package-C1uEtkqq.cjs");
+const require_list_tools = require("../list-tools-Ct6yJ_bo.cjs");
 const require_fs_errors = require("../fs-errors-CWNzOV75.cjs");
 let node_fs = require("node:fs");
 let node_path = require("node:path");

package/dist/cli/extract-manifest.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { t as version } from "../package-CUrmd7C5.js";
-import { t as buildMcpListing } from "../list-tools-DjzEigXr.js";
+import { t as version } from "../package-Aux8_a4B.js";
+import { t as buildMcpListing } from "../list-tools-S2xzLisA.js";
 import { t as isFileMissing } from "../fs-errors-PA2t1TIp.js";
 import { lstatSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";

package/dist/{cors-DW1p9Uzw.cjs → cors-B79id9hu.cjs}

@@ -1,5 +1,5 @@
 const require_logger = require("./logger-BSKbuM66.cjs");
-const require_package = require("./package-Wvf1u2OZ.cjs");
+const require_package = require("./package-C1uEtkqq.cjs");
 require("./metadata-path-zd7NSNoa.cjs");
 let jose = require("jose");
 //#region src/core/http.ts
@@ -168,8 +168,9 @@ var BaseMetricRecorder = class {
 			}
 			headers.authorization = `Bearer ${key}`;
 		}
+		const { errorText: _localOnly, ...wireEvent } = ev;
 		const body = buildLogsPayload([{
-			...ev,
+			...wireEvent,
 			timeUnixNano: nowUnixNano(),
 			stack: this.stack
 		}], this.server);

package/dist/{cors-1Iz86PSf.js → cors-DlHHW20_.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-3-kwsF-5.js";
-import { t as version } from "./package-CUrmd7C5.js";
+import { t as version } from "./package-Aux8_a4B.js";
 import "./metadata-path-CAkNcfyY.js";
 import { createLocalJWKSet, decodeProtectedHeader, jwtVerify } from "jose";
 //#region src/core/http.ts
@@ -168,8 +168,9 @@ var BaseMetricRecorder = class {
 			}
 			headers.authorization = `Bearer ${key}`;
 		}
+		const { errorText: _localOnly, ...wireEvent } = ev;
 		const body = buildLogsPayload([{
-			...ev,
+			...wireEvent,
 			timeUnixNano: nowUnixNano(),
 			stack: this.stack
 		}], this.server);

package/dist/errors-CN6Da8iz.cjs

@@ -0,0 +1,108 @@
+//#region src/auth/context.ts
+/**
+* The auth surface passed to every tool handler as its second argument. It wraps
+* the verified per-request auth context in a private field, so the context — and
+* the bearer token inside it — can't be read, enumerated, spread, or
+* `JSON.stringify`'d off the instance; the accessors below are the only way out.
+* `getToken()` is the single intentional escape hatch for the raw bearer.
+*/
+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;
+	}
+};
+//#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, "ToolContext", {
+	enumerable: true,
+	get: function() {
+		return ToolContext;
+	}
+});
+Object.defineProperty(exports, "ToolError", {
+	enumerable: true,
+	get: function() {
+		return ToolError;
+	}
+});
+Object.defineProperty(exports, "errorSummary", {
+	enumerable: true,
+	get: function() {
+		return errorSummary;
+	}
+});
+Object.defineProperty(exports, "resolveToolErrorMessage", {
+	enumerable: true,
+	get: function() {
+		return resolveToolErrorMessage;
+	}
+});

package/dist/{context-BweeEcoA.cjs → errors-DSe96Ffd.js}

@@ -48,9 +48,38 @@ var ToolContext = class {
 	}
 };
 //#endregion
-Object.defineProperty(exports, "ToolContext", {
-	enumerable: true,
-	get: function() {
-		return ToolContext;
+//#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
+export { ToolContext as i, errorSummary as n, resolveToolErrorMessage as r, ToolError as t };

package/dist/index.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_logger = require("./logger-BSKbuM66.cjs");
-const require_context = require("./context-BweeEcoA.cjs");
+const require_errors = require("./errors-CN6Da8iz.cjs");
 //#region src/core/define.ts
 function assertUniqueNames(mcp) {
 	const seen = /* @__PURE__ */ new Set();
@@ -142,7 +142,8 @@ function issuer(options) {
 const oauth = Object.freeze({ issuer });
 const auth = Object.freeze({ oauth });
 //#endregion
-exports.ToolContext = require_context.ToolContext;
+exports.ToolContext = require_errors.ToolContext;
+exports.ToolError = require_errors.ToolError;
 exports.auth = auth;
 exports.defineMcp = defineMcp;
 exports.defineTool = defineTool;

package/dist/index.d.cts

@@ -54,6 +54,13 @@ declare const auth: Readonly<{
   }>;
 }>;
 //#endregion
+//#region src/core/errors.d.ts
+/** Error whose message is meant for the remote MCP caller; thrown from a handler
+ *  it becomes an `isError` result carrying exactly `message`. */
+declare class ToolError extends Error {
+  constructor(message: string, options?: ErrorOptions);
+}
+//#endregion
 //#region src/core/logger.d.ts
 type LogLevel = "silent" | "error" | "warn" | "info" | "debug";
 /**
@@ -63,4 +70,4 @@ type LogLevel = "silent" | "error" | "warn" | "info" | "debug";
  */
 declare function setLogLevel(level: LogLevel): void;
 //#endregion
-export { type AudioContent, type ContentAnnotations, type ContentBlock, type EmbeddedBlobResource, type EmbeddedResource, type EmbeddedTextResource, type ImageContent, type IssuerOAuthOptions, type JwtClaims, type LogLevel, type McpDefinitionInput, type MetricsConfig, type MetricsOptions, type ResourceLink, type ResourceLinkIcon, type TextContent, type ToolAnnotations, type ToolContent, ToolContext, type ToolDefinition, type ToolHandlerResult, type ZodRawShape, type ZodSchema, auth, defineMcp, defineTool, setLogLevel };
+export { type AudioContent, type ContentAnnotations, type ContentBlock, type EmbeddedBlobResource, type EmbeddedResource, type EmbeddedTextResource, type ImageContent, type IssuerOAuthOptions, type JwtClaims, type LogLevel, type McpDefinitionInput, type MetricsConfig, type MetricsOptions, type ResourceLink, type ResourceLinkIcon, type TextContent, type ToolAnnotations, type ToolContent, ToolContext, type ToolDefinition, ToolError, type ToolHandlerResult, type ZodRawShape, type ZodSchema, auth, defineMcp, defineTool, setLogLevel };

package/dist/index.d.ts

@@ -54,6 +54,13 @@ declare const auth: Readonly<{
   }>;
 }>;
 //#endregion
+//#region src/core/errors.d.ts
+/** Error whose message is meant for the remote MCP caller; thrown from a handler
+ *  it becomes an `isError` result carrying exactly `message`. */
+declare class ToolError extends Error {
+  constructor(message: string, options?: ErrorOptions);
+}
+//#endregion
 //#region src/core/logger.d.ts
 type LogLevel = "silent" | "error" | "warn" | "info" | "debug";
 /**
@@ -63,4 +70,4 @@ type LogLevel = "silent" | "error" | "warn" | "info" | "debug";
  */
 declare function setLogLevel(level: LogLevel): void;
 //#endregion
-export { type AudioContent, type ContentAnnotations, type ContentBlock, type EmbeddedBlobResource, type EmbeddedResource, type EmbeddedTextResource, type ImageContent, type IssuerOAuthOptions, type JwtClaims, type LogLevel, type McpDefinitionInput, type MetricsConfig, type MetricsOptions, type ResourceLink, type ResourceLinkIcon, type TextContent, type ToolAnnotations, type ToolContent, ToolContext, type ToolDefinition, type ToolHandlerResult, type ZodRawShape, type ZodSchema, auth, defineMcp, defineTool, setLogLevel };
+export { type AudioContent, type ContentAnnotations, type ContentBlock, type EmbeddedBlobResource, type EmbeddedResource, type EmbeddedTextResource, type ImageContent, type IssuerOAuthOptions, type JwtClaims, type LogLevel, type McpDefinitionInput, type MetricsConfig, type MetricsOptions, type ResourceLink, type ResourceLinkIcon, type TextContent, type ToolAnnotations, type ToolContent, ToolContext, type ToolDefinition, ToolError, type ToolHandlerResult, type ZodRawShape, type ZodSchema, auth, defineMcp, defineTool, setLogLevel };

package/dist/index.js

@@ -1,5 +1,5 @@
 import { a as setLogLevel, o as parseSafeUrl, s as trimTrailingSlash, u as resolveMetricsConfig } from "./logger-3-kwsF-5.js";
-import { t as ToolContext } from "./context-CIpPzN7P.js";
+import { i as ToolContext, t as ToolError } from "./errors-DSe96Ffd.js";
 //#region src/core/define.ts
 function assertUniqueNames(mcp) {
 	const seen = /* @__PURE__ */ new Set();
@@ -141,4 +141,4 @@ function issuer(options) {
 const oauth = Object.freeze({ issuer });
 const auth = Object.freeze({ oauth });
 //#endregion
-export { ToolContext, auth, defineMcp, defineTool, setLogLevel };
+export { ToolContext, ToolError, auth, defineMcp, defineTool, setLogLevel };

package/dist/{io-CSsqm26s.d.ts → io-B-fV6rsM.d.ts}

@@ -1,4 +1,4 @@
-import "./list-tools-DKz6nJQ6.js";
+import "./list-tools-C6u8G4iq.js";
 //#region src/manifest/io.d.ts
 /**
  * Shape every MCP Vite plugin exposes on its `api` so `runExtract` can read

package/dist/{io-BlJ298VF.d.cts → io-Bd58IeVb.d.cts}

@@ -1,4 +1,4 @@
-import "./list-tools-Dk-QKfqy.cjs";
+import "./list-tools-DOBMd4AE.cjs";
 //#region src/manifest/io.d.ts
 /**
  * Shape every MCP Vite plugin exposes on its `api` so `runExtract` can read

package/dist/{list-tools-DKz6nJQ6.d.ts → list-tools-C6u8G4iq.d.ts}

@@ -1,5 +1,5 @@
 import { c as McpDefinition } from "./types-C0Wgm9zp.js";
-import { t as MetricsRecorder } from "./base-D-dYxK8t.js";
+import { t as MetricsRecorder } from "./base-CReh7d3E.js";
 import { t as McpRuntimeOptions } from "./authorize-Y6Jm8GhR.js";
 //#region src/protocols/rest/list-tools.d.ts
 type RestListToolsHandler = (request: Request, recorder?: MetricsRecorder) => Promise<Response>;

package/dist/{list-tools-DBidJV3L.cjs → list-tools-Ct6yJ_bo.cjs}

@@ -1,4 +1,4 @@
-const require_cors = require("./cors-DW1p9Uzw.cjs");
+const require_cors = require("./cors-B79id9hu.cjs");
 let _modelcontextprotocol_sdk_server_zod_compat_js = require("@modelcontextprotocol/sdk/server/zod-compat.js");
 let _modelcontextprotocol_sdk_server_zod_json_schema_compat_js = require("@modelcontextprotocol/sdk/server/zod-json-schema-compat.js");
 //#region src/protocols/rest/list-tools.ts

package/dist/{list-tools-Dk-QKfqy.d.cts → list-tools-DOBMd4AE.d.cts}

@@ -1,5 +1,5 @@
 import { c as McpDefinition } from "./types-C0Wgm9zp.cjs";
-import { t as MetricsRecorder } from "./base-D-dYxK8t.cjs";
+import { t as MetricsRecorder } from "./base-CReh7d3E.cjs";
 import { t as McpRuntimeOptions } from "./authorize-D3zzoTAG.cjs";
 //#region src/protocols/rest/list-tools.d.ts
 type RestListToolsHandler = (request: Request, recorder?: MetricsRecorder) => Promise<Response>;

package/dist/{list-tools-DjzEigXr.js → list-tools-S2xzLisA.js}

@@ -1,4 +1,4 @@
-import { i as createRequestAuthorizer, m as methodNotAllowed, n as withCors, p as headResponse, r as assertRestResourceBinding, t as corsPreflightResponse, u as createNoopRecorder } from "./cors-1Iz86PSf.js";
+import { i as createRequestAuthorizer, m as methodNotAllowed, n as withCors, p as headResponse, r as assertRestResourceBinding, t as corsPreflightResponse, u as createNoopRecorder } from "./cors-DlHHW20_.js";
 import { objectFromShape } from "@modelcontextprotocol/sdk/server/zod-compat.js";
 import { toJsonSchemaCompat } from "@modelcontextprotocol/sdk/server/zod-json-schema-compat.js";
 //#region src/protocols/rest/list-tools.ts

package/dist/{mcp-CoVt8EO9.js → mcp-BUR5KIhL.js}

@@ -1,6 +1,6 @@
 import { i as log, r as describeError } from "./logger-3-kwsF-5.js";
-import { t as ToolContext } from "./context-CIpPzN7P.js";
-import { d as nowMs, i as createRequestAuthorizer, n as withCors, t as corsPreflightResponse, u as createNoopRecorder } from "./cors-1Iz86PSf.js";
+import { i as ToolContext, n as errorSummary, r as resolveToolErrorMessage } from "./errors-DSe96Ffd.js";
+import { d as nowMs, i as createRequestAuthorizer, n as withCors, t as corsPreflightResponse, u as createNoopRecorder } from "./cors-DlHHW20_.js";
 import { t as extractTextContent } from "./content-D5LJAHyM.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
@@ -17,18 +17,29 @@ function adaptToolToSdkCallback(tool, auth, recorder) {
 		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 {
+		} catch (err) {
+			const callerMessage = resolveToolErrorMessage(err);
+			if (callerMessage === void 0) {
+				await recorder.emit({
+					tool: tool.name,
+					method: "tools/call",
+					outcome: "handler_error",
+					durationMs: nowMs() - start,
+					errorText: errorSummary(err),
+					endUserId
+				});
+				return {
+					content: [{
+						type: "text",
+						text: "tool execution failed"
+					}],
+					isError: true
+				};
+			}
+			result = {
 				content: [{
 					type: "text",
-					text: "tool execution failed"
+					text: callerMessage
 				}],
 				isError: true
 			};

package/dist/{mcp-DSo7xlpz.cjs → mcp-DNz7KIy4.cjs}

@@ -1,6 +1,6 @@
 const require_logger = require("./logger-BSKbuM66.cjs");
-const require_context = require("./context-BweeEcoA.cjs");
-const require_cors = require("./cors-DW1p9Uzw.cjs");
+const require_errors = require("./errors-CN6Da8iz.cjs");
+const require_cors = require("./cors-B79id9hu.cjs");
 const require_content = require("./content-NCYIGgOb.cjs");
 let _modelcontextprotocol_sdk_server_mcp_js = require("@modelcontextprotocol/sdk/server/mcp.js");
 let _modelcontextprotocol_sdk_server_webStandardStreamableHttp_js = require("@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js");
@@ -16,19 +16,30 @@ function adaptToolToSdkCallback(tool, auth, recorder) {
 		const start = require_cors.nowMs();
 		let result;
 		try {
-			result = await tool.handler(args, new require_context.ToolContext(auth));
-		} catch {
-			await recorder.emit({
-				tool: tool.name,
-				method: "tools/call",
-				outcome: "handler_error",
-				durationMs: require_cors.nowMs() - start,
-				endUserId
-			});
-			return {
+			result = await tool.handler(args, new require_errors.ToolContext(auth));
+		} catch (err) {
+			const callerMessage = require_errors.resolveToolErrorMessage(err);
+			if (callerMessage === void 0) {
+				await recorder.emit({
+					tool: tool.name,
+					method: "tools/call",
+					outcome: "handler_error",
+					durationMs: require_cors.nowMs() - start,
+					errorText: require_errors.errorSummary(err),
+					endUserId
+				});
+				return {
+					content: [{
+						type: "text",
+						text: "tool execution failed"
+					}],
+					isError: true
+				};
+			}
+			result = {
 				content: [{
 					type: "text",
-					text: "tool execution failed"
+					text: callerMessage
 				}],
 				isError: true
 			};

package/dist/{package-CUrmd7C5.js → package-Aux8_a4B.js}

@@ -1,4 +1,4 @@
 //#region package.json
-var version = "0.25.0";
+var version = "0.26.0";
 //#endregion
 export { version as t };

package/dist/{package-Wvf1u2OZ.cjs → package-C1uEtkqq.cjs}

@@ -1,5 +1,5 @@
 //#region package.json
-var version = "0.25.0";
+var version = "0.26.0";
 //#endregion
 Object.defineProperty(exports, "version", {
 	enumerable: true,

package/dist/protocols/mcp/index.cjs

@@ -1,3 +1,3 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_mcp = require("../../mcp-DSo7xlpz.cjs");
+const require_mcp = require("../../mcp-DNz7KIy4.cjs");
 exports.createMcpProtocolHandler = require_mcp.createMcpProtocolHandler;

package/dist/protocols/mcp/index.d.cts

@@ -1,5 +1,5 @@
 import { c as McpDefinition } from "../../types-C0Wgm9zp.cjs";
-import { t as MetricsRecorder } from "../../base-D-dYxK8t.cjs";
+import { t as MetricsRecorder } from "../../base-CReh7d3E.cjs";
 import { t as McpRuntimeOptions } from "../../authorize-D3zzoTAG.cjs";
 //#region src/protocols/mcp/protocol.d.ts
 type McpProtocolHandler = (request: Request, recorder?: MetricsRecorder) => Promise<Response>;

package/dist/protocols/mcp/index.d.ts

@@ -1,5 +1,5 @@
 import { c as McpDefinition } from "../../types-C0Wgm9zp.js";
-import { t as MetricsRecorder } from "../../base-D-dYxK8t.js";
+import { t as MetricsRecorder } from "../../base-CReh7d3E.js";
 import { t as McpRuntimeOptions } from "../../authorize-Y6Jm8GhR.js";
 //#region src/protocols/mcp/protocol.d.ts
 type McpProtocolHandler = (request: Request, recorder?: MetricsRecorder) => Promise<Response>;

package/dist/protocols/mcp/index.js

@@ -1,2 +1,2 @@
-import { t as createMcpProtocolHandler } from "../../mcp-CoVt8EO9.js";
+import { t as createMcpProtocolHandler } from "../../mcp-BUR5KIhL.js";
 export { createMcpProtocolHandler };

package/dist/protocols/oauth-metadata.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_logger = require("../logger-BSKbuM66.cjs");
-const require_cors = require("../cors-DW1p9Uzw.cjs");
+const require_cors = require("../cors-B79id9hu.cjs");
 //#region src/protocols/oauth-metadata.ts
 function notFound() {
 	return require_cors.withCors(new Response(JSON.stringify({ error: "not found" }), {

package/dist/protocols/oauth-metadata.js

@@ -1,5 +1,5 @@
 import { i as log, r as describeError } from "../logger-3-kwsF-5.js";
-import { a as getOAuthRuntime, c as resolveProtectedResource, f as JSON_HEADERS, m as methodNotAllowed, n as withCors, o as oauthConfigurationErrorResponse, p as headResponse, t as corsPreflightResponse } from "../cors-1Iz86PSf.js";
+import { a as getOAuthRuntime, c as resolveProtectedResource, f as JSON_HEADERS, m as methodNotAllowed, n as withCors, o as oauthConfigurationErrorResponse, p as headResponse, t as corsPreflightResponse } from "../cors-DlHHW20_.js";
 //#region src/protocols/oauth-metadata.ts
 function notFound() {
 	return withCors(new Response(JSON.stringify({ error: "not found" }), {

package/dist/protocols/rest/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_list_tools = require("../../list-tools-DBidJV3L.cjs");
-const require_rest = require("../../rest-CvdOnTsb.cjs");
+const require_list_tools = require("../../list-tools-Ct6yJ_bo.cjs");
+const require_rest = require("../../rest-DWrrqgYf.cjs");
 exports.createInvokeToolHandler = require_rest.createInvokeToolHandler;
 exports.createListToolsHandler = require_list_tools.createListToolsHandler;

package/dist/protocols/rest/index.d.cts

@@ -1,7 +1,7 @@
 import { c as McpDefinition } from "../../types-C0Wgm9zp.cjs";
-import { t as MetricsRecorder } from "../../base-D-dYxK8t.cjs";
+import { t as MetricsRecorder } from "../../base-CReh7d3E.cjs";
 import { t as McpRuntimeOptions } from "../../authorize-D3zzoTAG.cjs";
-import { n as createListToolsHandler, t as RestListToolsHandler } from "../../list-tools-Dk-QKfqy.cjs";
+import { n as createListToolsHandler, t as RestListToolsHandler } from "../../list-tools-DOBMd4AE.cjs";
 //#region src/protocols/rest/invoke-tool.d.ts
 type RestInvokeToolHandler = (request: Request, toolName: string, recorder?: MetricsRecorder) => Promise<Response>;
 declare function createInvokeToolHandler(mcp: McpDefinition, options?: McpRuntimeOptions): RestInvokeToolHandler;

package/dist/protocols/rest/index.d.ts

@@ -1,7 +1,7 @@
 import { c as McpDefinition } from "../../types-C0Wgm9zp.js";
-import { t as MetricsRecorder } from "../../base-D-dYxK8t.js";
+import { t as MetricsRecorder } from "../../base-CReh7d3E.js";
 import { t as McpRuntimeOptions } from "../../authorize-Y6Jm8GhR.js";
-import { n as createListToolsHandler, t as RestListToolsHandler } from "../../list-tools-DKz6nJQ6.js";
+import { n as createListToolsHandler, t as RestListToolsHandler } from "../../list-tools-C6u8G4iq.js";
 //#region src/protocols/rest/invoke-tool.d.ts
 type RestInvokeToolHandler = (request: Request, toolName: string, recorder?: MetricsRecorder) => Promise<Response>;
 declare function createInvokeToolHandler(mcp: McpDefinition, options?: McpRuntimeOptions): RestInvokeToolHandler;

package/dist/protocols/rest/index.js

@@ -1,3 +1,3 @@
-import { n as createListToolsHandler } from "../../list-tools-DjzEigXr.js";
-import { t as createInvokeToolHandler } from "../../rest-DdQMWvF4.js";
+import { n as createListToolsHandler } from "../../list-tools-S2xzLisA.js";
+import { t as createInvokeToolHandler } from "../../rest-xOYdRom7.js";
 export { createInvokeToolHandler, createListToolsHandler };

package/dist/{rest-CvdOnTsb.cjs → rest-DWrrqgYf.cjs}

@@ -1,7 +1,7 @@
-const require_context = require("./context-BweeEcoA.cjs");
-const require_cors = require("./cors-DW1p9Uzw.cjs");
+const require_errors = require("./errors-CN6Da8iz.cjs");
+const require_cors = require("./cors-B79id9hu.cjs");
 const require_content = require("./content-NCYIGgOb.cjs");
-require("./list-tools-DBidJV3L.cjs");
+require("./list-tools-Ct6yJ_bo.cjs");
 let _modelcontextprotocol_sdk_server_zod_compat_js = require("@modelcontextprotocol/sdk/server/zod-compat.js");
 //#region src/protocols/rest/invoke-tool.ts
 const MAX_REFLECTED_TOOL_NAME = 256;
@@ -64,22 +64,33 @@ function createInvokeToolHandler(mcp, options = {}) {
 		let result;
 		const start = require_cors.nowMs();
 		try {
-			result = await tool.handler(args, new require_context.ToolContext(authResult.auth));
-		} catch {
-			await recorder.emit({
-				tool: tool.name,
-				method: "tools/call",
-				outcome: "handler_error",
-				durationMs: require_cors.nowMs() - start,
-				endUserId
-			});
-			return new Response(JSON.stringify({
-				error: "handler threw",
-				tool: toolName
-			}), {
-				status: 500,
-				headers: require_cors.JSON_HEADERS
-			});
+			result = await tool.handler(args, new require_errors.ToolContext(authResult.auth));
+		} catch (err) {
+			const callerMessage = require_errors.resolveToolErrorMessage(err);
+			if (callerMessage === void 0) {
+				await recorder.emit({
+					tool: tool.name,
+					method: "tools/call",
+					outcome: "handler_error",
+					durationMs: require_cors.nowMs() - start,
+					errorText: require_errors.errorSummary(err),
+					endUserId
+				});
+				return new Response(JSON.stringify({
+					error: "handler threw",
+					tool: toolName
+				}), {
+					status: 500,
+					headers: require_cors.JSON_HEADERS
+				});
+			}
+			result = {
+				content: [{
+					type: "text",
+					text: callerMessage
+				}],
+				isError: true
+			};
 		}
 		if (result == null) {
 			await recorder.emit({

package/dist/{rest-DdQMWvF4.js → rest-xOYdRom7.js}

@@ -1,7 +1,7 @@
-import { t as ToolContext } from "./context-CIpPzN7P.js";
-import { d as nowMs, f as JSON_HEADERS, i as createRequestAuthorizer, m as methodNotAllowed, n as withCors, r as assertRestResourceBinding, t as corsPreflightResponse, u as createNoopRecorder } from "./cors-1Iz86PSf.js";
+import { i as ToolContext, n as errorSummary, r as resolveToolErrorMessage } from "./errors-DSe96Ffd.js";
+import { d as nowMs, f as JSON_HEADERS, i as createRequestAuthorizer, m as methodNotAllowed, n as withCors, r as assertRestResourceBinding, t as corsPreflightResponse, u as createNoopRecorder } from "./cors-DlHHW20_.js";
 import { t as extractTextContent } from "./content-D5LJAHyM.js";
-import "./list-tools-DjzEigXr.js";
+import "./list-tools-S2xzLisA.js";
 import { getParseErrorMessage, objectFromShape, safeParseAsync } from "@modelcontextprotocol/sdk/server/zod-compat.js";
 //#region src/protocols/rest/invoke-tool.ts
 const MAX_REFLECTED_TOOL_NAME = 256;
@@ -65,21 +65,32 @@ function createInvokeToolHandler(mcp, options = {}) {
 		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
-			});
+		} catch (err) {
+			const callerMessage = resolveToolErrorMessage(err);
+			if (callerMessage === void 0) {
+				await recorder.emit({
+					tool: tool.name,
+					method: "tools/call",
+					outcome: "handler_error",
+					durationMs: nowMs() - start,
+					errorText: errorSummary(err),
+					endUserId
+				});
+				return new Response(JSON.stringify({
+					error: "handler threw",
+					tool: toolName
+				}), {
+					status: 500,
+					headers: JSON_HEADERS
+				});
+			}
+			result = {
+				content: [{
+					type: "text",
+					text: callerMessage
+				}],
+				isError: true
+			};
 		}
 		if (result == null) {
 			await recorder.emit({

package/dist/stacks/supabase/index.cjs

@@ -1,11 +1,11 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_logger = require("../../logger-BSKbuM66.cjs");
-const require_cors = require("../../cors-DW1p9Uzw.cjs");
+const require_cors = require("../../cors-B79id9hu.cjs");
 const require_metadata_path = require("../../metadata-path-zd7NSNoa.cjs");
-const require_mcp = require("../../mcp-DSo7xlpz.cjs");
+const require_mcp = require("../../mcp-DNz7KIy4.cjs");
 const require_protocols_oauth_metadata = require("../../protocols/oauth-metadata.cjs");
-const require_list_tools = require("../../list-tools-DBidJV3L.cjs");
-const require_rest = require("../../rest-CvdOnTsb.cjs");
+const require_list_tools = require("../../list-tools-Ct6yJ_bo.cjs");
+const require_rest = require("../../rest-DWrrqgYf.cjs");
 const require_forwarded = require("../../forwarded-Pi8Hs5Ps.cjs");
 const require_paths = require("../../paths-OP318a6c.cjs");
 //#region src/stacks/supabase/handler.ts

package/dist/stacks/supabase/index.js

@@ -1,10 +1,10 @@
 import { s as trimTrailingSlash } from "../../logger-3-kwsF-5.js";
-import { l as createRecorderForRuntime, s as assertResourcePathShape } from "../../cors-1Iz86PSf.js";
+import { l as createRecorderForRuntime, s as assertResourcePathShape } from "../../cors-DlHHW20_.js";
 import { t as OAUTH_PROTECTED_RESOURCE_METADATA_PATH } from "../../metadata-path-CAkNcfyY.js";
-import { t as createMcpProtocolHandler } from "../../mcp-CoVt8EO9.js";
+import { t as createMcpProtocolHandler } from "../../mcp-BUR5KIhL.js";
 import { createOAuthProtectedResourceMetadataHandler } from "../../protocols/oauth-metadata.js";
-import { n as createListToolsHandler } from "../../list-tools-DjzEigXr.js";
-import { t as createInvokeToolHandler } from "../../rest-DdQMWvF4.js";
+import { n as createListToolsHandler } from "../../list-tools-S2xzLisA.js";
+import { t as createInvokeToolHandler } from "../../rest-xOYdRom7.js";
 import { t as applyForwardedOrigin } from "../../forwarded--h4efJy-.js";
 import { n as assertFunctionName, t as FUNCTIONS_MOUNT_PREFIX } from "../../paths-IS65L6TA.js";
 //#region src/stacks/supabase/handler.ts

package/dist/stacks/supabase/vite.cjs

@@ -2,7 +2,7 @@ Object.defineProperties(exports, {
 	__esModule: { value: true },
 	[Symbol.toStringTag]: { value: "Module" }
 });
-const require_package = require("../../package-Wvf1u2OZ.cjs");
+const require_package = require("../../package-C1uEtkqq.cjs");
 const require_fs_errors = require("../../fs-errors-CWNzOV75.cjs");
 const require_supabase_config = require("../../supabase-config-Dz7dnUv0.cjs");
 const require_paths = require("../../paths-OP318a6c.cjs");

package/dist/stacks/supabase/vite.d.cts

@@ -1,4 +1,4 @@
-import { t as McpPluginApi } from "../../io-BlJ298VF.cjs";
+import { t as McpPluginApi } from "../../io-Bd58IeVb.cjs";
 import { Plugin } from "vite";
 //#region src/stacks/supabase/vite.d.ts
 interface McpPluginOptions {

package/dist/stacks/supabase/vite.d.ts

@@ -1,4 +1,4 @@
-import { t as McpPluginApi } from "../../io-CSsqm26s.js";
+import { t as McpPluginApi } from "../../io-B-fV6rsM.js";
 import { Plugin } from "vite";
 //#region src/stacks/supabase/vite.d.ts
 interface McpPluginOptions {

package/dist/stacks/supabase/vite.js

@@ -1,4 +1,4 @@
-import { t as version } from "../../package-CUrmd7C5.js";
+import { t as version } from "../../package-Aux8_a4B.js";
 import { t as isFileMissing } from "../../fs-errors-PA2t1TIp.js";
 import { t as readSupabaseProjectRef } from "../../supabase-config-CakTU8YF.js";
 import { n as assertFunctionName, t as FUNCTIONS_MOUNT_PREFIX } from "../../paths-IS65L6TA.js";

package/dist/stacks/tanstack/index.cjs

@@ -1,9 +1,9 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_cors = require("../../cors-DW1p9Uzw.cjs");
-const require_mcp = require("../../mcp-DSo7xlpz.cjs");
+const require_cors = require("../../cors-B79id9hu.cjs");
+const require_mcp = require("../../mcp-DNz7KIy4.cjs");
 const require_protocols_oauth_metadata = require("../../protocols/oauth-metadata.cjs");
-const require_list_tools = require("../../list-tools-DBidJV3L.cjs");
-const require_rest = require("../../rest-CvdOnTsb.cjs");
+const require_list_tools = require("../../list-tools-Ct6yJ_bo.cjs");
+const require_rest = require("../../rest-DWrrqgYf.cjs");
 const require_forwarded = require("../../forwarded-Pi8Hs5Ps.cjs");
 //#region src/stacks/tanstack/handlers.ts
 const STACK = "tanstack";

package/dist/stacks/tanstack/index.js

@@ -1,8 +1,8 @@
-import { l as createRecorderForRuntime } from "../../cors-1Iz86PSf.js";
-import { t as createMcpProtocolHandler } from "../../mcp-CoVt8EO9.js";
+import { l as createRecorderForRuntime } from "../../cors-DlHHW20_.js";
+import { t as createMcpProtocolHandler } from "../../mcp-BUR5KIhL.js";
 import { createOAuthProtectedResourceMetadataHandler } from "../../protocols/oauth-metadata.js";
-import { n as createListToolsHandler } from "../../list-tools-DjzEigXr.js";
-import { t as createInvokeToolHandler } from "../../rest-DdQMWvF4.js";
+import { n as createListToolsHandler } from "../../list-tools-S2xzLisA.js";
+import { t as createInvokeToolHandler } from "../../rest-xOYdRom7.js";
 import { t as applyForwardedOrigin } from "../../forwarded--h4efJy-.js";
 //#region src/stacks/tanstack/handlers.ts
 const STACK = "tanstack";

package/dist/stacks/tanstack/vite.d.cts

@@ -1,4 +1,4 @@
-import { t as McpPluginApi } from "../../io-BlJ298VF.cjs";
+import { t as McpPluginApi } from "../../io-Bd58IeVb.cjs";
 import { Plugin } from "vite";
 //#region src/stacks/tanstack/vite.d.ts
 interface McpPluginOptions {

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

@@ -1,4 +1,4 @@
-import { t as McpPluginApi } from "../../io-CSsqm26s.js";
+import { t as McpPluginApi } from "../../io-B-fV6rsM.js";
 import { Plugin } from "vite";
 //#region src/stacks/tanstack/vite.d.ts
 interface McpPluginOptions {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lovable.dev/mcp-js",
-  "version": "0.25.0",
+  "version": "0.26.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": {

package/dist/context-CIpPzN7P.js

@@ -1,51 +0,0 @@
-//#region src/auth/context.ts
-/**
-* The auth surface passed to every tool handler as its second argument. It wraps
-* the verified per-request auth context in a private field, so the context — and
-* the bearer token inside it — can't be read, enumerated, spread, or
-* `JSON.stringify`'d off the instance; the accessors below are the only way out.
-* `getToken()` is the single intentional escape hatch for the raw bearer.
-*/
-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;
-	}
-};
-//#endregion
-export { ToolContext as t };