{"slug": "a-small-docs-mcp-server-search-retrieve-and-keep-track-of-the-source", "title": "A small docs MCP server: search, retrieve, and keep track of the source", "summary": "A developer built two small TypeScript MCP stdio servers, tailwind-docs-mcp and hermes-docs-mcp, that let AI agents search, retrieve, and list documentation pages without an embedding service or vector database. Each server exposes search, get, and list tools, with a source-specific MDX parser and a scorer that weights title and slug matches over body mentions and recognizes utility families like bg-red-500 for background-color. The developer notes search is a navigation step rather than a substitute for reading the full page, since snippets can omit warnings or conditions.", "body_md": "An agent can remember an API that no longer matches the project in front of it. Giving it documentation helps, but the source matters: the newest documentation and the documentation for an installed version are not necessarily the same.\n\nI use two small TypeScript servers to make that distinction explicit: [tailwind-docs-mcp](https://github.com/seppegadeyne/tailwind-docs-mcp) reads Tailwind's documentation source, while [hermes-docs-mcp](https://github.com/seppegadeyne/hermes-docs-mcp) prefers a local Hermes documentation tree and falls back to GitHub.\n\nBoth expose search, retrieval, and listing over MCP stdio. Neither needs an embedding service or vector database. The interesting engineering is in parsing the documentation, ranking a useful page above an incidental mention, and knowing when the index is stale.\n\nEach server has three tools:\n\n| Job | Tailwind | Hermes | \n|---|---|---|\n| Find candidate pages | `search_tailwind_docs` | `search_hermes_docs` | \n| Read one page | `get_tailwind_doc` | `get_hermes_doc` | \n| Browse available slugs | `list_tailwind_docs` | `list_hermes_docs` | \n\nSearch returns titles, slugs, source URLs, and snippets. The agent selects a slug and retrieves the page before answering. Listing helps when it does not know the right terminology; Hermes also supports filtering by section.\n\nI prefer this to returning an entire manual for every question. Search is a navigation step, though, not a substitute for reading the page. A snippet can omit a warning or the condition that makes an example valid.\n\nUnknown slugs return an MCP error with suggested matches. Neither server needs a tool that writes into the consuming project's files.\n\nTailwind's adapter reads MDX under `src/docs` in `tailwindlabs/tailwindcss.com`. It extracts exported titles and descriptions, headings, recognizable utility classes, and literal API-table rows. It removes selected MDX wrappers to produce Markdown-like content.\n\nThis is a source-specific parser, not an MDX runtime. It does not execute documentation components. Computed tables and unusual component syntax can lose information, and the cleanup can alter code-like expressions. Use the linked documentation page when exact presentation or a complete generated example matters.\n\nThe search scorer gives title and slug matches more weight than body mentions. It also recognizes utility families: a color utility such as `bg-red-500` gets a boost toward `background-color`.\n\nThat domain knowledge matters because many unrelated examples contain background classes. A plain text match can find a real occurrence on the wrong reference page.\n\nDuring verification, this call to `search_tailwind_docs` ranked `background-color` first:\n\n```\n{\"query\":\"bg-red-500 background\",\"limit\":3}\n```\n\nThen retrieve the selected page with `get_tailwind_doc`:\n\n```\n{\"slug\":\"background-color\"}\n```\n\nThose calls were executed against the pinned server. They show one working query, not a search-quality benchmark across the whole documentation set.\n\nYou need Git, npm, Node.js 20 or newer, and an MCP client that can launch stdio servers. GitHub access is needed for the default remote sources. A local documentation directory avoids those runtime fetches; Node and the server's npm dependencies are still required.\n\nThese are Bash commands for Linux, macOS, or WSL. Native Windows is not tested here. Start in a directory where you want the checkouts:\n\n```\ngit clone https://github.com/seppegadeyne/tailwind-docs-mcp.git\ncd tailwind-docs-mcp\ngit checkout --detach 072985944b26721d3c8d8161255fdde97da5f47e\nnpm ci --ignore-scripts\nnpm test\nnpm run build\ncd ..\n\ngit clone https://github.com/seppegadeyne/hermes-docs-mcp.git\ncd hermes-docs-mcp\ngit checkout --detach 0decc76d0d9a4f5b54ffa8b73c4dcc9f5d9c018b\nnpm ci --ignore-scripts\nnpm test\nnpm run build\n```\n\nThe locked installs and builds passed during verification on Linux with Node 25.2.1 and npm 11.6.2. Tailwind's three tests and Hermes's 15 tests passed. These suites check parser and search behavior using fixtures; the separate MCP smoke tests exercised discovery and real remote retrieval.\n\nIf you have not installed Hermes yet, my guide on Voltti walks through [installing Hermes with the desktop app or terminal](https://voltti.ai/en/insights/install-hermes-desktop-app-or-terminal). Return here once your client is ready; the configuration below connects it to the documentation servers.\n\nFor an existing Hermes client, merge the following into its configuration, using your own absolute paths. The syntax follows the [official MCP guide](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp).\n\n```\nmcp_servers:\n  tailwind-docs:\n    command: node\n    args: [\"/absolute/path/to/tailwind-docs-mcp/dist/cli.js\"]\n    timeout: 180\n    connect_timeout: 60\n    enabled: true\n  hermes-docs:\n    command: node\n    args: [\"/absolute/path/to/hermes-docs-mcp/dist/cli.js\"]\n    timeout: 180\n    connect_timeout: 60\n    enabled: true\n```\n\nCheck discovery before asking a model to use the tools:\n\n```\nhermes mcp test tailwind-docs\nhermes mcp test hermes-docs\n```\n\nDiscovery alone does not verify indexing: loading happens when a documentation tool is called. Follow it with the search and retrieval examples. Other clients need their own configuration format.\n\nHermes's adapter checks `HERMES_DOCS_DIR`, then its conventional local checkout location, and otherwise reads `website/docs` from `NousResearch/hermes-agent` on GitHub. Unlike the Tailwind local loader, the Hermes loader walks nested directories and accepts both Markdown and MDX.\n\nIt reads simple frontmatter metadata, derives slugs from paths, preserves fenced code, and converts Docusaurus admonitions into text markers. Its parser does not implement every frontmatter feature; a custom route declared in metadata is not necessarily the path-derived URL it returns.\n\nA local tree can correspond to the installed software, provided you point it at that installation and account for local modifications. The GitHub fallback follows `main`. It does not promise that the returned docs describe your installed release.\n\nThe fallback was exercised with an empty home directory and no local override. Search, retrieval, and listing succeeded. The actual list response began:\n\n```\nHermes Agent docs: 3 of 440 pages (installed commit unknown).\n```\n\nThat `unknown` matters. The current commit helper inspects a local Git checkout; it does not attach a resolved remote SHA to fallback content. The wording says “installed commit” even on the remote path. Do not interpret it as verified version provenance.\n\nFor a known page, this is the argument to `get_hermes_doc`:\n\n```\n{\"slug\":\"user-guide/features/mcp\"}\n```\n\nThe [Glama listing](https://glama.ai/mcp/servers/seppegadeyne/hermes-docs-mcp) provides discovery, not evidence of a successful hosted deployment. The standalone test establishes that the source loader works without a local Hermes checkout. Hosting still needs the runtime, a transport arrangement, and network access.\n\nBoth remote loaders cache their index in process memory without a time-based refresh. Restarting the process rebuilds it on the next request. Hermes caches its local index for 60 seconds; Tailwind rereads its local directory on each load.\n\nFor reproducible documentation, check out the upstream doc repository at a chosen commit and point the server at it. These are illustrative environment-variable examples; replace the paths with actual documentation directories and start the command from the corresponding server checkout:\n\n```\nTAILWIND_DOCS_DIR=/absolute/path/to/tailwindcss.com/src/docs npm start\nHERMES_DOCS_DIR=/absolute/path/to/hermes-agent/website/docs npm start\n```\n\nSet those variables in the client's server environment for normal MCP use. An explicitly configured but invalid Hermes directory fails locally rather than silently selecting GitHub.\n\nPinning the MCP adapter does not pin remotely fetched docs. The current loaders request the tree and individual files through moving `main` references, so an upstream change during indexing could mix revisions. They also fetch pages with `Promise.all`; they do not implement bounded concurrency or a persistent disk cache. A network failure can prevent the index from loading.\n\nStart with a normalized page record and tests for your source format. Preserve its URL, source path, and code examples. Build a small query set with expected reference pages, including terms that occur in many examples. The live Hermes query `mcp_servers`, for example, ranked a plugin guide first during verification. Lexical scoring is understandable, but it still needs evaluation.\n\nBefore distributing a corpus, check the documentation's own license and attribution requirements. Public source access is not a blanket redistribution license. Treat retrieved text as reference material, not instructions that grant the agent new permissions.\n\nFor a production adaptation, I would resolve one source SHA before fetching, report it with results, bound fetch concurrency, and define an explicit refresh policy. Those are improvements to make, not features to assume these versions already have.\n\nThe small tool surface is reusable. The parser, ranking rules, and version policy are the parts that need to fit the documentation you are serving.", "url": "https://wpnews.pro/news/a-small-docs-mcp-server-search-retrieve-and-keep-track-of-the-source", "canonical_source": "https://dev.to/seppegadeyne/a-small-docs-mcp-server-search-retrieve-and-keep-track-of-the-source-46h", "published_at": "2026-09-24 09:51:13+00:00", "updated_at": "2026-09-24 10:01:54.893709+00:00", "lang": "en", "topics": ["ai-agents", "agent-protocols", "developer-tools", "ai-tools"], "entities": ["tailwind-docs-mcp", "hermes-docs-mcp", "Tailwind CSS", "Hermes", "GitHub", "MCP", "Node.js", "TypeScript"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/a-small-docs-mcp-server-search-retrieve-and-keep-track-of-the-source", "markdown": "https://wpnews.pro/news/a-small-docs-mcp-server-search-retrieve-and-keep-track-of-the-source.md", "text": "https://wpnews.pro/news/a-small-docs-mcp-server-search-retrieve-and-keep-track-of-the-source.txt", "jsonld": "https://wpnews.pro/news/a-small-docs-mcp-server-search-retrieve-and-keep-track-of-the-source.jsonld"}}