@shoalrun/cli 0.0.0-stage → 0.1.0-alpha.12

package/agent-docs/publish/mcp-analytics.sections/event-fields-and-service-mappings.md

@@ -0,0 +1,53 @@
+---
+id: guide.mcp-analytics
+title: Measure MCP tool usage
+summary: Send optional server events to your analytics service without changing
+  the documentation tools.
+type: how-to
+area: discovery
+subarea: discovery-mcp
+canonical: /publish/mcp-analytics
+---
+
+# Measure MCP tool usage
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > MCP > Measure MCP tool usage
+
+**Updated: 2026-10-26.**
+
+Parent page: [Full Markdown page](/publish/mcp-analytics.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Read first**
+
+- [Connect an MCP client](https://www.shoalrun.com/publish/mcp.md) — Enable and verify the HTTP endpoint before adding analytics.
+
+Add a server adapter to measure calls to your [HTTP MCP endpoint](https://www.shoalrun.com/publish/mcp.md). Analytics is off by default. Enabling MCP does not enable tracking, and the browser analytics setting does not count tool calls.
+
+Your adapter chooses the service and sends the events. Shoalrun packages it for Node or the generated Vercel function. This setting does not instrument stdio, direct Markdown requests, or browser page views.
+
+## Event fields and service mappings
+
+Every event has the following fields. Arguments, search text, returned content, raw request headers, IP addresses, and user identity are excluded:
+
+| Field                 | Meaning                                                                          |
+| --------------------- | -------------------------------------------------------------------------------- |
+| `name`                | Always `mcp_tool_call`.                                                          |
+| `tool`                | `search_docs`, `get_page`, `get_outline`, or `get_section`.                      |
+| `durationMs`          | Tool execution time before analytics delivery.                                   |
+| `isError`             | Whether the documentation tool failed.                                           |
+| `errorCode`           | Error category when the tool failed.                                             |
+| `pageId`, `sectionId` | Published IDs when a successful read returns them.                               |
+| `buildId`             | Identity of the served build.                                                    |
+| `publication`         | Served `channel`, `version`, and `language`.                                     |
+| `client`              | Optional normalized client name, bounded version, source, and `verified: false`. |
+| `model`               | Optional model label, source, and `verified: false`.                             |
+
+Map these fields to your service’s event and property names. A service with native MCP analytics may require its SDK or reserved event names. A general event service can receive `mcp_tool_call` with these properties. The PostHog example below uses its native MCP SDK.
+
+Tool counts show usage, not comprehension. This adapter supplies no user or conversation identifier, so do not treat calls as unique people or agent sessions. Basic event capture leaves tool definitions and results unchanged. The optional SDK features below add analytics arguments and conversation handles.

package/agent-docs/publish/mcp-analytics.sections/optionally-collect-intent-and-group-calls.md

@@ -0,0 +1,62 @@
+---
+id: guide.mcp-analytics
+title: Measure MCP tool usage
+summary: Send optional server events to your analytics service without changing
+  the documentation tools.
+type: how-to
+area: discovery
+subarea: discovery-mcp
+canonical: /publish/mcp-analytics
+---
+
+# Measure MCP tool usage
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > MCP > Measure MCP tool usage
+
+**Updated: 2026-10-26.**
+
+Parent page: [Full Markdown page](/publish/mcp-analytics.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Read first**
+
+- [Connect an MCP client](https://www.shoalrun.com/publish/mcp.md) — Enable and verify the HTTP endpoint before adding analytics.
+
+Add a server adapter to measure calls to your [HTTP MCP endpoint](https://www.shoalrun.com/publish/mcp.md). Analytics is off by default. Enabling MCP does not enable tracking, and the browser analytics setting does not count tool calls.
+
+Your adapter chooses the service and sends the events. Shoalrun packages it for Node or the generated Vercel function. This setting does not instrument stdio, direct Markdown requests, or browser page views.
+
+## Optionally collect intent and group calls
+
+Intent describes why an agent called a tool. The PostHog adapter below supports separate `intent` and `conversationIds` switches, both off by default. Enable them alongside its module:
+
+```yaml title="docs.config.yaml"
+mcp:
+  enabled: true
+  access: public
+  publication: { channel: production, version: current, language: en }
+  analytics:
+    module: ./mcp-analytics/posthog.mjs
+    clientMetadata: true
+    intent: true
+    conversationIds: true
+```
+
+With intent enabled, the SDK adds a `context` argument asking for exactly one category: `discovery`, `setup`, `troubleshooting`, `configuration`, `reference_lookup`, `comparison`, `migration`, or `other`. Only these values can reach analytics. The adapter trims whitespace and normalizes case; it never stores an explanation or extracts a category from arbitrary text.
+
+An empty, invalid, or free-text value falls back to `discovery` for `search_docs` or `reference_lookup` for reading tools. PostHog marks the fallback as `inferred`. It describes the tool action, not a verified user goal, and does not invoke a model. Accepted client categories are also unverified claims.
+
+The SDK still accepts a string argument, so an agent might send private text despite the instruction. The outbound allowlist replaces that text before delivery. Raw queries, complete arguments, and returned documentation remain excluded.
+
+The endpoint creates a fresh server for every HTTP request. PostHog’s SDK can carry a stable session token for legacy clients. Conversation IDs also let clients reuse a handle across requests: the SDK adds a `conversation_id` argument and can return a handle for the agent to echo. Grouping depends on the client keeping its SDK token or echoing that handle. Reconnecting or ignoring the handle can split activity.
+
+These are analytics labels, not authentication. Client metadata capture in this SDK mode can also add an `llm_model` argument. It lets clients such as OpenCode report a model when no supported metadata field is available. Reported values remain unverified. Reconnect the client after enabling these options so it refreshes its tool schemas.
+
+An adapter can export `instrument(server, options)` to configure its SDK before serving the request. Return `true` to let that SDK own event capture; return `false` to retain Shoalrun’s `capture(event)` path. The options include these flags, build/publication identity, and helpers for normalized client/model labels and published resource IDs. Delivery still uses the adapter’s `flush()`.
+
+The PostHog example uses the existing low-level SDK server and resolves original tool argument names for stateless requests. Its outbound property allowlist drops raw headers, arguments, responses, and exception bodies. Other services need their own implementation of this optional hook.

package/agent-docs/publish/mcp-analytics.sections/optionally-identify-the-client-and-model.md

@@ -0,0 +1,54 @@
+---
+id: guide.mcp-analytics
+title: Measure MCP tool usage
+summary: Send optional server events to your analytics service without changing
+  the documentation tools.
+type: how-to
+area: discovery
+subarea: discovery-mcp
+canonical: /publish/mcp-analytics
+---
+
+# Measure MCP tool usage
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > MCP > Measure MCP tool usage
+
+**Updated: 2026-10-26.**
+
+Parent page: [Full Markdown page](/publish/mcp-analytics.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Read first**
+
+- [Connect an MCP client](https://www.shoalrun.com/publish/mcp.md) — Enable and verify the HTTP endpoint before adding analytics.
+
+Add a server adapter to measure calls to your [HTTP MCP endpoint](https://www.shoalrun.com/publish/mcp.md). Analytics is off by default. Enabling MCP does not enable tracking, and the browser analytics setting does not count tool calls.
+
+Your adapter chooses the service and sends the events. Shoalrun packages it for Node or the generated Vercel function. This setting does not instrument stdio, direct Markdown requests, or browser page views.
+
+## Optionally identify the client and model
+
+The harness is the application running the agent, such as Cursor or Claude Code. To collect available client and model labels, explicitly enable `clientMetadata` in your adapter config:
+
+```yaml title="docs.config.yaml"
+mcp:
+  enabled: true
+  access: public
+  publication: { channel: production, version: current, language: en }
+  analytics:
+    module: ./mcp-analytics/adapter.mjs
+    clientMetadata: true
+```
+
+This option defaults to `false`. Shoalrun recognizes a fixed set of client names from MCP identity metadata or product tokens in selected headers. It discards raw headers and unrelated metadata. Client versions must match a bounded numeric version format.
+
+Model capture currently recognizes `model` in Codex’s `x-codex-turn-metadata`. It accepts labels from a fixed model-name registry, normalizes supported provider prefixes, and drops other values. A recognized family prefix alone does not qualify; custom deployment names and unknown models are omitted. Other clients may supply no supported model field; missing labels remain absent. The harness name does not establish which model it uses.
+
+Both labels are unverified client claims. Use them for usage reports, never authentication, access control, or billing. No user fingerprint or cross-request identity cache is added.
+
+OpenCode can also be recognized by the presence of its documented session metadata marker. Shoalrun discards that identifier; it records only the client label. Client-specific markers do not establish the model.

package/agent-docs/publish/mcp-analytics.sections/related-reading.md

@@ -0,0 +1,36 @@
+---
+id: guide.mcp-analytics
+title: Measure MCP tool usage
+summary: Send optional server events to your analytics service without changing
+  the documentation tools.
+type: how-to
+area: discovery
+subarea: discovery-mcp
+canonical: /publish/mcp-analytics
+---
+
+# Measure MCP tool usage
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > MCP > Measure MCP tool usage
+
+**Updated: 2026-10-26.**
+
+Parent page: [Full Markdown page](/publish/mcp-analytics.md)
+
+Add a server adapter to measure calls to your [HTTP MCP endpoint](https://www.shoalrun.com/publish/mcp.md). Analytics is off by default. Enabling MCP does not enable tracking, and the browser analytics setting does not count tool calls.
+
+Your adapter chooses the service and sends the events. Shoalrun packages it for Node or the generated Vercel function. This setting does not instrument stdio, direct Markdown requests, or browser page views.
+
+## Related reading
+
+### Read first
+
+- [Connect an MCP client](https://www.shoalrun.com/publish/mcp.md) — Enable and verify the HTTP endpoint before adding analytics.
+
+### Related topics
+
+- [Bring your own analytics](https://www.shoalrun.com/author/analytics.md) — Collect browser interactions through the separate browser adapter.

package/agent-docs/publish/mcp-analytics.sections/safeguards-and-limits.md

@@ -0,0 +1,46 @@
+---
+id: guide.mcp-analytics
+title: Measure MCP tool usage
+summary: Send optional server events to your analytics service without changing
+  the documentation tools.
+type: how-to
+area: discovery
+subarea: discovery-mcp
+canonical: /publish/mcp-analytics
+---
+
+# Measure MCP tool usage
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > MCP > Measure MCP tool usage
+
+**Updated: 2026-10-26.**
+
+Parent page: [Full Markdown page](/publish/mcp-analytics.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Read first**
+
+- [Connect an MCP client](https://www.shoalrun.com/publish/mcp.md) — Enable and verify the HTTP endpoint before adding analytics.
+
+Add a server adapter to measure calls to your [HTTP MCP endpoint](https://www.shoalrun.com/publish/mcp.md). Analytics is off by default. Enabling MCP does not enable tracking, and the browser analytics setting does not count tool calls.
+
+Your adapter chooses the service and sends the events. Shoalrun packages it for Node or the generated Vercel function. This setting does not instrument stdio, direct Markdown requests, or browser page views.
+
+## Safeguards and limits
+
+If you need caller opt-in, the optional [`mcp.analytics.consent` header gate](https://www.shoalrun.com/config.md) records only calls with a matching header. Other callers can still use the tools. Leave it omitted for collection without client setup.
+
+The PostHog example builds each outbound event from allowed fields. It includes tool name, duration, outcome, build/publication identity, and validated public page or section IDs. Optional harness labels come from known names; optional model labels must appear in the fixed registry.
+
+The adapter drops raw arguments, search text, responses, headers, IP properties, error messages, and arbitrary event fields. It disables exception autocapture, requests no person profiles, and disables GeoIP enrichment. These controls apply to analytics delivery, not the documentation response or infrastructure access logs.
+
+Conversation and session IDs support grouping when enabled. They are pseudonymous identifiers, not proof that data is anonymous or that a particular person made the call. Leave grouping off when aggregate tool counts are enough. Never use client labels or intent categories for authentication or billing.
+
+Check PostHog’s **Settings → Project → IP data capture configuration → Discard client IP data** setting as an additional storage control. A network service still receives the source IP of its connection; this server adapter must not forward the caller’s IP. Hosting logs and other services need their own review. See [PostHog storage controls](https://posthog.com/docs/privacy/data-storage).
+
+Test the final delivered payload with a local receiver before changing the adapter or upgrading its SDK. Include names, emails, credentials, URLs, and private text in test arguments and metadata; verify they are absent from captured events. Public page IDs remain useful for usage analysis without recording the agent’s search or explanation. These safeguards do not establish a legal basis for collection or guarantee that all infrastructure stores no personal data.

package/agent-docs/publish/mcp.md

@@ -0,0 +1,190 @@
+---
+id: guide.mcp
+title: Connect an MCP client
+summary: Connect read-only MCP clients over stdio or HTTP to search and read
+  built documentation.
+type: how-to
+area: discovery
+subarea: discovery-mcp
+canonical: /publish/mcp
+---
+
+# Connect an MCP client
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > MCP > Connect an MCP client
+
+**Updated: 2026-10-27.**
+
+Connect an MCP client to built documentation through four read-only tools. Use stdio for a client-launched local process, or enable an HTTP endpoint on Node or in a generated Vercel function. Both use the same search and Markdown reading core.
+
+The HTTP endpoint currently supports one explicitly selected public publication. The generated Vercel endpoint is deployed and verified on this site. Netlify and Cloudflare adapters are not implemented. Analytics is off by default; an optional [server adapter](https://www.shoalrun.com/publish/mcp-analytics.md) can measure tool calls.
+
+You need Node.js 22.12 or newer, the installed Shoalrun CLI, and a client that supports MCP stdio or Streamable HTTP. Follow [Getting started](https://www.shoalrun.com/start.md) to install the public npm package.
+
+## Why offer MCP for public docs?
+
+MCP gives tool-capable agents a predictable way to search your docs and request a page or section within a token budget. For example, an agent answering “How do I configure analytics?” can search and follow the returned read instruction. The result includes relevant Markdown, its publication, and a source link.
+
+The documentation can already be public. MCP adds a tool interface; it does not grant access that public Markdown lacks. Agents that can fetch and search your Markdown may not need it. Offer both when your readers use MCP clients, and check whether the tools help them find answers with fewer requests or less content.
+
+To use Shoalrun's own live documentation endpoint, follow [use this site's MCP](https://www.shoalrun.com/connect/mcp.md). The setup below is for hosting your own project's tools.
+
+## Serve a public endpoint on Node
+
+Use this procedure when agents should connect to a URL instead of launching the CLI themselves. Analytics is not enabled by this setting.
+
+1. ### Enable a public publication
+
+   Add the endpoint and the exact channel, version, and language to your project config. The selected publication must contain public pages:
+
+   ```yaml title="docs.config.yaml"
+   mcp:
+     enabled: true
+     access: public
+     path: /mcp
+     publication: { channel: production, version: current, language: en }
+   ```
+
+   The endpoint supplies those publication coordinates when the client omits them. Requests for a different publication are rejected. Its lexical search index is generated even if browser search is disabled.
+
+2. ### Build and serve the site
+
+   With the CLI available as `shoalrun`, build the output and start the Node server:
+
+   ```sh
+   shoalrun build docs.config.yaml dist
+   shoalrun serve dist --port 8774
+   ```
+
+   The server reads the MCP settings from that build. It does not need the source config. With no site base path, the local endpoint is `http://127.0.0.1:8774/mcp`; a base path such as `/docs` makes it `/docs/mcp`.
+
+   Set `mcp: false` or remove the setting and rebuild to disable the endpoint. Restart a non-watching server after replacing its build; watched preview reloads settings with each successful build.
+
+3. ### Connect and check the tools
+
+   Add the endpoint URL in your client’s remote MCP settings. The client should discover the four tools listed below. Search for a known page, then follow the returned read instruction and verify its publication.
+
+   The SDK integration is tested with legacy and automatic protocol negotiation using MCP TypeScript client version `2.2.0`. Compatibility with a specific desktop client or public host still needs its own check.
+
+### Hosts, origins, and limits
+
+Local connections permit the configured loopback host. For a public Node deployment, `site.origin` supplies a trusted hostname and browser origin. Add explicit `mcp.allowedHosts` hostnames for other domains and `mcp.allowedOrigins` origins for browser-based clients. Forwarded host headers are not trusted. Native clients do not need an Origin header.
+
+The endpoint accepts JSON MCP requests through POST; it does not provide a persistent session or standalone event stream. GET and DELETE return 405. Browser preflight uses OPTIONS.
+
+Limits are 64 KiB per request, eight concurrent requests per handler, and a 15-second deadline. Excess concurrent requests return 429 with retry guidance. Tool token budgets still apply. These are process-local controls; configure deployment-level limits before exposing a public service. This is a public endpoint, not an authentication mechanism for private documentation.
+
+## Generate a Vercel endpoint
+
+With the public MCP configuration above, generate deployment output from your project:
+
+```sh
+shoalrun vercel build docs.config.yaml .vercel/output
+```
+
+No extra MCP flag, Ask configuration, embeddings, or model key is required. The command packages the four tools and their selected public documentation in a Node function at the configured endpoint. Internal runtime files stay out of the public static output. Follow [Publish on Vercel](https://www.shoalrun.com/publish/vercel.md) to deploy the complete output directory.
+
+The function trusts `site.origin`, explicit allowed hosts, and Vercel’s reserved deployment host variables. It does not trust arbitrary forwarded hosts or other projects’ preview domains. Deployment protection may block an MCP client from reaching a preview; check that host setting if a client cannot connect.
+
+Returned Markdown links use the URLs generated at build time. Set the intended origin before building; request headers do not rewrite the documentation identity. Per-instance limits are not global deployment limits. Configure host-level traffic controls before opening a public endpoint.
+
+Local package tests cover SDK clients and the generated function. Read-only SDK calls have also been verified at this site’s production Vercel endpoint. Named desktop-client checks remain separate.
+
+## Choose the documentation source
+
+From your documentation project with the CLI installed, start a server for Shoalrun's bundled documentation:
+
+```sh
+npx --no-install shoalrun docs mcp
+```
+
+For your site's documentation, build it first and pass the output directory. The following example runs from your documentation project root:
+
+```sh
+npx --no-install shoalrun build docs.config.yaml site-dist
+npx --no-install shoalrun docs mcp --site site-dist
+```
+
+Search needs `search-index.json`; page reads need `documents.json` and the generated Markdown files. The server does not rebuild the site or fetch remote pages. Rebuild after editing your site's sources. The shared core reads the built files on each call.
+
+## Configure the client
+
+Enter a stdio server command and arguments in your client's MCP settings. Use absolute paths to your installed package and built site so the client's working directory does not affect resolution:
+
+```json
+{
+  "command": "node",
+  "args": [
+    "/absolute/path/to/my-docs/node_modules/@shoalrun/cli/dist/cli.js",
+    "docs",
+    "mcp",
+    "--site",
+    "/absolute/path/to/my-docs/site-dist"
+  ]
+}
+```
+
+This is the server entry; the surrounding configuration differs by client. Omit `--site` and its directory to use the bundled Shoalrun docs. Once the CLI is linked or installed locally, the command can instead be `shoalrun` with arguments `docs`, `mcp`, and the optional site selection.
+
+Standard output contains only MCP protocol messages. Diagnostics go to standard error. The process waits for requests and exits when the client closes its input.
+
+## Search, then read
+
+Ask the client to discover the server's tools. It should find:
+
+| Tool          | Required input  | Optional inputs                                        | Result                                                              |
+| ------------- | --------------- | ------------------------------------------------------ | ------------------------------------------------------------------- |
+| `search_docs` | `query`         | `limit`, `maxTokens`, `channel`, `version`, `language` | Ranked document IDs, links, summaries, and excerpts.                |
+| `get_page`    | `id`            | `maxTokens`, `channel`, `version`, `language`          | The page's generated Markdown and publication metadata.             |
+| `get_outline` | `id`            | `maxTokens`, `channel`, `version`, `language`          | Top-level section IDs, fetch URLs, digests, and sizes.              |
+| `get_section` | `id`, `section` | `maxTokens`, `channel`, `version`, `language`          | One complete section with parent context and nested reader content. |
+
+For example, call `search_docs` with `{"query":"search provider","limit":5,"maxTokens":2048}`, choose a result, and call its `read.tool` with its `read.arguments` exactly. Choose a publication when the index or document ID spans multiple channels, versions, or languages. The server refuses to mix publications.
+
+Search uses the same lexical ranking as the CLI. Titles, summaries, and headings are searchable; article text is bounded. See [search index coverage](https://www.shoalrun.com/author/search.md). The page tool returns generated Markdown, including all reader-marked sections. Reader views remain visibility controls, not access controls.
+
+Search supplies the next call: `read.tool` is `get_section` for a unique matching section, or `get_page` otherwise. Its arguments include the ID, publication, section ID when needed, and a token budget based on the indexed size. Do not guess section IDs or call `get_outline` first. Check `budget.truncated` after a page read and increase the budget if needed.
+
+The result's `markdownUrl` fetches the recommended content directly; `pageMarkdownUrl` always fetches the full page. Use the full page when the section does not answer the question or needs more context. Search prefers the full page for short documents, broad queries, ambiguous headings, or queries spanning multiple sections. Search normally prefers complete lexical matches. With no complete match, results within one meaningful term of the best coverage (at least two matched terms) rank by non-filler field score first. A stronger result missing one meaningful term can outrank complete matches found only in body text; `matchMode: mixed` identifies that case. See [search ranking](https://www.shoalrun.com/author/search.md). A section recommendation also requires an explicit author declaration that its content and repeated introduction are self-contained. Undeclared sections use full-page reads, including indexes built before this declaration existed. The compiler checks heading identity, not prerequisite completeness. `get_outline` remains available for deliberate browsing. Retain publication coordinates and parent/section digests for citations. See [section resources](https://www.shoalrun.com/author/markdown-metadata.md).
+
+## Check budgets and errors
+
+All tools default to `maxTokens: 4096` and accept 256 through 100000. Search defaults to eight results; `limit` accepts 1 through 100.
+
+Successful results include `budget.maxTokens`, `budget.encoding`, `budget.tokens`, and `budget.truncated`. The budget covers the serialized JSON tool payload, including page or search metadata, using the `cl100k_base` tokenizer. `tokens` is a conservative count for that payload. It does not include the MCP envelope or the client's own prompts, and other models can tokenize the same text differently. MCP returns the payload as both text and structured data; the budget applies to one payload, rather than both copies together.
+
+Search drops lower-ranked results to fit. Page reads return a prefix of the Markdown; that prefix can end inside a section or code block. Check `truncated`, then increase the budget if needed. Outline and section reads instead require the complete result to fit; they never truncate code blocks. There is no pagination yet. For pages larger than the maximum budget, fetch their published Markdown directly. If even the metadata cannot fit, the tool reports `invalid_input`.
+
+| Error code        | Meaning                                                      | Next action                                       |
+| ----------------- | ------------------------------------------------------------ | ------------------------------------------------- |
+| `invalid_input`   | Empty query or ID, invalid budget, or ambiguous publication. | Correct the input or choose a publication.        |
+| `unknown_section` | Section ID is absent from the selected page.                 | Request its current outline.                      |
+| `unknown_page`    | The stable ID does not exist in the manifest.                | Search for the page's ID.                         |
+| `missing_index`   | The required search index or manifest is absent.             | Build the site with the required outputs.         |
+| `internal_error`  | Built metadata or a page file cannot be read correctly.      | Rebuild the documentation and inspect the output. |
+
+Tool failures set MCP `isError` and return a structured `error` with `code` and `message`. Protocol or schema validation failures may be reported by the MCP SDK before the documentation core runs. An ordinary search with no matches succeeds with an empty result list.
+
+## Verify the connection
+
+Search for a known page, read the returned ID, and inspect its Markdown. Then request a nonexistent ID: it should return `unknown_page` without stopping the server. Confirm that a small budget sets `truncated` on a long page. These checks exercise the source selection and tool contract without an agent harness.
+
+The tools are read-only and do not expose authoring commands. Stdio makes them available to a local tool-capable client; clients that cannot launch a local process cannot use this transport. They can read published Markdown over HTTP when their tools support fetching URLs. Stdio has no analytics adapter. The optional HTTP adapter records tool outcomes without raw queries.
+
+## Related reading
+
+### Next steps
+
+- [Measure MCP tool usage](https://www.shoalrun.com/publish/mcp-analytics.md) — Optionally measure tool calls through a server adapter.
+
+### Reference while working
+
+- [CLI reference](https://www.shoalrun.com/cli.md) — Look up shared search and read flags and error behavior.
+
+### Related topics
+
+- [Agent-friendly documentation](https://www.shoalrun.com/publish/agent-friendliness.md) — Understand the published Markdown and discovery surfaces alongside MCP.

package/agent-docs/publish/mcp.sections/check-budgets-and-errors.md

@@ -0,0 +1,52 @@
+---
+id: guide.mcp
+title: Connect an MCP client
+summary: Connect read-only MCP clients over stdio or HTTP to search and read
+  built documentation.
+type: how-to
+area: discovery
+subarea: discovery-mcp
+canonical: /publish/mcp
+---
+
+# Connect an MCP client
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > MCP > Connect an MCP client
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/publish/mcp.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Measure MCP tool usage](https://www.shoalrun.com/publish/mcp-analytics.md) — Optionally measure tool calls through a server adapter.
+
+Connect an MCP client to built documentation through four read-only tools. Use stdio for a client-launched local process, or enable an HTTP endpoint on Node or in a generated Vercel function. Both use the same search and Markdown reading core.
+
+The HTTP endpoint currently supports one explicitly selected public publication. The generated Vercel endpoint is deployed and verified on this site. Netlify and Cloudflare adapters are not implemented. Analytics is off by default; an optional [server adapter](https://www.shoalrun.com/publish/mcp-analytics.md) can measure tool calls.
+
+You need Node.js 22.12 or newer, the installed Shoalrun CLI, and a client that supports MCP stdio or Streamable HTTP. Follow [Getting started](https://www.shoalrun.com/start.md) to install the public npm package.
+
+## Check budgets and errors
+
+All tools default to `maxTokens: 4096` and accept 256 through 100000. Search defaults to eight results; `limit` accepts 1 through 100.
+
+Successful results include `budget.maxTokens`, `budget.encoding`, `budget.tokens`, and `budget.truncated`. The budget covers the serialized JSON tool payload, including page or search metadata, using the `cl100k_base` tokenizer. `tokens` is a conservative count for that payload. It does not include the MCP envelope or the client's own prompts, and other models can tokenize the same text differently. MCP returns the payload as both text and structured data; the budget applies to one payload, rather than both copies together.
+
+Search drops lower-ranked results to fit. Page reads return a prefix of the Markdown; that prefix can end inside a section or code block. Check `truncated`, then increase the budget if needed. Outline and section reads instead require the complete result to fit; they never truncate code blocks. There is no pagination yet. For pages larger than the maximum budget, fetch their published Markdown directly. If even the metadata cannot fit, the tool reports `invalid_input`.
+
+| Error code        | Meaning                                                      | Next action                                       |
+| ----------------- | ------------------------------------------------------------ | ------------------------------------------------- |
+| `invalid_input`   | Empty query or ID, invalid budget, or ambiguous publication. | Correct the input or choose a publication.        |
+| `unknown_section` | Section ID is absent from the selected page.                 | Request its current outline.                      |
+| `unknown_page`    | The stable ID does not exist in the manifest.                | Search for the page's ID.                         |
+| `missing_index`   | The required search index or manifest is absent.             | Build the site with the required outputs.         |
+| `internal_error`  | Built metadata or a page file cannot be read correctly.      | Rebuild the documentation and inspect the output. |
+
+Tool failures set MCP `isError` and return a structured `error` with `code` and `message`. Protocol or schema validation failures may be reported by the MCP SDK before the documentation core runs. An ordinary search with no matches succeeds with an empty result list.

package/agent-docs/publish/mcp.sections/choose-the-documentation-source.md

@@ -0,0 +1,51 @@
+---
+id: guide.mcp
+title: Connect an MCP client
+summary: Connect read-only MCP clients over stdio or HTTP to search and read
+  built documentation.
+type: how-to
+area: discovery
+subarea: discovery-mcp
+canonical: /publish/mcp
+---
+
+# Connect an MCP client
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > MCP > Connect an MCP client
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/publish/mcp.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Measure MCP tool usage](https://www.shoalrun.com/publish/mcp-analytics.md) — Optionally measure tool calls through a server adapter.
+
+Connect an MCP client to built documentation through four read-only tools. Use stdio for a client-launched local process, or enable an HTTP endpoint on Node or in a generated Vercel function. Both use the same search and Markdown reading core.
+
+The HTTP endpoint currently supports one explicitly selected public publication. The generated Vercel endpoint is deployed and verified on this site. Netlify and Cloudflare adapters are not implemented. Analytics is off by default; an optional [server adapter](https://www.shoalrun.com/publish/mcp-analytics.md) can measure tool calls.
+
+You need Node.js 22.12 or newer, the installed Shoalrun CLI, and a client that supports MCP stdio or Streamable HTTP. Follow [Getting started](https://www.shoalrun.com/start.md) to install the public npm package.
+
+## Choose the documentation source
+
+From your documentation project with the CLI installed, start a server for Shoalrun's bundled documentation:
+
+```sh
+npx --no-install shoalrun docs mcp
+```
+
+For your site's documentation, build it first and pass the output directory. The following example runs from your documentation project root:
+
+```sh
+npx --no-install shoalrun build docs.config.yaml site-dist
+npx --no-install shoalrun docs mcp --site site-dist
+```
+
+Search needs `search-index.json`; page reads need `documents.json` and the generated Markdown files. The server does not rebuild the site or fetch remote pages. Rebuild after editing your site's sources. The shared core reads the built files on each call.

package/agent-docs/publish/mcp.sections/configure-the-client.md

@@ -0,0 +1,55 @@
+---
+id: guide.mcp
+title: Connect an MCP client
+summary: Connect read-only MCP clients over stdio or HTTP to search and read
+  built documentation.
+type: how-to
+area: discovery
+subarea: discovery-mcp
+canonical: /publish/mcp
+---
+
+# Connect an MCP client
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > MCP > Connect an MCP client
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/publish/mcp.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Measure MCP tool usage](https://www.shoalrun.com/publish/mcp-analytics.md) — Optionally measure tool calls through a server adapter.
+
+Connect an MCP client to built documentation through four read-only tools. Use stdio for a client-launched local process, or enable an HTTP endpoint on Node or in a generated Vercel function. Both use the same search and Markdown reading core.
+
+The HTTP endpoint currently supports one explicitly selected public publication. The generated Vercel endpoint is deployed and verified on this site. Netlify and Cloudflare adapters are not implemented. Analytics is off by default; an optional [server adapter](https://www.shoalrun.com/publish/mcp-analytics.md) can measure tool calls.
+
+You need Node.js 22.12 or newer, the installed Shoalrun CLI, and a client that supports MCP stdio or Streamable HTTP. Follow [Getting started](https://www.shoalrun.com/start.md) to install the public npm package.
+
+## Configure the client
+
+Enter a stdio server command and arguments in your client's MCP settings. Use absolute paths to your installed package and built site so the client's working directory does not affect resolution:
+
+```json
+{
+  "command": "node",
+  "args": [
+    "/absolute/path/to/my-docs/node_modules/@shoalrun/cli/dist/cli.js",
+    "docs",
+    "mcp",
+    "--site",
+    "/absolute/path/to/my-docs/site-dist"
+  ]
+}
+```
+
+This is the server entry; the surrounding configuration differs by client. Omit `--site` and its directory to use the bundled Shoalrun docs. Once the CLI is linked or installed locally, the command can instead be `shoalrun` with arguments `docs`, `mcp`, and the optional site selection.
+
+Standard output contains only MCP protocol messages. Diagnostics go to standard error. The process waits for requests and exits when the client closes its input.