Autodocument MCP Server

An MCP (Model Context Protocol) server that automatically generates documentation for code repositories by analyzing directory structures and code files using OpenRouter API.

Features

• Smart Directory Analysis: Recursively analyzes directories and files in a code repository
• Git Integration: Respects .gitignore patterns to skip ignored files
• AI-Powered Documentation: Uses OpenRouter API (with Claude 3.7 by default) to generate comprehensive documentation
• Test Plan Generation: Automatically creates test plans with suitable test types, edge cases, and mock requirements
• Code Review: Performs senior developer-level code reviews focused on security, best practices, and improvements
• Bottom-Up Approach: Starts with leaf directories and works upward, creating a coherent documentation hierarchy
• Intelligent File Handling:
  • Creates documentation.md, testplan.md, and review.md files at each directory level
  • Skips single-file directories but includes their content in parent outputs
  • Supports updating existing files
  • Creates fallback files for directories that exceed limits
• Progress Reporting: Provides detailed progress updates to prevent timeouts in long-running operations
• Highly Configurable: Customize file extensions, size limits, models, prompts, and more
• Extensible Architecture: Modular design makes it easy to add more auto-* tools in the future

Installation

Prerequisites

• Node.js (v16 or newer)
• An OpenRouter API key

Installation Steps

# Clone the repository
git clone https://github.com/PARS-DOE/autodocument.git
cd autodocument

# Install dependencies
npm install

# Build the project
npm run build

Configuration

Configure autodocument using environment variables, command-line arguments, or an MCP configuration file:

Environment Variables

• OPENROUTER_API_KEY: Your OpenRouter API key
• OPENROUTER_MODEL: Model to use (default: anthropic/claude-3-7-sonnet)
• MAX_FILE_SIZE_KB: Maximum file size in KB (default: 100)
• MAX_FILES_PER_DIR: Maximum number of files per directory (default: 20)

Using with Roo or Cline

Roo Code and Cline are AI assistants that support the Model Context Protocol (MCP), which allows them to use external tools like autodocument.

Setup for Roo/Cline

1. Clone and build the repository (follow the Installation Steps above)

2. Configure the MCP server:

   For Roo:

   In the MCP Servers menu, Edit the MCP Settings and add the autodocument configuration using the full path to where you cloned the repository:

   Add the autodocument configuration using the full path to where you cloned the repository:

   {
     "mcpServers": {
       "autodocument": {
         "command": "node",
         "args": ["/path/to/autodocument/build/index.js"],
         "env": {
           "OPENROUTER_API_KEY": "your-api-key-here"
         },
         "disabled": false,
         "alwaysAllow": []
       }
     }
   }

   For Claude Desktop App:

   Edit the Claude desktop app configuration file at:

   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

   Add the autodocument configuration using the full path to where you cloned the repository:

   {
     "mcpServers": {
       "autodocument": {
         "command": "node",
         "args": ["/path/to/autodocument/build/index.js"],
         "env": {
           "OPENROUTER_API_KEY": "your-api-key-here"
         },
         "disabled": false,
         "alwaysAllow": []
       }
     }
   }

3. Important: Make sure to use absolute paths to the build/index.js file in your cloned repository

4. Restart Roo/Cline or the Claude desktop app

5. Use the tool: In a conversation with Roo or Claude, you can now ask it to generate documentation or test plans for your code repository:

   Please generate documentation for my project at /path/to/my/project
   

   Or for test plans:

   Please create a test plan for my project at /path/to/my/project
   

   Or for code reviews:

   Please review the code in my project at /path/to/my/project
   

How It Works

The autodocument server works using a bottom-up approach:

1. Discovery: Scans the target directory recursively, respecting .gitignore rules
2. Smart Directory Processing:
   • Identifies directories with multiple code files or subdirectories
   • Skips single-file directories but includes their content in parent documentation
3. File Analysis: Analyzes code files, filtering by extension and size
4. Documentation Generation: For each qualifying directory:
   • Reads code files
   • Sends code to OpenRouter API with optimized prompts
   • Creates a documentation.md file (or updates existing one)
5. Aggregation: As it moves up the directory tree:
   • Processes each parent directory
   • Includes documentation from child directories
   • Creates a comprehensive overview at each level

Architecture

The project follows a modular architecture:

• Core Components: Configuration management and server implementation
• Crawler Module: Directory traversal and file discovery
• Analyzer Module: Code file analysis and filtering
• OpenRouter Module: AI integration for LLM-based content generation
• Documentation Module: Orchestration of the documentation process
• Tools Module: Extensible system for different auto-* tools (documentation, test plans, etc.)
• Prompts Configuration: Centralized prompt management for easy customization

Example Usage

Command Line

# Navigate to your cloned repository
cd path/to/cloned/autodocument

# Set your API key (or configure in environment variables)
export OPENROUTER_API_KEY=your-api-key-here

# Run documentation generation on a project
node build/index.js /path/to/your/project

Programmatic Usage

const { spawn } = require('child_process');
const path = require('path');

// Path to your project
const projectPath = '/path/to/your/project';

// Your OpenRouter API key
const apiKey = 'your-api-key-here';

// Create a JSON command to simulate an MCP tool call
const toolCallCommand = JSON.stringify({
  jsonrpc: '2.0',
  method: 'call_tool',
  params: {
    name: 'generate_documentation',
    arguments: {
      path: projectPath,
      openRouterApiKey: apiKey
    }
  },
  id: 1
});

// Start the server process - use the full path to your cloned repository
const serverProcess = spawn('node', ['/path/to/autodocument/build/index.js'], {
  env: {
    ...process.env,
    OPENROUTER_API_KEY: apiKey
  }
});

// Send the tool command
serverProcess.stdin.write(toolCallCommand + '
');

// Handle server output and errors
// ...

Customizing Prompts

You can easily customize the prompts used by the tools by editing the src/prompt-config.ts file. This allows you to:

• Adjust the tone and style of generated content
• Add specific instructions for your project's needs
• Modify how existing content is updated

The prompt configuration is separated from the tool implementation, making it easy to experiment with different prompts without changing the code.

Available Tools

generate_documentation

Generates comprehensive documentation for a code repository:

{
  "path": "/path/to/your/project",
  "openRouterApiKey": "your-api-key-here", // Optional
  "model": "anthropic/claude-3-7-sonnet", // Optional
  "updateExisting": true // Optional, defaults to true
}

autotestplan

Generates test plans for functions and components in a code repository:

{
  "path": "/path/to/your/project",
  "openRouterApiKey": "your-api-key-here", // Optional
  "model": "anthropic/claude-3-7-sonnet", // Optional
  "updateExisting": true // Optional, defaults to true
}

autoreview

Generates a senior developer-level code review for a repository:

{
  "path": "/path/to/your/project",
  "openRouterApiKey": "your-api-key-here", // Optional
  "model": "anthropic/claude-3-7-sonnet", // Optional
  "updateExisting": true // Optional, defaults to true
}

Output Files

The server creates several types of output files:

documentation.md

Contains comprehensive documentation of the code in a directory, including:

• Purpose of the code
• Key functions and classes
• Relationships between files
• Integration with child components

testplan.md

Contains detailed test plans for code in a directory, including:

• Appropriate test types (unit, integration, e2e) for each function
• Common edge cases to test
• Dependency mocking requirements
• Integration testing strategies

review.md

Contains senior developer-level code review feedback, including:

• Security issues and vulnerabilities
• Best practice violations
• Potential bugs or architectural concerns
• Opportunities for refactoring
• Practical, constructive feedback (not nitpicking style issues)

Fallback Files

Created when a directory exceeds size or file count limits:

• undocumented.md - For documentation generation
• untested.md - For test plan generation
• review-skipped.md - For code review generation

These files contain:

• Reason for skipping processing
• List of files that were analyzed and excluded
• Instructions on how to fix (increase limits or manually create content)

Troubleshooting

API Key Issues

If you see errors about invalid API key:

• Ensure you've set the OPENROUTER_API_KEY environment variable
• Check that your OpenRouter account is active
• Verify you have sufficient credits for the API calls

Size Limit Errors

If too many directories are skipped due to size limits:

• Set environment variables to increase limits: MAX_FILE_SIZE_KB and MAX_FILES_PER_DIR
• Consider documenting very large directories manually

Model Selection

If you're not satisfied with the documentation quality:

• Try a different model by setting the OPENROUTER_MODEL environment variable

License

CC0-1.0 License - This work is dedicated to the public domain under CC0 by the United States Department of Energy

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Adding New Tools

The architecture is designed to make it easy to add new auto-* tools:

1. Create a new class that extends BaseTool in the src/tools directory
2. Define the prompts in src/prompt-config.ts
3. Register the tool in the ToolRegistry

See the existing tools for examples of how to implement new functionality.