@lunora/mcp 1.0.0-alpha.1 → 1.0.0-alpha.100

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