@buildbase/sdk 0.0.53 → 0.0.55

package/dist/mcp/index.d.ts

@@ -1,6 +1,35 @@
 import { z } from 'zod';
 
-/** MCP Server Card (SEP-1649 / SEP-2127), advertising a live MCP server. */
+/** An Agent Skill (Agent Skills Discovery RFC v0.2.0) published by this app. */
+interface AgentSkill {
+    /** Stable slug, e.g. `acme-api`. */
+    name: string;
+    /** One-line human/agent-readable summary. */
+    description: string;
+    /** Full markdown content of the SKILL.md served for this skill. */
+    content: string;
+    /**
+     * Path the SKILL.md is served from. Defaults to
+     * `/.well-known/agent-skills/<name>/SKILL.md`.
+     */
+    path?: string;
+    /** Skill artifact kind. Defaults to `skill-md`. */
+    type?: 'skill-md' | 'archive';
+}
+/** One API described in an API Catalog (RFC 9727 / RFC 9264 linkset). */
+interface ApiCatalogApi {
+    /** Anchor URL identifying the API, e.g. `https://api.example.com`. */
+    anchor: string;
+    /** OpenAPI / machine-readable description URL (link rel `service-desc`). */
+    serviceDesc?: string;
+    /** Human documentation URL (link rel `service-doc`). */
+    serviceDoc?: string;
+    /** Health / status endpoint URL (link rel `status`). */
+    status?: string;
+    /** Optional human title for the API. */
+    title?: string;
+}
+/** MCP Server Card (SEP-1649 v1.0), advertising a live MCP server. */
 interface McpServerCard {
     /** Server name. */
     name: string;
@@ -10,13 +39,251 @@ interface McpServerCard {
     endpoint: string;
     /** Transport type. Defaults to `"streamable-http"`. */
     transport?: string;
-    /** Capabilities object, e.g. `{ tools: {}, resources: {} }`. */
+    /** MCP protocol version the server speaks. Defaults to `"2025-11-25"`. */
+    protocolVersion?: string;
+    /**
+     * Capability flags. Booleans per SEP-1649 v1.0; a legacy object value
+     * (e.g. `{ tools: {} }`) is normalized to booleans by presence.
+     */
     capabilities?: Record<string, unknown>;
     /** Optional human description. */
     description?: string;
     /** Documentation URL. */
     documentationUrl?: string;
 }
+/** One OAuth scope an app declares in its scope catalog. */
+interface AppScope {
+    /** Scope name, e.g. `designs:read`. */
+    name: string;
+    /** Human-readable description, shown on the consent screen. */
+    description: string;
+}
+/** One skill advertised on the A2A Agent Card. */
+interface A2ACardSkill {
+    id: string;
+    name: string;
+    description: string;
+    tags?: string[];
+}
+/**
+ * Overrides for the A2A Agent Card (`/.well-known/agent-card.json`). Every
+ * field is optional — the card is fully derived from `site` + `skills` by
+ * default. See {@link buildA2AAgentCard}.
+ */
+interface A2ACardConfig {
+    name?: string;
+    version?: string;
+    description?: string;
+    /** The endpoint agents connect to. Defaults to `siteUrl`. */
+    serviceUrl?: string;
+    /** Transport protocol advertised for `serviceUrl`. Defaults to `'http'`. */
+    transportProtocol?: string;
+    /** A2A capability flags. Defaults to `{ streaming: false, pushNotifications: false }`. */
+    capabilities?: Record<string, unknown>;
+    /** Skills; defaults to a mapping of `config.skills` (or a generic site skill). */
+    skills?: A2ACardSkill[];
+}
+/** One robots.txt policy group (a `User-agent:` block). */
+interface RobotsPolicy {
+    /** User-agent(s) this group applies to, e.g. `'*'` or `'GPTBot'`. */
+    userAgent: string | string[];
+    /** Paths to allow, e.g. `['/']`. */
+    allow?: string[];
+    /** Paths to disallow, e.g. `['/api/']`. */
+    disallow?: string[];
+    /** Optional `Crawl-delay` (non-standard but widely honored). */
+    crawlDelay?: number;
+}
+/**
+ * Content Signals (https://contentsignals.org) — declares how crawlers may use
+ * this site's content. Each flag renders as `<signal>=yes|no`; omitted flags
+ * are not emitted (unset = no preference expressed).
+ */
+interface ContentSignals {
+    /** May content be indexed for search? → `search=yes|no`. */
+    search?: boolean;
+    /** May content be used as AI input (RAG, grounding)? → `ai-input=yes|no`. */
+    aiInput?: boolean;
+    /** May content be used for AI training? → `ai-train=yes|no`. */
+    aiTrain?: boolean;
+}
+/** Configuration for `buildRobotsTxt`. Every field is optional. */
+interface RobotsConfig {
+    /** Policy groups. Defaults to `[{ userAgent: '*', allow: ['/'] }]`. */
+    policies?: RobotsPolicy[];
+    /**
+     * Stance toward known AI crawlers ({@link AI_BOT_USER_AGENTS}): `'allow'`
+     * (default — an explicit `Allow: /` group per bot, so readiness checkers see
+     * AI bots addressed), `'deny'` (a `Disallow: /` group per bot), or explicit
+     * per-bot policies for finer control.
+     */
+    aiBots?: 'allow' | 'deny' | RobotsPolicy[];
+    /** Content-Signal directive attached to the `User-agent: *` group. */
+    contentSignals?: ContentSignals;
+    /**
+     * Sitemap URLs. Defaults to `${siteUrl}/sitemap.xml` when `config.sitemap`
+     * is set; pass `[]` to emit no `Sitemap:` line.
+     */
+    sitemaps?: string[];
+}
+/** One URL entry for the generated sitemap.xml. */
+interface SitemapUrl {
+    /** Absolute URL, or a path resolved against `siteUrl`. */
+    loc: string;
+    /** ISO-8601 last-modified date. */
+    lastmod?: string;
+    changefreq?: 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
+    /** 0.0–1.0. */
+    priority?: number;
+}
+/** Configuration for the agent-readiness discovery layer. */
+interface AgentReadyConfig {
+    /** BuildBase server base URL, e.g. `https://api.buildbase.app` (no trailing slash needed). */
+    serverUrl: string;
+    /** The org id (24-hex) whose agent-readiness config to serve. */
+    orgId: string;
+    /**
+     * This app's public origin, e.g. `https://example.com`. Used to build absolute
+     * URLs in the Agent Card and to match RFC 9728 resource paths.
+     */
+    siteUrl: string;
+    /** Static metadata for the Agent Card (`/.well-known/agent.json`). */
+    site: {
+        name: string;
+        description?: string;
+        /** Absolute URL to human/agent documentation. */
+        documentationUrl?: string;
+        /** Support/contact email surfaced on the Agent Card. */
+        contactEmail?: string;
+        /** Provider block; defaults to `{ name: site.name, url: siteUrl }`. */
+        provider?: {
+            name: string;
+            url: string;
+        };
+    };
+    /** Agent Skills to publish. Omit to skip the Agent Skills documents. */
+    skills?: AgentSkill[];
+    /**
+     * The app's OAuth scope catalog — the source of truth for `scopes_supported`
+     * in this app's RFC 9728 protected-resource metadata (served from your own
+     * origin). Declare real, per-app scopes here (`designs:read`,
+     * `render:execute`, …) instead of placeholders. A `protectedResources` entry
+     * without its own `scopes` list inherits every catalog scope name. Scopes are
+     * app-owned: the shared BuildBase authorization server stays scope-agnostic.
+     */
+    scopes?: AppScope[];
+    /** security.txt fields (RFC 9116). Omit to skip serving security.txt. */
+    security?: {
+        /** Contact URI(s) — email (`mailto:`) or URL. */
+        contact: string | string[];
+        /** ISO-8601 expiry; strongly recommended by RFC 9116. */
+        expires?: string;
+        /** Security policy URL. */
+        policy?: string;
+    };
+    /**
+     * API Catalog entries (RFC 9727), served at `/.well-known/api-catalog` as
+     * `application/linkset+json`. Omit to skip.
+     */
+    apiCatalog?: ApiCatalogApi[];
+    /**
+     * MCP Server Card (SEP-1649), served at `/.well-known/mcp/server-card.json`.
+     * Only set this when you actually run an MCP server — the card advertises a
+     * live transport endpoint. Omit to skip.
+     */
+    mcpServerCard?: McpServerCard;
+    /**
+     * Raw `/auth.md` content (agent registration/auth instructions). If omitted,
+     * `buildAuthMd` generates one from the OAuth metadata + site config.
+     */
+    authMd?: string;
+    /**
+     * Local `/llms.txt` content. Takes precedence over the org-authored llms.txt
+     * from the platform bundle — use when the app owns richer llms.txt content.
+     */
+    llmsTxt?: string;
+    /**
+     * Local `/llms-full.txt` content (llmstxt.org expanded document). Omit to
+     * skip serving it (or serve your own static file, which then wins).
+     */
+    llmsFullTxt?: string;
+    /**
+     * A2A Agent Card served at `/.well-known/agent-card.json`. Served by
+     * DEFAULT, derived from `site` + `skills`, so readiness scanners find a
+     * valid card with zero config. Pass `false` to disable, or an object to
+     * override any derived field.
+     */
+    a2aCard?: false | A2ACardConfig;
+    /**
+     * Web Bot Auth key directory (IETF WebBotAuth) served at
+     * `/.well-known/http-message-signatures-directory`. Only for apps whose own
+     * outbound bot/agent signs its requests — publish the JWKS public keys here
+     * so receiving sites can verify the signatures. Omitted = not served.
+     */
+    webBotAuth?: {
+        keys: Array<Record<string, unknown>>;
+    };
+    /**
+     * Extra literal documents served by {@link resolveAgentPath}, keyed by exact
+     * request path. The escape hatch for anything the SDK has no builder for —
+     * commerce discovery (x402, UCP, ACP, MPP), `/openapi.json`, future
+     * `.well-known` documents. A string value infers its content type from the
+     * path extension. Extra paths take precedence over built-in documents, so
+     * they can also override any SDK-generated document.
+     */
+    extraPaths?: Record<string, string | {
+        body: string;
+        contentType?: string;
+        status?: number;
+        cacheControl?: string;
+    }>;
+    /** robots.txt generation (`buildRobotsTxt`). Omitted = sane defaults. */
+    robots?: RobotsConfig;
+    /**
+     * URLs for a minimal generated sitemap.xml (`buildSitemap`). Omit when the
+     * app already generates sitemaps (e.g. next-sitemap) — the builder then
+     * returns null and your own files win.
+     */
+    sitemap?: {
+        urls: Array<string | SitemapUrl>;
+    };
+    /**
+     * RFC 9728 protected resources this app serves, defined locally (app-owned).
+     * When set, the SDK builds the `/.well-known/oauth-protected-resource`
+     * document from this config — `authorization_servers` is derived from
+     * `serverUrl`/`orgId` (the BuildBase issuer). Takes precedence over the
+     * platform bundle. Omit to fall back to the org-configured bundle.
+     */
+    protectedResources?: Array<{
+        /** The protected API's resource URI. Defaults to `siteUrl`. */
+        resource?: string;
+        /** Scopes this resource accepts (`scopes_supported`). */
+        scopes?: string[];
+        /** Human documentation URL (`resource_documentation`). */
+        documentationUrl?: string;
+        /** Bearer methods (`bearer_methods_supported`). Defaults to `['header']`. */
+        bearerMethods?: string[];
+    }>;
+    /** TTL (seconds) for cached platform fetches. Default 300 (5 min). */
+    cacheTtlSeconds?: number;
+    /**
+     * Timeout (ms) for platform fetches. Fail-soft on timeout, so a hung or slow
+     * BuildBase server can't hang discovery routes forever. Default 5000; set `0`
+     * to disable.
+     */
+    fetchTimeoutMs?: number;
+    /** Injectable fetch, mainly for testing. Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+}
+/** A rendered discovery document ready to become an HTTP response. */
+interface DiscoveryDocument {
+    status: number;
+    contentType: string;
+    body: string;
+    cacheControl: string;
+    /** Value for a `Vary` response header, when the body is negotiated. */
+    vary?: string;
+}
 
 /**
  * Built-in MCP tools mapping BuildBase capabilities to agent-callable tools.
@@ -40,14 +307,14 @@ interface McpServerCard {
  */
 
 /** Every built-in tool, keyed by name. */
-declare const builtinMcpTools: ReadonlyMap<string, McpToolDefinition<any>>;
+declare const builtinMcpTools: ReadonlyMap<string, AnyMcpTool>;
 /** The name of a built-in BuildBase MCP tool. */
 type BuiltinMcpToolName = 'list_workspaces' | 'get_workspace' | 'get_user_profile' | 'list_workspace_users' | 'get_subscription' | 'get_plans' | 'get_plan_versions' | 'get_public_plans' | 'get_plan_version' | 'list_invoices' | 'get_invoice' | 'get_quota_usage' | 'get_all_quota_usage' | 'get_usage_logs' | 'get_credit_balance' | 'list_credit_transactions' | 'get_credit_packages' | 'get_credit_buckets' | 'get_expiring_credits' | 'get_public_credit_packages' | 'check_feature_flag' | 'check_permission' | 'resolve_permissions' | 'get_settings' | 'record_usage' | 'record_usage_batch' | 'consume_credits' | 'send_notification' | 'create_workspace' | 'update_workspace' | 'delete_workspace' | 'invite_workspace_user' | 'remove_workspace_user' | 'update_workspace_user_role' | 'update_user_profile' | 'update_feature_flag' | 'create_subscription_checkout' | 'update_subscription' | 'cancel_subscription' | 'resume_subscription' | 'get_billing_portal_url' | 'purchase_credits';
 /** Resolve a `builtinTools` config value to the tools it selects. */
 declare function selectBuiltinTools(selection: 'all' | 'readonly' | false | {
     include?: BuiltinMcpToolName[];
     exclude?: BuiltinMcpToolName[];
-}): McpToolDefinition<any>[];
+}): AnyMcpTool[];
 
 interface IDocument {
     _id: string;
@@ -821,7 +1088,7 @@ interface ISettings {
         /** Auto-create workspace on first login */
         autoCreateFirst: boolean;
     };
-    [key: string]: any;
+    [key: string]: unknown;
 }
 
 /** Data passed to a notification template for merge tag replacement. */
@@ -880,7 +1147,7 @@ interface NotificationData {
         push?: boolean;
     };
     /** Any additional merge tags available as {{key}} in the email template. */
-    [key: string]: any;
+    [key: string]: unknown;
 }
 /** Result of sending a notification. */
 interface NotificationResult {
@@ -1082,13 +1349,20 @@ interface ScopedActions {
  *
  * export const mcp = createMcpHandler({
  *   buildbase,
- *   serverInfo: { name: 'imejis', version: '1.0.0' },
+ *   serverInfo: { name: 'acme', version: '1.0.0' },
  *   auth: {
  *     verify: (token) => {
  *       const c = verifyClientJwt(token, process.env.BUILDBASE_CLIENT_SECRET!);
- *       return { sessionId: String(c.sid), userId: String(c.sub), scopes: c.scope };
+ *       // Claims beyond RFC 7519 are `unknown` — narrow before use.
+ *       return {
+ *         sessionId: typeof c.sid === 'string' ? c.sid : '',
+ *         userId: c.sub,
+ *         scopes: Array.isArray(c.scope)
+ *           ? c.scope.filter((s): s is string => typeof s === 'string')
+ *           : undefined,
+ *       };
  *     },
- *     resourceMetadataUrl: 'https://imejis.io/.well-known/oauth-protected-resource',
+ *     resourceMetadataUrl: 'https://example.com/.well-known/oauth-protected-resource',
  *   },
  * });
  *
@@ -1155,6 +1429,14 @@ interface McpToolContext<TCustom = unknown> {
      */
     custom: TCustom;
 }
+/** An icon for display in host UIs (SEP-973, protocol 2025-11-25). */
+interface McpIcon {
+    /** Icon URL (https or data URI). */
+    src: string;
+    mimeType?: string;
+    /** e.g. `['48x48']` or `['any']` for scalable formats. */
+    sizes?: string[];
+}
 /** MCP tool annotations (behavior hints for agents). */
 interface McpToolAnnotations {
     title?: string;
@@ -1163,6 +1445,70 @@ interface McpToolAnnotations {
     idempotentHint?: boolean;
     openWorldHint?: boolean;
 }
+/** Plain text block. */
+interface McpTextContent {
+    type: 'text';
+    text: string;
+}
+/** Base64-encoded image (`data` has no data-URI prefix). */
+interface McpImageContent {
+    type: 'image';
+    data: string;
+    mimeType: string;
+}
+/** Base64-encoded audio (`data` has no data-URI prefix). */
+interface McpAudioContent {
+    type: 'audio';
+    data: string;
+    mimeType: string;
+}
+/** Link to a resource the client may fetch — the content itself is not embedded. */
+interface McpResourceLinkContent {
+    type: 'resource_link';
+    uri: string;
+    name: string;
+    title?: string;
+    description?: string;
+    mimeType?: string;
+    size?: number;
+}
+/** Resource contents embedded directly in the result (text or base64 blob). */
+interface McpEmbeddedResourceContent {
+    type: 'resource';
+    resource: {
+        uri: string;
+        mimeType?: string;
+        title?: string;
+    } & ({
+        text: string;
+    } | {
+        blob: string;
+    });
+}
+/** Any content block a tool result may carry. */
+type McpContentBlock = McpTextContent | McpImageContent | McpAudioContent | McpResourceLinkContent | McpEmbeddedResourceContent;
+/**
+ * Full wire-shaped tool result. Return this from `execute` to control the
+ * result exactly — mixed content blocks (text + images + resource links),
+ * `structuredContent`, and the `isError` flag. Any other return value keeps
+ * the legacy behavior: strings become one text block, objects become
+ * JSON text + `structuredContent`.
+ */
+interface McpToolResult {
+    content: McpContentBlock[];
+    structuredContent?: Record<string, unknown>;
+    isError?: boolean;
+}
+/** Text content block (`mcpText('done')`). */
+declare const mcpText: (text: string) => McpTextContent;
+/** Image content block from base64 data (`mcpImage(pngBase64, 'image/png')`). */
+declare const mcpImage: (data: string, mimeType: string) => McpImageContent;
+/** Audio content block from base64 data (`mcpAudio(wavBase64, 'audio/wav')`). */
+declare const mcpAudio: (data: string, mimeType: string) => McpAudioContent;
+/** Resource-link content block (`mcpResourceLink('https://…/report.pdf', 'report')`). */
+declare const mcpResourceLink: (uri: string, name: string, extra?: Omit<McpResourceLinkContent, "type" | "uri" | "name">) => McpResourceLinkContent;
+/** Embedded-resource content block (`mcpEmbeddedResource({ uri, text })`). */
+declare const mcpEmbeddedResource: (resource: McpEmbeddedResourceContent["resource"]) => McpEmbeddedResourceContent;
 /** A tool exposed over MCP. Use {@link defineMcpTool} for inferred input types. */
 interface McpToolDefinition<S extends z.ZodType = z.ZodType, TCustom = any> {
     /** Tool name: `[a-zA-Z0-9_-]`, 1–128 chars. */
@@ -1174,6 +1520,8 @@ interface McpToolDefinition<S extends z.ZodType = z.ZodType, TCustom = any> {
      */
     inputSchema: S | Record<string, unknown>;
     annotations?: McpToolAnnotations;
+    /** Optional icons for host UIs (protocol 2025-11-25). */
+    icons?: McpIcon[];
     /**
      * Scopes required to see/call this tool. The token must carry ALL of them
      * (`McpAuthInfo.scopes`) for the tool to be visible or callable; a token
@@ -1181,8 +1529,98 @@ interface McpToolDefinition<S extends z.ZodType = z.ZodType, TCustom = any> {
      * no scopes and are governed by `builtinTools` + the user's own permissions.
      */
     requiredScopes?: string[];
+    /**
+     * Runs the tool. Return an {@link McpToolResult} for full control over the
+     * wire result (images, resource links, mixed blocks); any other value is
+     * auto-wrapped (string → text block; object → JSON text + structuredContent).
+     */
     execute: (input: z.output<S>, ctx: McpToolContext<TCustom>) => unknown | Promise<unknown>;
 }
+/**
+ * Existential tool type for heterogeneous lists (registries, config arrays).
+ * Each tool keeps its precise schema/context types at its definition site
+ * (use {@link defineMcpTool}); `any` here only erases them for storage —
+ * never use it to define a tool.
+ */
+type AnyMcpTool = McpToolDefinition<any, any>;
+/**
+ * What a resource `read` may return. Strings become text contents, plain
+ * objects become pretty-printed JSON (`application/json`), and an explicit
+ * `{ text }` or `{ blob }` shape is used as-is (blob = base64).
+ */
+type McpResourceReadResult = string | {
+    text: string;
+    mimeType?: string;
+} | {
+    blob: string;
+    mimeType?: string;
+} | object;
+/** A fixed-URI resource served via `resources/list` + `resources/read`. */
+interface McpResourceDefinition<TCustom = any> {
+    /** Unique resource URI (custom schemes welcome, e.g. `app://orders`). */
+    uri: string;
+    name: string;
+    title?: string;
+    description?: string;
+    mimeType?: string;
+    icons?: McpIcon[];
+    /** Same gating semantics as tools: token must carry ALL listed scopes. */
+    requiredScopes?: string[];
+    read: (ctx: McpToolContext<TCustom>) => McpResourceReadResult | Promise<McpResourceReadResult>;
+}
+/**
+ * A parameterized resource (RFC 6570 level-1 `{var}` templates only), served
+ * via `resources/templates/list` and matched on `resources/read`.
+ */
+interface McpResourceTemplateDefinition<TCustom = any> {
+    /** e.g. `buildbase://workspace/{workspaceId}` — `{var}` matches one segment. */
+    uriTemplate: string;
+    name: string;
+    title?: string;
+    description?: string;
+    mimeType?: string;
+    icons?: McpIcon[];
+    requiredScopes?: string[];
+    read: (params: Record<string, string>, uri: string, ctx: McpToolContext<TCustom>) => McpResourceReadResult | Promise<McpResourceReadResult>;
+}
+/** Message content allowed in prompts (spec: text, image, audio, embedded resource). */
+type McpPromptContent = McpTextContent | McpImageContent | McpAudioContent | McpEmbeddedResourceContent;
+/** One message of a prompt template. */
+interface McpPromptMessage {
+    role: 'user' | 'assistant';
+    content: McpPromptContent;
+}
+/** A prompt template served via `prompts/list` + `prompts/get`. */
+interface McpPromptDefinition<TCustom = any> {
+    /** Unique prompt name (same charset rules as tool names). */
+    name: string;
+    title?: string;
+    description?: string;
+    icons?: McpIcon[];
+    arguments?: Array<{
+        name: string;
+        description?: string;
+        required?: boolean;
+    }>;
+    requiredScopes?: string[];
+    /**
+     * Build the messages. A plain string return becomes one user text message;
+     * an array is used as the messages; the object form also sets `description`.
+     */
+    get: (args: Record<string, string>, ctx: McpToolContext<TCustom>) => string | McpPromptMessage[] | {
+        description?: string;
+        messages: McpPromptMessage[];
+    } | Promise<string | McpPromptMessage[] | {
+        description?: string;
+        messages: McpPromptMessage[];
+    }>;
+}
+/** Identity helper for inferred types (mirror of {@link defineMcpTool}). */
+declare const defineMcpResource: <TCustom = any>(resource: McpResourceDefinition<TCustom>) => McpResourceDefinition<TCustom>;
+/** Identity helper for inferred types (mirror of {@link defineMcpTool}). */
+declare const defineMcpResourceTemplate: <TCustom = any>(template: McpResourceTemplateDefinition<TCustom>) => McpResourceTemplateDefinition<TCustom>;
+/** Identity helper for inferred types (mirror of {@link defineMcpTool}). */
+declare const defineMcpPrompt: <TCustom = any>(prompt: McpPromptDefinition<TCustom>) => McpPromptDefinition<TCustom>;
 /** Configuration for {@link createMcpHandler}. */
 interface CreateMcpHandlerConfig {
     /**
@@ -1219,7 +1657,28 @@ interface CreateMcpHandlerConfig {
      * built-in (your definition wins); duplicate custom names or invalid names
      * throw at create time.
      */
-    tools?: McpToolDefinition<any, any>[];
+    tools?: AnyMcpTool[];
+    /**
+     * App-defined resources (`resources/list` + `resources/read`). The
+     * `resources` capability is advertised only when at least one resource,
+     * template, or `builtinResources` is configured.
+     */
+    resources?: McpResourceDefinition[];
+    /** App-defined parameterized resources (`resources/templates/list`). */
+    resourceTemplates?: McpResourceTemplateDefinition[];
+    /**
+     * Built-in BuildBase context resources (opt-in; requires `buildbase`):
+     * `buildbase://profile`, `buildbase://workspaces`, and the
+     * `buildbase://workspace/{workspaceId}` template — read-only context a host
+     * can load without spending tool calls. Richer data (subscription, usage,
+     * credits) stays tools-only.
+     */
+    builtinResources?: boolean;
+    /**
+     * App-defined prompt templates (`prompts/list` + `prompts/get`). The
+     * `prompts` capability is advertised only when at least one is configured.
+     */
+    prompts?: McpPromptDefinition[];
     /**
      * Which built-in BuildBase tools to expose. **Defaults to `'readonly'`**
      * when a `buildbase` client is configured (`false` otherwise) — reads only,
@@ -1240,6 +1699,15 @@ interface CreateMcpHandlerConfig {
      * an Origin header (curl, server-to-server) always pass.
      */
     allowedOrigins?: string[];
+    /**
+     * CORS for browser-based MCP clients. Default **true**: emit
+     * `Access-Control-Allow-Origin: *` (safe for a Bearer-token API — no
+     * cookies are ever involved), or reflect the matching origin when
+     * `allowedOrigins` is set. Pass an origin array to allow only those, or
+     * `false` to emit no CORS headers at all. Preflight (OPTIONS) is answered
+     * automatically either way — no wrapper needed in your route.
+     */
+    cors?: boolean | string[];
     /**
      * Hard cap on the raw request-body size in bytes (DoS protection). Bodies
      * larger than this are rejected with 413 before parsing. Defaults to
@@ -1351,6 +1819,58 @@ declare class AppBridgeError extends Error {
     readonly code: string;
     constructor(code: string, message: string);
 }
+/**
+ * The user + grant context BuildBase sends to `applicationTokenUrl`. The app
+ * mints a token for this user; `resource` is the RFC 8707 audience(s) the token
+ * should be bound to (stamp them as `aud`), and `scope` is what the user granted.
+ * Unknown claims are preserved for forward-compatibility.
+ */
+interface AppTokenRequestClaims {
+    /** The user's id in the org. */
+    id: string;
+    email: string;
+    name?: string;
+    role?: string;
+    emailVerified?: boolean;
+    image?: string;
+    blocked?: boolean;
+    blockedReason?: string;
+    blockedAt?: string;
+    /** Which grant triggered this mint. */
+    grantType?: 'authorization_code' | 'refresh_token';
+    /** Scopes granted at authorization time. */
+    scope?: string[];
+    /** RFC 8707 resource indicator(s) — bind the minted token's `aud` to these. */
+    resource?: string[];
+    /** The OAuth2 client's display title. */
+    clientTitle?: string;
+    /**
+     * Per-user BuildBase session bound to this grant. Embed it ENCRYPTED in the
+     * token you mint (JWTs are signed, not encrypted) and never store it — your
+     * MCP/agent endpoints decrypt it per request to call BuildBase as this user
+     * (`buildbase.withSession(...)`). Fresh on every grant, including refresh.
+     */
+    sessionId?: string;
+    [claim: string]: unknown;
+}
+/**
+ * A verified JWT payload: registered claims (RFC 7519) are typed AND
+ * runtime-validated by {@link verifyClientJwt} (a signed token whose `sub` is
+ * a number is rejected, so the types here are real guarantees). Every other
+ * claim is `unknown` — custom claims are attacker-influenced input until you
+ * narrow them (`typeof payload.sid === 'string'`), even after the signature
+ * checks out.
+ */
+interface VerifiedJwtPayload {
+    iss?: string;
+    sub?: string;
+    aud?: string | string[];
+    exp?: number;
+    nbf?: number;
+    iat?: number;
+    jti?: string;
+    [claim: string]: unknown;
+}
 /** Options for {@link verifyClientJwt} (all optional; secure defaults). */
 interface VerifyClientJwtOptions {
     /** Allowed clock skew in seconds for `exp`/`nbf`. Default 60. */
@@ -1371,11 +1891,8 @@ interface VerifyClientJwtOptions {
  * its payload. Checks the signature (timing-safe), the algorithm, `exp`/`nbf`,
  * and — by default — that an `exp` is present at all. Optionally pins `iss`/`aud`.
  * Throws {@link AppBridgeError} on any failure.
- *
- * The third argument accepts either the legacy `clockToleranceSec` number or a
- * {@link VerifyClientJwtOptions} object.
  */
-declare function verifyClientJwt(token: string, clientSecret: string, optionsOrTolerance?: number | VerifyClientJwtOptions): Record<string, any>;
+declare function verifyClientJwt(token: string, clientSecret: string, options?: VerifyClientJwtOptions): VerifiedJwtPayload;
 /** Extract the token from an `Authorization: Bearer <token>` header. */
 declare function extractBearerToken(authorization: string | null | undefined): string | null;
 /**
@@ -1398,5 +1915,252 @@ declare function bearerChallenge(options: {
     body: string;
 };
 
-export { AppBridgeError, bearerChallenge, builtinMcpTools, createMcpHandler, defineMcpTool, extractBearerToken, selectBuiltinTools, signClientJwt, verifyClientJwt };
-export type { BuiltinMcpToolName, CreateMcpHandlerConfig, McpAuthInfo, McpBuildBaseClient, McpHandler, McpHttpRequest, McpHttpResponse, McpServerCard, McpToolAnnotations, McpToolContext, McpToolDefinition, ScopedActions };
+/**
+ * createAgentStack — the whole agent-readiness + MCP surface from ONE config.
+ *
+ * Everything the SDK can derive, it derives: the MCP endpoint, the server
+ * card, the RFC 9728 protected-resource metadata, the API-catalog entry, the
+ * BuildBase client, token verification (via `buildbaseAuth`), CORS, and the
+ * discovery `Link` header — so a consumer configures identity once and wires
+ * two routes. Every derived value stays overridable ("accelerate, never
+ * gate").
+ *
+ * @example Next.js App Router — complete agent support:
+ * ```ts
+ * // lib/agent.ts
+ * import { createAgentStack } from "@buildbase/sdk/mcp";
+ * export const agent = createAgentStack({
+ *   serverUrl: process.env.NEXT_PUBLIC_BUILDBASE_SERVER_URL!,
+ *   orgId: process.env.NEXT_PUBLIC_BUILDBASE_ORG_ID!,
+ *   siteUrl: "https://app.example.com",
+ *   site: { name: "My App" },
+ *   secret: process.env.SYSTEM_SECRET!,
+ * });
+ *
+ * // app/api/mcp/route.ts
+ * import { agent } from "@/lib/agent";
+ * export const { GET, POST, DELETE, OPTIONS } = agent.routes;
+ *
+ * // app/.well-known/[...path]/route.ts — and identical one-liners at
+ * // app/robots.txt/route.ts, app/auth.md/route.ts, app/security.txt/route.ts
+ * import { agent } from "@/lib/agent";
+ * export const GET = agent.serveAgentPath;
+ * ```
+ *
+ * @example Express / Hono / Bun — same stack, `handle`/`fetch` style:
+ * ```ts
+ * app.all("/api/mcp", async (req, res) => {
+ *   const r = await agent.mcp.handle({ method: req.method, headers: req.headers, body: req.body });
+ *   res.status(r.status).set(r.headers).send(r.body);
+ * });
+ * app.use(async (req, res, next) => {
+ *   const doc = await agent.resolvePath(req.path);
+ *   if (!doc) return next();
+ *   res.status(doc.status).set("Content-Type", doc.contentType).send(doc.body);
+ * });
+ * ```
+ */
+
+/** Configuration for {@link createAgentStack}. */
+interface AgentStackConfig {
+    /** BuildBase server base URL. */
+    serverUrl: string;
+    /** The org id. */
+    orgId: string;
+    /** This app's public origin, e.g. `https://app.example.com`. */
+    siteUrl: string;
+    /** Site identity for every discovery document. */
+    site: AgentReadyConfig['site'];
+    /**
+     * The app's token-signing secret — wires `buildbaseAuth` (verify + audience
+     * binding + `sid` decryption) automatically. Never sent anywhere. Omit only
+     * when supplying `mcp.auth` yourself.
+     */
+    secret?: string;
+    /**
+     * The app's OAuth scope catalog (see `AgentReadyConfig.scopes`) —
+     * `scopes_supported` in the protected-resource metadata reads from it.
+     */
+    scopes?: AppScope[];
+    /** MCP server options. All optional — omit the whole block for defaults. */
+    mcp?: {
+        /** Endpoint path on `siteUrl`. Default `/api/mcp`. */
+        path?: string;
+        /** Advertised server identity. Defaults to the site name, v1.0.0. */
+        serverInfo?: {
+            name: string;
+            version: string;
+        };
+        /** Your custom tools. */
+        tools?: AnyMcpTool[];
+        /** Built-in tool selection. Default `'readonly'`. */
+        builtinTools?: CreateMcpHandlerConfig['builtinTools'];
+        /** Scopes advertised on the protected-resource metadata. */
+        scopes?: string[];
+        /** Your own BuildBase client; auto-created from serverUrl/orgId if omitted. */
+        buildbase?: McpBuildBaseClient;
+        /** Override the derived auth (e.g. `false` for local dev). */
+        auth?: CreateMcpHandlerConfig['auth'];
+        /** Any remaining `createMcpHandler` option, merged last. */
+        handler?: Partial<CreateMcpHandlerConfig>;
+    };
+    /**
+     * Any {@link AgentReadyConfig} field (robots, skills, llms.txt, security,
+     * a2aCard, extraPaths, …) — merged over the derived discovery config, so
+     * every derived value can be replaced.
+     */
+    discovery?: Partial<AgentReadyConfig>;
+}
+/** What {@link createAgentStack} returns. */
+interface AgentStack {
+    /** The MCP handler (`handle`/`fetch`/`listTools`/`serverCard`). */
+    mcp: McpHandler;
+    /** Absolute MCP endpoint URL. */
+    mcpEndpoint: string;
+    /** The fully derived discovery config (inspect or reuse in middleware). */
+    config: AgentReadyConfig;
+    /** Discovery `Link` header value for your middleware / edge responses. */
+    linkHeader: string;
+    /** Resolve any agent-facing path to a document (framework-agnostic). */
+    resolvePath(path: string): Promise<DiscoveryDocument | null>;
+    /** Web-standard discovery route: hand it any `Request`, get a `Response`. */
+    serveAgentPath(request: Request): Promise<Response>;
+    /**
+     * Web-standard MCP route handlers, ready to re-export from a route file:
+     * `export const { GET, POST, DELETE, OPTIONS } = agent.routes`.
+     */
+    routes: {
+        GET: (request: Request) => Promise<Response>;
+        POST: (request: Request) => Promise<Response>;
+        DELETE: (request: Request) => Promise<Response>;
+        OPTIONS: (request: Request) => Promise<Response>;
+    };
+}
+/**
+ * Build the complete agent stack — MCP server + discovery surface — from one
+ * config object. See the module doc for full wiring examples.
+ */
+declare function createAgentStack(stack: AgentStackConfig): AgentStack;
+
+/**
+ * BuildBase agent-auth presets (server-side, framework-agnostic).
+ *
+ * The BuildBase security model: the platform runs the OAuth2 flow (login,
+ * consent, PKCE, refresh) but the APP mints and verifies its own user tokens,
+ * signed with the app's own secret. The platform only relays the minted token
+ * to the agent — it never sees the secret, so it can neither forge nor decode
+ * an app token. The per-user BuildBase session travels inside the token only
+ * as an AES-256-GCM-encrypted `sid` claim, so it is never stored and never
+ * plaintext anywhere; access to it expires with the token.
+ *
+ * These presets make that model a one-liner on each side of the flow, and run
+ * entirely in the app's process — pure local crypto, zero platform calls:
+ *
+ *   • {@link mintAgentToken}  — inside your `applicationTokenUrl` handler:
+ *     signs the app JWT (HS256) with your secret, stamps `aud` from the RFC
+ *     8707 resource, and embeds the encrypted `sid` automatically.
+ *   • {@link buildbaseAuth}   — the `auth` config for `createMcpHandler`:
+ *     verifies the JWT, enforces audience binding, decrypts the `sid`, and
+ *     maps the claims to `McpAuthInfo`.
+ *
+ * @example The full loop:
+ * ```ts
+ * // applicationTokenUrl route — the platform calls this on every grant
+ * const { status, body } = await handleAppTokenRequest({
+ *   authorization: req.headers.get("authorization"),
+ *   clientSecret: process.env.BUILDBASE_CLIENT_SECRET!,
+ *   mintToken: (claims) => mintAgentToken({ claims, secret: process.env.SYSTEM_SECRET! }),
+ * });
+ *
+ * // MCP server — verifies what the route above minted
+ * const mcp = createMcpHandler({
+ *   buildbase,
+ *   auth: buildbaseAuth({ secret: process.env.SYSTEM_SECRET!, resource: "https://app.example.com/api/mcp" }),
+ * });
+ * ```
+ *
+ * AES-GCM comes from WebCrypto (`globalThis.crypto.subtle`) — Node 18+, Bun,
+ * Deno, edge runtimes, browsers. The wire format is
+ * `base64url(iv(12) || authTag(16) || ciphertext)` with the key derived as
+ * `SHA-256(secret + ":bb-session")`, byte-compatible with Node
+ * `createCipheriv("aes-256-gcm", ...)` implementations of the same layout.
+ */
+
+/** Encrypt/decrypt pair for the `sid` claim, bound to one app secret. */
+interface SessionRefCrypto {
+    /** Encrypt a BuildBase session id for embedding in an app JWT. */
+    encryptSessionRef(sessionId: string): Promise<string>;
+    /** Decrypt a `sid` claim. Returns null on any failure (wrong key, garbage). */
+    decryptSessionRef(ref: string): Promise<string | null>;
+}
+/**
+ * Session-ref crypto derived from the app's secret. Both sides of the loop
+ * ({@link mintAgentToken}, {@link buildbaseAuth}) use this internally — reach
+ * for it directly only when minting or verifying tokens by hand.
+ */
+declare function createSessionRefCrypto(secret: string): SessionRefCrypto;
+/** Options for {@link mintAgentToken}. */
+interface MintAgentTokenOptions {
+    /** The verified platform claims (from `handleAppTokenRequest`'s callback). */
+    claims: AppTokenRequestClaims;
+    /** The APP's token-signing secret. Never leaves this process. */
+    secret: string;
+    /** Token lifetime in seconds. Default 3600 — keep agent tokens short-lived. */
+    expiresInSec?: number;
+    /**
+     * App-specific claims merged into the token — e.g. a `workspaceId` resolved
+     * by your own user sync. Merged last, so they can override the defaults.
+     */
+    extraClaims?: Record<string, unknown>;
+}
+/**
+ * Mint the app's agent access token from a platform grant: HS256-signed with
+ * YOUR secret, `aud` bound to the granted RFC 8707 resource(s), scopes carried
+ * through, and the per-user BuildBase session embedded as an encrypted `sid`
+ * claim. The result plugs straight into `handleAppTokenRequest`'s `mintToken`.
+ */
+declare function mintAgentToken(options: MintAgentTokenOptions): Promise<{
+    token: string;
+    expiresIn: number;
+}>;
+/** Options for {@link buildbaseAuth}. */
+interface BuildBaseAuthOptions {
+    /** The APP's token-signing secret — the same one `mintAgentToken` used. */
+    secret: string;
+    /**
+     * The protected resource(s) this server IS. Enforces RFC 8707 audience
+     * binding — the token's `aud` must include one of these URIs. Pass an array
+     * when the server is addressable under more than one resource identifier
+     * (e.g. the canonical `<host>/mcp` plus the literal endpoint URL); the
+     * FIRST entry is the canonical one used to derive `resourceMetadataUrl`.
+     */
+    resource?: string | string[];
+    /**
+     * Explicit RFC 9728 metadata URL for the 401 challenge. Defaults to the
+     * path-derived `/.well-known/oauth-protected-resource<path>` of the first
+     * `resource`.
+     */
+    resourceMetadataUrl?: string;
+    /**
+     * Reject tokens that carry no `aud` claim at all. Default false: audience is
+     * enforced when present, and legacy audience-less tokens still work. Turn
+     * this on once every minted token is audience-bound.
+     */
+    requireAudience?: boolean;
+    /** Extra JWT verification options (clock tolerance, issuer pinning). */
+    verify?: Pick<VerifyClientJwtOptions, 'clockToleranceSec' | 'issuer'>;
+}
+/**
+ * The `auth` config for `createMcpHandler`, prewired for BuildBase-minted app
+ * tokens: HS256 verification with your secret, RFC 8707 audience binding,
+ * `sid` decryption to the BuildBase session, claim mapping to `McpAuthInfo`,
+ * and the derived RFC 9728 `resourceMetadataUrl`. Entirely local — the token
+ * and secret never leave this process.
+ */
+declare function buildbaseAuth(options: BuildBaseAuthOptions): {
+    verify: (token: string, req: McpHttpRequest) => Promise<McpAuthInfo | null>;
+    resourceMetadataUrl?: string;
+};
+
+export { AppBridgeError, bearerChallenge, buildbaseAuth, builtinMcpTools, createAgentStack, createMcpHandler, createSessionRefCrypto, defineMcpPrompt, defineMcpResource, defineMcpResourceTemplate, defineMcpTool, extractBearerToken, mcpAudio, mcpEmbeddedResource, mcpImage, mcpResourceLink, mcpText, mintAgentToken, selectBuiltinTools, signClientJwt, verifyClientJwt };
+export type { AgentStack, AgentStackConfig, AnyMcpTool, BuildBaseAuthOptions, BuiltinMcpToolName, CreateMcpHandlerConfig, McpAudioContent, McpAuthInfo, McpBuildBaseClient, McpContentBlock, McpEmbeddedResourceContent, McpHandler, McpHttpRequest, McpHttpResponse, McpIcon, McpImageContent, McpPromptContent, McpPromptDefinition, McpPromptMessage, McpResourceDefinition, McpResourceLinkContent, McpResourceReadResult, McpResourceTemplateDefinition, McpServerCard, McpTextContent, McpToolAnnotations, McpToolContext, McpToolDefinition, McpToolResult, MintAgentTokenOptions, ScopedActions, SessionRefCrypto, VerifiedJwtPayload };