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

package/LICENSE.md

@@ -103,3 +103,129 @@ Unless required by applicable law or agreed to in writing, software distributed
 under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
 CONDITIONS OF ANY KIND, either express or implied. See the License for the
 specific language governing permissions and limitations under the License.
+
+<!-- DEPENDENCIES -->
+<!-- /DEPENDENCIES -->
+
+<!-- TYPE_DEPENDENCIES -->
+
+# Licenses of bundled types
+The published @lunora/mcp artifact additionally contains code with the following licenses:
+FSL-1.1-Apache-2.0
+
+# Bundled types:
+## @lunora/x402
+License: FSL-1.1-Apache-2.0
+By: Daniel Bannert
+Repository: git+https://github.com/anolilab/lunora.git
+
+> # Functional Source License, Version 1.1, Apache 2.0 Future License
+>
+> ## Abbreviation
+>
+> FSL-1.1-Apache-2.0
+>
+> ## Notice
+>
+> Copyright 2026 anolilab and contributors
+>
+> ## Terms and Conditions
+>
+> ### Licensor ("We")
+>
+> The party offering the Software under these Terms and Conditions.
+>
+> ### The Software
+>
+> The "Software" is each version of the software that we make available under
+> these Terms and Conditions, as indicated by our inclusion of these Terms and
+> Conditions with the Software.
+>
+> ### License Grant
+>
+> Subject to your compliance with this License Grant and the Patents,
+> Redistribution and Trademark clauses below, we hereby grant you the right to
+> use, copy, modify, create derivative works, publicly perform, publicly display
+> and redistribute the Software for any Permitted Purpose identified below.
+>
+> ### Permitted Purpose
+>
+> A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+> means making the Software available to others in a commercial product or service
+> that:
+>
+> 1. substitutes for the Software;
+>
+> 2. substitutes for any other product or service we offer using the Software that
+>    exists as of the date we make the Software available; or
+>
+> 3. offers the same or substantially similar functionality as the Software.
+>
+> Permitted Purposes specifically include using the Software:
+>
+> 1. for your internal use and access;
+>
+> 2. for non-commercial education;
+>
+> 3. for non-commercial research; and
+>
+> 4. in connection with professional services that you provide to a licensee using
+>    the Software in accordance with these Terms and Conditions.
+>
+> ### Patents
+>
+> To the extent your use for a Permitted Purpose would necessarily infringe our
+> patents, the license grant above includes a license under our patents. If you
+> make a claim against any party that the Software infringes or contributes to the
+> infringement of any patent, then your patent license to the Software ends
+> immediately.
+>
+> ### Redistribution
+>
+> The Terms and Conditions apply to all copies, modifications and derivatives of
+> the Software.
+>
+> If you redistribute any copies, modifications or derivatives of the Software,
+> you must include a copy of or a link to these Terms and Conditions and not
+> remove any copyright notices provided in or with the Software.
+>
+> ### Disclaimer
+>
+> THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+> IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+> PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+>
+> IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+> SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES, EVEN
+> IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+>
+> ### Trademarks
+>
+> Except for displaying the License Details and identifying us as the origin of
+> the Software, you have no right under these Terms and Conditions to use our
+> trademarks, trade names, service marks or product names.
+>
+> ## Grant of Future License
+>
+> We hereby irrevocably grant you an additional license to use the Software under
+> the Apache License, Version 2.0 that is effective on the second anniversary of
+> the date we make the Software available. On or after that date, you may use the
+> Software under the Apache License, Version 2.0, in which case the following will
+> apply:
+>
+> Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+> this file except in compliance with the License.
+>
+> You may obtain a copy of the License at
+>
+> http://www.apache.org/licenses/LICENSE-2.0
+>
+> Unless required by applicable law or agreed to in writing, software distributed
+> under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+> CONDITIONS OF ANY KIND, either express or implied. See the License for the
+> specific language governing permissions and limitations under the License.
+>
+> <!-- DEPENDENCIES -->
+> <!-- /DEPENDENCIES -->
+
+<!-- /TYPE_DEPENDENCIES -->

package/README.md

@@ -34,20 +34,32 @@
 
 ---
 
-A [Model Context Protocol](https://modelcontextprotocol.io) server that exposes a deployed Lunora app to AI agents. It registers tools for introspecting a deployment (`lunora_list_functions`, `lunora_list_tables`, `lunora_get_function_schema`) and invoking its functions (`lunora_run_query`, `lunora_run_mutation`, `lunora_run_action`), each backed by `@lunora/client` over HTTP RPC.
+[Model Context Protocol](https://modelcontextprotocol.io) servers for Lunora, in two flavours:
+
+- **Deployment** (the main entry) — exposes a deployed Lunora app to AI agents: introspection tools (`lunora_list_functions`, `lunora_list_tables`, `lunora_get_function_schema`) and invocation tools (`lunora_run_query`, `lunora_run_mutation`, `lunora_run_action`), each backed by `@lunora/client` over HTTP RPC. Needs an admin token.
+- **Documentation** ([`@lunora/mcp/docs`](#documentation-server)) — exposes the framework's _docs_ so an agent writing Lunora code can look up the real API instead of guessing. Credential-free, and safe to host publicly; Lunora runs it at `https://lunora.sh/mcp`.
+
+Most users never install this package directly — `lunora mcp install` wires both servers into their editor. See [`@lunora/cli`](https://www.npmjs.com/package/@lunora/cli).
 
 Part of the [Lunora](https://github.com/anolilab/lunora) framework — a type-safe, real-time backend on Cloudflare Workers + Durable Objects with a Vite-first DX.
 
 ## Tools
 
-| Tool                         | Description                                                                                                    |
-| ---------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| `lunora_list_functions`      | List the deployment's public functions (queries, mutations, actions) with their kinds.                         |
-| `lunora_list_tables`         | List the deployment's `.global()` tables with their row counts.                                                |
-| `lunora_get_function_schema` | Return a function's argument descriptors and kind by path, so a caller can construct a valid arguments object. |
-| `lunora_run_query`           | Run a query and return its result. Read-only.                                                                  |
-| `lunora_run_mutation`        | Run a mutation and return its result. Writes data — use with care.                                             |
-| `lunora_run_action`          | Run an action and return its result. May call external services.                                               |
+| Tool                          | Description                                                                                                                                                   |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `lunora_list_functions`       | List the deployment's public functions (queries, mutations, actions) with their kinds.                                                                        |
+| `lunora_list_tables`          | List the deployment's `.global()` tables with their row counts.                                                                                               |
+| `lunora_get_function_schema`  | Return a function's argument descriptors and kind by path, so a caller can construct a valid arguments object.                                                |
+| `lunora_run_query`            | Run a query and return its result. Read-only.                                                                                                                 |
+| `lunora_run_mutation`         | Run a mutation and return its result. Writes data — use with care.                                                                                            |
+| `lunora_run_action`           | Run an action and return its result. May call external services.                                                                                              |
+| `lunora_get_logs`             | Read the deployment's recent log entries (newest first). Requires an admin token.                                                                             |
+| `lunora_get_issues`           | List errors grouped into Issues by fingerprint, with counts and triage status. Requires an admin token.                                                       |
+| `lunora_get_advisories`       | List the deployment's schema/query advisories. Requires an admin token.                                                                                       |
+| `lunora_get_query_insights`   | Per-statement execution counts and latency over a recent window. Requires an admin token.                                                                     |
+| `lunora_get_migration_status` | Which migrations are applied and which are pending. Requires an admin token.                                                                                  |
+| `agent_<name>`                | Start a durable [`@lunora/agent`](https://www.npmjs.com/package/@lunora/agent) run and await its answer. One tool per exposed agent. Requires agents enabled. |
+| `lunora_agent_status`         | Poll a running agent by `threadKey` and return its answer once finished. Requires agents enabled.                                                             |
 
 ### Recommended agent flow
 
@@ -58,6 +70,25 @@ Part of the [Lunora](https://github.com/anolilab/lunora) framework — a type-sa
                                   → call the function with a well-formed arguments object
 ```
 
+### Observability tools (privileged)
+
+The five `lunora_get_*` observability tools are read-only, but they surface the
+deployment's **operational data** — log lines, request metadata, and grouped
+error messages, all of which may contain user data, and all of which land in the
+model's context (and therefore at its provider). They are exposed **only when an
+admin token resolved**: without one they are omitted from `ListTools` entirely
+and refused at dispatch, the same omit-don't-refuse rule the write tools use.
+They are independent of `--allow-writes`, which is about changing data, not
+reading operational data.
+
+They return `structuredContent` alongside the usual text block, described by each
+tool's `outputSchema` (MCP revision `2025-06-18` and later; older clients keep
+reading the text block). All but `lunora_get_migration_status` take a `limit`
+clamped server-side; migration status takes only `shardKey` and returns every
+migration, because truncating that list would hide the pending one. Each also
+takes an optional `shardKey` — on a `.shardBy()`-partitioned deployment these
+reads are **per-shard**, not deployment-wide.
+
 `lunora_get_function_schema` returns a JSON object with three fields:
 
 - `path` — the function path (e.g. `"messages:send"`)
@@ -70,6 +101,8 @@ Part of the [Lunora](https://github.com/anolilab/lunora) framework — a type-sa
 npm install @lunora/mcp
 ```
 
+Paid MCP tools (`createPaidMcpServer`) additionally need the optional peer [`@lunora/x402`](https://www.npmjs.com/package/@lunora/x402); it is loaded lazily, so installs that never charge for a tool don't pay for its dependency tree.
+
 ```sh
 yarn add @lunora/mcp
 ```
@@ -105,6 +138,102 @@ const server = createLunoraMcpServer({ url: "https://app.example.workers.dev", t
 await server.connect(myTransport);
 ```
 
+## Expose an agent
+
+A deployment's durable [`@lunora/agent`](https://www.npmjs.com/package/@lunora/agent) agents can be fronted as MCP tools. This is **opt-in and fail-closed**, mirroring `allowWrites`: starting an agent run is a side effect, so the agent tools are omitted from the advertised list _and_ refused at dispatch unless you explicitly enable them. `@lunora/mcp` takes no dependency on `@lunora/agent` — it reaches the agent's public `agents:agentRun` mutation over RPC like any other function.
+
+Enable it with two env vars (or the matching `createLunoraMcpServer` options):
+
+- `LUNORA_MCP_ALLOW_AGENTS` — set to `1`/`true`/`yes`/`on` to expose the agent tools. Default: agents disabled.
+- `LUNORA_MCP_AGENTS` — a `;`-separated list of `name:description` pairs selecting which agents to expose, e.g. `"support:Support questions;billing:Billing help"`.
+- `LUNORA_MCP_AGENT_TIMEOUT_MS` (optional) — wall-clock budget a single `agent_<name>` call awaits before returning a pending result to poll.
+
+```jsonc
+{
+    "mcpServers": {
+        "lunora": {
+            "command": "lunora-mcp",
+            "env": {
+                "LUNORA_URL": "https://app.example.workers.dev",
+                "LUNORA_ADMIN_TOKEN": "...",
+                "LUNORA_MCP_ALLOW_AGENTS": "1",
+                "LUNORA_MCP_AGENTS": "support:Support questions;billing:Billing help",
+            },
+        },
+    },
+}
+```
+
+Each exposed agent gets an `agent_<name>` tool taking `prompt` (required), an optional `threadKey` (reuse to continue a conversation; omit to start a new thread), and an optional `title`. The tool starts a durable run and awaits it up to the timeout budget; if the run outlasts the budget it returns a pending result whose `threadKey` you feed to the generic `lunora_agent_status` tool to poll for the final answer.
+
+Runs are **owner-scoped** to the identity the configured token resolves to. Grant a **least-privilege** token mapped to a bot identity so an agent's threads stay isolated per deployment — never the admin token.
+
+## Resources and annotations
+
+Both servers implement MCP **tools**; the documentation server additionally exposes every page as an MCP **resource** (`lunora-docs:/docs/…`, `text/markdown`), so a client can enumerate and attach a page directly instead of the model having to guess a search query first.
+
+Every tool carries **annotations** — `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint` and a human-facing `title` — so a client can badge the read-only surface and confirm before a write. They are hints; the actual guarantee is still made at dispatch, where a write tool is refused unless writes are enabled.
+
+## Documentation server
+
+`@lunora/mcp/docs` is a second, independent surface: it serves **published documentation**, not a deployment. No credentials, no writes, no `@lunora/client` — and no Node built-ins, so it runs unchanged on Workers, Netlify/Vercel functions, Deno, and Bun.
+
+| Tool                 | Description                                                           |
+| -------------------- | --------------------------------------------------------------------- |
+| `lunora_search_docs` | Search the docs; returns matching pages and sections with their URLs. |
+| `lunora_get_doc`     | Return one page in full, as Markdown.                                 |
+| `lunora_list_docs`   | List every page with its title and description.                       |
+
+The tools read a `DocsIndex`, which has two implementations. A docs site wires up its own in-process index and mounts the server as an HTTP route:
+
+```ts
+import { createDocsMcpFetchHandler } from "@lunora/mcp/docs";
+
+const handle = createDocsMcpFetchHandler({ index: myDocsIndex });
+
+// e.g. in a Worker: export default { fetch: handle }
+```
+
+Anything else reads a published site over HTTP:
+
+```ts
+import { createDocsMcpServer, createRemoteDocsIndex } from "@lunora/mcp/docs";
+
+const server = createDocsMcpServer({ index: createRemoteDocsIndex({ baseUrl: "https://lunora.sh" }) });
+```
+
+Point a client at the hosted endpoint with no install at all:
+
+```sh
+claude mcp add --transport http lunora-docs https://lunora.sh/mcp
+```
+
+### Hosting it safely
+
+`createDocsMcpFetchHandler` screens each request before the transport sees it, because this surface is meant to be public and unauthenticated:
+
+- **Bodies are capped** (128 KiB by default; override with `maxRequestBytes`).
+- **JSON-RPC batches are refused.** The stateless transport buffers a whole batch's replies into one response, so a single small request carrying thousands of `tools/call` messages would amplify into hundreds of megabytes out, with no session to rate-limit against. A docs client gains nothing from batching.
+- `lunora_search_docs` bounds its `query`, and `lunora_list_docs` caps how many pages it serialises.
+
+## Local development server
+
+`createLocalMcpServer` / `connectLocalStdio` compose the docs tools, the deployment tools, and any extra tools a host supplies into one stdio server — this is what `lunora mcp serve` runs.
+
+```ts
+import { connectLocalStdio } from "@lunora/mcp";
+
+await connectLocalStdio({
+    // Consulted per tool call, so a dev server started later is picked up
+    // without reconnecting.
+    deployment: () => readMyDevServer(),
+    docs: { baseUrl: "https://lunora.sh" },
+    extraTools: myLocalTools,
+});
+```
+
+The deployment tools are advertised even when the resolver currently returns nothing — MCP clients cache the tool list, so a surface that appeared only when the dev server happened to be up would stay invisible for the rest of the session. Calling one with nothing running returns an actionable error instead.
+
 > This README covers the basics. For the full API, options, and guides, see the **[documentation](https://lunora.sh/docs)**.
 
 ## Related
@@ -112,6 +241,7 @@ await server.connect(myTransport);
 - [`@lunora/client`](https://www.npmjs.com/package/@lunora/client) — the HTTP RPC client backing every tool.
 - [`@lunora/cli`](https://www.npmjs.com/package/@lunora/cli) — deploy the app the server introspects and invokes.
 - [`@lunora/server`](https://www.npmjs.com/package/@lunora/server) — defines the queries, mutations, and actions the tools call.
+- [`@lunora/agent`](https://www.npmjs.com/package/@lunora/agent) — the durable agents the `agent_<name>` tools front over RPC.
 
 ## Supported Node.js Versions
 

package/dist/bin.mjs

@@ -1,36 +1,4 @@
 #!/usr/bin/env node
-import { connectStdio } from './packem_shared/connectStdio-C_mvQBs2.mjs';
-
-class BinError extends Error {
-  code;
-  constructor(message, code) {
-    super(message);
-    this.name = "BinError";
-    this.code = code;
-  }
-}
-const runBin = async (environment, dependencies = {}) => {
-  const connect = dependencies.connect ?? connectStdio;
-  const writeError = dependencies.writeError ?? ((message) => {
-    process.stderr.write(message);
-  });
-  const url = environment.LUNORA_URL;
-  if (url === void 0 || url.length === 0) {
-    writeError("lunora-mcp: LUNORA_URL environment variable is required\n");
-    throw new BinError("LUNORA_URL environment variable is required", 1);
-  }
-  try {
-    await connect({ token: environment.LUNORA_ADMIN_TOKEN, url });
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    writeError(`lunora-mcp: failed to start — ${message}
-`);
-    throw new BinError(`failed to start — ${message}`, 1);
-  }
-};
-
-try {
-  await runBin(process.env);
-} catch (error) {
-  process.exit(error instanceof BinError ? error.code : 1);
-}
+import{parseAgentsEnv as A}from"./packem_shared/AGENT_RUN_INPUT_SCHEMA-DRSY74ed.mjs";import{connectStdio as L}from"./packem_shared/connectStdio-BCeI0Wqu.mjs";const N=new Set(["1","on","true","yes"]),_=r=>r!==void 0&&N.has(r.trim().toLowerCase());class i extends Error{code;constructor(o,e){super(o),this.name="BinError",this.code=e}}const w=async(r,o={})=>{const e=o.connect??L,a=o.writeError??(t=>{process.stderr.write(t)}),s=r.LUNORA_URL;if(s===void 0||s.length===0)throw a(`lunora-mcp: LUNORA_URL environment variable is required
+`),new i("LUNORA_URL environment variable is required",1);const n=Number(r.LUNORA_MCP_AGENT_TIMEOUT_MS),c=Number.isFinite(n)&&n>0?n:void 0;try{await e({agents:A(r.LUNORA_MCP_AGENTS),allowAgents:_(r.LUNORA_MCP_ALLOW_AGENTS),allowWrites:_(r.LUNORA_MCP_ALLOW_WRITES),token:r.LUNORA_ADMIN_TOKEN,url:s,...c===void 0?{}:{agentMaxWaitMs:c}})}catch(t){const E=t instanceof Error?t.message:String(t);throw a(`lunora-mcp: failed to start — ${E}
+`),new i(`failed to start — ${E}`,1)}};try{await w(process.env)}catch(r){process.exit(r instanceof i?r.code:1)}

package/dist/docs/index.d.mts

@@ -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.mjs";
+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.mjs";
+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 };