Docs-Agent - AI for Continuous Tech Docs Improvement

Helping technical writers, engineering managers, and Open Source authors maintain a technically accurate and comprehensive documentation. Available as MCP server, HTTP APIs, and Node.js Library.

Built on Diataxis: This project implements the Diataxis Documentation Framework created by Daniele Procida. Diataxis is a systematic approach to technical documentation authoring. This approach is followed by Canonical/Ubuntu, Python, Cloudflare, JupyterHub, Gatsby, etc.

Features

Docs-Agent leverages AI to find and fix issues related to comprehensiblity or technical accuracy.

• 🔍 Audit docs against source code for technical accuracy
• 📝 Auto-fix outdated content that's out of sync from the source code
• 🤖 AI-powered analysis with human oversight
• 🔗 Enhance internal linking between docs pages and concepts
• 🎯 Improve comprehensibility following Diataxis Documentation Framework principles (you may override it)
• 🔍 Code auditing capabilities to validate documentation against source
• 🔒 Path traversal protection with different access controls for API vs MCP modes

Docs-Agent does not expect its users to learn the details of the Diataxis Documentation Framework

Neither Diataxis, nor Docs-Agent impose any rigid rules, rather Docs-Agent uses the analytical approach provided by Diataxis that emerges from identifying four core user needs which naturally fall into four patterns (tutorials, how-tos, reference, explanation).

Quickstart

You may use the Docs-Agent at any of the following three different levels of autonomy vs quality

1. (Recommended) In AI IDEs (e.g. Cursor) as MCP server - Best combination of quality and control
2. In Cursor as rules - Low quality results and potentially negative productivity benefits in some cases
3. In your systems integrated using HTTP API or Node.js library - Can be made fully autonomous, but takes significant efforts compared to the AI IDE approach

Option 1 (Recommended): Docs-Agent MCP server + Cursor Custom Mode agent

Great quality and control. But not fully autonomous. Best AI <> Human collaborative experience.

To leverage Cursor's strength and overcome its limitations by delegating tasks to Docs-Agent MCP server.

• Cursor strength: great DX in reviewing and editing the AI suggested changes
• Cursor weakness: limited control over AI settings frequently results in seemingly correct but technically incorrect output
• Docs-Agent MCP strength: fine control over AI settings (e.g. temperature, top_p, etc.) and context results in more predictable and technically correct output. Also it is a great choice for extensibility (e.g. include non-ai ops as part of the workflow) and consistency.

Set up Docs-Agent MCP server

1. git clone https://github.com/rudderstack/docs-agent
2. npm install (use node v20+)
3. You may test the project by running npm test (e2e tests for each task, skips all tests except one at a time, it costs money), npm run mcp-list, and npm run mcp-run

Integrate Docs-Agent MCP server with Cursor Custom Mode

1. Add MCP Server to Cursor (.cursor/mcp.json)

   {
   "mcpServers": {
      "docs-agent": {
         "command": "/path/to/node",
         "args": ["/path/to/docs-agent/src/index.js"],
         "env": {
            "GITHUB_TOKEN": "github-token-is-needed-for-code-search",
            "REVIEW_AI_SERVICE": "gemini",
            "REVIEW_AI_MODEL": "gemini-2.5-pro-exp-03-25",
            "GOOGLE_GENERATIVE_AI_API_KEY": "secret-api-key",
            "ANTHROPIC_API_KEY": "secret-api-key",
            "ALLOW_DISRUPTIVE_CHANGES": "false",
            "OPENAI_API_KEY": "notinuse",
            "MAX_TOKENS": "8000",
            "MAX_CHANGES": "1",
            "API_DISABLED": "true",
            "MCP_DISABLED": "false",
            "PREFERRED_AI_SERVICE": "anthropic",
            "PREFERRED_AI_MODEL": "claude-3-5-sonnet-20240620",
            "OLLAMA_API_URL": "http://localhost:11434/api/generate",
            "OTEL_EXPORTER_OTLP_ENDPOINT": "https://api.braintrust.dev/otel",
            "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer <Your API Key>, x-bt-parent=project_id:<Your Project ID>"
         }
      }
   }
   }

   To start with, you only need following env variables - GITHUB_TOKEN, GOOGLE_GENERATIVE_AI_API_KEY, ANTHROPIC_API_KEY, MCP_DISABLED. Refer how to get the necessary secrets. Make sure MCP_DISABLED value is set to "false".
2. Enable Cursor Custom Mode - Cursor Settings > Chat (or Features) > Custom Modes (Beta)
3. Create your own Custom Mode (I name it Docs Agent) - Cursor chat box > Mode selection dropdown (where you see Agent by default) > Add custom mode. a. Choose the set of tools you'd want this mode to use. I get the best outcome by disabling Run (commands) tool, and enabling all other tools e.g. MCP, edit, and Search (excluding web search). b. Choose the choice of your model, I get the best outcome from Claude 3.5 Sonnet. c. Set a shortcut to quickly start this mode. I use Cmd+Shift+D on macOS and Ctrl+Shift+D ond other OS.
4. Set the prompt for the Custom mode. Check out this example prompt, it works well for me in Cursor's Custom Mode. You may further personalize it. If you want to pass on a specific file (e.g. your own docs rules) for all docs improvement requests to the MCP server as context, you may choose to specify the absolute path of that file in the prompt so that Cursor (or whichever AI IDE you use).

Option 2: Cursor rules

Lowest quality and impact on productivity, but fits in the current human workflow. Simply move the config folder content to .cursor/rules as .mdc files. No server required for this.

Option 3: Integrate with your own program using API or Node.js library (e.g. GitHub app)

It can be made completely autonomous + Optional feedback via your systems (e.g. GitHub issues)

You can integrate Docs Agent with your system either by using Docs Agent as an HTTP API or using as a Node.js library.

3.1: Integrating docs-agent as an API

1. git clone https://github.com/rudderstack/docs-agent
2. npm install (use node v20+)
3. cp env.example .env update var values (make sure API_DISABLED=false; GOOGLE_GENERATIVE_AI_API_KEY and ANTHROPIC_API_KEY values have valid API keys).
4. Make sure to add all webhook URLs to ALLOWED_WEBHOOK_URLS (comma separated list) where the Docs-Agent is supposed to send back the results when done. Optionally set RESULTS_WEBHOOK_KEY to authenticate webhook requests (sent as x-api-key header).
5. npm test (e2e tests for each task, skips all tests except one at a time, it costs money)
6. npm start

You should be now able to make HTTP requests to following endpoints:

• POST /review --data { content: "docs page code", filepath: "/path/to/file/to/edit", filename: "my.file.md", webhookUrl?: "https://your-app.com/webhook", webhookMetadata?: {...} } : Returns the improvement suggestions (must provide either the content or filepath). Optionally, provide webhookUrl to receive results via webhook POST request (requires ALLOWED_WEBHOOK_URLS configuration). If RESULTS_WEBHOOK_KEY is set, it will be sent as x-api-key header in the webhook request.
• POST /prioritize --data { content: "docs page code", review: "improvement suggestions" } - Returns the prioritized actionable instructions to improve docs incrementally
• POST /edit --data { content: "docs page code", editPlan: "specific tasks to improve docs" } - Returns new file content edited according to the edit plan
• GET /health - Returns health status and system information

For more details, check out reference documentation.

3.2: Integrating docs-agent as a Node.js library

1. Link this source code as a node.js package in your Node.js program
2. Call the neccessary functions as described in references

For more details, check out reference documentation.

Security

Docs-Agent implements comprehensive security measures to protect against common attacks:

• Path Traversal Protection: Prevents unauthorized file access with different controls per mode:
  • API Mode: Restricts file access to public/ subdirectory only
  • MCP Mode: Allows unrestricted local file access (relies on MCP client permissions and OS-level security)
  • Both Modes: Allow validated remote file access (GitHub/GitLab URLs only)
• SSRF Protection: Configurable allowlists for webhook URLs and remote file hosts
• API Authentication: Optional API key authentication for HTTP endpoints
• Input Validation: Comprehensive validation of file paths and URLs

For detailed security configuration, see docs/DEPLOYMENT.md.

Deployment

See the deployment guide for containerized, Compose, and bare‑metal instructions: docs/DEPLOYMENT.md

Architecture

1. Documentation Analysis Pipeline (Default: Gemini 2.5 Pro Exp)
   • Document parsing and structure analysis
   • Issue identification and categorization
   • Improvement planning and prioritization
   • Code auditing against source files
2. Documentation Editing/Generation Pipeline (Default: Claude 3.5 Sonnet)
   • Content generation based on approved plans
   • Code example creation and refinement
   • Ensuring documentation framework compatibility e.g. hugo markdownm
3. Workflow Orchestration
   • MCP Tools (reviewDocs, improveDocs, linkifyDocs, auditDocsAgainstCode)
   • REST APIs
   • GitHub webhook handling (Future/Community/Your-Own-App)
   • Issue and PR management (Future/Community/Your-Own-App)

How to get the necessary secrets

GitHub Personal Access Token

1. Go to GitHub Settings → Developer Settings → Personal Access Tokens
2. Click "Generate new token"
3. Set an expiration date and select required scopes (typically repo for repository access)
4. Copy the token immediately - GitHub only shows it once
5. Set as environment variable: GITHUB_TOKEN=your_token_here

Google Generative AI API Key

1. Visit Google AI Studio
2. Click "Get API Key"
3. Accept the Terms of Service
4. Your API key will be auto-generated
5. Store securely and set as: GOOGLE_GENERATIVE_AI_API_KEY=your_key_here

Anthropic API Key

1. Sign up at Anthropic Console
2. Go to Account Settings → API Keys
3. Click "Create Key" and provide a name
4. Copy and save immediately - you won't see it again
5. Set as environment variable: ANTHROPIC_API_KEY=your_key_here

FAQ

• Audit docs against source code and ensure technical accuracy
• Fix docs content that is out of sync from the source code
• Find comprehensibility and readability issues
• Align technical docs with the Diataxis framework principles (reference, tutorial, how to guides, explanation)
• Find deviations from the writing style and align it with your own principles
• Improve consistency and increase accurate usage of your own technical glossary
• Find and fix typo
• Find and fix broken links
• Improve internal linking of docs pages to other docs pages and concepts/glossary
• Validate documentation against actual source code implementation

A short chat message is all you need.

When using Docs-Agent as an MCP server in Cursor, simply open the docs page, and ask in plain English what you want to do The queries can be broad as well as specific. Some examples:

• improve this docs page
• audit this docs page against relevant source code
• improve linking of this page
• users complained about this docs page being too verbose, improve it

Incremental changes that can be reviewed under a min.

In the default mode, the Docs-Agent does not aim to improve everything in one go. That would make the life of humans harder to understand the changes and thus making it hard and even slow to bring positive change. Instead, Docs-Agent follows incremental approach - one tiny easy to review PR at a time. Once Docs-Agent finds the gaps in the documentation, it prioritizes one impactful change, and makes only the change that would be quick to review without much cognitive overload. For example: in order to align docs with Diataxis principles, it would require tonnes of changes to convert existing docs to different Diataxis types such as reference, tutotrial, how to, and explanation. When you ask Docs-Agent to improve any docs page, it will figure out the Diataxis type that current page closely matches with, how well it does in the following Diataxis principles for that type, and introduce one tiny change to align its content more with that type.

License

This project is licensed under the MIT License.

Credits

Diataxis Framework by Daniele Procida • diataxis.fr • Licensed under CC-BY-SA 4.0