diff --git a/docs/agents/introduction.mdx b/docs/agents/introduction.mdx new file mode 100644 index 00000000..0dcd6a2b --- /dev/null +++ b/docs/agents/introduction.mdx @@ -0,0 +1,75 @@ +--- +title: Agents +description: llms.txt dumps, and the pmndrs MCP server +sourcecode: docs/agents/introduction.mdx +nav: 16 +--- + + + Every site built with this generator also publishes machine-readable dumps of its content — and [docs.pmnd.rs](https://docs.pmnd.rs) serves them to agents over MCP. + + +## llms.txt + +As alternate content, we provide you [llms.txt](/llms.txt) and [llms-full.txt](/llms-full.txt). + +These URLs are linked in the HTML header as: + +```html + + +``` + +## MCP Server + +`llms-full.txt` is a whole documentation site in one file — too big to paste into an agent for a one-line question. So [docs.pmnd.rs](https://docs.pmnd.rs) also exposes it as an [MCP](https://modelcontextprotocol.io) server, which lets an agent read a table of contents first, then fetch the one page it needs. + +One endpoint for all libraries, over streamable HTTP: `https://docs.pmnd.rs/api/mcp`. It exposes: + +| kind | name | what it gives | +| -------- | ------------------------ | ------------------------------------------------------------------ | +| resource | `docs://pmndrs/manifest` | which libraries are served, and how to query them | +| resource | `docs://{lib}/index` | that library's pages, one `{path} - {title}` per line | +| tool | `get_page_content` | the markdown of a single page, given a `lib` + a `path` from the index | + +A typical round-trip — *"how do I use TypeScript with Zustand?"*: + +``` +read docs://zustand/index + → /learn/guides/beginner-typescript - Beginner TypeScript Guide +call get_page_content(lib="zustand", path="/learn/guides/beginner-typescript") + → the page, as markdown +``` + +Two pages transferred instead of the whole site. + +> [!TIP] +> +> [`pmndrs/claude-code-plugin`](https://github.com/pmndrs/claude-code-plugin) supports it natively +> +> ```sh +> /plugin marketplace add pmndrs/claude-code-plugin +> /plugin install pmndrs@pmndrs +> ``` + +For other clients, see the JSON config in the [MCP-server](https://docs.pmnd.rs) box on the home page. To poke at it by hand — see the resources, call the tool, read the raw JSON-RPC — run the official inspector: + +```sh +$ HOST=127.0.0.1 npx -y @modelcontextprotocol/inspector +``` + +In the web UI it opens: **Add Servers** › **Add manually**, transport `streamable-http`, URL `https://docs.pmnd.rs/api/mcp` (or your own `http://localhost:3000/api/mcp`), and flip the server's toggle to connect. + +![MCP Inspector connected to docs.pmnd.rs, previewing the react-three-fiber index resource](mcp-inspector.png) + +### Getting your library served + +Only libraries publishing a `/llms-full.txt` dump are served — the ones badged `MCP` on [docs.pmnd.rs](https://docs.pmnd.rs). To join them: + +1. **Publish the dump.** If your site is already built with this generator, bump it to a version shipping `/llms-full.txt` and redeploy. Otherwise, either migrate to this generator, or emit that file yourself with the same XML shape (`…`). +2. **Check it.** `curl -sI /llms-full.txt` must return `200`, and the body must contain `` entries. A missing dump makes the library's index resource fail loudly, on purpose. +3. **Flip the flag.** Open a PR on [pmndrs/docs](https://github.com/pmndrs/docs) setting `llms_full: true` on your entry in `libs` ([`src/app/page.tsx`](https://github.com/pmndrs/docs/blob/main/src/app/page.tsx)). That single flag drives the `MCP` badge, the `docs://{lib}/index` resource and the `get_page_content` enum. It takes effect once [docs.pmnd.rs](https://docs.pmnd.rs) is redeployed — every push to `main` does that. + +> [!NOTE] +> +> This is a one-off. Once served, **content** updates need no redeploy on either side: pages are fetched at request time and revalidated every 5 minutes. diff --git a/docs/agents/mcp-inspector.png b/docs/agents/mcp-inspector.png new file mode 100644 index 00000000..c16f0400 Binary files /dev/null and b/docs/agents/mcp-inspector.png differ diff --git a/docs/getting-started/introduction.mdx b/docs/getting-started/introduction.mdx index bd6ae7b8..631f333e 100644 --- a/docs/getting-started/introduction.mdx +++ b/docs/getting-started/introduction.mdx @@ -289,17 +289,4 @@ Then go to: http://localhost:3000 ## Agents -As alternate content, we provide you [llms.txt](/llms.txt) and [llms-full.txt](/llms-full.txt). - -These URLs are linked in the HTML header as: - -```html - - -``` - -## MCP Server - -```sh -$ npx -y @modelcontextprotocol/inspector -``` \ No newline at end of file +`llms.txt` dumps and the pmndrs MCP server moved to their own page: [Agents](/agents/introduction). diff --git a/docs/github-actions/introduction.mdx b/docs/github-actions/introduction.mdx index 391e8cf6..b72eaca5 100644 --- a/docs/github-actions/introduction.mdx +++ b/docs/github-actions/introduction.mdx @@ -1,6 +1,7 @@ --- title: Reusable GitHub Actions workflow description: Call from your CI +nav: 15 --- diff --git a/src/app/api/[transport]/route.ts b/src/app/api/[transport]/route.ts index 3f893a69..aa69aa64 100644 --- a/src/app/api/[transport]/route.ts +++ b/src/app/api/[transport]/route.ts @@ -128,8 +128,9 @@ Resources use the \`docs://\` URI scheme: ### Architecture - Built with \`mcp-handler\` for Vercel deployment -- Uses Server-Sent Events (SSE) transport at \`/api/sse\` -- HTTP streamable transport available at \`/api/mcp\` +- HTTP streamable transport at \`/api/mcp\` -- the only transport served. The legacy + SSE transport would need a Redis instance to relay messages, which this deployment + does not have, so \`/api/sse\` is not usable. - Documentation is parsed from XML-tagged full-text dumps (\`/llms-full.txt\`) ### Security @@ -146,7 +147,7 @@ Resources use the \`docs://\` URI scheme: ## Getting Started -1. Connect to the server at \`https://docs.pmnd.rs/api/mcp\` (or \`/api/sse\` for the legacy SSE transport) +1. Connect to the server at \`https://docs.pmnd.rs/api/mcp\` 2. Read \`docs://pmndrs/manifest\` to understand server capabilities 3. Access \`docs://{lib}/index\` to discover available documentation for a library 4. Request specific pages with \`get_page_content\` tool