@lovable.dev/mcp-js 0.22.1 → 0.22.2-rc.0

package/dist/types-BYdYYTjk.d.cts

@@ -0,0 +1,321 @@
+import { TypeOf, ZodRawShape, ZodType } from "zod";
+//#region src/auth/types.d.ts
+type JwtClaims = Record<string, unknown> & {
+  iss?: string;
+  sub?: string;
+  aud?: string | string[];
+  exp?: number;
+  iat?: number;
+  nbf?: number;
+  scope?: string;
+  client_id?: string;
+  email?: string;
+  /** RFC 8707 resource indicator(s) the token was granted for (Lovable OAuth convention). */
+  resource?: string | string[];
+};
+/**
+ * The safe-to-surface half of the auth context, reachable by tools only through
+ * `ToolContext` accessors (`getUserId()`, `getClaims()`, …). Carries no
+ * credential — the bearer is isolated in `OAuthBearer`.
+ */
+interface OAuthPrincipal {
+  claims: JwtClaims;
+  issuer: string;
+  resource: string;
+  acceptedAudiences: readonly string[];
+  scopes: string[];
+  sub?: string;
+  email?: string;
+  clientId?: string;
+}
+/**
+ * The raw bearer, isolated from the safe fields. Pass it only into outbound
+ * `fetch`/client construction; never return or log it — a leaked token stays
+ * valid at the AS until it expires. `token` is a non-enumerable property, so
+ * `JSON.stringify`, object spread, and `console.log` omit it by construction.
+ */
+interface OAuthBearer {
+  readonly token: string;
+}
+interface McpAuthContext {
+  type: "oauth";
+  principal: OAuthPrincipal;
+  bearer: OAuthBearer;
+}
+interface McpAuthConfig {
+  readonly type: "oauth";
+  readonly issuer: string;
+  readonly resource?: string;
+  readonly resourceName?: string;
+  readonly resourceDocumentation?: string;
+  /**
+   * Absolute URL of an externally hosted RFC 9728 protected-resource metadata
+   * document. When set, the SDK advertises this URL in the 401
+   * `WWW-Authenticate: resource_metadata` challenge and does not generate or
+   * serve its own metadata (the `/.well-known/oauth-protected-resource` handler
+   * 404s). Use it when the resource server already publishes its own PRM.
+   *
+   * Mutually exclusive with the Vite plugin's `metadataPath`: that option has
+   * the SDK serve the document itself at a custom path, so configuring both is
+   * rejected at handler construction.
+   */
+  readonly protectedResourceMetadataUrl?: string;
+  readonly requireOAuthClientClaim?: boolean;
+  readonly acceptedAudiences?: readonly string[];
+  /**
+   * Accept a token whose RFC 8707 `resource` claim matches an accepted
+   * audience (trailing slashes ignored) when its `aud` is an empty array or
+   * absent — the shape Lovable's OAuth server mints; applies to any configured
+   * issuer. A populated `aud` is always authoritative and is never overridden.
+   * Defaults to true. Set false to require a matching `aud` (strict RFC 9068).
+   */
+  readonly acceptResourceClaim?: boolean;
+  readonly requiredScopes?: readonly string[];
+  readonly jwksUri?: string;
+  readonly algorithms?: readonly string[];
+  readonly clockToleranceSeconds?: number;
+  /**
+   * Allowed values for the access token's JOSE `typ` header. Defaults to
+   * `["at+jwt", "JWT"]` so both the RFC 9068 access-token shape and the plain
+   * user-JWT shape (notably Supabase GoTrue's OAuth tokens) are accepted out of
+   * the box. Pin to `["at+jwt"]` to enforce strict RFC 9068. The header `typ`
+   * must be present and string-typed; this option only controls which values pass.
+   */
+  readonly accessTokenTyp?: readonly string[];
+}
+//#endregion
+//#region src/auth/context.d.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.
+ */
+declare class ToolContext {
+  #private;
+  constructor(auth: McpAuthContext | undefined);
+  /** Whether the in-flight tool call carries a verified auth context. */
+  isAuthenticated(): boolean;
+  /** The verified bearer token, or `undefined` when unauthenticated. Pass it to downstream APIs; never return or log it. */
+  getToken(): string | undefined;
+  /** The verified user id (the token `sub`), or `undefined`. */
+  getUserId(): string | undefined;
+  /** The verified user email, or `undefined` when absent. */
+  getUserEmail(): string | undefined;
+  /** The verified OAuth `client_id`, or `undefined`. */
+  getClientId(): string | undefined;
+  /** The verified OAuth scopes, or `undefined` when unauthenticated. */
+  getScopes(): string[] | undefined;
+  /** The verified token issuer, or `undefined`. */
+  getIssuer(): string | undefined;
+  /**
+   * The full verified JWT claims, or `undefined`. Use this for app/business
+   * authorization on issuer-specific claims that have no dedicated accessor.
+   */
+  getClaims(): JwtClaims | undefined;
+}
+//#endregion
+//#region src/metrics/config.d.ts
+/**
+ * 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 each invocation 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 request (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;
+//#endregion
+//#region src/core/types.d.ts
+/**
+ * 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;
+ * for the `{ text: z.string() }` shape passed to `defineTool`'s
+ * `inputSchema`, use `ZodRawShape`.
+ */
+type ZodSchema = ZodType;
+/**
+ * A raw zod shape (`{ text: z.string(), n: z.number() }`) — the format
+ * `defineTool`'s `inputSchema`/`outputSchema` expects.
+ */
+type ZodRawShape$1 = ZodRawShape;
+/**
+ * Infer the parsed-output type of a zod raw shape — given
+ * `{ text: ZodString, n: ZodNumber }`, produces `{ text: string, n: number }`.
+ */
+type ShapeOutput<Shape extends ZodRawShape$1> = { [K in keyof Shape]: Shape[K] extends ZodType ? TypeOf<Shape[K]> : unknown; };
+/**
+ * Per-content-block metadata. Distinct from `ToolAnnotations`, which
+ * decorates the tool as a whole — these decorate a single piece of
+ * content (an image, a text block, etc.) within the tool's result.
+ */
+interface ContentAnnotations {
+  /** Which side of the conversation the content is addressed at. */
+  audience?: ("user" | "assistant")[];
+  /** Higher = more important. Used by clients that summarise content. */
+  priority?: number;
+  /** ISO 8601 timestamp. */
+  lastModified?: string;
+}
+interface ContentBlockBase {
+  annotations?: ContentAnnotations;
+  _meta?: Record<string, unknown>;
+}
+interface TextContent extends ContentBlockBase {
+  type: "text";
+  text: string;
+}
+interface ImageContent extends ContentBlockBase {
+  type: "image";
+  data: string;
+  mimeType: string;
+}
+interface AudioContent extends ContentBlockBase {
+  type: "audio";
+  data: string;
+  mimeType: string;
+}
+interface EmbeddedTextResource extends ContentBlockBase {
+  type: "resource";
+  resource: {
+    uri: string;
+    mimeType?: string;
+    text: string;
+    _meta?: Record<string, unknown>;
+  };
+}
+interface EmbeddedBlobResource extends ContentBlockBase {
+  type: "resource";
+  resource: {
+    uri: string;
+    mimeType?: string;
+    blob: string;
+    _meta?: Record<string, unknown>;
+  };
+}
+type EmbeddedResource = EmbeddedTextResource | EmbeddedBlobResource;
+/**
+ * Optional icon entry on `ResourceLink`. Clients that display a resource
+ * with a glyph (file browsers, side panels, etc.) pick the best match by
+ * MIME type, `sizes`, and the active `theme`. All fields besides `src`
+ * are optional — `src` is typically a `file://`, `data:`, or `https:` URI.
+ */
+interface ResourceLinkIcon {
+  src: string;
+  mimeType?: string;
+  /** Space-separated dimension string, HTML `<link sizes>` convention (e.g. `"16x16 32x32"`). */
+  sizes?: string;
+  theme?: "light" | "dark";
+}
+interface ResourceLink extends ContentBlockBase {
+  type: "resource_link";
+  uri: string;
+  name: string;
+  title?: string;
+  description?: string;
+  mimeType?: string;
+  icons?: ResourceLinkIcon[];
+}
+/**
+ * A single content block in a tool result. Matches the MCP wire format
+ * for `tools/call` responses (`type: "text" | "image" | "audio" |
+ * "resource" | "resource_link"`).
+ */
+type ContentBlock = TextContent | ImageContent | AudioContent | EmbeddedResource | ResourceLink;
+/**
+ * The shape of `ToolHandlerResult.content` — an array of content blocks
+ * the tool returns to the caller.
+ */
+type ToolContent = ContentBlock[];
+/**
+ * Per-tool client hints (not enforcement). `annotations.title` is
+ * intentionally omitted — use `ToolDefinition.title`, which the MCP
+ * 2025-06-18+ spec promoted to top-level.
+ */
+interface ToolAnnotations {
+  /** Tool does not modify state. */
+  readOnlyHint?: boolean;
+  /** Tool may make irreversible changes. Only meaningful when readOnlyHint is false. */
+  destructiveHint?: boolean;
+  /** Calling N times has the same effect as calling once. */
+  idempotentHint?: boolean;
+  /** Tool interacts with external/unbounded systems (DB, network, third-party APIs). */
+  openWorldHint?: boolean;
+}
+interface ToolHandlerResult {
+  content?: ToolContent;
+  structuredContent?: Record<string, unknown>;
+  isError?: boolean;
+}
+interface ToolDefinition<TInput extends ZodRawShape$1 | undefined = ZodRawShape$1 | undefined, TOutput extends ZodRawShape$1 | undefined = ZodRawShape$1 | undefined> {
+  readonly name: string;
+  /** Human-readable display name shown to the user in MCP clients. Required. */
+  readonly title: string;
+  /** Prose read by the LLM to decide whether to call this tool. Required. */
+  readonly description: string;
+  readonly inputSchema?: TInput;
+  readonly outputSchema?: TOutput;
+  readonly annotations?: ToolAnnotations;
+  readonly handler: TInput extends ZodRawShape$1 ? (args: ShapeOutput<TInput>, ctx: ToolContext) => ToolHandlerResult | Promise<ToolHandlerResult> : (args: Record<string, never> | undefined, ctx: ToolContext) => ToolHandlerResult | Promise<ToolHandlerResult>;
+}
+/**
+ * Type-erased element of `McpDefinition.tools`. Per-tool generic typing
+ * happens at the `defineTool` call site; see README §6 for the rationale.
+ */
+interface AnyToolDefinition {
+  readonly name: string;
+  readonly title: string;
+  readonly description: string;
+  readonly inputSchema?: ZodRawShape$1;
+  readonly outputSchema?: ZodRawShape$1;
+  readonly annotations?: ToolAnnotations;
+  readonly handler: (args: any, ctx: ToolContext) => ToolHandlerResult | Promise<ToolHandlerResult>;
+}
+/**
+ * Fields a caller supplies when constructing an MCP definition. Pass this
+ * shape to `defineMcp(...)` — its return type is the branded `McpDefinition`,
+ * which is the type every internal factory (`createInvokeToolHandler`,
+ * `createMcpProtocolHandler`, …) consumes. The brand forces consumers
+ * through `defineMcp`'s `assertUniqueNames` + freeze.
+ */
+interface McpDefinitionInput {
+  readonly name: string;
+  /** Human-readable display name shown to MCP clients. Required. */
+  readonly title: string;
+  readonly version: string;
+  readonly auth?: McpAuthConfig;
+  /**
+   * Server-level prose the LLM reads as context for all tools on this server.
+   * Required for the same reason `ToolDefinition.description` is — optional
+   * fields encourage drift in production agent behavior. Pass an explicit
+   * empty string to opt out.
+   */
+  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;
+};
+//#endregion
+export { McpAuthConfig as C, JwtClaims as S, ZodRawShape$1 as _, EmbeddedResource as a, MetricsOptions as b, McpDefinition as c, ResourceLinkIcon as d, TextContent as f, ToolHandlerResult as g, ToolDefinition as h, EmbeddedBlobResource as i, McpDefinitionInput as l, ToolContent as m, ContentAnnotations as n, EmbeddedTextResource as o, ToolAnnotations as p, ContentBlock as r, ImageContent as s, AudioContent as t, ResourceLink as u, ZodSchema as v, ToolContext as x, MetricsConfig as y };

package/dist/types-BYdYYTjk.d.ts

@@ -0,0 +1,321 @@
+import { TypeOf, ZodRawShape, ZodType } from "zod";
+//#region src/auth/types.d.ts
+type JwtClaims = Record<string, unknown> & {
+  iss?: string;
+  sub?: string;
+  aud?: string | string[];
+  exp?: number;
+  iat?: number;
+  nbf?: number;
+  scope?: string;
+  client_id?: string;
+  email?: string;
+  /** RFC 8707 resource indicator(s) the token was granted for (Lovable OAuth convention). */
+  resource?: string | string[];
+};
+/**
+ * The safe-to-surface half of the auth context, reachable by tools only through
+ * `ToolContext` accessors (`getUserId()`, `getClaims()`, …). Carries no
+ * credential — the bearer is isolated in `OAuthBearer`.
+ */
+interface OAuthPrincipal {
+  claims: JwtClaims;
+  issuer: string;
+  resource: string;
+  acceptedAudiences: readonly string[];
+  scopes: string[];
+  sub?: string;
+  email?: string;
+  clientId?: string;
+}
+/**
+ * The raw bearer, isolated from the safe fields. Pass it only into outbound
+ * `fetch`/client construction; never return or log it — a leaked token stays
+ * valid at the AS until it expires. `token` is a non-enumerable property, so
+ * `JSON.stringify`, object spread, and `console.log` omit it by construction.
+ */
+interface OAuthBearer {
+  readonly token: string;
+}
+interface McpAuthContext {
+  type: "oauth";
+  principal: OAuthPrincipal;
+  bearer: OAuthBearer;
+}
+interface McpAuthConfig {
+  readonly type: "oauth";
+  readonly issuer: string;
+  readonly resource?: string;
+  readonly resourceName?: string;
+  readonly resourceDocumentation?: string;
+  /**
+   * Absolute URL of an externally hosted RFC 9728 protected-resource metadata
+   * document. When set, the SDK advertises this URL in the 401
+   * `WWW-Authenticate: resource_metadata` challenge and does not generate or
+   * serve its own metadata (the `/.well-known/oauth-protected-resource` handler
+   * 404s). Use it when the resource server already publishes its own PRM.
+   *
+   * Mutually exclusive with the Vite plugin's `metadataPath`: that option has
+   * the SDK serve the document itself at a custom path, so configuring both is
+   * rejected at handler construction.
+   */
+  readonly protectedResourceMetadataUrl?: string;
+  readonly requireOAuthClientClaim?: boolean;
+  readonly acceptedAudiences?: readonly string[];
+  /**
+   * Accept a token whose RFC 8707 `resource` claim matches an accepted
+   * audience (trailing slashes ignored) when its `aud` is an empty array or
+   * absent — the shape Lovable's OAuth server mints; applies to any configured
+   * issuer. A populated `aud` is always authoritative and is never overridden.
+   * Defaults to true. Set false to require a matching `aud` (strict RFC 9068).
+   */
+  readonly acceptResourceClaim?: boolean;
+  readonly requiredScopes?: readonly string[];
+  readonly jwksUri?: string;
+  readonly algorithms?: readonly string[];
+  readonly clockToleranceSeconds?: number;
+  /**
+   * Allowed values for the access token's JOSE `typ` header. Defaults to
+   * `["at+jwt", "JWT"]` so both the RFC 9068 access-token shape and the plain
+   * user-JWT shape (notably Supabase GoTrue's OAuth tokens) are accepted out of
+   * the box. Pin to `["at+jwt"]` to enforce strict RFC 9068. The header `typ`
+   * must be present and string-typed; this option only controls which values pass.
+   */
+  readonly accessTokenTyp?: readonly string[];
+}
+//#endregion
+//#region src/auth/context.d.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.
+ */
+declare class ToolContext {
+  #private;
+  constructor(auth: McpAuthContext | undefined);
+  /** Whether the in-flight tool call carries a verified auth context. */
+  isAuthenticated(): boolean;
+  /** The verified bearer token, or `undefined` when unauthenticated. Pass it to downstream APIs; never return or log it. */
+  getToken(): string | undefined;
+  /** The verified user id (the token `sub`), or `undefined`. */
+  getUserId(): string | undefined;
+  /** The verified user email, or `undefined` when absent. */
+  getUserEmail(): string | undefined;
+  /** The verified OAuth `client_id`, or `undefined`. */
+  getClientId(): string | undefined;
+  /** The verified OAuth scopes, or `undefined` when unauthenticated. */
+  getScopes(): string[] | undefined;
+  /** The verified token issuer, or `undefined`. */
+  getIssuer(): string | undefined;
+  /**
+   * The full verified JWT claims, or `undefined`. Use this for app/business
+   * authorization on issuer-specific claims that have no dedicated accessor.
+   */
+  getClaims(): JwtClaims | undefined;
+}
+//#endregion
+//#region src/metrics/config.d.ts
+/**
+ * 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 each invocation 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 request (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;
+//#endregion
+//#region src/core/types.d.ts
+/**
+ * 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;
+ * for the `{ text: z.string() }` shape passed to `defineTool`'s
+ * `inputSchema`, use `ZodRawShape`.
+ */
+type ZodSchema = ZodType;
+/**
+ * A raw zod shape (`{ text: z.string(), n: z.number() }`) — the format
+ * `defineTool`'s `inputSchema`/`outputSchema` expects.
+ */
+type ZodRawShape$1 = ZodRawShape;
+/**
+ * Infer the parsed-output type of a zod raw shape — given
+ * `{ text: ZodString, n: ZodNumber }`, produces `{ text: string, n: number }`.
+ */
+type ShapeOutput<Shape extends ZodRawShape$1> = { [K in keyof Shape]: Shape[K] extends ZodType ? TypeOf<Shape[K]> : unknown; };
+/**
+ * Per-content-block metadata. Distinct from `ToolAnnotations`, which
+ * decorates the tool as a whole — these decorate a single piece of
+ * content (an image, a text block, etc.) within the tool's result.
+ */
+interface ContentAnnotations {
+  /** Which side of the conversation the content is addressed at. */
+  audience?: ("user" | "assistant")[];
+  /** Higher = more important. Used by clients that summarise content. */
+  priority?: number;
+  /** ISO 8601 timestamp. */
+  lastModified?: string;
+}
+interface ContentBlockBase {
+  annotations?: ContentAnnotations;
+  _meta?: Record<string, unknown>;
+}
+interface TextContent extends ContentBlockBase {
+  type: "text";
+  text: string;
+}
+interface ImageContent extends ContentBlockBase {
+  type: "image";
+  data: string;
+  mimeType: string;
+}
+interface AudioContent extends ContentBlockBase {
+  type: "audio";
+  data: string;
+  mimeType: string;
+}
+interface EmbeddedTextResource extends ContentBlockBase {
+  type: "resource";
+  resource: {
+    uri: string;
+    mimeType?: string;
+    text: string;
+    _meta?: Record<string, unknown>;
+  };
+}
+interface EmbeddedBlobResource extends ContentBlockBase {
+  type: "resource";
+  resource: {
+    uri: string;
+    mimeType?: string;
+    blob: string;
+    _meta?: Record<string, unknown>;
+  };
+}
+type EmbeddedResource = EmbeddedTextResource | EmbeddedBlobResource;
+/**
+ * Optional icon entry on `ResourceLink`. Clients that display a resource
+ * with a glyph (file browsers, side panels, etc.) pick the best match by
+ * MIME type, `sizes`, and the active `theme`. All fields besides `src`
+ * are optional — `src` is typically a `file://`, `data:`, or `https:` URI.
+ */
+interface ResourceLinkIcon {
+  src: string;
+  mimeType?: string;
+  /** Space-separated dimension string, HTML `<link sizes>` convention (e.g. `"16x16 32x32"`). */
+  sizes?: string;
+  theme?: "light" | "dark";
+}
+interface ResourceLink extends ContentBlockBase {
+  type: "resource_link";
+  uri: string;
+  name: string;
+  title?: string;
+  description?: string;
+  mimeType?: string;
+  icons?: ResourceLinkIcon[];
+}
+/**
+ * A single content block in a tool result. Matches the MCP wire format
+ * for `tools/call` responses (`type: "text" | "image" | "audio" |
+ * "resource" | "resource_link"`).
+ */
+type ContentBlock = TextContent | ImageContent | AudioContent | EmbeddedResource | ResourceLink;
+/**
+ * The shape of `ToolHandlerResult.content` — an array of content blocks
+ * the tool returns to the caller.
+ */
+type ToolContent = ContentBlock[];
+/**
+ * Per-tool client hints (not enforcement). `annotations.title` is
+ * intentionally omitted — use `ToolDefinition.title`, which the MCP
+ * 2025-06-18+ spec promoted to top-level.
+ */
+interface ToolAnnotations {
+  /** Tool does not modify state. */
+  readOnlyHint?: boolean;
+  /** Tool may make irreversible changes. Only meaningful when readOnlyHint is false. */
+  destructiveHint?: boolean;
+  /** Calling N times has the same effect as calling once. */
+  idempotentHint?: boolean;
+  /** Tool interacts with external/unbounded systems (DB, network, third-party APIs). */
+  openWorldHint?: boolean;
+}
+interface ToolHandlerResult {
+  content?: ToolContent;
+  structuredContent?: Record<string, unknown>;
+  isError?: boolean;
+}
+interface ToolDefinition<TInput extends ZodRawShape$1 | undefined = ZodRawShape$1 | undefined, TOutput extends ZodRawShape$1 | undefined = ZodRawShape$1 | undefined> {
+  readonly name: string;
+  /** Human-readable display name shown to the user in MCP clients. Required. */
+  readonly title: string;
+  /** Prose read by the LLM to decide whether to call this tool. Required. */
+  readonly description: string;
+  readonly inputSchema?: TInput;
+  readonly outputSchema?: TOutput;
+  readonly annotations?: ToolAnnotations;
+  readonly handler: TInput extends ZodRawShape$1 ? (args: ShapeOutput<TInput>, ctx: ToolContext) => ToolHandlerResult | Promise<ToolHandlerResult> : (args: Record<string, never> | undefined, ctx: ToolContext) => ToolHandlerResult | Promise<ToolHandlerResult>;
+}
+/**
+ * Type-erased element of `McpDefinition.tools`. Per-tool generic typing
+ * happens at the `defineTool` call site; see README §6 for the rationale.
+ */
+interface AnyToolDefinition {
+  readonly name: string;
+  readonly title: string;
+  readonly description: string;
+  readonly inputSchema?: ZodRawShape$1;
+  readonly outputSchema?: ZodRawShape$1;
+  readonly annotations?: ToolAnnotations;
+  readonly handler: (args: any, ctx: ToolContext) => ToolHandlerResult | Promise<ToolHandlerResult>;
+}
+/**
+ * Fields a caller supplies when constructing an MCP definition. Pass this
+ * shape to `defineMcp(...)` — its return type is the branded `McpDefinition`,
+ * which is the type every internal factory (`createInvokeToolHandler`,
+ * `createMcpProtocolHandler`, …) consumes. The brand forces consumers
+ * through `defineMcp`'s `assertUniqueNames` + freeze.
+ */
+interface McpDefinitionInput {
+  readonly name: string;
+  /** Human-readable display name shown to MCP clients. Required. */
+  readonly title: string;
+  readonly version: string;
+  readonly auth?: McpAuthConfig;
+  /**
+   * Server-level prose the LLM reads as context for all tools on this server.
+   * Required for the same reason `ToolDefinition.description` is — optional
+   * fields encourage drift in production agent behavior. Pass an explicit
+   * empty string to opt out.
+   */
+  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;
+};
+//#endregion
+export { McpAuthConfig as C, JwtClaims as S, ZodRawShape$1 as _, EmbeddedResource as a, MetricsOptions as b, McpDefinition as c, ResourceLinkIcon as d, TextContent as f, ToolHandlerResult as g, ToolDefinition as h, EmbeddedBlobResource as i, McpDefinitionInput as l, ToolContent as m, ContentAnnotations as n, EmbeddedTextResource as o, ToolAnnotations as p, ContentBlock as r, ImageContent as s, AudioContent as t, ResourceLink as u, ZodSchema as v, ToolContext as x, MetricsConfig as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lovable.dev/mcp-js",
-  "version": "0.22.1",
+  "version": "0.22.2-rc.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": {
@@ -126,16 +126,16 @@
   "devDependencies": {
     "@types/node": "22.13.13",
     "rimraf": "^5.0.0",
-    "tsup": "^7.2.0",
+    "tsdown": "^0.22.5",
     "typescript": "^5.9.3",
     "vite": "^7.3.1",
     "vitest": "^4.1.5",
     "zod": "^4.1.13"
   },
   "scripts": {
-    "build": "tsup src/index.ts src/protocols/mcp/index.ts src/protocols/oauth-metadata.ts src/protocols/rest/index.ts src/stacks/tanstack/index.ts src/stacks/tanstack/vite.ts src/stacks/supabase/index.ts src/stacks/supabase/vite.ts src/cli/extract-manifest.ts --format cjs,esm --dts --outDir dist",
+    "build": "tsdown",
     "check:package": "tmp=$(mktemp -d) && pnpm pack --out \"$tmp/pkg.tgz\" && tar -xzf \"$tmp/pkg.tgz\" -C \"$tmp\" && publint \"$tmp/package\" --strict && attw \"$tmp/pkg.tgz\"",
-    "dev": "tsup src/index.ts src/protocols/mcp/index.ts src/protocols/oauth-metadata.ts src/protocols/rest/index.ts src/stacks/tanstack/index.ts src/stacks/tanstack/vite.ts src/stacks/supabase/index.ts src/stacks/supabase/vite.ts src/cli/extract-manifest.ts --format cjs,esm --dts --watch",
+    "dev": "tsdown --watch",
     "typecheck": "tsgo --noEmit",
     "format": "oxfmt --write src/ tests/",
     "format:check": "oxfmt --check src/ tests/",