DevDocs-MCP: Documentation Authority for AI Agents

1# DevDocs-MCP:  Documentation Authority for AI Agents
2 
3<table width="100%">
4<tbody width="100%" style="margin: 0 auto;">
5<tr>
6<td width="50%" align="center">
7<a href="https://glama.ai/mcp/servers/@madhan-g-p/devdocs-mcp">
8  <img height="130" src="https://glama.ai/mcp/servers/@madhan-g-p/devdocs-mcp/badge" />
9</a>
10</td>
11<td width="50%" align="center">
12<a href="https://registry.modelcontextprotocol.io/?q=io.github.madhan-g-p%2Fdevdocs-mcp">
13  <img height="180" src="./mcp_registry.png" />
14</a>
15</td>
16</tr>
17</tbody>
18</table>
19 
20> **Eliminate AI hallucinations with local, version-aware, and authoritative documentation.**
21 
22  DevDocs-MCP is a Model Context Protocol (MCP) server that provides version-pinned, deterministic documentation sourced from [DevDocs.io](https://devdocs.io) to AI assistants (Claude, RooCode, Cline, Copilot etc.). It acts as a local Documentation Intelligence Layer, ensuring your agent always has the correct API context without network latency or training data drift. 
23 
24  This server follows the proposed MCP server standard defined by the [MCP](https://modelcontextprotocol.io/docs/getting-started/intro) , which is being adopted by AI tools and agents across the ecosystem, including those from providers such as Anthropic, OpenAI, and Google.
25 
26---
27 
28> ⚠️ **Project Status Notice** ⚠️
29> This project is under active and heavy development. Still need to test existing features and implement more new features like optimal caching , update latest doc automatically and also on request basis , optimal querying and more... Design decisions, APIs, and structure are expected to evolve based on strong opinions, reviews, and feedback from the developer community. I warmly welcome discussions, critiques, and contributions to help shape this project in the right direction.
30 
31---
32 
33## 📑 Table of Contents
34 
351. [Overview](#-overview)
362. [Key Capabilities](#-key-capabilities)
373. [Quickstart](#-quickstart)
384. [Installation & Setup](#-installation--setup)
395. [AI Agent Configuration](#-ai-agent-configuration)
406. [Further Reading](#-further-reading)
41 
42---
43 
44## 🎯 Overview
45 
46<details>
47<summary><b>What This Project Is</b></summary>
48 
49- A **local MCP server** written in NestJS (TypeScript).
50- A **deterministic authority** for documentation metadata and content.
51- A **lazy-ingestion engine** that caches DevDocs offline.
52- A **project-aware context manager** that pins docs to your `package.json` versions.
53 
54</details>
55 
56<details>
57<summary><b>What This Project Is NOT</b></summary>
58 
59- ❌ An AI agent or code generator.
60- ❌ A web scraper (it uses structured DevDocs datasets).
61- ❌ A DevDocs UI replacement.
62- ❌ A hosted SaaS (it runs 100% locally).
63 
64</details>
65 
66<details>
67<summary><b>Why This Exists (The Problem)</b></summary>
68 
69Modern AI coding agents face three major hurdles:
70 
711. **Hallucination**: Guessing API signatures or using deprecated methods.
722. **Latency**: Fetching live web docs for every query is slow.
733. **Version Drift**: Mixing up React 18 with React 19 features.
74 
75**The Solution**: DevDocs-MCP provides "Just-in-Time" documentation retrieved from local storage, filtered by your project's specific dependency versions.
76</details>
77 
78<details>
79<summary><b>Mental Model</b></summary>
80 
81DevDocs-MCP acts as a middleware between your IDE Agent and the documentation source.
82 
83```mermaid
84graph TD
85    Agent["AI Agents"] -->|MCP Search/Explain| Server["DevDocs-MCP Server"]
86    Server -->|Metadata| DB[(SQLite - sql.js)]
87    Server -->|Content| FS[Local Disk - JSON Cache]
88    Server -.->|Lazy Fetch| Web[DevDocs.io API]
89```
90 
91</details>
92 
93---
94 
95## 🚀 Key Capabilities
96 
97- **Offline-First**: Documentation is cached locally; no internet is needed after ingestion.
98- **Ranked Fuzzy Search**: Instantly find relevant entries (e.g., "intersection observer").
99- **Version Awareness**: Automatically maps to specific library versions in your project.
100- **Node-Only Architecture**: Uses `sql.js` for zero-native dependencies (no Python/C++ build steps).
101- **Structured Outputs**: Returns clean, LLM-optimized content.
102 
103---
104 
105## ⚡ Quickstart
106 
1071. **Clone & Install**
108 
109  ```bash
110  git clone https://github.com/madhan-g-p/DevDocs-MCP.git
111  cd DevDocs-MCP
112  pnpm install
113  ```
114 
1152. **Configure Environment**
116 
117  ```bash
118  cp .env.example .env
119  # Edit .env: Set DEVDOCS_DATA_PATH to where you want to store docs.
120  ```
121 
1223. **Build & Run**
123 
124  ```bash
125  pnpm build
126  pnpm start:prod
127  ```
128 
129> **Note:** Strictly use `pnpm` for development and contributions.
130 
131---
132 
133## 🛠️ Installation & Setup
134 
135DevDocs-MCP is optimized for zero-fuss setup with `pnpm`. It is a **Node-only** project.
136 
137### Prerequisites
138 
139- Node.js 18+ (tested on 18.x and 20.x).
140 
141### 🐳 Docker Usage
142 
143DevDocs-MCP is designed to be lightweight and persistent. Since it downloads and caches large documentation datasets, managing your data volumes correctly is essential.
144 
145#### Method A: Docker Compose (Dynamic & Persistent)
146This is the recommended way. It supports 3 storage modes via the `DEVDOCS_VOLUME_SOURCE` variable in your `.env` file.
147 
1481.  **Configure your preferred storage** in `.env`:
149    ```bash
150    # Mode 1: Named volume (Default - Docker manages it)
151    DEVDOCS_VOLUME_SOURCE=devdocs_data
152 
153    # Mode 2: Host Path (Outside Docker - Local folder)
154    # DEVDOCS_VOLUME_SOURCE=./my-docs-storage
155    ```
156 
1572.  **Start the server**:
158    ```bash
159    docker compose up -d
160    ```
161 
162> **Flexibility**: Every time you start the container, you can point to a **new volume** (to start fresh) or an **existing volume** (to keep your data) just by changing the `DEVDOCS_VOLUME_SOURCE` in your `.env` file. Both the `mcp.db` (database library) and the `data/` (documentation downloads) are stored inside this volume.
163 
164#### Method B: Docker Run (Manual)
165If you just want to run the public image directly from Docker Hub:
166 
167```bash
168docker run -d -p 3000:3000 \
169  -v "devdocs_data:/app/data" \
170  --name devdocs-mcp \
171  madhandock1/devdocs-mcp:latest
172```
173 
174#### 💾 Data Strategy
175The project uses a single mount point at `/app/data` which contains:
176- `/app/data/mcp.db`: The SQLite registry.
177- `/app/data/docs/`: The cached documentation files.
178This unified structure makes it easy to backup or move your entire documentation authority by simply moving one folder or volume.
179 
180 
181### Configuration (`.env`)
182 
183| Variable | Description | Default |
184| :--- | :--- | :--- |
185| `DEVDOCS_DATA_PATH` | Path to store downloaded documentation JSONs. | `./data` |
186| `MCP_DB_PATH` | Path to the SQLite metadata database. | `mcp.db` |
187| `LOG_LEVEL` | Verbosity (debug, info, warn, error). | `info` |
188 
189### Ingesting Documentation
190 
191Once the server is connected to your agent, use the `ingest` tool to download documentation for your specific stack:
192Agent will take care of it once the server is up and running , it is supposed to list the available to tools and take decision accordingly.
193 
194```json
195{
196  "dependencies": {
197    "react": "18.2.0",
198    "typescript": "5.0.0"
199  }
200}
201```
202>Note: The Devdocs fetch url required to be used for ingestion is defined in `src/config/constants.ts`. This URL currently points to the correct and officially supported path. If the [devdocs](https://github.com/freecodecamp/devdocs) community changes this path in future, the configuration may need to be updated accordingly.<br/>
203This approach does not involve web scraping. It follows the same supported mechanism used by DevDocs to provide documentation for [offline use](https://devdocs.io/settings), similar to how users download documentation within DevDocs itself.
204 
205---
206 
207## 🤖 AI Agent Configuration
208 
209### RooCode / Cline / Claude Desktop (Recommended: STDIO)
210 
211Add this to your `mcp_settings.json`. By setting the `cwd` (Current Working Directory), the server will automatically load configuration from your `.env` file, allowing you to use relative paths for data storage.
212 
213```json
214{
215  "mcpServers": {
216    "devdocs": {
217      "command": "node",
218      "args": ["dist/main.js"],
219      "cwd": "file://path/to/your/DevDocs-MCP"
220    }
221  }
222}
223```
224 
225> **Pro Tip**: Use the absolute path to the project in `cwd`. The server will then find your `.env` and use the `DEVDOCS_DATA_PATH` and `MCP_DB_PATH` you've defined there (e.g., `./data` or `mcp.db`), making the setup portable!
226 
227### Remote / Web Clients (HTTP SSE)
228 
229If you need to expose the server via a port (for production/remote setups):
230 
2311. **Start the server with a port flag**:
232   ```bash
233   node dist/main.js --port 3000
234   ```
2352. **Configure your client**:
236   - **SSE URL**: `http://your-server:3000/mcp/sse`
237   - **Type**: `SSE` (Supported by most MCP clients, atleast I guess so)
238 
239---
240 
241## 📖 Further Reading
242 
243- [**System Architecture**](ARCHITECTURE.md): Deep dive into the data flow, schema, and `sql.js` internals.
244- [**Contributor Guidelines**](CONTRIBUTING.md): Workflow, coding standards, and PR requirements.
245- [**LICENSE**](LICENSE): MIT License.
246 
247---
248*Inspired from this project [devdocs-local](https://github.com/whiteinge/dotfiles/blob/master/bin/devdocs-local) ,
249[devdocs-local-demo](https://eseth.org/2020/devdocs-cli.html) by [@Nathaniel Whiteinge](https://github.com/whiteinge)*
250