@lunora/mcp 1.0.0-alpha.23 → 1.0.0-alpha.231

package/dist/index.d.mts

@@ -1,83 +1,564 @@
 import { LunoraClient } from '@lunora/client';
+import { T as ToolDefinition, f as ToolResult, e as ToolInputSchema, a as McpFetchHandler, b as McpTool } from "./packem_shared/serve-stateless.d-CKsbI0fP.mjs";
+export { D as DEFAULT_MAX_REQUEST_BYTES, type d as McpServerInfo, type S as ServeStatelessOptions, g as createToolServer, s as serveStateless } from "./packem_shared/serve-stateless.d-CKsbI0fP.mjs";
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
-import { X402ChargeConfig, X402Price } from '@lunora/x402/charge';
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
-interface ToolInputSchema {
-  properties: Record<string, unknown>;
-  required?: ReadonlyArray<string>;
-  type: "object";
-}
-interface ToolDefinition {
-  description: string;
-  inputSchema: ToolInputSchema;
-  name: string;
-}
-interface ToolResult {
-  content: {
-    text: string;
-    type: "text";
-  }[];
-  isError?: boolean;
-}
+import '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
+/**
+ * The observability tools. Descriptions say WHEN to call the tool, not just
+ * what it returns — an agent picking between five similar reads needs the
+ * trigger, and it pays for these strings on every turn.
+ */
+declare const OBSERVABILITY_TOOL_DEFINITIONS: ReadonlyArray<ToolDefinition>;
+/** The read-only tool surface: introspection + query. Always exposed. */
 declare const READ_ONLY_TOOL_DEFINITIONS: ReadonlyArray<ToolDefinition>;
+/** The write tool surface (mutations + actions). Exposed ONLY when writes are enabled. */
 declare const WRITE_TOOL_DEFINITIONS: ReadonlyArray<ToolDefinition>;
-declare const toolDefinitions: (allowWrites: boolean) => ReadonlyArray<ToolDefinition>;
-declare const callTool: (client: LunoraClient, name: string, input: Record<string, unknown>, allowWrites?: boolean) => Promise<ToolResult>;
+/**
+ * The tools this server advertises: every family whose gate is open, in table
+ * order. A gated family is OMITTED rather than refused — an AI agent can't
+ * invoke what it can't see — and {@link callTool} re-checks the same gate at
+ * dispatch, so the guarantee does not depend on a client honouring this list.
+ */
+declare const toolDefinitions: (allowWrites: boolean, allowObservability?: boolean, allowDataReads?: boolean) => ReadonlyArray<ToolDefinition>;
+/**
+ * Dispatch a tool call against `client`: find the family that owns `name`, check
+ * its gate, hand off. Unknown tools and thrown errors are returned as `isError`
+ * results (rather than rejections) so the calling model sees the failure as tool
+ * output, per the MCP convention.
+ *
+ * Each gate is enforced HERE as well as in {@link toolDefinitions}, so a call to
+ * a gated tool is refused even if the client somehow names one it was never
+ * shown.
+ */
+declare const callTool: (client: LunoraClient, name: string, input: Record<string, unknown>, allowWrites?: boolean, allowObservability?: boolean, allowDataReads?: boolean) => Promise<ToolResult>;
+/**
+ * Agent exposure for the MCP server: a durable `@lunora/agent` run fronted as an
+ * MCP tool an external agent can call. The capability boundary is the MCP-server
+ * process + its token, so WHICH agents are exposed is config on the server (like
+ * `allowWrites`), not on `defineAgent` — keeping `@lunora/agent` codegen
+ * byte-identical.
+ */
 interface McpAgentExposure {
+  /** What the agent does — shown to the calling model, which decides from it. */
   description: string;
+  /** The agent's export name (its `ctx.agents.<name>` / `AGENT_<NAME>` binding). */
   name: string;
+  /** Override the model-facing tool name (default `agent_<name>`). */
   toolName?: string;
 }
+/** The generic status/poll tool advertised alongside the per-agent tools. */
 declare const AGENT_STATUS_TOOL_NAME = "lunora_agent_status";
+/**
+ * The uniform input schema every agent tool advertises. Agents share ONE run
+ * input (`@lunora/agent` has no per-agent validator), so there is nothing to
+ * derive per agent — a single static schema is reused for every agent tool.
+ */
 declare const AGENT_RUN_INPUT_SCHEMA: ToolInputSchema;
+/**
+ * Parse `LUNORA_MCP_AGENTS` — a `;`-separated list of `name:description` pairs,
+ * e.g. `"support:Handles support questions;billing:Billing help"`. The
+ * description may itself contain colons (only the FIRST colon splits). Blank
+ * entries and entries with an empty name/description are skipped.
+ */
 declare const parseAgentsEnv: (raw: string | undefined) => McpAgentExposure[];
+/**
+ * The tools this module advertises. Fail-closed: only the boolean `true` opts
+ * in (an env-plumbed caller could pass a truthy string), and the tools appear
+ * ONLY when at least one agent is exposed — so an agent-free or non-opted-in
+ * server never lists them.
+ */
 declare const agentToolDefinitions: (exposures: ReadonlyArray<McpAgentExposure>, allowAgents: boolean) => ReadonlyArray<ToolDefinition>;
+/** Options threaded into a single agent tool dispatch. */
 interface CallAgentToolOptions {
+  /** Opt-in gate — must be exactly `true` or the call is refused fail-closed. */
   allowAgents: boolean;
+  /** The exposures advertised by this server. */
   exposures: ReadonlyArray<McpAgentExposure>;
+  /** Wall-clock budget a single call awaits before returning a pending result. */
   maxWaitMs?: number;
+  /** Delay between thread-status polls. */
   pollIntervalMs?: number;
+  /** Test seam replacing the between-poll wait; production uses a real timer. */
   wait?: (ms: number) => Promise<void>;
 }
+/**
+ * Dispatch an agent tool call: start a durable run via `agents:agentRun`, then
+ * await-with-timeout — poll `agents:agentThread` until terminal (returning the
+ * final answer from `agents:agentMessages`) or, on budget exhaustion, return a
+ * NON-error pending payload the caller resumes with `lunora_agent_status`.
+ *
+ * Fail-closed: refused at dispatch unless `allowAgents === true`, mirroring the
+ * `allowWrites` guard — starting a run is a side effect and must not ride the
+ * read-only default.
+ */
 declare const callAgentTool: (client: LunoraClient, name: string, input: Record<string, unknown>, options: CallAgentToolOptions) => Promise<ToolResult>;
 interface LunoraMcpServerOptions {
+  /** Wall-clock budget a single agent tool call awaits before returning a pending result. */
   agentMaxWaitMs?: number;
+  /** Delay between agent thread-status polls. */
   agentPollIntervalMs?: number;
+  /** The agents this server fronts as MCP tools (see `allowAgents`). */
   agents?: ReadonlyArray<McpAgentExposure>;
+  /**
+   * Expose the per-agent tools (`agent_<name>` + the generic
+   * `lunora_agent_status`). Defaults to `false`, mirroring `allowWrites`:
+   * starting a durable agent run is a side effect, so the agent tools are
+   * omitted from the advertised list AND refused at dispatch unless explicitly
+   * opted in. Only takes effect together with a non-empty `agents` list.
+   */
   allowAgents?: boolean;
+  /**
+   * Expose `lunora_find_related`, which returns raw table rows read through the
+   * admin writer, so RLS policies and column masks do not apply. Defaults to
+   * `false`, for the same reason as `allowObservability`. Only takes effect
+   * when a `token` resolved. On the OAuth-protected path the verified token must
+   * also carry the data-read scope (see `DATA_READ_SCOPE` in `./tools`).
+   */
+  allowDataReads?: boolean;
+  /**
+   * Expose the observability tools (`lunora_get_logs`, `lunora_get_issues`,
+   * `lunora_get_advisories`, `lunora_get_query_insights`,
+   * `lunora_get_migration_status`). Defaults to `false`, mirroring
+   * `allowWrites`: they are read-only, but every row they return — log lines,
+   * request metadata, grouped error messages — is production user data that
+   * lands in the model's context and therefore at its provider. Holding the
+   * admin bearer is not consent to ship that, so it is a separate opt-in;
+   * without it the tools are omitted from the advertised list AND refused at
+   * dispatch. Only takes effect when a `token` resolved. On the OAuth-protected
+   * path the verified token must also carry the observability scope (see
+   * `OBSERVABILITY_SCOPE` in `./tools`); this option stays the outer gate.
+   */
+  allowObservability?: boolean;
+  /**
+   * Expose the write tools (`lunora_run_mutation` / `lunora_run_action`).
+   * Defaults to `false`: the server is READ-ONLY unless explicitly opted in,
+   * so a prompt-injected or misaligned agent can't mutate the deployment with
+   * the configured token. When false the write tools are omitted from the
+   * advertised tool list AND refused at dispatch.
+   */
   allowWrites?: boolean;
+  /**
+   * Pre-built client (test injection). When omitted a `LunoraClient` is
+   * created from `url`/`token`/`fetch`.
+   */
   client?: LunoraClient;
+  /** `fetch` implementation; defaults to the ambient global. */
   fetch?: typeof fetch;
+  /**
+   * Bearer token sent on every RPC. **Required** alongside `url`, and it must
+   * be the deployment's **admin bearer**: the introspection/allowlist path
+   * every tool depends on (`lunora_list_functions`, `lunora_list_tables`, and
+   * the `assertRunnable` precheck that runs before every `run` tool) hits
+   * admin-gated `/_lunora/admin/*` routes, so no scoped/app token works
+   * today — it would 403 (`ADMIN_FORBIDDEN`) on the first tool call. The
+   * read-only guarantee is therefore NOT enforced by the token's scope; it is
+   * enforced in-process via `allowWrites: false` (the default), which omits
+   * the write tools from the advertised list and refuses them at dispatch.
+   *
+   * Because EVERY tool needs it, omitting it is a misconfiguration rather than
+   * a reduced-capability mode, and `createLunoraMcpServer` says so at
+   * construction instead of advertising a surface that 403s on first use. The
+   * one exception is the `client` injection seam (tests / a pre-authenticated
+   * client), where this server cannot know what the client can reach and so
+   * reads "unknown" fail-closed: the privileged observability tools stay
+   * unadvertised and are refused at dispatch.
+   */
   token?: string;
+  /** Base URL of the deployed Lunora Worker. Required unless `client` is given. */
   url?: string;
 }
+/**
+ * Build an MCP `Server` whose tools talk to a Lunora deployment. The server is
+ * transport-agnostic — call `.connect(transport)` yourself, or use
+ * `connectStdio` for the common stdio case.
+ *
+ * Tool calls are dispatched through `callTool`, which the deployment reaches
+ * over HTTP RPC. No WebSocket is opened (the tools never subscribe), so this is
+ * safe to run as a short-lived stdio process.
+ */
 declare const createLunoraMcpServer: (options: LunoraMcpServerOptions) => Server;
+/**
+ * Build the server and connect it over stdio — the transport MCP clients use
+ * when they spawn the `lunora-mcp` binary. Resolves once the transport is
+ * connected; the process then stays alive serving requests.
+ */
 declare const connectStdio: (options: LunoraMcpServerOptions) => Promise<Server>;
-type McpFetchHandler = (request: Request) => Promise<Response>;
-declare const createMcpFetchHandler: (options: LunoraMcpServerOptions) => McpFetchHandler;
+/**
+ * The verified access-token payload better-auth hands a protected handler.
+ *
+ * A JWT payload is an open bag of claims, so this is deliberately an index
+ * signature with the two entries this module reads named. It is structurally
+ * satisfied by `jose`'s `JWTPayload`, which is what better-auth passes.
+ */
+interface McpAccessTokenClaims {
+  readonly [claim: string]: unknown;
+  /** Space-delimited granted scopes (RFC 6749 §3.3). */
+  readonly scope?: unknown;
+  /** Subject — the user the token was issued for. */
+  readonly sub?: string;
+}
+/**
+ * The MCP auth gate: wraps a claims-aware handler into a plain fetch handler.
+ *
+ * Declared structurally here rather than imported from `@better-auth/mcp`,
+ * following the same rule `./paid` follows for `@lunora/x402`: a type import
+ * from a package this one does not depend on puts that package's `.d.ts` into
+ * the build graph, and a consumer that never installs it never builds it
+ * either — so the dts bundler looks for a `dist/` that does not exist and fails
+ * the build. Structural typing costs nothing here because this module never
+ * inspects the gate; it only applies it.
+ *
+ * Both better-auth entry points partially apply to this shape:
+ * `(handler) => requireMcpAuth(auth, handler, opts)` and
+ * `(handler) => createMcpProtectedRequestHandler(options, handler)`.
+ */
+type McpAuthProtect = (handler: (request: Request, claims: McpAccessTokenClaims) => Promise<Response>) => McpFetchHandler;
+/** Server options, or a function deriving them from the request's verified claims. */
+type AuthedMcpServerOptions = ((claims: McpAccessTokenClaims) => LunoraMcpServerOptions | Promise<LunoraMcpServerOptions>) | LunoraMcpServerOptions;
+interface AuthedMcpFetchHandlerOptions {
+  /**
+   * Largest accepted request body, in bytes — enforced while the body streams
+   * in, not after it is buffered. Defaults to `DEFAULT_MAX_REQUEST_BYTES`
+   * (128 KiB), which a value that is not a non-negative safe integer also
+   * falls back to.
+   */
+  maxRequestBytes?: number;
+  /**
+   * The OAuth gate to mount the MCP server behind. Pass
+   * `(handler) => requireMcpAuth(auth, handler, opts)` from
+   * `@lunora/auth/plugins`.
+   */
+  protect: McpAuthProtect;
+  /**
+   * The Lunora MCP server to serve once a request is authorized — either a
+   * fixed options object, or a function of the verified token claims so tool
+   * exposure can follow the scopes the token actually carries.
+   */
+  server: AuthedMcpServerOptions;
+  /**
+   * Step-up for the side-effecting tools: the write tools
+   * (`lunora_run_mutation` / `lunora_run_action`) and the agent tools (each
+   * `agent_<name>` and `lunora_agent_status`, since starting a durable run is a
+   * side effect). A token without `scope` still sees them in `tools/list`, and
+   * a `tools/call` to one throws `challenge([scope])` instead of running, so the
+   * client can re-authorize for the scope and retry. Unset, tools follow
+   * `allowWrites` / `allowAgents` alone. The raw-row and observability families
+   * need their own token scopes with or without `stepUp`; without it a call
+   * without the scope is refused as a tool error, not challenged.
+   */
+  stepUp?: {
+    /**
+     * Build the error that makes the gate answer 403 `insufficient_scope`
+     * naming `scopes`. Pass `createInsufficientScopeError` from
+     * `@lunora/auth/plugins`: better-auth only turns an error that factory
+     * created into the challenge.
+     */
+    challenge: (scopes: string[]) => unknown;
+    /** The scope a call to a side-effecting tool needs, e.g. `"lunora:write"`. */
+    scope: string;
+  };
+}
+/**
+ * Parse an access token's `scope` claim into a set.
+ *
+ * RFC 6749 §3.3 makes `scope` a space-delimited string, and better-auth issues
+ * it that way; anything else (absent, or a non-string an extension wrote)
+ * yields an empty set rather than throwing, so a scope check on a malformed
+ * token denies instead of crashing the tool call.
+ */
+declare const mcpTokenScopes: (claims: McpAccessTokenClaims) => ReadonlySet<string>;
+/**
+ * Build an OAuth-protected stateless Streamable-HTTP fetch handler for a Lunora
+ * MCP server.
+ *
+ * Unauthenticated requests never reach the MCP server at all: `protect` answers
+ * them with the RFC 9728 `WWW-Authenticate` challenge that starts the client's
+ * authorization flow. An authorized request builds a fresh proxy server from
+ * `server` (resolved against the verified claims) and serves it through
+ * {@link serveStateless}, exactly as the unprotected `createMcpFetchHandler`
+ * does — the transport behaviour is identical, only the gate is new.
+ *
+ * A fixed `server` object names one deployment, so its `LunoraClient` is
+ * resolved once and shared: the public-function registry memo in `./tools` is
+ * keyed by client identity and never hits when each request builds its own. The
+ * `(claims) => …` form is per-request by construction — the claims decide which
+ * deployment and token to use — so it keeps a client per request.
+ */
+declare const createAuthedMcpFetchHandler: (options: AuthedMcpFetchHandlerOptions) => McpFetchHandler;
+/** {@link createMcpFetchHandler} options: the server's, plus this transport's body limit. */
+interface McpFetchHandlerOptions extends LunoraMcpServerOptions {
+  /**
+   * Largest accepted request body, in bytes — enforced while the body streams
+   * in, not after it is buffered. Defaults to `DEFAULT_MAX_REQUEST_BYTES`
+   * (128 KiB), which a value that is not a non-negative safe integer also
+   * falls back to.
+   */
+  maxRequestBytes?: number;
+}
+/**
+ * Build a stateless Streamable-HTTP fetch handler for a Lunora MCP server. Each
+ * invocation constructs a fresh proxy server and serves the request through
+ * {@link serveStateless}.
+ *
+ * The `LunoraClient` is resolved ONCE, here, and shared by every request: it is
+ * the same deployment on each one, and the public-function registry memo in
+ * `./tools` is keyed by client identity, so a per-request client would re-fetch
+ * that registry on every tool call. A misconfiguration (`url` without `token`)
+ * therefore throws when the handler is built rather than on first request,
+ * which is where `createLunoraMcpServer` already documents reporting it.
+ */
+declare const createMcpFetchHandler: (options: McpFetchHandlerOptions) => McpFetchHandler;
+/** A Lunora deployment the tools dispatch against. */
+interface LocalDeployment {
+  token?: string;
+  url: string;
+}
+/**
+ * Where the deployment comes from: a fixed value, or a function consulted on
+ * every tool call.
+ *
+ * The resolver form exists because an editor spawns this server when the
+ * project opens — routinely *before* `lunora dev` is running, and it keeps the
+ * process alive across every restart afterwards. A URL captured once at startup
+ * would therefore be absent for the entire first session and stale after the
+ * first restart.
+ */
+type LocalDeploymentSource = (() => LocalDeployment | undefined) | LocalDeployment;
+interface LocalMcpServerOptions {
+  /**
+   * Expose the deployment write tools (`lunora_run_mutation` /
+   * `lunora_run_action`). Defaults to `false` — the same fail-closed default
+   * as the remote server. Locally the blast radius is dev data rather than
+   * production, but a mutation is still a side effect an agent should be
+   * granted deliberately.
+   */
+  allowWrites?: boolean;
+  /**
+   * The Lunora deployment (usually the running dev server) to expose. Omit to
+   * leave the deployment tools out entirely.
+   */
+  deployment?: LocalDeploymentSource;
+  /** Docs site origin backing the documentation tools; `false` omits them. */
+  docs?: false | {
+    baseUrl?: string;
+  };
+  /** Extra tools to compose in, e.g. the CLI's local dev-server tools. */
+  extraTools?: ReadonlyArray<McpTool>;
+  /** `fetch` implementation; defaults to the ambient global. */
+  fetch?: typeof fetch;
+  /** Version reported in the MCP handshake — the host CLI's, not this package's. */
+  version?: string;
+}
+/** Server identity advertised in the MCP `initialize` handshake. */
+declare const LOCAL_SERVER_NAME = "lunora";
+/** Shown when a deployment tool is called and no dev server can be found. */
+declare const NO_DEPLOYMENT_MESSAGE = "no Lunora dev server is running for this project — start one with `lunora dev`, then call this tool again (call lunora_dev_status to check).";
+/**
+ * Assemble the tool list, in the order it is advertised: docs first (the
+ * surface that always works), then the caller's extras, then the error catalog
+ * (compiled in, so it needs no deployment either), then the deployment tools.
+ * Order also decides precedence — `createToolServer` keeps the first
+ * registration of a duplicated name.
+ *
+ * `clientFor` is the shared client cache built once by
+ * {@link createLocalMcpServer} and threaded into both the tool and resource
+ * surfaces. Exported (and called directly by tests) without going through
+ * `createLocalMcpServer`, so a caller that omits it gets a private,
+ * call-scoped cache — same shape as before this surface was shared, just
+ * without the cross-surface sharing that only matters once a resource
+ * surface exists alongside it.
+ */
+declare const localTools: (options: LocalMcpServerOptions, clientFor?: (deployment: LocalDeployment) => LunoraClient) => ReadonlyArray<McpTool>;
+/** Build the composed local server without connecting a transport. */
+declare const createLocalMcpServer: (options?: LocalMcpServerOptions) => Server;
+/**
+ * Build the composed local server and connect it over stdio — the transport an
+ * MCP client uses when it spawns `lunora mcp serve`. Resolves once connected;
+ * the process then stays alive serving requests.
+ */
+declare const connectLocalStdio: (options?: LocalMcpServerOptions) => Promise<Server>;
+/** A tool handler: receives the call's `arguments` bag, returns an MCP tool result. */
+/**
+ * The x402 vocabulary this module needs, declared here rather than imported.
+ *
+ * The x402 package is an optional peer, and a type import from its `charge`
+ * entry puts its `.d.ts` back into this package's build graph:
+ * a consumer that never installs x402 never builds it either, so the dts bundler
+ * looks for a `dist/` that does not exist and fails. That is not hypothetical —
+ * it broke the docs site build, which runs a filtered build over the docs app and its dependency closure
+ * and therefore never builds x402.
+ *
+ * Declaring them locally is safe because this module never *inspects* a charge
+ * config; it forwards it whole to `createChargeMiddleware`. The index signature
+ * keeps a real charge config assignable as x402 grows fields.
+ */
+/** Mirrors x402's `X402Price` — a decimal string like `"$0.05"`, or a number. */
+type X402Price = number | string;
+/** Mirrors x402's charge config with the per-tool price omitted. */
+interface X402ChargeSettings {
+  /** Network this resource settles on. */
+  readonly network: string;
+  /** Everything else x402 accepts, forwarded untouched. */
+  readonly [key: string]: unknown;
+  /** Payout wallet(s), per network family. */
+  readonly recipient: {
+    readonly evm?: string;
+    readonly svm?: string;
+  };
+}
 type ToolHandler = (arguments_: Record<string, unknown>) => Promise<ToolResult> | ToolResult;
+/** Registration shape for a free tool. */
 interface RegisterToolOptions {
+  /** Optional MCP tool annotations (`readOnlyHint`, `title`, …). */
   annotations?: Tool["annotations"];
+  /** Human/model-facing description of what the tool does. */
   description: string;
+  /** JSON-Schema object describing the tool's arguments. */
   inputSchema: ToolInputSchema;
+  /** Unique tool name (the MCP `tools/call` `name`). */
   name: string;
 }
+/** Registration shape for a paid tool: a {@link RegisterToolOptions} plus its USD price. */
 interface RegisterPaidToolOptions extends RegisterToolOptions {
+  /** USD price per call (e.g. `"$0.05"`), charged via x402 before dispatch. */
   price: X402Price;
 }
-type PaidMcpChargeConfig = Omit<X402ChargeConfig, "price">;
+/** x402 settlement vocabulary shared by every paid tool (network, recipient, facilitator); price is per-tool. */
+type PaidMcpChargeConfig = X402ChargeSettings;
+/** Config for `createPaidMcpServer`. */
 interface PaidMcpServerConfig {
+  /** The worker-level x402 charge config; each paid tool supplies only its own `price`. */
   charge: PaidMcpChargeConfig;
+  /**
+   * Largest accepted request body, in bytes — enforced while the body streams
+   * in, not after it is buffered. Defaults to `DEFAULT_MAX_REQUEST_BYTES`
+   * (128 KiB), which a value that is not a non-negative safe integer also
+   * falls back to.
+   */
+  maxRequestBytes?: number;
+  /** Name/version advertised in the MCP `initialize` handshake. Defaults to `lunora-paid-mcp`. */
   serverInfo?: {
     name: string;
     version: string;
   };
 }
+/**
+ * The Worker execution context, as this module reads it: only `waitUntil`, and
+ * structurally, so the package takes no `@cloudflare/workers-types` dependency.
+ */
+interface PaidMcpExecutionContext {
+  waitUntil?: (promise: Promise<unknown>) => void;
+}
+/**
+ * The paid server's fetch handler.
+ *
+ * Unlike the free `McpFetchHandler` it takes the Worker's full
+ * `(request, env, ctx)` triple — the shape `export default { fetch }` is called
+ * with — because the x402 receipt sink NEEDS `ctx.waitUntil`: work that is
+ * neither awaited into the response nor registered with it is cancelled when the
+ * request ends, so an async `onReceipt` (inserting the settled payment into a
+ * durable table) frequently never runs while the money has already moved
+ * on-chain. `env` is accepted and ignored so the handler drops straight into the
+ * default export; both are optional, so a non-Workers caller may still invoke it
+ * with a bare `Request` (the middleware then simply sees no `waitUntil`).
+ */
+type PaidMcpFetchHandler = (request: Request, env?: unknown, context?: PaidMcpExecutionContext) => Promise<Response>;
+/** A paid MCP server: register free/paid tools, then serve over Streamable HTTP. */
 interface PaidMcpServer {
-  readonly fetchHandler: McpFetchHandler;
+  /** The Streamable-HTTP fetch handler; gates each paid `tools/call` behind x402. */
+  readonly fetchHandler: PaidMcpFetchHandler;
+  /** Register a **paid** tool: its dispatch runs the x402 charge middleware first. */
   paidTool: (options: RegisterPaidToolOptions, handler: ToolHandler) => void;
+  /** Register a **free** tool (coexists with paid tools on the same server). */
   tool: (options: RegisterToolOptions, handler: ToolHandler) => void;
 }
+/**
+ * Create a paid MCP server. Register free tools with `tool()` and priced tools
+ * with `paidTool()` (they coexist), then serve `fetchHandler` over HTTP.
+ *
+ * The server is **stateless**: `fetchHandler` builds a fresh `Server` per
+ * request (reading the live tool registry), so tools registered before the
+ * first request are all visible. Each priced tool memoises one initialised
+ * `ChargeMiddleware` (keyed by tool name, baking that tool's price and naming
+ * the tool as the challenge `resource`); a failed init is not cached, so a
+ * transient facilitator outage retries on the next call.
+ */
 declare const createPaidMcpServer: (config: PaidMcpServerConfig) => PaidMcpServer;
-export { AGENT_RUN_INPUT_SCHEMA, AGENT_STATUS_TOOL_NAME, type CallAgentToolOptions, type LunoraMcpServerOptions, type McpAgentExposure, type McpFetchHandler, type PaidMcpChargeConfig, type PaidMcpServer, type PaidMcpServerConfig, READ_ONLY_TOOL_DEFINITIONS, type RegisterPaidToolOptions, type RegisterToolOptions, type ToolDefinition, type ToolHandler, type ToolInputSchema, type ToolResult, WRITE_TOOL_DEFINITIONS, agentToolDefinitions, callAgentTool, callTool, connectStdio, createLunoraMcpServer, createMcpFetchHandler, createPaidMcpServer, parseAgentsEnv, toolDefinitions };
+export { AGENT_RUN_INPUT_SCHEMA, AGENT_STATUS_TOOL_NAME, type AuthedMcpFetchHandlerOptions, type AuthedMcpServerOptions,
+/**
+ * `@lunora/mcp` — Model Context Protocol servers for Lunora. This entry exposes
+ * a *deployment* to AI agents; the `@lunora/mcp/docs` subpath exposes the
+ * framework's *documentation* (credential-free, and safe to host publicly).
+ *
+ * The deployment server: It registers tools for introspecting a deployment
+ * (`lunora_list_functions`, `lunora_list_tables`) and invoking its functions
+ * (`lunora_run_query`, plus `lunora_run_mutation` and `lunora_run_action` when
+ * writes are enabled), each backed by `LunoraClient` over HTTP RPC, plus
+ * `lunora_explain_error` — a credential-free read of the static error catalog
+ * (status, title, hint, matched solution) that needs no deployment at all. It also
+ * exposes the deployment's observability reads (`lunora_get_logs`,
+ * `lunora_get_issues`, `lunora_get_advisories`, `lunora_get_query_insights`,
+ * `lunora_get_migration_status`) when `allowObservability` (or the
+ * LUNORA_MCP_ALLOW_OBSERVABILITY env) is set — read-only, but they return
+ * production user data, so they are omitted entirely without it. The server is
+ * read-only by default — the write tools are exposed only when `allowWrites`
+ * (or the `LUNORA_MCP_ALLOW_WRITES` env) is set, and every run tool is
+ * allowlisted against the deployment's discovered public functions. Past that
+ * gate the two write tools run a two-step confirmation handshake: the first
+ * call writes nothing and returns the proposed action plus a self-verifying
+ * `actionDigest`, and only a second call carrying `confirmed: true` and that
+ * digest executes (see `./write-confirmation`). It can also
+ * front durable `@lunora/agent` runs as `agent_<name>` tools when `allowAgents`
+ * (or `LUNORA_MCP_ALLOW_AGENTS` + `LUNORA_MCP_AGENTS`) is set. Run the
+ * `lunora-mcp` binary (configured via the `LUNORA_URL`, `LUNORA_ADMIN_TOKEN`,
+ * and `LUNORA_MCP_ALLOW_WRITES` env vars) for the stdio transport, serve the
+ * server remotely over Streamable HTTP with `createMcpFetchHandler` (a
+ * Workers-ready `Request` → `Response` handler), or build a server
+ * programmatically with `createLunoraMcpServer` and connect any transport.
+ *
+ * A remote endpoint is reachable by anyone who knows its URL, and the tools
+ * carry the deployment's admin bearer — so for a public deployment use
+ * `createAuthedMcpFetchHandler` instead, which mounts the same server behind
+ * better-auth's MCP OAuth gate (`requireMcpAuth` from `@lunora/auth/plugins`)
+ * and can scope tool exposure to the access token's own scopes.
+ */
+type CallAgentToolOptions, LOCAL_SERVER_NAME, type LocalDeployment, type LocalDeploymentSource, type LocalMcpServerOptions, type LunoraMcpServerOptions, type McpAccessTokenClaims,
+/**
+ * `@lunora/mcp` — Model Context Protocol servers for Lunora. This entry exposes
+ * a *deployment* to AI agents; the `@lunora/mcp/docs` subpath exposes the
+ * framework's *documentation* (credential-free, and safe to host publicly).
+ *
+ * The deployment server: It registers tools for introspecting a deployment
+ * (`lunora_list_functions`, `lunora_list_tables`) and invoking its functions
+ * (`lunora_run_query`, plus `lunora_run_mutation` and `lunora_run_action` when
+ * writes are enabled), each backed by `LunoraClient` over HTTP RPC, plus
+ * `lunora_explain_error` — a credential-free read of the static error catalog
+ * (status, title, hint, matched solution) that needs no deployment at all. It also
+ * exposes the deployment's observability reads (`lunora_get_logs`,
+ * `lunora_get_issues`, `lunora_get_advisories`, `lunora_get_query_insights`,
+ * `lunora_get_migration_status`) when `allowObservability` (or the
+ * LUNORA_MCP_ALLOW_OBSERVABILITY env) is set — read-only, but they return
+ * production user data, so they are omitted entirely without it. The server is
+ * read-only by default — the write tools are exposed only when `allowWrites`
+ * (or the `LUNORA_MCP_ALLOW_WRITES` env) is set, and every run tool is
+ * allowlisted against the deployment's discovered public functions. Past that
+ * gate the two write tools run a two-step confirmation handshake: the first
+ * call writes nothing and returns the proposed action plus a self-verifying
+ * `actionDigest`, and only a second call carrying `confirmed: true` and that
+ * digest executes (see `./write-confirmation`). It can also
+ * front durable `@lunora/agent` runs as `agent_<name>` tools when `allowAgents`
+ * (or `LUNORA_MCP_ALLOW_AGENTS` + `LUNORA_MCP_AGENTS`) is set. Run the
+ * `lunora-mcp` binary (configured via the `LUNORA_URL`, `LUNORA_ADMIN_TOKEN`,
+ * and `LUNORA_MCP_ALLOW_WRITES` env vars) for the stdio transport, serve the
+ * server remotely over Streamable HTTP with `createMcpFetchHandler` (a
+ * Workers-ready `Request` → `Response` handler), or build a server
+ * programmatically with `createLunoraMcpServer` and connect any transport.
+ *
+ * A remote endpoint is reachable by anyone who knows its URL, and the tools
+ * carry the deployment's admin bearer — so for a public deployment use
+ * `createAuthedMcpFetchHandler` instead, which mounts the same server behind
+ * better-auth's MCP OAuth gate (`requireMcpAuth` from `@lunora/auth/plugins`)
+ * and can scope tool exposure to the access token's own scopes.
+ */
+type McpAgentExposure, type McpAuthProtect, type McpFetchHandler, type McpFetchHandlerOptions, type McpTool, NO_DEPLOYMENT_MESSAGE, OBSERVABILITY_TOOL_DEFINITIONS, type PaidMcpChargeConfig, type PaidMcpExecutionContext, type PaidMcpFetchHandler, type PaidMcpServer, type PaidMcpServerConfig, READ_ONLY_TOOL_DEFINITIONS, type RegisterPaidToolOptions, type RegisterToolOptions, type ToolDefinition, type ToolHandler, type ToolInputSchema, type ToolResult, WRITE_TOOL_DEFINITIONS, agentToolDefinitions, callAgentTool, callTool, connectLocalStdio, connectStdio, createAuthedMcpFetchHandler, createLocalMcpServer, createLunoraMcpServer, createMcpFetchHandler, createPaidMcpServer, localTools, mcpTokenScopes, parseAgentsEnv, toolDefinitions };