The Problem: Stale Documentation for AI Agents
AI agents often struggle with outdated or mismatched documentation. An agent might be trained on API documentation that no longer aligns with the actual code it's interacting with. Providing documentation is a step, but it's crucial to reference the specific source code version. The newest documentation might not reflect the installed version, and vice-versa. This discrepancy can lead to incorrect actions, failed integrations, and a general lack of reliability for AI-powered tools.
Consider a developer onboarding an AI assistant to manage their project's infrastructure. If the AI relies on documentation for a cloud provider's API that has since been updated, or if it's referencing documentation for a feature that was deprecated in the specific version the developer is using, the AI's generated commands or advice will be flawed. This isn't a minor inconvenience; it's a fundamental breakdown in trust and functionality.
The Solution: tailwind-docs-mcp and hermes-docs-mcp
To address this, seppegadeyne developed two small, specialized TypeScript servers: tailwind-docs-mcp and hermes-docs-mcp. These servers are designed to provide AI agents with precise access to documentation corresponding to specific source versions, without the overhead of embedding services or vector databases.
tailwind-docs-mcp is tailored to read Tailwind CSS's documentation source directly. It parses the official documentation to ensure that any information provided to an agent accurately reflects the current state of Tailwind CSS. This is critical for developers who need to ensure their CSS configurations and utility class usage are up-to-date and compatible with the version of Tailwind they have installed.
hermes-docs-mcp takes a slightly different approach, prioritizing a local Hermes documentation tree. This means it first attempts to find documentation on the agent's local system. If it cannot find the necessary information locally, it falls back to fetching documentation from GitHub. This dual strategy ensures that the agent always has access to the most relevant documentation, whether it's a local, version-specific copy or the latest available online.
Core Functionality: Search, Retrieve, and Track
Both servers expose their functionality over MCP (Message Passing Control Protocol) stdio. This allows AI agents to communicate with them using a standardized, efficient message-passing interface. The core capabilities offered are:
- Search: Agents can query the documentation for specific terms, functions, or concepts. The servers are designed to return the most relevant results, not just incidental mentions.
- Retrieve: Once a relevant document or section is identified, agents can retrieve its full content. This provides the agent with the detailed information needed to perform its tasks.
- Keep Track: The underlying mechanism ensures that the documentation source is tied to a specific version. This prevents the agent from acting on outdated information, maintaining consistency and accuracy.
The engineering focus is not on complex AI models for understanding natural language, but on the robust parsing of documentation files and intelligent ranking of search results. The goal is to present the agent with high-quality, contextually relevant information derived directly from the source, ranking a useful page above a mere incidental mention. Furthermore, the servers incorporate logic to detect when their index might be stale, prompting updates when necessary.
Engineering Nuances: Parsing and Ranking
The real innovation in these servers lies in their ability to parse documentation effectively and rank results accurately. Unlike systems that rely on vector embeddings to find semantic similarities, these servers work with the structure and content of the documentation itself.
Parsing involves taking raw documentation files (e.g., Markdown, HTML) and transforming them into a structured format that can be easily queried. This might involve identifying headings, code blocks, parameter lists, and example usage. The accuracy of this parsing directly impacts the quality of the information retrieved.
Ranking is equally critical. A simple keyword search might return dozens of results, many of which are only tangentially related to the user's query. These servers aim to rank pages that provide comprehensive answers or definitions higher than those that merely mention the keyword in passing. This requires a deeper understanding of the documentation's hierarchy and the relationships between different sections.
The challenge of knowing when an index is stale is also significant. Documentation sources can change frequently. The servers need a mechanism to detect these changes—perhaps by monitoring file modification times, checking version control, or periodically re-syncing with their primary source—and update their internal indexes accordingly. This ensures that the agents are always working with the most current information available from the designated source.
Why This Matters: Precision over Abstraction
The approach taken by tailwind-docs-mcp and hermes-docs-mcp represents a move towards precision in how AI agents access and utilize information. Instead of relying on abstract representations like embeddings, which can sometimes lose nuance or introduce misinterpretations, these servers provide a direct link to the authoritative source. This is akin to a researcher citing primary source documents rather than relying solely on secondary summaries.
For developers integrating AI into their workflows, this means greater confidence in the AI's output. When an agent can retrieve information directly from the source code's documentation, the risk of errors due to outdated or misinterpreted data is significantly reduced. This architecture is particularly valuable in rapidly evolving technical domains where documentation changes frequently, such as front-end frameworks, cloud services, and programming language libraries.
The decision to forgo embedding services and vector databases also points to a pragmatic engineering choice. It simplifies the infrastructure required, reduces computational overhead, and potentially lowers latency. The focus remains on the core task: making accurate documentation accessible. This makes the solution lightweight and easier to deploy, especially for smaller projects or teams looking for efficient tooling.
What remains to be seen is how this model scales to documentation sets that are orders of magnitude larger or more complex than those for Tailwind or Hermes. The parsing and ranking algorithms, while effective for these specific cases, will undoubtedly face new challenges with broader, more intricate documentation structures.