Documentation Generator MCP Server

# docs-mcp User Guide > **Automatically generate professional documentation for your code projects** > Uses the POWER framework to create comprehensive, AI-optimized documentation --- ## Table of Contents - [What is docs-mcp?](#what-is-docs-mcp) - [Prerequisites](#prerequisites) - [Installation](#installation) - [How It Works](#how-it-works) - [Usage](#usage) - [Generate All 6 Docs](#generate-all-6-docs-new-project) - [Generate Single Doc](#generate-single-doc-update) - [Output Structure](#output-structure) - [Documentation Contents](#documentation-contents) - [Common Use Cases](#common-use-cases) - [Best Practices](#best-practices) - [Troubleshooting](#troubleshooting) - [Quick Reference](#quick-reference) --- ## What is docs-mcp? **docs-mcp** is a Model Context Protocol (MCP) server that integrates with Claude Code to automatically generate foundation documentation for software projects. ### Key Features ✅ **6 Core Documents**: README, ARCHITECTURE, API, COMPONENTS, SCHEMA, USER-GUIDE ✅ **Template-Driven**: Uses POWER framework (Purpose, Output, Work, Examples, Requirements) ✅ **AI-Optimized**: Generated docs include context for AI assistants ✅ **Flexible**: Generate all docs or update individual files ✅ **Smart**: Analyzes your codebase to create specific, accurate documentation ### What Gets Generated Each project receives 6 comprehensive markdown files: 1. **README.md** - Project overview, installation, usage 2. **ARCHITECTURE.md** - System design, topology, tech stack 3. **API.md** - Endpoints, interfaces, integration patterns 4. **COMPONENTS.md** - Reusable components with examples 5. **SCHEMA.md** - Data structures, types, validation rules 6. **USER-GUIDE.md** - User onboarding, step-by-step tutorials --- ## Prerequisites Before using docs-mcp, ensure you have: ### Required - ✅ **Claude Code CLI** installed and configured - ✅ **Python 3.10+** installed on your system - ✅ **Working project** with actual code files to document ### Verify Requirements ```bash # Check Claude Code CLI claude --version # Check Python version python --version # Should show: Python 3.10.x or higher # Check MCP capability claude mcp list ``` > 💡 **What is MCP?** > Model Context Protocol allows AI assistants (like Claude) to access external tools and data sources. docs-mcp is an MCP server that provides documentation generation tools. --- ## Installation ### Step 1: Install the MCP Server ```bash # Navigate to your MCP servers directory cd C:\Users\willh\.mcp-servers\docs-mcp # Install Python dependencies (if not already installed) pip install mcp>=1.0.0 ``` ### Step 2: Register with Claude Code ```bash # Add docs-mcp as a user-scoped MCP server claude mcp add docs-mcp --scope user --command python --args "C:\Users\willh\.mcp-servers\docs-mcp\server.py" ``` **Expected Output:** ``` ✓ docs-mcp added successfully ``` ### Step 3: Verify Installation ```bash # List all MCP servers claude mcp list ``` **Expected Output:** ``` MCP Servers: ✓ docs-mcp - Connected ``` > ⚠️ **Important**: If docs-mcp shows as "Not Connected", restart Claude Code and try again. --- ## How It Works ### Architecture Overview ``` ┌──────────────────┐ │ Your Project │ │ (Source Code) │ └────────┬─────────┘ │ │ Claude Code analyzes │ ▼ ┌──────────────────┐ │ docs-mcp Server │ │ (MCP Protocol) │ └────────┬─────────┘ │ │ Uses POWER templates │ ▼ ┌──────────────────┐ │ Generated Docs │ │ coderef/ │ │ foundation- │ │ docs/ │ └──────────────────┘ ``` ### Process Flow 1. **You invoke** a natural language command in Claude Code 2. **Claude Code calls** the appropriate MCP tool (`generate_foundation_docs` or `generate_individual_doc`) 3. **docs-mcp analyzes** your project structure, code files, and configuration 4. **Templates guide** the generation using the POWER framework 5. **Claude creates** the documentation based on template structure and code analysis 6. **Files are saved** to `your-project/coderef/foundation-docs/` --- ## Usage ### Generate All 6 Docs (New Project) **When to use:** Starting documentation from scratch or doing a complete refresh #### Command Format In Claude Code, type: ``` Generate foundation documentation for my project at <absolute-path-to-project> ``` #### Real Example ``` Generate foundation documentation for my project at C:\Users\willh\Desktop\projects - current-location\sidebar-app ``` #### What Happens 1. **Directory Created**: `sidebar-app/coderef/foundation-docs/` 2. **Files Generated**: - ✅ README.md - ✅ ARCHITECTURE.md - ✅ API.md - ✅ COMPONENTS.md - ✅ SCHEMA.md - ✅ USER-GUIDE.md 3. **Time**: 8-20 minutes (depends on project size) 4. **Process**: Sequential generation (each doc references previous docs) #### Behind the Scenes **MCP Tool Used**: `generate_foundation_docs` **Tool Schema**: ```json { "name": "generate_foundation_docs", "inputSchema": { "properties": { "project_path": { "type": "string", "description": "Absolute path to the project directory" } }, "required": ["project_path"] } } ``` --- ### Generate Single Doc (Update) **When to use:** Updating documentation after code changes #### Command Format In Claude Code, type: ``` Generate individual doc for my project at <absolute-path-to-project> using template <template-name> ``` #### Template Options | Template Name | Document | Use When | |---------------|----------|----------| | `readme` | README.md | Changed setup, added features, updated overview | | `architecture` | ARCHITECTURE.md | Refactored structure, changed tech stack, updated design | | `api` | API.md | Added/changed endpoints, updated integration patterns | | `components` | COMPONENTS.md | Added/modified components, changed patterns | | `schema` | SCHEMA.md | Changed data structures, updated database schema | | `user-guide` | USER-GUIDE.md | Updated onboarding flow, added tutorials, changed UX | #### Real Examples **Update API Documentation:** ``` Generate individual doc for my project at C:\Users\willh\Desktop\projects - current-location\sidebar-app using template api ``` **Update Components Documentation:** ``` Generate individual doc for my project at C:\Users\willh\Desktop\projects - current-location\sidebar-app using template components ``` **Update Schema Documentation:** ``` Generate individual doc for my project at C:\Users\willh\Desktop\projects - current-location\sidebar-app using template schema ``` **Update User Guide Documentation:** ``` Generate individual doc for my project at C:\Users\willh\Desktop\projects - current-location\sidebar-app using template user-guide ``` #### What Happens 1. **Single File Updated**: Only the specified document is regenerated 2. **Time**: 1-3 minutes per document 3. **Context Preserved**: References to other docs remain intact #### Behind the Scenes **MCP Tool Used**: `generate_individual_doc` **Tool Schema**: ```json { "name": "generate_individual_doc", "inputSchema": { "properties": { "project_path": { "type": "string", "description": "Absolute path to the project directory" }, "template_name": { "type": "string", "enum": ["readme", "architecture", "api", "components", "schema", "user-guide"] } }, "required": ["project_path", "template_name"] } } ``` --- ## Output Structure ### Default Location > 📁 **Output Directory**: `coderef/foundation-docs/` This is the **new default location** (changed from `docs/` to `coderef/foundation-docs/` for better organization). ### Project Structure After Generation ``` your-project/ ├── src/ # Your source code ├── public/ # Your assets ├── package.json # Your config ├── coderef/ # ← NEW: Documentation root │ └── foundation-docs/ # ← All generated docs here │ ├── README.md # Project overview & setup │ ├── ARCHITECTURE.md # System design & topology │ ├── API.md # Endpoints & integrations │ ├── COMPONENTS.md # Reusable components │ ├── SCHEMA.md # Data structures & types │ └── USER-GUIDE.md # User onboarding & tutorials └── ... ``` ### Why `coderef/foundation-docs/`? - **Organized**: Separates documentation from source code - **Scalable**: Room for other doc types (e.g., `coderef/api-docs/`, `coderef/guides/`) - **Clear Purpose**: "foundation-docs" indicates these are base reference documents - **Git-Friendly**: Easy to add to `.gitignore` if desired --- ## Documentation Contents ### README.md **Purpose**: Entry point for understanding the project **Includes**: - Project overview and purpose - Prerequisites and dependencies - Installation steps with commands - Usage examples - Available scripts - Troubleshooting guide - Environment variables - Development workflow **Example Sections**: ```markdown # Project Name ## Overview ## Prerequisites ## Installation ## Usage ## Troubleshooting ``` --- ### ARCHITECTURE.md **Purpose**: System design and technical decisions **Includes**: - System topology with ASCII diagrams - Module boundaries and responsibilities - Technology stack with rationale - Data flow diagrams - Design decisions and trade-offs - Security considerations - Extension points **Example Sections**: ```markdown # ARCHITECTURE.md ## System Topology ## Module Boundaries ## Technology Stack ## Data Flow ## Design Rationale ``` --- ### API.md **Purpose**: Technical interface reference **Includes**: - All endpoints/routes - Request/response formats - Authentication patterns - Error handling - Rate limiting - Code examples with cURL - Integration patterns - Testing approaches **Example Sections**: ```markdown # API.md ## Authentication ## Endpoints ## Error Handling ## Usage Examples ## Rate Limits ``` --- ### COMPONENTS.md **Purpose**: Reusable code component library **Includes**: - Component inventory - Props/interfaces for each component - Usage patterns - Copy-paste examples - State management patterns - Styling patterns - Accessibility considerations - Extension guidelines **Example Sections**: ```markdown # COMPONENTS.md ## Component Inventory ## UI Components ## Usage Patterns ## Code Examples ## Best Practices ``` --- ### SCHEMA.md **Purpose**: Data structure and validation reference **Includes**: - TypeScript type definitions - Database schemas - Zod validation schemas - Data relationships - Migration strategies - Constraints and rules - Future schema plans **Example Sections**: ```markdown # SCHEMA.md ## Type Definitions ## Database Schema ## Validation Rules ## Relationships ## Migration Guide ``` --- ### USER-GUIDE.md **Purpose**: User onboarding and reference documentation **Includes**: - Table of contents with anchor links - Prerequisites with verification commands - Step-by-step installation instructions - Architecture explanation with diagrams - Explicit command examples - Common use cases and workflows - Best practices (Do/Don't/Tips) - Troubleshooting guide - Quick reference tables **Example Sections**: ```markdown # USER-GUIDE.md ## Prerequisites ## Installation ## How It Works ## Usage Examples ## Best Practices ## Troubleshooting ## Quick Reference ``` --- ## Common Use Cases ### Use Case 1: Brand New Project **Scenario**: You've built a new project and need documentation **Steps**: 1. Complete your initial code 2. Run: `Generate foundation documentation for my project at C:\path\to\project` 3. Review generated docs in `coderef/foundation-docs/` 4. Commit to git **Result**: Complete foundation documentation suite --- ### Use Case 2: Added API Endpoints **Scenario**: You added new routes or changed API patterns **Steps**: 1. Implement your API changes 2. Test the new endpoints 3. Run: `Generate individual doc for my project at C:\path\to\project using template api` 4. Review updated API.md 5. Commit changes **Result**: API.md reflects new endpoints and patterns --- ### Use Case 3: Component Refactor **Scenario**: You refactored components or added new ones **Steps**: 1. Complete your component changes 2. Test components work correctly 3. Run: `Generate individual doc for my project at C:\path\to\project using template components` 4. Review updated COMPONENTS.md 5. Commit changes **Result**: COMPONENTS.md documents new/changed components --- ### Use Case 4: Database Schema Changes **Scenario**: You modified your database schema or TypeScript types **Steps**: 1. Update database migrations 2. Update TypeScript types 3. Run: `Generate individual doc for my project at C:\path\to\project using template schema` 4. Review updated SCHEMA.md 5. Commit changes **Result**: SCHEMA.md reflects new data structures --- ### Use Case 5: Major Refactor **Scenario**: You did a major rewrite affecting multiple areas **Steps**: 1. Complete your refactor 2. Test everything works 3. Run: `Generate foundation documentation for my project at C:\path\to\project` 4. Review all 6 regenerated docs 5. Commit changes **Result**: All documentation refreshed to match new architecture --- ### Use Case 6: Legacy Project Documentation **Scenario**: You inherited a project with no documentation **Steps**: 1. Familiarize yourself with the codebase 2. Run: `Generate foundation documentation for my project at C:\path\to\project` 3. Review generated docs for accuracy 4. Fill in any gaps manually (if needed) 5. Commit documentation **Result**: Legacy project now has complete documentation --- ## Best Practices ### ✅ Do - **Run on complete code**: Ensure your project has actual code files before generating docs - **Use absolute paths**: Always provide full paths like `C:\Users\...\project` - **Update incrementally**: Use single doc generation after small changes - **Regenerate after major changes**: Use full generation after significant refactors - **Review generated docs**: Check for accuracy and completeness - **Commit docs with code**: Keep documentation in sync with code changes - **Use as AI context**: Generated docs are optimized for AI assistant consumption ### 🚫 Don't - **Don't edit manually**: Generated docs will be overwritten on next generation - **Don't run on empty projects**: Need actual code to document - **Don't use relative paths**: Always use absolute paths - **Don't skip verification**: Always check that docs match your code - **Don't ignore errors**: If generation fails, investigate and fix ### 💡 Tips - **For custom content**: Create separate manual docs (e.g., `CONTRIBUTING.md`, `CHANGELOG.md`) - **For project-specific notes**: Use inline code comments or separate `.notes/` directory - **For temporary docs**: Create in a different location to avoid conflicts - **For versioning**: Consider creating `docs/v1.0/`, `docs/v2.0/` for version-specific docs --- ## Troubleshooting ### Problem: "Tool not found" or "No such tool available" **Symptom**: Claude Code says it can't find the docs-mcp tools **Cause**: MCP server not connected or not registered **Solution**: ```bash # 1. Check if docs-mcp is registered claude mcp list # 2. If not listed, register it claude mcp add docs-mcp --scope user --command python --args "C:\Users\willh\.mcp-servers\docs-mcp\server.py" # 3. Restart Claude Code # 4. Verify connection claude mcp list # Should show: ✓ docs-mcp - Connected ``` --- ### Problem: "Project path does not exist" **Symptom**: Error says the project path doesn't exist **Cause**: Using relative path or incorrect path **Solution**: ```bash # ❌ Wrong: Relative path Generate foundation documentation for my project at ./my-project # ❌ Wrong: Missing drive letter Generate foundation documentation for my project at Users\willh\Desktop\project # ✅ Correct: Absolute path Generate foundation documentation for my project at C:\Users\willh\Desktop\my-project # ✅ Correct: Path with spaces (quotes not needed in command) Generate foundation documentation for my project at C:\Users\willh\Desktop\projects - current-location\sidebar-app ``` --- ### Problem: Generated docs are too generic **Symptom**: Documentation doesn't mention specific features or components **Cause**: Project has minimal code or generic structure **Solution**: 1. Ensure your project has actual implementation code (not just boilerplate) 2. Check that files are in expected locations (`src/`, `lib/`, etc.) 3. Try running on a specific module first 4. Review generated docs and manually enhance if needed --- ### Problem: Only got README, not all 6 docs **Symptom**: Generation stopped after creating only one document **Cause**: Agent hit token limit or encountered an error **Solution**: 1. Run the command again - it will continue where it left off 2. Or generate missing docs individually: ``` Generate individual doc for my project at C:\path\to\project using template architecture Generate individual doc for my project at C:\path\to\project using template api ``` 3. Check Claude Code logs for errors --- ### Problem: Generation takes too long **Symptom**: Documentation generation exceeds expected time **Cause**: Large project with many files or complex structure **Solution**: 1. Be patient - large projects take longer (10-20 minutes possible) 2. Generate docs individually instead of all at once 3. Consider documenting modules separately 4. Check if Claude Code is responsive (not frozen) --- ### Problem: Docs reference old/removed code **Symptom**: Generated documentation mentions features you removed **Cause**: Documentation was generated before code changes **Solution**: ```bash # Regenerate all docs after major changes Generate foundation documentation for my project at C:\path\to\project # Or update specific doc Generate individual doc for my project at C:\path\to\project using template architecture ``` --- ### Problem: Python version error **Symptom**: Error about Python version or module imports **Cause**: Python 3.10+ not installed or wrong Python version active **Solution**: ```bash # 1. Check Python version python --version # 2. If < 3.10, upgrade Python # 3. Verify docs-mcp uses correct Python claude mcp list # Check command path # 4. Update MCP server with correct Python path if needed claude mcp remove docs-mcp claude mcp add docs-mcp --scope user --command python --args "C:\Users\willh\.mcp-servers\docs-mcp\server.py" ``` --- ## Quick Reference ### Command Templates | Goal | Command Pattern | |------|-----------------| | **All 6 docs** | `Generate foundation documentation for my project at <path>` | | **README only** | `Generate individual doc for my project at <path> using template readme` | | **ARCHITECTURE only** | `Generate individual doc for my project at <path> using template architecture` | | **API only** | `Generate individual doc for my project at <path> using template api` | | **COMPONENTS only** | `Generate individual doc for my project at <path> using template components` | | **SCHEMA only** | `Generate individual doc for my project at <path> using template schema` | | **USER-GUIDE only** | `Generate individual doc for my project at <path> using template user-guide` | ### Template Reference | Template | Output File | Typical Size | Generation Time | |----------|-------------|--------------|-----------------| | `readme` | README.md | 5-15KB | 1-3 min | | `architecture` | ARCHITECTURE.md | 10-25KB | 2-4 min | | `api` | API.md | 8-20KB | 2-4 min | | `components` | COMPONENTS.md | 15-40KB | 3-6 min | | `schema` | SCHEMA.md | 10-30KB | 2-4 min | | `user-guide` | USER-GUIDE.md | 20-50KB | 4-8 min | ### MCP Tools | Tool Name | Purpose | Parameters | |-----------|---------|------------| | `generate_foundation_docs` | Generate all 6 foundation documents | `project_path` (string) | | `generate_individual_doc` | Generate single document | `project_path` (string), `template_name` (enum) | | `list_templates` | List available templates | None | | `get_template` | Get template content | `template_name` (enum) | | `list_frameworks` | List prompt frameworks | None | ### Output Locations | Project Type | Output Directory | |--------------|------------------| | **Default** | `<project>/coderef/foundation-docs/` | | **Custom** | Pass `subdir` parameter (advanced usage) | --- ## Additional Resources ### Related Files - **`README.md`** - docs-mcp project overview - **`ARCHITECTURE.md`** - docs-mcp system design - **`templates/power/`** - POWER framework templates - **`generators/`** - Generator implementation ### External Links - [POWER Framework Documentation](https://github.com/srwlli/docs-mcp) - [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) - [Claude Code Documentation](https://docs.anthropic.com/claude-code) --- **Last Updated**: 2025-10-08 **Version**: 1.0.0 **Maintainer**: willh --- > 💡 **Pro Tip**: Generated documentation is optimized for both human readers and AI assistants. Use these docs as context when working with Claude Code on your projects!