@lunora/mcp 1.0.0-alpha.3 → 1.0.0-alpha.30

package/LICENSE.md

@@ -103,3 +103,9 @@ 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 -->
+<!-- /TYPE_DEPENDENCIES -->

package/README.md

@@ -40,14 +40,16 @@ Part of the [Lunora](https://github.com/anolilab/lunora) framework — a type-sa
 
 ## 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.                                                                                              |
+| `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
 
@@ -105,6 +107,36 @@ 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.
+
 > This README covers the basics. For the full API, options, and guides, see the **[documentation](https://lunora.sh/docs)**.
 
 ## Related
@@ -112,6 +144,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,6 +1,9 @@
 #!/usr/bin/env node
-import { connectStdio } from './packem_shared/connectStdio-C_mvQBs2.mjs';
+import { parseAgentsEnv } from './packem_shared/AGENT_RUN_INPUT_SCHEMA-DWobae3P.mjs';
+import { connectStdio } from './packem_shared/connectStdio-bkJcaXYE.mjs';
 
+const ENABLED_ENV_VALUES = /* @__PURE__ */ new Set(["1", "on", "true", "yes"]);
+const isEnvEnabled = (value) => value !== void 0 && ENABLED_ENV_VALUES.has(value.trim().toLowerCase());
 class BinError extends Error {
   code;
   constructor(message, code) {
@@ -19,8 +22,17 @@ const runBin = async (environment, dependencies = {}) => {
     writeError("lunora-mcp: LUNORA_URL environment variable is required\n");
     throw new BinError("LUNORA_URL environment variable is required", 1);
   }
+  const rawTimeout = Number(environment.LUNORA_MCP_AGENT_TIMEOUT_MS);
+  const agentMaxWaitMs = Number.isFinite(rawTimeout) && rawTimeout > 0 ? rawTimeout : void 0;
   try {
-    await connect({ token: environment.LUNORA_ADMIN_TOKEN, url });
+    await connect({
+      agents: parseAgentsEnv(environment.LUNORA_MCP_AGENTS),
+      allowAgents: isEnvEnabled(environment.LUNORA_MCP_ALLOW_AGENTS),
+      allowWrites: isEnvEnabled(environment.LUNORA_MCP_ALLOW_WRITES),
+      token: environment.LUNORA_ADMIN_TOKEN,
+      url,
+      ...agentMaxWaitMs === void 0 ? {} : { agentMaxWaitMs }
+    });
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     writeError(`lunora-mcp: failed to start — ${message}

package/dist/index.d.mts

@@ -1,13 +1,17 @@
 import { LunoraClient } from '@lunora/client';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-interface LunoraMcpServerOptions {
-  client?: LunoraClient;
-  fetch?: typeof fetch;
-  token?: string;
-  url?: string;
-}
-declare const createLunoraMcpServer: (options: LunoraMcpServerOptions) => Server;
-declare const connectStdio: (options: LunoraMcpServerOptions) => Promise<Server>;
+import '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
+import { X402ChargeConfig, X402Price } from '@lunora/x402/charge';
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * 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.
+ *
+ * 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>;
@@ -18,6 +22,7 @@ interface ToolDefinition {
   inputSchema: ToolInputSchema;
   name: string;
 }
+/** The MCP `CallToolResult` shape this server returns. */
 interface ToolResult {
   content: {
     text: string;
@@ -25,6 +30,205 @@ interface ToolResult {
   }[];
   isError?: boolean;
 }
-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 };
+/** 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.
+ *
+ * `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.
+ */
+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_&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.
+ *
+ * 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>;
+/** 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 };

package/dist/index.d.ts

@@ -1,13 +1,17 @@
 import { LunoraClient } from '@lunora/client';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-interface LunoraMcpServerOptions {
-  client?: LunoraClient;
-  fetch?: typeof fetch;
-  token?: string;
-  url?: string;
-}
-declare const createLunoraMcpServer: (options: LunoraMcpServerOptions) => Server;
-declare const connectStdio: (options: LunoraMcpServerOptions) => Promise<Server>;
+import '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
+import { X402ChargeConfig, X402Price } from '@lunora/x402/charge';
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * 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.
+ *
+ * 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>;
@@ -18,6 +22,7 @@ interface ToolDefinition {
   inputSchema: ToolInputSchema;
   name: string;
 }
+/** The MCP `CallToolResult` shape this server returns. */
 interface ToolResult {
   content: {
     text: string;
@@ -25,6 +30,205 @@ interface ToolResult {
   }[];
   isError?: boolean;
 }
-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 };
+/** 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.
+ *
+ * `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.
+ */
+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_&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.
+ *
+ * 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>;
+/** 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 };

package/dist/index.mjs

@@ -1,2 +1,5 @@
-export { connectStdio, createLunoraMcpServer } from './packem_shared/connectStdio-C_mvQBs2.mjs';
-export { TOOL_DEFINITIONS, callTool } from './packem_shared/TOOL_DEFINITIONS-Dpiu38ji.mjs';
+export { AGENT_RUN_INPUT_SCHEMA, AGENT_STATUS_TOOL_NAME, agentToolDefinitions, callAgentTool, parseAgentsEnv } from './packem_shared/AGENT_RUN_INPUT_SCHEMA-DWobae3P.mjs';
+export { createMcpFetchHandler } from './packem_shared/createMcpFetchHandler-DfzBSLrm.mjs';
+export { createPaidMcpServer } from './packem_shared/createPaidMcpServer-b-qp_aEF.mjs';
+export { connectStdio, createLunoraMcpServer } from './packem_shared/connectStdio-bkJcaXYE.mjs';
+export { READ_ONLY_TOOL_DEFINITIONS, WRITE_TOOL_DEFINITIONS, callTool, toolDefinitions } from './packem_shared/READ_ONLY_TOOL_DEFINITIONS-CWb_wFd5.mjs';

package/dist/packem_shared/AGENT_RUN_INPUT_SCHEMA-DWobae3P.mjs

@@ -0,0 +1,168 @@
+const AGENT_RUN_PATH = "agents:agentRun";
+const AGENT_THREAD_PATH = "agents:agentThread";
+const AGENT_MESSAGES_PATH = "agents:agentMessages";
+const AGENT_STATUS_TOOL_NAME = "lunora_agent_status";
+const TERMINAL_STATUSES = /* @__PURE__ */ new Set(["cancelled", "error", "idle"]);
+const DEFAULT_MAX_WAIT_MS = 6e4;
+const DEFAULT_POLL_INTERVAL_MS = 600;
+const AGENT_RUN_INPUT_SCHEMA = {
+  properties: {
+    prompt: { description: "The task or message for the agent.", type: "string" },
+    threadKey: { description: "Reuse to continue a conversation; omit to start a new thread.", type: "string" },
+    title: { description: "Optional thread title (first run only).", type: "string" }
+  },
+  required: ["prompt"],
+  type: "object"
+};
+const AGENT_STATUS_INPUT_SCHEMA = {
+  properties: {
+    threadKey: { description: "The thread key returned by an agent tool call.", type: "string" }
+  },
+  required: ["threadKey"],
+  type: "object"
+};
+const agentToolName = (exposure) => exposure.toolName ?? `agent_${exposure.name}`;
+const parseAgentsEnv = (raw) => {
+  if (raw === void 0) {
+    return [];
+  }
+  const exposures = [];
+  for (const entry of raw.split(";")) {
+    const trimmed = entry.trim();
+    if (trimmed.length === 0) {
+      continue;
+    }
+    const separator = trimmed.indexOf(":");
+    if (separator <= 0) {
+      continue;
+    }
+    const name = trimmed.slice(0, separator).trim();
+    const description = trimmed.slice(separator + 1).trim();
+    if (name.length === 0 || description.length === 0) {
+      continue;
+    }
+    exposures.push({ description, name });
+  }
+  return exposures;
+};
+const agentToolDefinitions = (exposures, allowAgents) => {
+  if (allowAgents !== true || exposures.length === 0) {
+    return [];
+  }
+  const perAgent = exposures.map((exposure) => {
+    return {
+      description: `${exposure.description} Starts a durable agent run and returns its final answer.`,
+      inputSchema: AGENT_RUN_INPUT_SCHEMA,
+      name: agentToolName(exposure)
+    };
+  });
+  return [
+    ...perAgent,
+    {
+      description: "Check the status of a durable agent run (and its answer if finished) by its threadKey.",
+      inputSchema: AGENT_STATUS_INPUT_SCHEMA,
+      name: AGENT_STATUS_TOOL_NAME
+    }
+  ];
+};
+const isAgentToolName = (name, exposures) => name === AGENT_STATUS_TOOL_NAME || exposures.some((exposure) => agentToolName(exposure) === name);
+const freshThreadKey = () => `mcp-${crypto.randomUUID()}`;
+const reference = (path) => {
+  return { __lunoraRef: path };
+};
+const defaultWait = async (ms) => {
+  await new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+};
+const ok = (value) => {
+  return { content: [{ text: JSON.stringify(value, void 0, 2), type: "text" }] };
+};
+const fail = (text) => {
+  return { content: [{ text, type: "text" }], isError: true };
+};
+const readString = (input, key) => {
+  const value = input[key];
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+};
+const finalAnswer = (messages) => {
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const row = messages[index];
+    const toolCalls = row?.["toolCalls"];
+    const pending = Array.isArray(toolCalls) && toolCalls.length > 0;
+    if (row?.["role"] === "assistant" && !pending) {
+      return typeof row["content"] === "string" ? row["content"] : "";
+    }
+  }
+  return "";
+};
+const readThreadStatus = (thread) => {
+  if (thread !== null && typeof thread === "object" && typeof thread.status === "string") {
+    return thread.status;
+  }
+  return "unknown";
+};
+const readTerminal = async (client, threadKey, status, thread) => {
+  const messages = await client.query(reference(AGENT_MESSAGES_PATH), { key: threadKey });
+  if (status === "error") {
+    const error = thread !== null && typeof thread === "object" ? thread.error : void 0;
+    return ok({ error: typeof error === "string" ? error : "the agent run failed", status, threadKey });
+  }
+  return ok({ status, text: finalAnswer(messages), threadKey });
+};
+const callAgentStatus = async (client, input) => {
+  const threadKey = readString(input, "threadKey");
+  if (threadKey === void 0) {
+    return fail('"threadKey" is required and must be a non-empty string');
+  }
+  const thread = await client.query(reference(AGENT_THREAD_PATH), { key: threadKey });
+  const status = readThreadStatus(thread);
+  if (TERMINAL_STATUSES.has(status)) {
+    return readTerminal(client, threadKey, status, thread);
+  }
+  return ok({ status: status === "unknown" ? "running" : status, threadKey });
+};
+const callAgentTool = async (client, name, input, options) => {
+  try {
+    if (options.allowAgents !== true) {
+      return fail(`tool "${name}" is disabled: agent tools are off. Enable them with the LUNORA_MCP_ALLOW_AGENTS env var.`);
+    }
+    if (name === AGENT_STATUS_TOOL_NAME) {
+      return await callAgentStatus(client, input);
+    }
+    const exposure = options.exposures.find((candidate) => agentToolName(candidate) === name);
+    if (exposure === void 0) {
+      return fail(`agent tool "${name}" is not exposed by this MCP server`);
+    }
+    const prompt = readString(input, "prompt");
+    if (prompt === void 0) {
+      return fail('"prompt" is required and must be a non-empty string');
+    }
+    const threadKey = readString(input, "threadKey") ?? freshThreadKey();
+    const title = readString(input, "title");
+    const { id } = await client.mutation(reference(AGENT_RUN_PATH), {
+      agent: exposure.name,
+      input: prompt,
+      threadKey,
+      ...title === void 0 ? {} : { title }
+    });
+    const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const maxWaitMs = options.maxWaitMs ?? DEFAULT_MAX_WAIT_MS;
+    const wait = options.wait ?? defaultWait;
+    const maxPolls = Math.max(1, Math.ceil(maxWaitMs / pollIntervalMs));
+    for (let attempt = 0; attempt < maxPolls; attempt += 1) {
+      const thread = await client.query(reference(AGENT_THREAD_PATH), { key: threadKey });
+      const status = readThreadStatus(thread);
+      if (TERMINAL_STATUSES.has(status)) {
+        return await readTerminal(client, threadKey, status, thread);
+      }
+      await wait(pollIntervalMs);
+    }
+    return ok({ hint: "call lunora_agent_status with this threadKey to poll for the answer", runId: id, status: "running", threadKey });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return fail(message);
+  }
+};
+
+export { AGENT_RUN_INPUT_SCHEMA, AGENT_STATUS_TOOL_NAME, agentToolDefinitions, callAgentTool, finalAnswer, isAgentToolName, parseAgentsEnv };

package/dist/packem_shared/READ_ONLY_TOOL_DEFINITIONS-CWb_wFd5.mjs

@@ -0,0 +1,204 @@
+import { LunoraError } from '@lunora/errors';
+
+const RUN_INPUT_SCHEMA = {
+  properties: {
+    args: { description: "Arguments object passed to the function", type: "object" },
+    functionPath: { description: 'Function reference, e.g. "messages:send"', type: "string" },
+    shardKey: { description: "Optional shard key when the function is .shardBy()-partitioned", type: "string" }
+  },
+  required: ["functionPath"],
+  type: "object"
+};
+const NO_INPUT_SCHEMA = { properties: {}, type: "object" };
+const FUNCTION_PATH_INPUT_SCHEMA = {
+  properties: {
+    functionPath: { description: 'Function reference, e.g. "messages:send"', type: "string" }
+  },
+  required: ["functionPath"],
+  type: "object"
+};
+const READ_ONLY_TOOL_DEFINITIONS = [
+  {
+    description: "List the deployment's public functions (queries, mutations, actions) with their kinds.",
+    inputSchema: NO_INPUT_SCHEMA,
+    name: "lunora_list_functions"
+  },
+  {
+    description: "List the deployment's .global() tables and their column shapes.",
+    inputSchema: NO_INPUT_SCHEMA,
+    name: "lunora_list_tables"
+  },
+  {
+    description: "Return a function's argument JSON Schema and kind, so a caller can construct a valid arguments object. Call lunora_list_functions first to discover available function paths.",
+    inputSchema: FUNCTION_PATH_INPUT_SCHEMA,
+    name: "lunora_get_function_schema"
+  },
+  {
+    description: "Run a query and return its result. Read-only.",
+    inputSchema: RUN_INPUT_SCHEMA,
+    name: "lunora_run_query"
+  }
+];
+const WRITE_TOOL_DEFINITIONS = [
+  {
+    description: "Run a mutation and return its result. Writes data — use with care.",
+    inputSchema: RUN_INPUT_SCHEMA,
+    name: "lunora_run_mutation"
+  },
+  {
+    description: "Run an action and return its result. May call external services.",
+    inputSchema: RUN_INPUT_SCHEMA,
+    name: "lunora_run_action"
+  }
+];
+const WRITE_TOOL_NAMES = new Set(WRITE_TOOL_DEFINITIONS.map((tool) => tool.name));
+const toolDefinitions = (allowWrites) => (
+  // Fail closed: only the boolean `true` opts in. These are exported helpers, so
+  // an env-plumbed/JS caller could pass a truthy string like `"false"`/`"0"` —
+  // the explicit `=== true` guards that despite the declared `boolean` type.
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-boolean-literal-compare -- intentional runtime guard at an exported API boundary against non-boolean callers
+  allowWrites === true ? [...READ_ONLY_TOOL_DEFINITIONS, ...WRITE_TOOL_DEFINITIONS] : READ_ONLY_TOOL_DEFINITIONS
+);
+const readFunctionPath = (input) => {
+  const { functionPath } = input;
+  if (typeof functionPath !== "string" || functionPath.length === 0) {
+    throw new LunoraError("INTERNAL", '"functionPath" is required and must be a non-empty string');
+  }
+  return functionPath;
+};
+const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const describeArgs = (value) => Array.isArray(value) ? "an array" : `a ${typeof value}`;
+const readArgumentsBag = (raw) => {
+  if (raw === void 0 || raw === null) {
+    return {};
+  }
+  if (typeof raw === "string") {
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      throw new LunoraError("BAD_REQUEST", `"args" must be a JSON object; received a string that is not valid JSON`);
+    }
+    if (!isPlainObject(parsed)) {
+      throw new LunoraError("BAD_REQUEST", `"args" must be a JSON object; the provided string decoded to ${describeArgs(parsed)}`);
+    }
+    return parsed;
+  }
+  if (!isPlainObject(raw)) {
+    throw new LunoraError("BAD_REQUEST", `"args" must be a JSON object, got ${describeArgs(raw)}`);
+  }
+  return raw;
+};
+const readRunArguments = (input) => {
+  const functionPath = readFunctionPath(input);
+  const args = readArgumentsBag(input.args);
+  const shardKey = typeof input.shardKey === "string" && input.shardKey.length > 0 ? input.shardKey : void 0;
+  return { args, functionPath, shardKey };
+};
+const reference = (functionPath) => {
+  return { __lunoraRef: functionPath };
+};
+const bytesToBase64 = (bytes) => {
+  let binary = "";
+  const chunk = 32768;
+  for (let index = 0; index < bytes.length; index += chunk) {
+    binary += String.fromCharCode(...bytes.subarray(index, index + chunk));
+  }
+  return btoa(binary);
+};
+const jsonResultReplacer = (_key, value) => {
+  if (typeof value === "bigint") {
+    return value.toString();
+  }
+  if (value instanceof ArrayBuffer) {
+    return bytesToBase64(new Uint8Array(value));
+  }
+  if (ArrayBuffer.isView(value)) {
+    const view = value;
+    return bytesToBase64(new Uint8Array(view.buffer, view.byteOffset, view.byteLength));
+  }
+  return value;
+};
+const ok = (value) => {
+  const text = value === void 0 ? "null" : JSON.stringify(value, jsonResultReplacer, 2);
+  return { content: [{ text, type: "text" }] };
+};
+const FUNCTIONS_CACHE_TTL_MS = 3e4;
+const functionsCache = /* @__PURE__ */ new WeakMap();
+const listFunctionsCached = (client) => {
+  const now = Date.now();
+  const cached = functionsCache.get(client);
+  if (cached !== void 0 && cached.expiresAt > now) {
+    return cached.promise;
+  }
+  const promise = client.listFunctions().catch((error) => {
+    if (functionsCache.get(client)?.promise === promise) {
+      functionsCache.delete(client);
+    }
+    throw error;
+  });
+  functionsCache.set(client, { expiresAt: now + FUNCTIONS_CACHE_TTL_MS, promise });
+  return promise;
+};
+const assertRunnable = async (client, functionPath, expectedKind) => {
+  const functions = await listFunctionsCached(client);
+  const descriptor = functions.find((function_) => function_.path === functionPath);
+  if (descriptor === void 0) {
+    throw new LunoraError("NOT_FOUND", `function not found or not public: ${functionPath}`);
+  }
+  if (descriptor.kind !== expectedKind) {
+    throw new LunoraError("BAD_REQUEST", `function ${functionPath} is a ${descriptor.kind}, not a ${expectedKind}`);
+  }
+};
+const callTool = async (client, name, input, allowWrites = false) => {
+  try {
+    if (allowWrites !== true && WRITE_TOOL_NAMES.has(name)) {
+      return {
+        content: [
+          { text: `tool "${name}" is disabled: this MCP server is read-only. Enable writes with the LUNORA_MCP_ALLOW_WRITES env var.`, type: "text" }
+        ],
+        isError: true
+      };
+    }
+    switch (name) {
+      case "lunora_get_function_schema": {
+        const functionPath = readFunctionPath(input);
+        const functions = await listFunctionsCached(client);
+        const descriptor = functions.find((function_) => function_.path === functionPath);
+        if (descriptor === void 0) {
+          return { content: [{ text: `function not found: ${functionPath}`, type: "text" }], isError: true };
+        }
+        return ok({ args: descriptor.args ?? [], kind: descriptor.kind, path: descriptor.path });
+      }
+      case "lunora_list_functions": {
+        return ok(await listFunctionsCached(client));
+      }
+      case "lunora_list_tables": {
+        return ok(await client.listGlobalTables());
+      }
+      case "lunora_run_action": {
+        const { args, functionPath, shardKey } = readRunArguments(input);
+        await assertRunnable(client, functionPath, "action");
+        return ok(await client.action(reference(functionPath), args, { shardKey }));
+      }
+      case "lunora_run_mutation": {
+        const { args, functionPath, shardKey } = readRunArguments(input);
+        await assertRunnable(client, functionPath, "mutation");
+        return ok(await client.mutation(reference(functionPath), args, { shardKey }));
+      }
+      case "lunora_run_query": {
+        const { args, functionPath, shardKey } = readRunArguments(input);
+        await assertRunnable(client, functionPath, "query");
+        return ok(await client.query(reference(functionPath), args, { shardKey }));
+      }
+      default: {
+        return { content: [{ text: `unknown tool: ${name}`, type: "text" }], isError: true };
+      }
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { content: [{ text: message, type: "text" }], isError: true };
+  }
+};
+
+export { READ_ONLY_TOOL_DEFINITIONS, WRITE_TOOL_DEFINITIONS, callTool, toolDefinitions };

package/dist/packem_shared/{connectStdio-C_mvQBs2.mjs → connectStdio-bkJcaXYE.mjs}

@@ -2,10 +2,12 @@ import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { LunoraClient } from '@lunora/client';
+import { LunoraError } from '@lunora/errors';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
-import { TOOL_DEFINITIONS, callTool } from './TOOL_DEFINITIONS-Dpiu38ji.mjs';
+import { agentToolDefinitions, isAgentToolName, callAgentTool } from './AGENT_RUN_INPUT_SCHEMA-DWobae3P.mjs';
+import { toolDefinitions, callTool } from './READ_ONLY_TOOL_DEFINITIONS-CWb_wFd5.mjs';
 
 const resolveVersion = () => {
   try {
@@ -35,7 +37,7 @@ const resolveClient = (options) => {
     return options.client;
   }
   if (options.url === void 0) {
-    throw new Error("createLunoraMcpServer requires either a `client` or a `url`");
+    throw new LunoraError("INTERNAL", "createLunoraMcpServer requires either a `client` or a `url`");
   }
   const client = new LunoraClient({ fetch: options.fetch, url: options.url });
   if (options.token !== void 0) {
@@ -45,12 +47,22 @@ const resolveClient = (options) => {
 };
 const createLunoraMcpServer = (options) => {
   const client = resolveClient(options);
+  const allowWrites = options.allowWrites ?? false;
+  const allowAgents = options.allowAgents ?? false;
+  const agents = options.agents ?? [];
   const server = new Server(SERVER_INFO, { capabilities: { tools: {} } });
   server.setRequestHandler(ListToolsRequestSchema, () => {
-    return { tools: [...TOOL_DEFINITIONS] };
+    return { tools: [...toolDefinitions(allowWrites), ...agentToolDefinitions(agents, allowAgents)] };
   });
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    const result = await callTool(client, request.params.name, request.params.arguments ?? {});
+    const { arguments: rawArguments, name } = request.params;
+    const input = rawArguments ?? {};
+    const result = isAgentToolName(name, agents) ? await callAgentTool(client, name, input, {
+      allowAgents,
+      exposures: agents,
+      ...options.agentMaxWaitMs === void 0 ? {} : { maxWaitMs: options.agentMaxWaitMs },
+      ...options.agentPollIntervalMs === void 0 ? {} : { pollIntervalMs: options.agentPollIntervalMs }
+    }) : await callTool(client, name, input, allowWrites);
     return result;
   });
   return server;

package/dist/packem_shared/createMcpFetchHandler-DfzBSLrm.mjs

@@ -0,0 +1,14 @@
+import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
+import { createLunoraMcpServer } from './connectStdio-bkJcaXYE.mjs';
+
+const serveStateless = async (server, request, options) => {
+  const transport = new WebStandardStreamableHTTPServerTransport({ enableJsonResponse: true, sessionIdGenerator: void 0 });
+  await server.connect(transport);
+  const response = await transport.handleRequest(request, options);
+  transport.close().catch(() => void 0);
+  server.close().catch(() => void 0);
+  return response;
+};
+const createMcpFetchHandler = (options) => (request) => serveStateless(createLunoraMcpServer(options), request);
+
+export { createMcpFetchHandler, serveStateless };

package/dist/packem_shared/createPaidMcpServer-b-qp_aEF.mjs

@@ -0,0 +1,93 @@
+import { LunoraError } from '@lunora/errors';
+import { createChargeMiddleware } from '@lunora/x402/charge';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { serveStateless } from './createMcpFetchHandler-DfzBSLrm.mjs';
+
+const DEFAULT_SERVER_INFO = { name: "lunora-paid-mcp", version: "0.0.0" };
+const CALL_TOOL_METHOD = "tools/call";
+const callToolName = (message) => {
+  if (typeof message !== "object" || message === null) {
+    return void 0;
+  }
+  const { method, params } = message;
+  if (method !== CALL_TOOL_METHOD || typeof params !== "object" || params === null) {
+    return void 0;
+  }
+  const { name } = params;
+  return typeof name === "string" ? name : void 0;
+};
+const refuseBatch = () => Response.json({ error: "A JSON-RPC batch may not reference a paid MCP tool; send paid tools/call requests individually." }, { status: 400 });
+const createPaidMcpServer = (config) => {
+  const tools = /* @__PURE__ */ new Map();
+  const prices = /* @__PURE__ */ new Map();
+  const middlewareByTool = /* @__PURE__ */ new Map();
+  const serverInfo = config.serverInfo ?? DEFAULT_SERVER_INFO;
+  const register = (options, handler, price) => {
+    if (tools.has(options.name)) {
+      throw new LunoraError("BAD_REQUEST", `MCP tool "${options.name}" is already registered.`);
+    }
+    const definition = { description: options.description, inputSchema: options.inputSchema, name: options.name };
+    if (options.annotations !== void 0) {
+      definition.annotations = options.annotations;
+    }
+    tools.set(options.name, { definition, handler });
+    if (price !== void 0) {
+      prices.set(options.name, price);
+    }
+  };
+  const buildServer = () => {
+    const server = new Server(serverInfo, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, () => {
+      return { tools: [...tools.values()].map((entry) => entry.definition) };
+    });
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      const entry = tools.get(request.params.name);
+      if (entry === void 0) {
+        return { content: [{ text: `unknown tool: ${request.params.name}`, type: "text" }], isError: true };
+      }
+      const result = await entry.handler(request.params.arguments ?? {});
+      return result;
+    });
+    return server;
+  };
+  const gateFor = (name, price) => {
+    let pending = middlewareByTool.get(name);
+    if (pending === void 0) {
+      pending = createChargeMiddleware({ ...config.charge, price }, { resource: name }).catch((error) => {
+        middlewareByTool.delete(name);
+        throw error;
+      });
+      middlewareByTool.set(name, pending);
+    }
+    return pending;
+  };
+  const fetchHandler = async (request) => {
+    let parsedBody;
+    try {
+      parsedBody = await request.clone().json();
+    } catch {
+      parsedBody = void 0;
+    }
+    const dispatch = () => serveStateless(buildServer(), request, parsedBody === void 0 ? void 0 : { parsedBody });
+    if (Array.isArray(parsedBody)) {
+      return parsedBody.some((message) => prices.has(callToolName(message) ?? "")) ? refuseBatch() : dispatch();
+    }
+    const name = callToolName(parsedBody);
+    const price = name === void 0 ? void 0 : prices.get(name);
+    if (name === void 0 || price === void 0) {
+      return dispatch();
+    }
+    const middleware = await gateFor(name, price);
+    return middleware.handle(request, dispatch);
+  };
+  const paidTool = (options, handler) => {
+    register(options, handler, options.price);
+  };
+  const tool = (options, handler) => {
+    register(options, handler);
+  };
+  return { fetchHandler, paidTool, tool };
+};
+
+export { createPaidMcpServer };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/mcp",
-  "version": "1.0.0-alpha.3",
+  "version": "1.0.0-alpha.30",
   "description": "Model Context Protocol server exposing a Lunora deployment to AI agents",
   "keywords": [
     "ai-agents",
@@ -49,7 +49,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@lunora/client": "1.0.0-alpha.3",
+    "@lunora/client": "1.0.0-alpha.28",
+    "@lunora/errors": "1.0.0-alpha.8",
+    "@lunora/x402": "1.0.0-alpha.6",
     "@modelcontextprotocol/sdk": "^1.29.0"
   },
   "engines": {

package/dist/packem_shared/TOOL_DEFINITIONS-Dpiu38ji.mjs

@@ -1,112 +0,0 @@
-const RUN_INPUT_SCHEMA = {
-  properties: {
-    args: { description: "Arguments object passed to the function", type: "object" },
-    functionPath: { description: 'Function reference, e.g. "messages:send"', type: "string" },
-    shardKey: { description: "Optional shard key when the function is .shardBy()-partitioned", type: "string" }
-  },
-  required: ["functionPath"],
-  type: "object"
-};
-const NO_INPUT_SCHEMA = { properties: {}, type: "object" };
-const FUNCTION_PATH_INPUT_SCHEMA = {
-  properties: {
-    functionPath: { description: 'Function reference, e.g. "messages:send"', type: "string" }
-  },
-  required: ["functionPath"],
-  type: "object"
-};
-const TOOL_DEFINITIONS = [
-  {
-    description: "List the deployment's public functions (queries, mutations, actions) with their kinds.",
-    inputSchema: NO_INPUT_SCHEMA,
-    name: "lunora_list_functions"
-  },
-  {
-    description: "List the deployment's .global() tables and their column shapes.",
-    inputSchema: NO_INPUT_SCHEMA,
-    name: "lunora_list_tables"
-  },
-  {
-    description: "Return a function's argument JSON Schema and kind, so a caller can construct a valid arguments object. Call lunora_list_functions first to discover available function paths.",
-    inputSchema: FUNCTION_PATH_INPUT_SCHEMA,
-    name: "lunora_get_function_schema"
-  },
-  {
-    description: "Run a query and return its result. Read-only.",
-    inputSchema: RUN_INPUT_SCHEMA,
-    name: "lunora_run_query"
-  },
-  {
-    description: "Run a mutation and return its result. Writes data — use with care.",
-    inputSchema: RUN_INPUT_SCHEMA,
-    name: "lunora_run_mutation"
-  },
-  {
-    description: "Run an action and return its result. May call external services.",
-    inputSchema: RUN_INPUT_SCHEMA,
-    name: "lunora_run_action"
-  }
-];
-const readFunctionPath = (input) => {
-  const { functionPath } = input;
-  if (typeof functionPath !== "string" || functionPath.length === 0) {
-    throw new Error('"functionPath" is required and must be a non-empty string');
-  }
-  return functionPath;
-};
-const readRunArguments = (input) => {
-  const functionPath = readFunctionPath(input);
-  const rawArguments = input.args;
-  const isPlainObject = typeof rawArguments === "object" && rawArguments !== null && !Array.isArray(rawArguments);
-  const args = isPlainObject ? rawArguments : {};
-  const shardKey = typeof input.shardKey === "string" && input.shardKey.length > 0 ? input.shardKey : void 0;
-  return { args, functionPath, shardKey };
-};
-const reference = (functionPath) => {
-  return { __lunoraRef: functionPath };
-};
-const ok = (value) => {
-  const text = value === void 0 ? "null" : JSON.stringify(value, void 0, 2);
-  return { content: [{ text, type: "text" }] };
-};
-const callTool = async (client, name, input) => {
-  try {
-    switch (name) {
-      case "lunora_get_function_schema": {
-        const functionPath = readFunctionPath(input);
-        const functions = await client.listFunctions();
-        const descriptor = functions.find((function_) => function_.path === functionPath);
-        if (descriptor === void 0) {
-          return { content: [{ text: `function not found: ${functionPath}`, type: "text" }], isError: true };
-        }
-        return ok({ args: descriptor.args ?? [], kind: descriptor.kind, path: descriptor.path });
-      }
-      case "lunora_list_functions": {
-        return ok(await client.listFunctions());
-      }
-      case "lunora_list_tables": {
-        return ok(await client.listGlobalTables());
-      }
-      case "lunora_run_action": {
-        const { args, functionPath, shardKey } = readRunArguments(input);
-        return ok(await client.action(reference(functionPath), args, { shardKey }));
-      }
-      case "lunora_run_mutation": {
-        const { args, functionPath, shardKey } = readRunArguments(input);
-        return ok(await client.mutation(reference(functionPath), args, { shardKey }));
-      }
-      case "lunora_run_query": {
-        const { args, functionPath, shardKey } = readRunArguments(input);
-        return ok(await client.query(reference(functionPath), args, { shardKey }));
-      }
-      default: {
-        return { content: [{ text: `unknown tool: ${name}`, type: "text" }], isError: true };
-      }
-    }
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    return { content: [{ text: message, type: "text" }], isError: true };
-  }
-};
-
-export { TOOL_DEFINITIONS, callTool };