doc-bot

An intelligent MCP (Model Context Protocol) server that gives AI assistants like Claude and Cursor deep understanding of your project through smart documentation management.

What is doc-bot?

doc-bot is a documentation server that enhances AI coding assistants by providing:

• 🧠 Smart search through your project documentation

• 📖 Contextual docs that surface guidance based on what you're working on

• 🔄 Live updates as your documentation changes

• 📚 API references from official documentation (via Docsets)

• 🤖 MCP tools for AI agents to query and understand your project

• ✍️ Agent-driven updates so new knowledge is captured in docs

Why doc-bot?

Traditional AI assistants have limited context windows and no understanding of your specific project. doc-bot solves this by:

1. Providing project-specific knowledge - Your conventions, patterns, and decisions

2. Searching intelligently - AI finds exactly what it needs without cluttering context

3. Scaling infinitely - Thousands of docs without token limits

4. Staying current - Live reload ensures AI always has latest information

How It Works

doc-bot acts as a bridge between your documentation and AI assistants:

When you ask your AI assistant to write code, it can:

1. Search for relevant documentation

2. Read project docs for patterns and examples

3. Find API references and examples

4. Update documentation when new patterns are discovered

Quick Start

1. Install doc-bot

Add doc-bot to your AI assistant's configuration:

For Claude Desktop or Claude Code:

Location of config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

For Cursor:

• Add an mcp.json file with the contents above to your .cursor folder

2. Create Your Documentation

Create a doc-bot folder in your project root and add markdown files:

3. Test it!

Ask your AI assistant: "What are the coding standards for this project?"

Versioning and Compatibility

doc-bot 2.0 is a breaking change. Rule enforcement is removed in favor of documentation-first guidance. As a legacy fallback, docs marked alwaysApply: true (or always_apply: true) are surfaced in the system prompt and get_file_docs results.

• If you need the legacy rule enforcement flow, pin to @afterxleep/doc-bot@1 or build from the 1.x branch.

• New installs should use the latest 2.x line (@afterxleep/doc-bot@latest).

Project Documentation

doc-bot treats your project documentation as a searchable knowledge base for AI assistants.

Agent-Driven Updates

doc-bot is designed for agents to keep documentation current as they work. When an assistant discovers a new pattern or a change, it can add or update docs directly:

Agent Documentation Loop

Use this fast loop to extend project knowledge and keep docs current:

1. Orient quickly: call doc_bot(task) or get_document_index() when the project is unfamiliar.

2. Find specifics: use search_documentation with concrete terms (API names, class names, errors).

3. Read the full context: open matches with read_specific_document or get_file_docs.

4. Capture new knowledge: when behavior changes or new patterns emerge, write it with create_or_update_rule.

5. Refresh when needed: if docs are edited manually, run refresh_documentation().

Keep docs short, scoped, and searchable with clear titles, keywords, and filePatterns.

Documentation Format

Create markdown files with frontmatter metadata:

Frontmatter Options

How Search Works

1. Intelligent Parsing - Queries are parsed, stop words removed

2. Multi-field Matching - Searches title, description, keywords, and content

3. Relevance Scoring - Results ranked by relevance (exact matches score highest)

4. Context Extraction - Returns snippets showing matched content

doc-bot surfaces documentation for agents; it does not enforce rules. Docs marked alwaysApply: true are always surfaced for agents. Agents should update docs when new patterns or changes appear.

Types of Documentation

General Documentation

Contextual Documentation

Searchable References

Docsets (API Documentation)

doc-bot can also search official API documentation from Docsets, giving your AI assistant access to comprehensive framework and library references.

What are Docsets?

Docsets are pre-built documentation databases containing official docs for:

• Programming languages (Python, JavaScript, Go, etc.)

• Frameworks (React, Vue, Django, Rails, etc.)

• Libraries (NumPy, Express, jQuery, etc.)

• Platforms (iOS, Android, AWS, etc.)

Setting Up Docsets

1. Option A: Ask your AI assistant to install directly:

   From a URL:

   Use the add_docset tool to install Swift documentation from https://kapeli.com/feeds/Swift.tgz

   From a local file:

   Use the add_docset tool to install the docset at /Users/me/Downloads/React.docset

2. Manage your docsets:

   List all installed docsets Remove docset with ID abc123

   Docsets are automatically stored in ~/Developer/DocSets by default.

Docset Sources

• User Contributed Docsets: https://github.com/Kapeli/Dash-User-Contributions

• Docset Generation Tools: https://github.com/Kapeli/docset-generator

Popular docsets available:

• Programming Languages: Python, JavaScript, Go, Rust, Swift

• Web Frameworks: React, Vue, Angular, Django, Rails

• Mobile: iOS, Android, React Native, Flutter

• Databases: PostgreSQL, MySQL, MongoDB, Redis

• Cloud: AWS, Google Cloud, Azure

3. Configure custom path (optional):

   { "mcpServers": { "doc-bot": { "command": "npx", "args": ["@afterxleep/doc-bot@latest", "--docsets", "/path/to/docsets"] } } }

How Docset Search Works

• Unified Search: One query searches both your docs and API docs

• Smart Prioritization: Your project docs are boosted 5x in relevance

• API Exploration: Use explore_api tool to discover related classes, methods

• Performance: Parallel search across multiple docsets with caching

Available Tools

doc-bot provides these tools to AI assistants:

Configuration Options

CLI Options

Advanced Configuration

Documentation

• API Reference - Complete reference for all MCP tools

• Architecture Guide - Technical architecture and components

• Configuration Guide - All configuration options

• Troubleshooting Guide - Common issues and solutions

• Examples & Best Practices - Real-world usage examples

• Contributing Guide - How to contribute to doc-bot

Best Practices

Writing Effective Documentation

1. Use descriptive titles and keywords

   --- title: "Authentication Flow" keywords: ["auth", "login", "jwt", "security", "authentication"] ---

2. Use file patterns for contextual docs

   --- filePatterns: ["**/auth/**", "*.auth.js"] ---

3. Keep docs focused - One topic per file

4. Include examples - Show, don't just tell

Optimizing Search

• Include synonyms in keywords: ["test", "testing", "spec", "jest"]

• Use clear section headers for better snippet extraction

• Add descriptions to improve search relevance

Why MCP over Static Instruction Files?

Unlike static .cursorrules or .github/copilot-instructions.md files:

• Dynamic: AI searches for what it needs instead of reading everything

• Scalable: Unlimited docs without token limits

• Intelligent: Context-aware documentation based on current file

• Unified: Works with any MCP-compatible AI tool

• Live: Hot reload on documentation changes

Contributing

See our Contributing Guide for development setup and guidelines.

License

MIT - See LICENSE for details.

Support

• Issues: GitHub Issues

• Discussions: GitHub Discussions

Releases

We publish from the stable branch via GitHub Actions. Use the Publish to npm workflow (manual trigger) or merge to stable to release.

Legacy Agent Enforcement (Optional)

This is not the primary workflow; doc-bot focuses on documentation-first guidance and agent-driven updates. If you still need the legacy "always apply" flow enforced by your agent host, copy templates/AGENTS.md into your project's AGENTS.md. This forces the agent to call doc_bot() first and follow doc-bot's tool sequence, ensuring alwaysApply docs are surfaced before work begins.

Note: doc-bot does not enforce rules. Your agent host must honor AGENTS.md for this to work.

Built with ❤️ in Spain