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

package/dist/packem_shared/serve-stateless.d-B_q8q39X.d.mts

@@ -0,0 +1,133 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { HandleRequestOptions } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
+/**
+ * The MCP wire shapes every tool surface in this package speaks — the
+ * deployment tools (`./tools`), the agent tools (`./agent-tools`), and the
+ * documentation tools (`./docs`).
+ *
+ * They live in their own module (rather than in `./tools`) so a consumer that
+ * only wants the docs surface can import the types without dragging
+ * `@lunora/client` into its bundle. `./tools` re-exports them, so the package's
+ * public API is unchanged.
+ */
+/** A JSON-Schema object describing a tool's arguments, per the MCP spec. */
+interface ToolInputSchema {
+  properties: Record<string, unknown>;
+  required?: ReadonlyArray<string>;
+  type: "object";
+}
+/**
+ * MCP tool annotations — hints a client may use to decide how to present a tool
+ * (badge it read-only, confirm before a destructive call).
+ *
+ * They are hints, not enforcement: this package's actual guarantees are made at
+ * dispatch, where a write tool is refused unless `allowWrites` is set. These
+ * exist so a client can *show* the user what the server already enforces,
+ * instead of every tool looking equally dangerous.
+ */
+interface ToolAnnotations {
+  /** The tool may perform irreversible changes. Only meaningful when `readOnlyHint` is false. */
+  destructiveHint?: boolean;
+  /** Repeating the call with the same arguments has no additional effect. */
+  idempotentHint?: boolean;
+  /** The tool reaches systems beyond this server (the network, external services). */
+  openWorldHint?: boolean;
+  /** The tool does not modify anything. */
+  readOnlyHint?: boolean;
+  /** Human-facing title, shown instead of the raw tool name. */
+  title?: string;
+}
+interface ToolDefinition {
+  annotations?: ToolAnnotations;
+  description: string;
+  inputSchema: ToolInputSchema;
+  name: string;
+  /**
+   * JSON Schema for the tool's `structuredContent`. Optional: a tool that
+   * emits only a text block declares none, and a client that negotiated an
+   * MCP revision older than `2025-06-18` ignores it either way.
+   */
+  outputSchema?: ToolInputSchema;
+}
+/** The MCP `CallToolResult` shape this package's tools return. */
+interface ToolResult {
+  content: {
+    text: string;
+    type: "text";
+  }[];
+  isError?: boolean;
+  /**
+   * The machine-readable result, mirroring the text block. Present only for
+   * tools that declare an `outputSchema`; per the MCP spec it must be a JSON
+   * OBJECT (never a bare array) and must survive `JSON.stringify` — the
+   * transport serializes it, so an un-mapped `bigint` here fails the whole
+   * response rather than one field.
+   */
+  structuredContent?: Record<string, unknown>;
+}
+/** A tool: what to advertise in `ListTools`, and what to run on `CallTool`. */
+interface McpTool {
+  definition: ToolDefinition;
+  handle: (input: Record<string, unknown>) => Promise<ToolResult>;
+}
+/** Name/version pair reported in the MCP `initialize` handshake. */
+interface McpServerInfo {
+  name: string;
+  version: string;
+}
+/** One addressable document a client can list and read directly. */
+interface McpResourceSummary {
+  description?: string;
+  mimeType?: string;
+  name: string;
+  uri: string;
+}
+/**
+ * A set of resources the server exposes alongside its tools.
+ *
+ * Tools are calls a model chooses to make; resources are documents a *client*
+ * can enumerate and attach on its own — the user picking a page to put in
+ * context, without the model having to guess a search query first. The same
+ * corpus is worth offering both ways.
+ */
+interface McpResourceProvider {
+  /** Every resource, for `resources/list`. */
+  list: () => Promise<ReadonlyArray<McpResourceSummary>>;
+  /** One resource's body, or `undefined` when the uri is unknown. */
+  read: (uri: string) => Promise<{
+    mimeType?: string;
+    text: string;
+  } | undefined>;
+}
+/**
+ * Build an MCP `Server` that advertises and dispatches `tools`.
+ *
+ * On duplicate names the FIRST wins, so a caller can layer surfaces in
+ * precedence order without the later list silently shadowing the earlier one.
+ * Thrown errors become `isError` results rather than rejections, per the MCP
+ * convention that a tool failure is output the model can read and react to,
+ * not a protocol-level fault.
+ */
+declare const createToolServer: (info: McpServerInfo, tools: ReadonlyArray<McpTool>, resources?: McpResourceProvider) => Server;
+/** A Web-Standard fetch handler: takes a `Request`, returns the MCP `Response`. */
+type McpFetchHandler = (request: Request) => Promise<Response>;
+/**
+ * Drive one request through a fresh **stateless** Streamable-HTTP transport bound
+ * to `server`, then tear both down.
+ *
+ * `sessionIdGenerator: undefined` → stateless (no cross-request session store);
+ * `enableJsonResponse: true` → the whole JSON-RPC response is buffered into the
+ * returned `Response`, so closing the transport/server afterwards can't truncate
+ * an in-flight body. Cleanup is fire-and-forget with swallowed rejections (a
+ * `.catch()`-terminated chain) so it never delays or masks the resolved response.
+ *
+ * `options.parsedBody` lets a caller hand over a body it already read (e.g. the
+ * paid-tool gate, which peeks the JSON-RPC message to price the call) so the
+ * transport doesn't re-read a consumed stream.
+ *
+ * Teardown runs in a `finally`: a rejection from `connect` or `handleRequest`
+ * would otherwise skip it and leak a server + transport per failed request,
+ * which on a public endpoint is exactly the request an attacker can repeat.
+ */
+declare const serveStateless: (server: Server, request: Request, options?: HandleRequestOptions) => Promise<Response>;
+export { McpResourceProvider as M, ToolDefinition as T, McpFetchHandler as a, McpTool as b, McpResourceSummary as c, McpServerInfo as d, ToolInputSchema as e, ToolResult as f, createToolServer as g, serveStateless as s };

package/dist/packem_shared/serve-stateless.d-B_q8q39X.d.ts

@@ -0,0 +1,133 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { HandleRequestOptions } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
+/**
+ * The MCP wire shapes every tool surface in this package speaks — the
+ * deployment tools (`./tools`), the agent tools (`./agent-tools`), and the
+ * documentation tools (`./docs`).
+ *
+ * They live in their own module (rather than in `./tools`) so a consumer that
+ * only wants the docs surface can import the types without dragging
+ * `@lunora/client` into its bundle. `./tools` re-exports them, so the package's
+ * public API is unchanged.
+ */
+/** A JSON-Schema object describing a tool's arguments, per the MCP spec. */
+interface ToolInputSchema {
+  properties: Record<string, unknown>;
+  required?: ReadonlyArray<string>;
+  type: "object";
+}
+/**
+ * MCP tool annotations — hints a client may use to decide how to present a tool
+ * (badge it read-only, confirm before a destructive call).
+ *
+ * They are hints, not enforcement: this package's actual guarantees are made at
+ * dispatch, where a write tool is refused unless `allowWrites` is set. These
+ * exist so a client can *show* the user what the server already enforces,
+ * instead of every tool looking equally dangerous.
+ */
+interface ToolAnnotations {
+  /** The tool may perform irreversible changes. Only meaningful when `readOnlyHint` is false. */
+  destructiveHint?: boolean;
+  /** Repeating the call with the same arguments has no additional effect. */
+  idempotentHint?: boolean;
+  /** The tool reaches systems beyond this server (the network, external services). */
+  openWorldHint?: boolean;
+  /** The tool does not modify anything. */
+  readOnlyHint?: boolean;
+  /** Human-facing title, shown instead of the raw tool name. */
+  title?: string;
+}
+interface ToolDefinition {
+  annotations?: ToolAnnotations;
+  description: string;
+  inputSchema: ToolInputSchema;
+  name: string;
+  /**
+   * JSON Schema for the tool's `structuredContent`. Optional: a tool that
+   * emits only a text block declares none, and a client that negotiated an
+   * MCP revision older than `2025-06-18` ignores it either way.
+   */
+  outputSchema?: ToolInputSchema;
+}
+/** The MCP `CallToolResult` shape this package's tools return. */
+interface ToolResult {
+  content: {
+    text: string;
+    type: "text";
+  }[];
+  isError?: boolean;
+  /**
+   * The machine-readable result, mirroring the text block. Present only for
+   * tools that declare an `outputSchema`; per the MCP spec it must be a JSON
+   * OBJECT (never a bare array) and must survive `JSON.stringify` — the
+   * transport serializes it, so an un-mapped `bigint` here fails the whole
+   * response rather than one field.
+   */
+  structuredContent?: Record<string, unknown>;
+}
+/** A tool: what to advertise in `ListTools`, and what to run on `CallTool`. */
+interface McpTool {
+  definition: ToolDefinition;
+  handle: (input: Record<string, unknown>) => Promise<ToolResult>;
+}
+/** Name/version pair reported in the MCP `initialize` handshake. */
+interface McpServerInfo {
+  name: string;
+  version: string;
+}
+/** One addressable document a client can list and read directly. */
+interface McpResourceSummary {
+  description?: string;
+  mimeType?: string;
+  name: string;
+  uri: string;
+}
+/**
+ * A set of resources the server exposes alongside its tools.
+ *
+ * Tools are calls a model chooses to make; resources are documents a *client*
+ * can enumerate and attach on its own — the user picking a page to put in
+ * context, without the model having to guess a search query first. The same
+ * corpus is worth offering both ways.
+ */
+interface McpResourceProvider {
+  /** Every resource, for `resources/list`. */
+  list: () => Promise<ReadonlyArray<McpResourceSummary>>;
+  /** One resource's body, or `undefined` when the uri is unknown. */
+  read: (uri: string) => Promise<{
+    mimeType?: string;
+    text: string;
+  } | undefined>;
+}
+/**
+ * Build an MCP `Server` that advertises and dispatches `tools`.
+ *
+ * On duplicate names the FIRST wins, so a caller can layer surfaces in
+ * precedence order without the later list silently shadowing the earlier one.
+ * Thrown errors become `isError` results rather than rejections, per the MCP
+ * convention that a tool failure is output the model can read and react to,
+ * not a protocol-level fault.
+ */
+declare const createToolServer: (info: McpServerInfo, tools: ReadonlyArray<McpTool>, resources?: McpResourceProvider) => Server;
+/** A Web-Standard fetch handler: takes a `Request`, returns the MCP `Response`. */
+type McpFetchHandler = (request: Request) => Promise<Response>;
+/**
+ * Drive one request through a fresh **stateless** Streamable-HTTP transport bound
+ * to `server`, then tear both down.
+ *
+ * `sessionIdGenerator: undefined` → stateless (no cross-request session store);
+ * `enableJsonResponse: true` → the whole JSON-RPC response is buffered into the
+ * returned `Response`, so closing the transport/server afterwards can't truncate
+ * an in-flight body. Cleanup is fire-and-forget with swallowed rejections (a
+ * `.catch()`-terminated chain) so it never delays or masks the resolved response.
+ *
+ * `options.parsedBody` lets a caller hand over a body it already read (e.g. the
+ * paid-tool gate, which peeks the JSON-RPC message to price the call) so the
+ * transport doesn't re-read a consumed stream.
+ *
+ * Teardown runs in a `finally`: a rejection from `connect` or `handleRequest`
+ * would otherwise skip it and leak a server + transport per failed request,
+ * which on a public endpoint is exactly the request an attacker can repeat.
+ */
+declare const serveStateless: (server: Server, request: Request, options?: HandleRequestOptions) => Promise<Response>;
+export { McpResourceProvider as M, ToolDefinition as T, McpFetchHandler as a, McpTool as b, McpResourceSummary as c, McpServerInfo as d, ToolInputSchema as e, ToolResult as f, createToolServer as g, serveStateless as s };

package/dist/packem_shared/serveStateless-Db7J3pAO.mjs

@@ -0,0 +1 @@
+import{WebStandardStreamableHTTPServerTransport as o}from"@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";const s=async(t,a,n)=>{const e=new o({enableJsonResponse:!0,sessionIdGenerator:void 0});try{return await t.connect(e),await e.handleRequest(a,n)}finally{e.close().catch(()=>{}),t.close().catch(()=>{})}};export{s as serveStateless};

package/dist/packem_shared/toDocsSearchHits-CBLmtWXt.mjs

@@ -0,0 +1 @@
+const e=t=>typeof t=="object"&&t!==null,i=t=>t.split("<mark>").join("").split("</mark>").join(""),l=t=>Array.isArray(t)?t.filter(o=>typeof o=="string"):[],p=t=>{if(!e(t)||typeof t.url!="string"||t.url.length===0)return;const o=t,r=typeof o.content=="string"?i(o.content):"",s=l(o.breadcrumbs),n=o.type==="page",c=n?r:s.at(-1)??r;return{...n||r.length===0?{}:{excerpt:r},...s.length>0?{section:s.join(" › ")}:{},title:c.length>0?c:t.url,url:t.url}},u=t=>{const o=[];for(const r of t){const s=p(r);s!==void 0&&o.push(s)}return o};export{u as toDocsSearchHits};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/mcp",
-  "version": "1.0.0-alpha.7",
+  "version": "1.0.0-alpha.71",
   "description": "Model Context Protocol server exposing a Lunora deployment to AI agents",
   "keywords": [
     "ai-agents",
@@ -43,14 +43,28 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.mjs"
     },
+    "./docs": {
+      "types": "./dist/docs/index.d.ts",
+      "import": "./dist/docs/index.mjs"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@lunora/client": "1.0.0-alpha.7",
-    "@modelcontextprotocol/sdk": "^1.29.0"
+    "@lunora/client": "1.0.0-alpha.50",
+    "@lunora/errors": "1.0.0-alpha.21",
+    "@lunora/shard-engine": "1.0.0-alpha.27",
+    "@modelcontextprotocol/sdk": "^1.30.0"
+  },
+  "peerDependencies": {
+    "@lunora/x402": ">=1.0.0-alpha.21 <2.0.0-0"
+  },
+  "peerDependenciesMeta": {
+    "@lunora/x402": {
+      "optional": true
+    }
   },
   "engines": {
     "node": "^22.15.0 || >=24.11.0"

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 };

package/dist/packem_shared/connectStdio-C_mvQBs2.mjs

@@ -1,64 +0,0 @@
-import { readFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { LunoraClient } from '@lunora/client';
-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';
-
-const resolveVersion = () => {
-  try {
-    let directory = dirname(fileURLToPath(import.meta.url));
-    for (let depth = 0; depth < 8; depth += 1) {
-      try {
-        const raw = readFileSync(join(directory, "package.json"), "utf8");
-        const pkg = JSON.parse(raw);
-        if (pkg.name === "@lunora/mcp" && typeof pkg.version === "string" && pkg.version.length > 0) {
-          return pkg.version;
-        }
-      } catch {
-      }
-      const parent = dirname(directory);
-      if (parent === directory) {
-        break;
-      }
-      directory = parent;
-    }
-  } catch {
-  }
-  return "0.0.0";
-};
-const SERVER_INFO = { name: "lunora", version: resolveVersion() };
-const resolveClient = (options) => {
-  if (options.client !== void 0) {
-    return options.client;
-  }
-  if (options.url === void 0) {
-    throw new Error("createLunoraMcpServer requires either a `client` or a `url`");
-  }
-  const client = new LunoraClient({ fetch: options.fetch, url: options.url });
-  if (options.token !== void 0) {
-    client.setAuthToken(options.token);
-  }
-  return client;
-};
-const createLunoraMcpServer = (options) => {
-  const client = resolveClient(options);
-  const server = new Server(SERVER_INFO, { capabilities: { tools: {} } });
-  server.setRequestHandler(ListToolsRequestSchema, () => {
-    return { tools: [...TOOL_DEFINITIONS] };
-  });
-  server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    const result = await callTool(client, request.params.name, request.params.arguments ?? {});
-    return result;
-  });
-  return server;
-};
-const connectStdio = async (options) => {
-  const server = createLunoraMcpServer(options);
-  await server.connect(new StdioServerTransport());
-  return server;
-};
-
-export { connectStdio, createLunoraMcpServer };