@lunora/mcp 1.0.0-alpha.28 → 1.0.0-alpha.280

package/dist/index.d.mts

@@ -1,234 +1,85 @@
-import { LunoraClient } from '@lunora/client';
-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';
+export { A as AGENT_RUN_INPUT_SCHEMA, a as AGENT_STATUS_TOOL_NAME,
 /**
- * The tool surface this MCP server exposes. Each tool maps onto a method the
- * `LunoraClient` already provides, so an AI agent can introspect a deployment
- * (functions, global tables) and invoke its functions over HTTP RPC.
+ * `@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).
  *
- * Definitions and dispatch live here — separate from the server wiring — so the
- * behaviour is unit-testable against a mock client without driving a transport.
- */
-/** A JSON-Schema object describing a tool's arguments, per the MCP spec. */
-interface ToolInputSchema {
-  properties: Record<string, unknown>;
-  required?: ReadonlyArray<string>;
-  type: "object";
-}
-interface ToolDefinition {
-  description: string;
-  inputSchema: ToolInputSchema;
-  name: string;
-}
-/** The MCP `CallToolResult` shape this server returns. */
-interface ToolResult {
-  content: {
-    text: string;
-    type: "text";
-  }[];
-  isError?: boolean;
-}
-/** 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>;
-/**
- * The tools this server advertises. When `allowWrites` is false (the default),
- * only the read-only surface is exposed — the mutation/action tools are omitted
- * from `ListTools` entirely, so an AI agent can't invoke a write it can't see.
- */
-declare const toolDefinitions: (allowWrites: boolean) => ReadonlyArray<ToolDefinition>;
-/**
- * Dispatch a tool call against `client`. 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.
+ * 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.
  *
- * `allowWrites` gates the mutation/action tools: when false (the default) a call
- * to a write tool is refused even if the client somehow names it, so the
- * read-only guarantee holds at dispatch, not just in the advertised tool list.
- */
-declare const callTool: (client: LunoraClient, name: string, input: Record<string, unknown>, allowWrites?: 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.&lt;name>` / `AGENT_&lt;NAME>` binding). */
-  name: string;
-  /** Override the model-facing tool name (default `agent_&lt;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.
+ * 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.
  */
-declare const AGENT_RUN_INPUT_SCHEMA: ToolInputSchema;
+type C as CallAgentToolOptions, type F as FunctionMcpServerOptions, type L as LunoraMcpServerOptions,
 /**
- * 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`.
+ * `@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).
  *
- * 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_&lt;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 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. This 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.
-   */
-  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.
+ * 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.
  *
- * 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.
+ * 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.
  */
-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>;
-/** A Web-Standard fetch handler: takes a `Request`, returns the MCP `Response`. */
-type McpFetchHandler = (request: Request) => Promise<Response>;
-/**
- * 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}.
- */
-declare const createMcpFetchHandler: (options: LunoraMcpServerOptions) => McpFetchHandler;
-/** A tool handler: receives the call's `arguments` bag, returns an MCP tool result. */
-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;
-}
-/** x402 settlement vocabulary shared by every paid tool (network, recipient, facilitator); price is per-tool. */
-type PaidMcpChargeConfig = Omit<X402ChargeConfig, "price">;
-/** Config for `createPaidMcpServer`. */
-interface PaidMcpServerConfig {
-  /** The worker-level x402 charge config; each paid tool supplies only its own `price`. */
-  charge: PaidMcpChargeConfig;
-  /** Name/version advertised in the MCP `initialize` handshake. Defaults to `lunora-paid-mcp`. */
-  serverInfo?: {
-    name: string;
-    version: string;
-  };
-}
-/** A paid MCP server: register free/paid tools, then serve over Streamable HTTP. */
-interface PaidMcpServer {
-  /** The Streamable-HTTP fetch handler; gates each paid `tools/call` behind x402. */
-  readonly fetchHandler: McpFetchHandler;
-  /** 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 };
+type M as McpAgentExposure, b as agentToolDefinitions, c as callAgentTool, d as createFunctionMcpServer, e as createLunoraMcpServer, p as parseAgentsEnv } from "./packem_shared/function-server.d-BoX-fd2B.mjs";
+export { type AuthedMcpFetchHandlerOptions, type AuthedMcpServerOptions, type McpAccessTokenClaims, type McpAuthProtect, type McpFetchHandlerOptions, OBSERVABILITY_TOOL_DEFINITIONS, type PaidMcpChargeConfig, type PaidMcpExecutionContext, type PaidMcpFetchHandler, type PaidMcpServer, type PaidMcpServerConfig, READ_ONLY_TOOL_DEFINITIONS, type RegisterPaidToolOptions, type RegisterToolOptions, type ToolHandler, WRITE_TOOL_DEFINITIONS, callTool, createAuthedMcpFetchHandler, createMcpFetchHandler, createPaidMcpServer, mcpTokenScopes, toolDefinitions } from "./worker/index.mjs";
+export { type M as McpServerInfo, type a as McpTool, type T as ToolDefinition, type b as ToolInputSchema, type c as ToolOutputSchema, type d as ToolResult, e as createToolServer } from "./packem_shared/compose.d-DiPnHeQv.mjs";
+export { LOCAL_SERVER_NAME, type LocalDeployment, type LocalDeploymentSource, type LocalMcpServerOptions, NO_DEPLOYMENT_MESSAGE, connectFunctionStdio, connectLocalStdio, connectStdio, createLocalMcpServer, localTools } from "./node/index.mjs";
+export { D as DEFAULT_MAX_REQUEST_BYTES, type M as McpFetchHandler, type S as ServeStatelessOptions, s as serveStateless } from "./packem_shared/serve-stateless.d-DD5arqFx.mjs";
+import '@lunora/client/admin';
+import '@modelcontextprotocol/sdk/server/index.js';
+import '@lunora/client';
+import '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';