@lovable.dev/mcp-js 0.5.0

package/dist/index.cjs

@@ -0,0 +1,271 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  ToolContext: () => ToolContext,
+  auth: () => auth,
+  defineMcp: () => defineMcp,
+  defineTool: () => defineTool
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/core/url.ts
+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;
+}
+
+// src/core/define.ts
+function assertUniqueNames(mcp) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const tool of mcp.tools) {
+    if (seen.has(tool.name)) {
+      throw new Error(`@lovable.dev/mcp-js: duplicate tool name "${tool.name}"`);
+    }
+    seen.add(tool.name);
+  }
+}
+function assertNonEmptyString(label, value) {
+  if (value.trim() === "") {
+    throw new Error(`@lovable.dev/mcp-js: ${label} must not be empty`);
+  }
+  if (value !== value.trim()) {
+    throw new Error(`@lovable.dev/mcp-js: ${label} must not have leading or trailing whitespace`);
+  }
+}
+function assertHttpsUrlField(name, value) {
+  assertNonEmptyString(`auth.${name}`, value);
+  parseSafeUrl(`@lovable.dev/mcp-js: auth.${name}`, value);
+}
+function assertScope(scope) {
+  if (scope.trim() === "" || /\s/.test(scope)) {
+    throw new Error(`@lovable.dev/mcp-js: OAuth scopes must be non-empty space-free tokens`);
+  }
+}
+function assertJwtAlgorithm(algorithm) {
+  if (algorithm.trim() === "" || /\s/.test(algorithm)) {
+    throw new Error(`@lovable.dev/mcp-js: auth.algorithms must contain non-empty space-free tokens`);
+  }
+  if (/^HS\d+$/i.test(algorithm) || algorithm.toLowerCase() === "none") {
+    throw new Error(`@lovable.dev/mcp-js: auth.algorithms cannot include "${algorithm}"; this verifier is JWKS-only`);
+  }
+}
+var MAX_CLOCK_TOLERANCE_SECONDS = 300;
+function assertClockToleranceSeconds(value) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > MAX_CLOCK_TOLERANCE_SECONDS) {
+    throw new Error(
+      `@lovable.dev/mcp-js: auth.clockToleranceSeconds must be a non-negative number of seconds no greater than ${MAX_CLOCK_TOLERANCE_SECONDS}`
+    );
+  }
+}
+function assertOAuthConfig(auth2) {
+  if (auth2.type !== "oauth") {
+    const authType = String(auth2.type);
+    throw new Error(`@lovable.dev/mcp-js: unsupported auth type "${authType}"`);
+  }
+  if (auth2.issuer === void 0) {
+    throw new Error(`@lovable.dev/mcp-js: auth.issuer is required`);
+  }
+  assertHttpsUrlField("issuer", auth2.issuer);
+  if (auth2.jwksUri !== void 0) {
+    assertHttpsUrlField("jwksUri", auth2.jwksUri);
+  }
+  if (auth2.resource !== void 0) {
+    assertHttpsUrlField("resource", auth2.resource);
+  }
+  if (auth2.resourceName !== void 0) {
+    assertNonEmptyString("auth.resourceName", auth2.resourceName);
+  }
+  if (auth2.resourceDocumentation !== void 0) {
+    assertHttpsUrlField("resourceDocumentation", auth2.resourceDocumentation);
+  }
+  if (auth2.protectedResourceMetadataUrl !== void 0) {
+    assertHttpsUrlField("protectedResourceMetadataUrl", auth2.protectedResourceMetadataUrl);
+  }
+  if (auth2.acceptedAudiences !== void 0) {
+    if (!Array.isArray(auth2.acceptedAudiences)) {
+      throw new Error(`@lovable.dev/mcp-js: auth.acceptedAudiences must be an array`);
+    }
+    if (auth2.acceptedAudiences.length === 0) {
+      throw new Error(`@lovable.dev/mcp-js: auth.acceptedAudiences must not be empty`);
+    }
+    for (const audience of auth2.acceptedAudiences) {
+      if (typeof audience !== "string") {
+        throw new Error(`@lovable.dev/mcp-js: auth.acceptedAudiences must contain strings`);
+      }
+      assertNonEmptyString("auth.acceptedAudiences", audience);
+    }
+  }
+  if (auth2.requiredScopes !== void 0) {
+    if (!Array.isArray(auth2.requiredScopes)) {
+      throw new Error(`@lovable.dev/mcp-js: auth.requiredScopes must be an array`);
+    }
+    for (const scope of auth2.requiredScopes)
+      assertScope(scope);
+  }
+  if (auth2.algorithms !== void 0) {
+    if (!Array.isArray(auth2.algorithms)) {
+      throw new Error(`@lovable.dev/mcp-js: auth.algorithms must be an array`);
+    }
+    if (auth2.algorithms.length === 0) {
+      throw new Error(`@lovable.dev/mcp-js: auth.algorithms must not be empty`);
+    }
+    for (const algorithm of auth2.algorithms)
+      assertJwtAlgorithm(algorithm);
+  }
+  if (auth2.clockToleranceSeconds !== void 0)
+    assertClockToleranceSeconds(auth2.clockToleranceSeconds);
+  if (auth2.resource === void 0 && auth2.acceptedAudiences === void 0) {
+    throw new Error(`@lovable.dev/mcp-js: auth.resource or auth.acceptedAudiences is required`);
+  }
+}
+function freezeAuth(auth2) {
+  if (!auth2)
+    return;
+  if (auth2.acceptedAudiences)
+    Object.freeze(auth2.acceptedAudiences);
+  if (auth2.requiredScopes)
+    Object.freeze(auth2.requiredScopes);
+  if (auth2.algorithms)
+    Object.freeze(auth2.algorithms);
+  Object.freeze(auth2);
+}
+function defineTool(def) {
+  return def;
+}
+function defineMcp(def) {
+  assertNonEmptyString("name", def.name);
+  assertNonEmptyString("title", def.title);
+  assertNonEmptyString("version", def.version);
+  assertUniqueNames(def);
+  if (def.auth)
+    assertOAuthConfig(def.auth);
+  freezeAuth(def.auth);
+  Object.freeze(def.tools);
+  for (const tool of def.tools)
+    Object.freeze(tool);
+  return def;
+}
+
+// src/auth/config.ts
+function frozenArray(value) {
+  return value === void 0 ? void 0 : Object.freeze([...value]);
+}
+function frozenAudiences(value) {
+  return frozenArray(typeof value === "string" ? [value] : value);
+}
+function stripUndefined(value) {
+  for (const key of Object.keys(value)) {
+    if (value[key] === void 0)
+      delete value[key];
+  }
+  return value;
+}
+function issuer(options) {
+  return Object.freeze(
+    stripUndefined({
+      type: "oauth",
+      ...options,
+      acceptedAudiences: frozenAudiences(options.acceptedAudiences),
+      requiredScopes: frozenArray(options.requiredScopes),
+      algorithms: frozenArray(options.algorithms)
+    })
+  );
+}
+var oauth = Object.freeze({ issuer });
+var auth = Object.freeze({ oauth });
+
+// src/auth/context.ts
+var ToolContext = class {
+  #auth;
+  constructor(auth2) {
+    this.#auth = auth2;
+  }
+  /** 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;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ToolContext,
+  auth,
+  defineMcp,
+  defineTool
+});

package/dist/index.d.cts

@@ -0,0 +1,56 @@
+import { e as McpDefinitionInput, d as McpDefinition, Z as ZodRawShape, j as ToolDefinition, M as McpAuthConfig } from './types-zMlr1mOK.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-zMlr1mOK.js';
+import 'zod';
+
+/**
+ * Declare a single MCP tool. Import the result into your MCP definition's
+ * `tools` array — `defineMcp({ tools: [echoTool, ...] })`.
+ *
+ * `inputSchema` is a raw zod shape (e.g. `{ text: z.string() }`), not a
+ * full `z.object(...)` — the MCP SDK builds the object wrapper internally
+ * and the raw shape is what the JSON-RPC `tools/list` payload exposes.
+ */
+declare function defineTool<TInput extends ZodRawShape | undefined = undefined, TOutput extends ZodRawShape | undefined = undefined>(def: ToolDefinition<TInput, TOutput>): ToolDefinition<TInput, TOutput>;
+/**
+ * Declare the MCP server. `export default` the result from your MCP
+ * entrypoint (default `lib/mcp/index.ts`); the Vite plugin reads it to
+ * emit the framework-specific route(s) at build time.
+ */
+declare function defineMcp(def: McpDefinitionInput): McpDefinition;
+
+type IssuerAcceptedAudiences = string | readonly string[];
+interface IssuerOAuthOptionsBase {
+    readonly resourceName?: string;
+    readonly resourceDocumentation?: string;
+    readonly protectedResourceMetadataUrl?: string;
+    readonly requireOAuthClientClaim?: boolean;
+    readonly issuer: string;
+    readonly requiredScopes?: readonly string[];
+    readonly jwksUri?: string;
+    readonly algorithms?: readonly string[];
+    readonly clockToleranceSeconds?: number;
+}
+type IssuerOAuthOptions = IssuerOAuthOptionsBase & ({
+    readonly resource: string;
+    readonly acceptedAudiences?: IssuerAcceptedAudiences;
+} | {
+    readonly resource?: string;
+    readonly acceptedAudiences: IssuerAcceptedAudiences;
+});
+/**
+ * Configure OAuth against an issuer. `acceptedAudiences` (or `resource`) is the
+ * token-acceptance policy, not a per-request authorization decision: any token
+ * carrying an accepted `aud` passes. When an issuer mints broad project-wide
+ * audiences (e.g. Supabase's `aud: "authenticated"`), a token for one resource
+ * is structurally accepted by another sharing that audience — so gate per-tool
+ * authorization on `ctx.getClaims()` / `ctx.getClientId()`, never on the
+ * accepted audience.
+ */
+declare function issuer(options: IssuerOAuthOptions): McpAuthConfig;
+declare const auth: Readonly<{
+    oauth: Readonly<{
+        issuer: typeof issuer;
+    }>;
+}>;
+
+export { type IssuerOAuthOptions, McpDefinitionInput, ToolDefinition, ZodRawShape, auth, defineMcp, defineTool };

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+import { e as McpDefinitionInput, d as McpDefinition, Z as ZodRawShape, j as ToolDefinition, M as McpAuthConfig } from './types-zMlr1mOK.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-zMlr1mOK.js';
+import 'zod';
+
+/**
+ * Declare a single MCP tool. Import the result into your MCP definition's
+ * `tools` array — `defineMcp({ tools: [echoTool, ...] })`.
+ *
+ * `inputSchema` is a raw zod shape (e.g. `{ text: z.string() }`), not a
+ * full `z.object(...)` — the MCP SDK builds the object wrapper internally
+ * and the raw shape is what the JSON-RPC `tools/list` payload exposes.
+ */
+declare function defineTool<TInput extends ZodRawShape | undefined = undefined, TOutput extends ZodRawShape | undefined = undefined>(def: ToolDefinition<TInput, TOutput>): ToolDefinition<TInput, TOutput>;
+/**
+ * Declare the MCP server. `export default` the result from your MCP
+ * entrypoint (default `lib/mcp/index.ts`); the Vite plugin reads it to
+ * emit the framework-specific route(s) at build time.
+ */
+declare function defineMcp(def: McpDefinitionInput): McpDefinition;
+
+type IssuerAcceptedAudiences = string | readonly string[];
+interface IssuerOAuthOptionsBase {
+    readonly resourceName?: string;
+    readonly resourceDocumentation?: string;
+    readonly protectedResourceMetadataUrl?: string;
+    readonly requireOAuthClientClaim?: boolean;
+    readonly issuer: string;
+    readonly requiredScopes?: readonly string[];
+    readonly jwksUri?: string;
+    readonly algorithms?: readonly string[];
+    readonly clockToleranceSeconds?: number;
+}
+type IssuerOAuthOptions = IssuerOAuthOptionsBase & ({
+    readonly resource: string;
+    readonly acceptedAudiences?: IssuerAcceptedAudiences;
+} | {
+    readonly resource?: string;
+    readonly acceptedAudiences: IssuerAcceptedAudiences;
+});
+/**
+ * Configure OAuth against an issuer. `acceptedAudiences` (or `resource`) is the
+ * token-acceptance policy, not a per-request authorization decision: any token
+ * carrying an accepted `aud` passes. When an issuer mints broad project-wide
+ * audiences (e.g. Supabase's `aud: "authenticated"`), a token for one resource
+ * is structurally accepted by another sharing that audience — so gate per-tool
+ * authorization on `ctx.getClaims()` / `ctx.getClientId()`, never on the
+ * accepted audience.
+ */
+declare function issuer(options: IssuerOAuthOptions): McpAuthConfig;
+declare const auth: Readonly<{
+    oauth: Readonly<{
+        issuer: typeof issuer;
+    }>;
+}>;
+
+export { type IssuerOAuthOptions, McpDefinitionInput, ToolDefinition, ZodRawShape, auth, defineMcp, defineTool };

package/dist/index.js

@@ -0,0 +1,172 @@
+import {
+  ToolContext
+} from "./chunk-MA5H6PSF.js";
+import {
+  parseSafeUrl
+} from "./chunk-QA3FWDUV.js";
+
+// src/core/define.ts
+function assertUniqueNames(mcp) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const tool of mcp.tools) {
+    if (seen.has(tool.name)) {
+      throw new Error(`@lovable.dev/mcp-js: duplicate tool name "${tool.name}"`);
+    }
+    seen.add(tool.name);
+  }
+}
+function assertNonEmptyString(label, value) {
+  if (value.trim() === "") {
+    throw new Error(`@lovable.dev/mcp-js: ${label} must not be empty`);
+  }
+  if (value !== value.trim()) {
+    throw new Error(`@lovable.dev/mcp-js: ${label} must not have leading or trailing whitespace`);
+  }
+}
+function assertHttpsUrlField(name, value) {
+  assertNonEmptyString(`auth.${name}`, value);
+  parseSafeUrl(`@lovable.dev/mcp-js: auth.${name}`, value);
+}
+function assertScope(scope) {
+  if (scope.trim() === "" || /\s/.test(scope)) {
+    throw new Error(`@lovable.dev/mcp-js: OAuth scopes must be non-empty space-free tokens`);
+  }
+}
+function assertJwtAlgorithm(algorithm) {
+  if (algorithm.trim() === "" || /\s/.test(algorithm)) {
+    throw new Error(`@lovable.dev/mcp-js: auth.algorithms must contain non-empty space-free tokens`);
+  }
+  if (/^HS\d+$/i.test(algorithm) || algorithm.toLowerCase() === "none") {
+    throw new Error(`@lovable.dev/mcp-js: auth.algorithms cannot include "${algorithm}"; this verifier is JWKS-only`);
+  }
+}
+var MAX_CLOCK_TOLERANCE_SECONDS = 300;
+function assertClockToleranceSeconds(value) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > MAX_CLOCK_TOLERANCE_SECONDS) {
+    throw new Error(
+      `@lovable.dev/mcp-js: auth.clockToleranceSeconds must be a non-negative number of seconds no greater than ${MAX_CLOCK_TOLERANCE_SECONDS}`
+    );
+  }
+}
+function assertOAuthConfig(auth2) {
+  if (auth2.type !== "oauth") {
+    const authType = String(auth2.type);
+    throw new Error(`@lovable.dev/mcp-js: unsupported auth type "${authType}"`);
+  }
+  if (auth2.issuer === void 0) {
+    throw new Error(`@lovable.dev/mcp-js: auth.issuer is required`);
+  }
+  assertHttpsUrlField("issuer", auth2.issuer);
+  if (auth2.jwksUri !== void 0) {
+    assertHttpsUrlField("jwksUri", auth2.jwksUri);
+  }
+  if (auth2.resource !== void 0) {
+    assertHttpsUrlField("resource", auth2.resource);
+  }
+  if (auth2.resourceName !== void 0) {
+    assertNonEmptyString("auth.resourceName", auth2.resourceName);
+  }
+  if (auth2.resourceDocumentation !== void 0) {
+    assertHttpsUrlField("resourceDocumentation", auth2.resourceDocumentation);
+  }
+  if (auth2.protectedResourceMetadataUrl !== void 0) {
+    assertHttpsUrlField("protectedResourceMetadataUrl", auth2.protectedResourceMetadataUrl);
+  }
+  if (auth2.acceptedAudiences !== void 0) {
+    if (!Array.isArray(auth2.acceptedAudiences)) {
+      throw new Error(`@lovable.dev/mcp-js: auth.acceptedAudiences must be an array`);
+    }
+    if (auth2.acceptedAudiences.length === 0) {
+      throw new Error(`@lovable.dev/mcp-js: auth.acceptedAudiences must not be empty`);
+    }
+    for (const audience of auth2.acceptedAudiences) {
+      if (typeof audience !== "string") {
+        throw new Error(`@lovable.dev/mcp-js: auth.acceptedAudiences must contain strings`);
+      }
+      assertNonEmptyString("auth.acceptedAudiences", audience);
+    }
+  }
+  if (auth2.requiredScopes !== void 0) {
+    if (!Array.isArray(auth2.requiredScopes)) {
+      throw new Error(`@lovable.dev/mcp-js: auth.requiredScopes must be an array`);
+    }
+    for (const scope of auth2.requiredScopes)
+      assertScope(scope);
+  }
+  if (auth2.algorithms !== void 0) {
+    if (!Array.isArray(auth2.algorithms)) {
+      throw new Error(`@lovable.dev/mcp-js: auth.algorithms must be an array`);
+    }
+    if (auth2.algorithms.length === 0) {
+      throw new Error(`@lovable.dev/mcp-js: auth.algorithms must not be empty`);
+    }
+    for (const algorithm of auth2.algorithms)
+      assertJwtAlgorithm(algorithm);
+  }
+  if (auth2.clockToleranceSeconds !== void 0)
+    assertClockToleranceSeconds(auth2.clockToleranceSeconds);
+  if (auth2.resource === void 0 && auth2.acceptedAudiences === void 0) {
+    throw new Error(`@lovable.dev/mcp-js: auth.resource or auth.acceptedAudiences is required`);
+  }
+}
+function freezeAuth(auth2) {
+  if (!auth2)
+    return;
+  if (auth2.acceptedAudiences)
+    Object.freeze(auth2.acceptedAudiences);
+  if (auth2.requiredScopes)
+    Object.freeze(auth2.requiredScopes);
+  if (auth2.algorithms)
+    Object.freeze(auth2.algorithms);
+  Object.freeze(auth2);
+}
+function defineTool(def) {
+  return def;
+}
+function defineMcp(def) {
+  assertNonEmptyString("name", def.name);
+  assertNonEmptyString("title", def.title);
+  assertNonEmptyString("version", def.version);
+  assertUniqueNames(def);
+  if (def.auth)
+    assertOAuthConfig(def.auth);
+  freezeAuth(def.auth);
+  Object.freeze(def.tools);
+  for (const tool of def.tools)
+    Object.freeze(tool);
+  return def;
+}
+
+// src/auth/config.ts
+function frozenArray(value) {
+  return value === void 0 ? void 0 : Object.freeze([...value]);
+}
+function frozenAudiences(value) {
+  return frozenArray(typeof value === "string" ? [value] : value);
+}
+function stripUndefined(value) {
+  for (const key of Object.keys(value)) {
+    if (value[key] === void 0)
+      delete value[key];
+  }
+  return value;
+}
+function issuer(options) {
+  return Object.freeze(
+    stripUndefined({
+      type: "oauth",
+      ...options,
+      acceptedAudiences: frozenAudiences(options.acceptedAudiences),
+      requiredScopes: frozenArray(options.requiredScopes),
+      algorithms: frozenArray(options.algorithms)
+    })
+  );
+}
+var oauth = Object.freeze({ issuer });
+var auth = Object.freeze({ oauth });
+export {
+  ToolContext,
+  auth,
+  defineMcp,
+  defineTool
+};