@lunora/mcp 1.0.0-alpha.13 → 1.0.0-alpha.130

package/dist/docs/index.d.ts

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

package/dist/docs/index.mjs

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