feat(docs): doc-sections system, crdt package, MCP server, and responsive fixes

Adds a hand-authored .vue doc-sections system (intro + guide pages per package, #docs/sections map, sidebar Guide group, client-side TOC), registers @robonen/crdt, renders demos client-only, base64-encodes the server-metadata virtual, plus the MCP docs endpoint and responsive/overflow fixes across pages and tables.
2026-06-08 15:52:03 +07:00
parent def1db8b6c
commit 09433415b6
23 changed files with 1107 additions and 35 deletions
@@ -0,0 +1,65 @@
+# Docs MCP server
+
+An [MCP](https://modelcontextprotocol.io) server that exposes the `@robonen/tools`
+documentation to any MCP client (Claude Code, Claude Desktop, Cursor, …).
+
+It is **served by the Nuxt/Nitro docs server itself** — there is no separate
+process. The documentation metadata is the same data that renders the docs site
+(produced by [`../extractor`](../extractor) at build time and injected into Nitro
+as the `#docs/server-metadata` virtual), so what an agent reads is always in sync
+with the site.
+
+## Run
+
+Start the docs server, and the MCP endpoint comes up with it:
+
+```sh
+pnpm docs:dev      # → http://localhost:3000, MCP at http://localhost:3000/mcp
+```
+
+`POST /mcp` speaks the MCP **Streamable HTTP** transport (stateless, JSON
+responses). The route lives at [`../../server/routes/mcp.post.ts`](../../server/routes/mcp.post.ts).
+
+## Register with a client
+
+A project-scoped [`.mcp.json`](../../../.mcp.json) at the repo root already points
+Claude Code at the endpoint — start the docs server, then approve the
+`robonen-docs` server:
+
+```json
+{
+  "mcpServers": {
+    "robonen-docs": { "type": "http", "url": "http://localhost:3000/mcp" }
+  }
+}
+```
+
+## Tools
+
+| Tool            | Arguments                       | Returns                                                                 |
+| --------------- | ------------------------------- | ----------------------------------------------------------------------- |
+| `list_packages` | —                               | Every documented package grouped by core / vue / configs / infra.       |
+| `search_docs`   | `query`, `limit?`               | Ranked `package/slug` matches across items, components and guides.      |
+| `get_package`   | `slug`                          | A package's table of contents (categories, components or sections).     |
+| `get_doc`       | `package`, `name`               | Full reference for one item: signatures, params, examples, props/emits. |
+
+`name` accepts either the URL slug (`use-clipboard`) or the exported name
+(`useClipboard`). Slugs are unique within a package; case-only collisions (e.g.
+the `useProjection` function vs the `UseProjection` type) are disambiguated with
+a kind suffix (`use-projection-type`).
+
+## Resources
+
+- `robonen-docs://index` — the documentation index.
+- `robonen-docs://{package}/{slug}` — full Markdown for a single documented item
+  (listable, one entry per leaf).
+
+## Layout
+
+| File                                  | Responsibility                                                          |
+| ------------------------------------- | ----------------------------------------------------------------------- |
+| `../../server/routes/mcp.post.ts`     | Nitro HTTP route — bridges the request to the MCP transport.            |
+| `create-server.ts`                    | Builds the configured `McpServer` (tools + resources) from metadata.   |
+| `docs-index.ts`                       | Pure query layer — flatten, unique-slug, search, resolve.              |
+| `format.ts`                           | Markdown renderers for tool/resource payloads.                          |
+| `*.test.ts`                           | Unit tests for the query layer.                                         |