@lunora/mcp 1.0.0-alpha.7 → 1.0.0-alpha.71

package/dist/docs/index.d.ts

@@ -0,0 +1,250 @@
+import { M as McpResourceProvider, a as McpFetchHandler, T as ToolDefinition, b as McpTool } from "../packem_shared/serve-stateless.d-B_q8q39X.js";
+export type {
+/**
+ * `@lunora/mcp/docs` — the documentation tool surface: `lunora_search_docs`,
+ * `lunora_get_doc`, and `lunora_list_docs`.
+ *
+ * Where the package's main entry exposes a deployment to an agent (its
+ * functions and data, behind an admin token), this entry exposes the
+ * framework's documentation, so an agent writing Lunora code can look up the
+ * real API instead of inventing one. It reads published docs only — no
+ * credentials, no writes — so a server built from it is safe to host
+ * unauthenticated.
+ *
+ * Two backends implement the same `DocsIndex` contract: a docs site wires up
+ * its own in-process search index, while anything else (the CLI's
+ * `lunora mcp serve`, a script) uses `createRemoteDocsIndex` to read a
+ * published site over HTTP.
+ *
+ * This entry is free of Node built-ins and of `@lunora/client`, so it runs on
+ * Workers, Netlify/Vercel functions, Deno, and Bun unchanged —
+ * `scripts/check-dist-production.js` asserts that against the emitted chunks.
+ *
+ * Only the documentation surface lives here. The generic composition primitive
+ * (`createToolServer`) is exported from the package root, so a consumer using
+ * both entries gets one implementation rather than two copies.
+ */
+c as McpResourceSummary,
+/**
+ * `@lunora/mcp/docs` — the documentation tool surface: `lunora_search_docs`,
+ * `lunora_get_doc`, and `lunora_list_docs`.
+ *
+ * Where the package's main entry exposes a deployment to an agent (its
+ * functions and data, behind an admin token), this entry exposes the
+ * framework's documentation, so an agent writing Lunora code can look up the
+ * real API instead of inventing one. It reads published docs only — no
+ * credentials, no writes — so a server built from it is safe to host
+ * unauthenticated.
+ *
+ * Two backends implement the same `DocsIndex` contract: a docs site wires up
+ * its own in-process search index, while anything else (the CLI's
+ * `lunora mcp serve`, a script) uses `createRemoteDocsIndex` to read a
+ * published site over HTTP.
+ *
+ * This entry is free of Node built-ins and of `@lunora/client`, so it runs on
+ * Workers, Netlify/Vercel functions, Deno, and Bun unchanged —
+ * `scripts/check-dist-production.js` asserts that against the emitted chunks.
+ *
+ * Only the documentation surface lives here. The generic composition primitive
+ * (`createToolServer`) is exported from the package root, so a consumer using
+ * both entries gets one implementation rather than two copies.
+ */
+d as McpServerInfo, e as ToolInputSchema, f as ToolResult } from "../packem_shared/serve-stateless.d-B_q8q39X.js";
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
+/**
+ * The documentation source the docs tools read.
+ *
+ * The tools are written against this interface rather than against a concrete
+ * search engine so the same tool surface can be backed two ways: in-process by
+ * the docs site itself (fumadocs `source` + its Orama index), or over HTTP by a
+ * remote reader that only has the published site (see `./remote-index`). Both
+ * expose the identical tool names and result shapes to the model.
+ */
+/** One hit from {@link DocsIndex.search}. */
+interface DocsSearchHit {
+  /** The matched text, when the backend returns one (headings/paragraph hits). */
+  excerpt?: string;
+  /** Breadcrumb trail to the matched section, e.g. `"Guides › Sharding"`. */
+  section?: string;
+  /** Page title. */
+  title: string;
+  /** Site-relative page URL, e.g. `"/docs/sharding"` — feed this to `lunora_get_doc`. */
+  url: string;
+}
+/** A page listed by {@link DocsIndex.listPages}. */
+interface DocsPageSummary {
+  description?: string;
+  title: string;
+  /** Site-relative page URL, e.g. `"/docs/sharding"`. */
+  url: string;
+}
+/** A page's full text, as returned by {@link DocsIndex.getPage}. */
+interface DocsPage extends DocsPageSummary {
+  /** The page body as Markdown. */
+  content: string;
+}
+interface DocsIndex {
+  /**
+   * The page at a site-relative URL, or `undefined` when there is no such
+   * page. Implementations should accept the URL exactly as it appears in a
+   * search hit.
+   */
+  getPage: (url: string) => Promise<DocsPage | undefined>;
+  /** Every indexed page, for a model that wants to browse rather than search. */
+  listPages: () => Promise<ReadonlyArray<DocsPageSummary>>;
+  /**
+   * Full-text search, returning whatever the backend found.
+   *
+   * Deliberately unbounded: the tool layer decides how many hits reach the
+   * model's context, so there is one truncation site rather than one per
+   * backend plus one in the tool.
+   */
+  search: (query: string) => Promise<ReadonlyArray<DocsSearchHit>>;
+}
+/** The subset of a fumadocs `SortedResult` these tools consume. */
+interface FumadocsSearchResult {
+  breadcrumbs?: string[];
+  content?: string;
+  type?: string;
+  url?: string;
+}
+/** Map every result, skipping any entry {@link toDocsSearchHit} rejects. */
+declare const toDocsSearchHits: (results: ReadonlyArray<unknown>) => DocsSearchHit[];
+/** The public docs site the remote index reads when no base URL is configured. */
+declare const DEFAULT_DOCS_BASE_URL = "https://lunora.sh";
+interface RemoteDocsIndexOptions {
+  /** Origin of the docs site, e.g. `"https://lunora.sh"`. Defaults to {@link DEFAULT_DOCS_BASE_URL}. */
+  baseUrl?: string;
+  /** `fetch` implementation; defaults to the ambient global. */
+  fetch?: typeof fetch;
+  /** Per-request deadline in ms. Defaults to {@link DEFAULT_REQUEST_TIMEOUT_MS}. */
+  timeoutMs?: number;
+}
+declare const createRemoteDocsIndex: (options?: RemoteDocsIndexOptions) => DocsIndex;
+/** URI scheme identifying a Lunora documentation page. */
+declare const DOCS_URI_SCHEME = "lunora-docs:";
+/** `"/docs/sharding"` → `"lunora-docs:/docs/sharding"`. */
+declare const toDocsUri: (url: string) => string;
+/** The inverse, or `undefined` for a uri this provider does not own. */
+declare const fromDocsUri: (uri: string) => string | undefined;
+/** Expose `index`'s pages as listable, readable resources. */
+declare const docsResources: (index: DocsIndex) => McpResourceProvider;
+/** Server identity advertised in the MCP `initialize` handshake. */
+declare const DOCS_SERVER_NAME = "lunora-docs";
+interface DocsMcpServerOptions {
+  /** The documentation source the tools read. */
+  index: DocsIndex;
+  /** Largest accepted request body. Defaults to {@link DEFAULT_MAX_REQUEST_BYTES}. */
+  maxRequestBytes?: number;
+  /**
+   * Version reported in the handshake. Defaults to `"0.0.0"` — a docs site
+   * bundles this code rather than installing it, so it, not the package, is
+   * the thing whose version a client would want to see.
+   */
+  version?: string;
+}
+/**
+ * Build a transport-agnostic MCP server exposing the documentation tools.
+ * Connect it yourself, or use {@link createDocsMcpFetchHandler} for the remote
+ * HTTP case.
+ */
+declare const createDocsMcpServer: (options: DocsMcpServerOptions) => Server;
+/**
+ * Build a stateless Streamable-HTTP fetch handler serving the documentation
+ * tools — the `Request` → `Response` function a docs site mounts at `/mcp`.
+ *
+ * A fresh server per request keeps the handler safe on platforms that fan
+ * requests across isolates, where nothing may be assumed to persist between
+ * them.
+ */
+declare const createDocsMcpFetchHandler: (options: DocsMcpServerOptions) => McpFetchHandler;
+/** Hits returned when the caller doesn't ask for a specific number. */
+declare const DEFAULT_SEARCH_LIMIT = 10;
+/**
+ * Ceiling on hits per call. Search results are pasted into the model's context
+ * verbatim, so an unbounded `limit` is a context-exhaustion foot-gun rather
+ * than a useful option.
+ */
+declare const MAX_SEARCH_LIMIT = 50;
+/** The advertised surface, in the order a caller should reach for it. */
+declare const DOCS_TOOL_DEFINITIONS: ReadonlyArray<ToolDefinition>;
+/**
+ * Normalize whatever a model passes as a page URL into the site-relative form
+ * an index stores.
+ *
+ * Models copy URLs from anywhere — a search hit (`/docs/sharding`), the browser
+ * (`https://lunora.sh/docs/sharding`), or their own memory of the slug
+ * (`sharding`, `docs/sharding`). All four are the same page, and failing three
+ * of them would push the model into a guess-and-retry loop, so resolve them to
+ * one form. A trailing slash is dropped for the same reason.
+ *
+ * A `..` segment is REJECTED rather than resolved. The remote backend appends
+ * this path to `/llms.mdx`, so `../../api/search` would walk back out of the
+ * documentation tree and pull an unrelated path on the docs origin into the
+ * model's context — harmless against a public site, less so against the
+ * internal host a self-hosted `--docs-url` may point at.
+ */
+declare const normalizeDocUrl: (raw: string) => string;
+/**
+ * The documentation surface, bound to `index`.
+ *
+ * Each tool carries its own handler rather than routing through a shared
+ * `switch`: `createToolServer` already dispatches by name, so a second switch
+ * here would be a duplicate table with an unreachable `default`. It also owns
+ * the throw-to-`isError` conversion, so these handlers signal argument problems
+ * by throwing and return `isError` only for the expected misses a model should
+ * read and act on.
+ */
+declare const docsTools: (index: DocsIndex) => ReadonlyArray<McpTool>;
+export { DEFAULT_DOCS_BASE_URL, DEFAULT_SEARCH_LIMIT, DOCS_SERVER_NAME, DOCS_TOOL_DEFINITIONS, DOCS_URI_SCHEME, type DocsIndex, type DocsMcpServerOptions, type DocsPage, type DocsPageSummary, type DocsSearchHit, type FumadocsSearchResult, MAX_SEARCH_LIMIT, type McpFetchHandler,
+/**
+ * `@lunora/mcp/docs` — the documentation tool surface: `lunora_search_docs`,
+ * `lunora_get_doc`, and `lunora_list_docs`.
+ *
+ * Where the package's main entry exposes a deployment to an agent (its
+ * functions and data, behind an admin token), this entry exposes the
+ * framework's documentation, so an agent writing Lunora code can look up the
+ * real API instead of inventing one. It reads published docs only — no
+ * credentials, no writes — so a server built from it is safe to host
+ * unauthenticated.
+ *
+ * Two backends implement the same `DocsIndex` contract: a docs site wires up
+ * its own in-process search index, while anything else (the CLI's
+ * `lunora mcp serve`, a script) uses `createRemoteDocsIndex` to read a
+ * published site over HTTP.
+ *
+ * This entry is free of Node built-ins and of `@lunora/client`, so it runs on
+ * Workers, Netlify/Vercel functions, Deno, and Bun unchanged —
+ * `scripts/check-dist-production.js` asserts that against the emitted chunks.
+ *
+ * Only the documentation surface lives here. The generic composition primitive
+ * (`createToolServer`) is exported from the package root, so a consumer using
+ * both entries gets one implementation rather than two copies.
+ */
+type McpResourceProvider,
+/**
+ * `@lunora/mcp/docs` — the documentation tool surface: `lunora_search_docs`,
+ * `lunora_get_doc`, and `lunora_list_docs`.
+ *
+ * Where the package's main entry exposes a deployment to an agent (its
+ * functions and data, behind an admin token), this entry exposes the
+ * framework's documentation, so an agent writing Lunora code can look up the
+ * real API instead of inventing one. It reads published docs only — no
+ * credentials, no writes — so a server built from it is safe to host
+ * unauthenticated.
+ *
+ * Two backends implement the same `DocsIndex` contract: a docs site wires up
+ * its own in-process search index, while anything else (the CLI's
+ * `lunora mcp serve`, a script) uses `createRemoteDocsIndex` to read a
+ * published site over HTTP.
+ *
+ * This entry is free of Node built-ins and of `@lunora/client`, so it runs on
+ * Workers, Netlify/Vercel functions, Deno, and Bun unchanged —
+ * `scripts/check-dist-production.js` asserts that against the emitted chunks.
+ *
+ * Only the documentation surface lives here. The generic composition primitive
+ * (`createToolServer`) is exported from the package root, so a consumer using
+ * both entries gets one implementation rather than two copies.
+ */
+type McpTool, type RemoteDocsIndexOptions, type ToolDefinition, createDocsMcpFetchHandler, createDocsMcpServer, createRemoteDocsIndex, docsResources, docsTools, fromDocsUri, normalizeDocUrl, toDocsSearchHits, toDocsUri };

package/dist/docs/index.mjs

@@ -0,0 +1 @@
+import{toDocsSearchHits as e}from"../packem_shared/toDocsSearchHits-CBLmtWXt.mjs";import{DEFAULT_DOCS_BASE_URL as D,createRemoteDocsIndex as t}from"../packem_shared/DEFAULT_DOCS_BASE_URL-CZ3fVsSc.mjs";import{DOCS_URI_SCHEME as s,docsResources as S,fromDocsUri as E,toDocsUri as I}from"../packem_shared/DOCS_URI_SCHEME-CFANc3vr.mjs";import{DOCS_SERVER_NAME as R,createDocsMcpFetchHandler as p,createDocsMcpServer as A}from"../packem_shared/DOCS_SERVER_NAME-BWzPxJyZ.mjs";import{DEFAULT_SEARCH_LIMIT as M,DOCS_TOOL_DEFINITIONS as O,MAX_SEARCH_LIMIT as T,docsTools as U,normalizeDocUrl as a}from"../packem_shared/DEFAULT_SEARCH_LIMIT-DWPt0hvR.mjs";export{D as DEFAULT_DOCS_BASE_URL,M as DEFAULT_SEARCH_LIMIT,R as DOCS_SERVER_NAME,O as DOCS_TOOL_DEFINITIONS,s as DOCS_URI_SCHEME,T as MAX_SEARCH_LIMIT,p as createDocsMcpFetchHandler,A as createDocsMcpServer,t as createRemoteDocsIndex,S as docsResources,U as docsTools,E as fromDocsUri,a as normalizeDocUrl,e as toDocsSearchHits,I as toDocsUri};

package/dist/index.d.mts

@@ -1,30 +1,371 @@
 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-B_q8q39X.mjs";
+export { type d as McpServerInfo, g as createToolServer, s as serveStateless } from "./packem_shared/serve-stateless.d-B_q8q39X.mjs";
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+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>;
+/**
+ * The tools this server advertises, in three tiers:
+ *
+ * - the read-only surface, always exposed;
+ * - the observability surface, exposed only when an admin token resolved —
+ * read-only, but it surfaces production logs and grouped errors, so an
+ * unauthenticated server must not even advertise that it exists;
+ * - the write surface, exposed only when `allowWrites` is set.
+ *
+ * Both gates OMIT rather than refuse: an AI agent can't invoke what it can't
+ * see. Dispatch re-checks both in {@link callTool}, so the guarantee does not
+ * depend on a client honouring the advertised list.
+ */
+declare const toolDefinitions: (allowWrites: boolean, hasAdminToken?: 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.
+ *
+ * `allowWrites` gates the mutation/action tools and `hasAdminToken` gates the
+ * observability tools: when either is false a call to the gated tool is refused
+ * even if the client somehow names it, so both guarantees hold at dispatch, not
+ * just in the advertised tool list.
+ */
+declare const callTool: (client: LunoraClient, name: string, input: Record<string, unknown>, allowWrites?: boolean, hasAdminToken?: 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 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.
+   *
+   * Its presence is also what gates the observability tools (logs, Issues,
+   * advisories, query insights, migration status): without a token they are
+   * omitted from `ListTools` and 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>;
-interface ToolInputSchema {
-  properties: Record<string, unknown>;
-  required?: ReadonlyArray<string>;
-  type: "object";
+/**
+ * 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 Lunora deployment the tools dispatch against. */
+interface LocalDeployment {
+  token?: string;
+  url: string;
 }
-interface ToolDefinition {
+/**
+ * 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 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;
 }
-interface ToolResult {
-  content: {
-    text: string;
-    type: "text";
-  }[];
-  isError?: boolean;
+/** 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 = X402ChargeSettings;
+/** 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;
 }
-declare const TOOL_DEFINITIONS: ReadonlyArray<ToolDefinition>;
-declare const callTool: (client: LunoraClient, name: string, input: Record<string, unknown>) => Promise<ToolResult>;
-export { type LunoraMcpServerOptions, TOOL_DEFINITIONS, type ToolDefinition, type ToolInputSchema, type ToolResult, callTool, connectStdio, createLunoraMcpServer };
+/**
+ * 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,
+/**
+ * `@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. 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`) whenever an admin token resolved — read-only,
+ * but privileged, so they are omitted entirely without one. 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. 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.
+ */
+type CallAgentToolOptions, LOCAL_SERVER_NAME, type LocalDeployment, type LocalDeploymentSource, type LocalMcpServerOptions, type LunoraMcpServerOptions,
+/**
+ * `@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. 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`) whenever an admin token resolved — read-only,
+ * but privileged, so they are omitted entirely without one. 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. 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.
+ */
+type McpAgentExposure, type McpFetchHandler, type McpTool, NO_DEPLOYMENT_MESSAGE, OBSERVABILITY_TOOL_DEFINITIONS, 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, connectLocalStdio, connectStdio, createLocalMcpServer, createLunoraMcpServer, createMcpFetchHandler, createPaidMcpServer, localTools, parseAgentsEnv, toolDefinitions };