Autodocument MCP Server

Autodocument MCP 服务

一个 MCP（Model Context Protocol）服务，通过分析代码仓库的目录结构和代码文件，使用 OpenRouter API 自动生成文档。

功能特性

• 智能目录分析：递归分析代码仓库中的目录和文件
• Git 集成：遵循 .gitignore 模式，跳过被忽略的文件
• AI 驱动的文档生成：使用 OpenRouter API（默认使用 Claude 3.7）生成全面的文档
• 测试计划生成：自动创建测试计划，包含合适的测试类型、边界情况和模拟要求
• 代码审查：执行资深开发者级别的代码审查，重点关注安全性、最佳实践和改进
• 自底向上的处理方式：从叶子目录开始向上处理，创建连贯的文档层级
• 智能文件处理：
  • 在每个目录层级创建 documentation.md、testplan.md 和 review.md 文件
  • 跳过只包含单个文件的目录，但将其内容纳入父级输出
  • 支持更新现有文件
  • 为超出限制的目录创建备用文件
• 进度报告：提供详细的进度更新，避免长时间运行的操作超时
• 高度可配置：可自定义文件扩展名、大小限制、模型、提示词等
• 可扩展架构：模块化设计便于今后添加更多自动化工具

安装

前置条件

• Node.js（v16 或更新版本）
• 一个 OpenRouter API 密钥

安装步骤

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

# Install dependencies
npm install

# Build the project
npm run build

配置

可通过环境变量、命令行参数或 MCP 配置文件配置 autodocument：

环境变量

• OPENROUTER_API_KEY：你的 OpenRouter API 密钥
• OPENROUTER_MODEL：要使用的模型（默认：anthropic/claude-3-7-sonnet）
• MAX_FILE_SIZE_KB：文件大小上限，单位为 KB（默认：100）
• MAX_FILES_PER_DIR：每个目录中的文件数量上限（默认：20）

与 Roo 或 Cline 搭配使用

Roo Code 和 Cline 是支持 Model Context Protocol（MCP）的 AI 助手，因此可以使用 autodocument 之类的外部工具。

Roo/Cline 的设置方法

1. 克隆并构建仓库（按照上文的安装步骤操作）

2. 配置 MCP 服务：

   Roo：

   在 MCP Servers 菜单中，编辑 MCP 设置，并使用克隆仓库所在位置的完整路径添加 autodocument 配置：

   使用克隆仓库所在位置的完整路径添加 autodocument 配置：

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

   Claude Desktop App：

   编辑 Claude 桌面应用配置文件：

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

   使用克隆仓库所在位置的完整路径添加 autodocument 配置：

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

3. **重要：**确保在克隆的仓库中，为 build/index.js 文件使用绝对路径

4. 重启 Roo/Cline 或 Claude 桌面应用

5. 使用工具： 现在，你可以在与 Roo 或 Claude 的对话中要求它为代码仓库生成文档或测试计划：

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

   或生成测试计划：

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

   或进行代码审查：

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

工作原理

自动文档服务采用自底向上的方式运行：

1. 发现：递归扫描目标目录，并遵循 .gitignore 规则
2. 智能目录处理：
   • 识别包含多个代码文件或子目录的目录
   • 跳过只有单个文件的目录，但将其内容纳入父目录文档
3. 文件分析：分析代码文件，并按扩展名和大小进行筛选
4. 生成文档：针对每个符合条件的目录：
   • 读取代码文件
   • 使用经过优化的提示词将代码发送到 OpenRouter API
   • 创建 documentation.md 文件（或更新现有文件）
5. 汇总：沿目录树向上移动时：
   • 处理每个父目录
   • 纳入子目录中的文档
   • 在每一层创建全面的概览

架构

该项目采用模块化架构：

• 核心组件：配置管理和服务实现
• 爬虫模块：目录遍历和文件发现
• 分析器模块：代码文件分析和筛选
• OpenRouter 模块：基于 LLM 的内容生成 AI 集成
• 文档模块：编排文档处理流程
• 工具模块：用于不同自动化工具（文档、测试计划等）的可扩展系统
• 提示词配置：集中管理提示词，便于自定义

使用示例

命令行

# 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

编程方式调用

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 + '\n');

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

自定义提示词

你可以通过编辑 src/prompt-config.ts 文件，轻松自定义工具使用的提示词。你可以：

• 调整生成内容的语气和风格
• 根据项目需求添加具体说明
• 修改现有内容的更新方式

提示词配置与工具实现相分离，因此你可以轻松尝试不同的提示词，而无需更改代码。

可用工具

generate_documentation

为代码仓库生成全面的文档：

{
  "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

为代码仓库中的函数和组件生成测试计划：

{
  "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

为仓库生成高级开发者级别的代码审查：

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

输出文件

该服务会创建多种类型的输出文件：

documentation.md

包含目录中代码的全面文档，包括：

• 代码用途
• 关键函数和类
• 文件之间的关系
• 与子组件的集成

testplan.md

包含目录中代码的详细测试计划，包括：

• 各函数适用的测试类型（单元测试、集成测试、端到端测试）
• 常见的待测边界情况
• 依赖模拟要求
• 集成测试策略

review.md

包含高级开发者级别的代码审查反馈，包括：

• 安全问题和漏洞
• 违反最佳实践之处
• 潜在错误或架构问题
• 重构机会
• 实用且有建设性的反馈（不挑剔风格问题）

备用文件

当目录超出大小或文件数量限制时创建：

• undocumented.md - 用于文档生成
• untested.md - 用于测试计划生成
• review-skipped.md - 用于代码审查生成

这些文件包含：

• 跳过处理的原因
• 已分析但未纳入处理的文件列表
• 如何解决问题的说明（提高限制或手动创建内容）

故障排除

API 密钥问题

如果看到有关 API 密钥无效的错误：

• 确保已设置 OPENROUTER_API_KEY 环境变量
• 检查 OpenRouter 账户是否处于活跃状态
• 确认有足够的额度用于 API 调用

大小限制错误

如果因大小限制而跳过了过多目录：

• 设置环境变量以提高限制：MAX_FILE_SIZE_KB 和 MAX_FILES_PER_DIR
• 考虑手动为非常大的目录编写文档

模型选择

如果您对文档质量不满意：

• 尝试通过设置 OPENROUTER_MODEL 环境变量来更换模型

许可证

CC0-1.0 许可证 - 本作品由美国能源部根据 CC0 贡献至公有领域

贡献

欢迎贡献！请随时提交 Pull Request。

添加新工具

该架构旨在便于添加新的 auto-* 工具：

1. 在 src/tools 目录中创建一个扩展 BaseTool 的新类
2. 在 src/prompt-config.ts 中定义提示词
3. 在 ToolRegistry 中注册该工具

请参阅现有工具，了解如何实现新功能。