Autodocument MCP 服务器

一个 MCP (模型上下文协议) 服务器，通过使用 OpenRouter API 分析目录结构和代码文件，自动为代码仓库生成文档。

功能

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

安装

前提条件

• Node.js (v16 或更高版本)
• 一个 OpenRouter API 密钥

安装步骤

# 克隆仓库
git clone https://github.com/PARS-DOE/autodocument.git
cd autodocument

# 安装依赖
npm install

# 构建项目
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 是支持模型上下文协议 (MCP) 的 AI 助手，它们可以使用像 autodocument 这样的外部工具。

Roo/Cline 的设置

1. 克隆并构建仓库 (按照上面的安装步骤)

2. 配置 MCP 服务器:

   对于 Roo:

   在 MCP 服务器菜单中，编辑 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 桌面应用:

   编辑 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 的对话中，你现在可以要求它为你的代码仓库生成文档或测试计划：

   请为我的项目生成文档，项目路径为 /path/to/my/project
   

   或者生成测试计划：

   请为我的项目创建一个测试计划，项目路径为 /path/to/my/project
   

   或者进行代码审查：

   请审查我的项目中的代码，项目路径为 /path/to/my/project
   

工作原理

autodocument 服务器使用自下而上的方法工作：

1. 发现: 递归扫描目标目录，遵循 .gitignore 规则
2. 智能目录处理:
   • 识别包含多个代码文件或子目录的目录
   • 跳过单文件目录，但将其内容包含在父级文档中
3. 文件分析: 分析代码文件，按扩展名和大小进行过滤
4. 文档生成: 对于每个符合条件的目录：
   • 读取代码文件
   • 使用优化的提示将代码发送到 OpenRouter API
   • 创建一个 documentation.md 文件 (或更新现有文件)
5. 聚合: 当它向上移动目录树时：
   • 处理每个父目录
   • 包含来自子目录的文档
   • 在每个级别创建一个全面的概述

架构

该项目遵循模块化架构：

• 核心组件: 配置管理和服务器实现
• 爬虫模块: 目录遍历和文件发现
• 分析器模块: 代码文件分析和过滤
• OpenRouter 模块: 用于基于 LLM 的内容生成的 AI 集成
• 文档模块: 文档流程的编排
• 工具模块: 用于不同 auto-* 工具 (文档、测试计划等) 的可扩展系统
• 提示配置: 用于轻松自定义的集中式提示管理

使用示例

命令行

# 导航到你克隆的仓库
cd path/to/cloned/autodocument

# 设置你的 API 密钥 (或在环境变量中配置)
export OPENROUTER_API_KEY=your-api-key-here

# 在项目上运行文档生成
node build/index.js /path/to/your/project

编程方式

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

// 项目路径
const projectPath = '/path/to/your/project';

// 你的 OpenRouter API 密钥
const apiKey = 'your-api-key-here';

// 创建一个 JSON 命令来模拟 MCP 工具调用
const toolCallCommand = JSON.stringify({
  jsonrpc: '2.0',
  method: 'call_tool',
  params: {
    name: 'generate_documentation',
    arguments: {
      path: projectPath,
      openRouterApiKey: apiKey
    }
  },
  id: 1
});

// 启动服务器进程 - 使用指向克隆仓库的完整路径
const serverProcess = spawn('node', ['/path/to/autodocument/build/index.js'], {
  env: {
    ...process.env,
    OPENROUTER_API_KEY: apiKey
  }
});

// 发送工具命令
serverProcess.stdin.write(toolCallCommand + '\n');

// 处理服务器输出和错误
// ...

自定义提示

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

• 调整生成内容的语气和风格
• 为你的项目需求添加特定说明
• 修改现有内容的更新方式

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

可用工具

generate_documentation

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

{
  "path": "/path/to/your/project",
  "openRouterApiKey": "your-api-key-here", // 可选
  "model": "anthropic/claude-3-7-sonnet", // 可选
  "updateExisting": true // 可选，默认为 true
}

autotestplan

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

{
  "path": "/path/to/your/project",
  "openRouterApiKey": "your-api-key-here", // 可选
  "model": "anthropic/claude-3-7-sonnet", // 可选
  "updateExisting": true // 可选，默认为 true
}

autoreview

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

{
  "path": "/path/to/your/project",
  "openRouterApiKey": "your-api-key-here", // 可选
  "model": "anthropic/claude-3-7-sonnet", // 可选
  "updateExisting": true // 可选，默认为 true
}

输出文件

服务器创建几种类型的输出文件：

documentation.md

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

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

testplan.md

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

• 每个函数的适当测试类型 (单元、集成、e2e)
• 要测试的常见边缘情况
• 依赖模拟要求
• 集成测试策略

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 中注册该工具

有关如何实现新功能的示例，请参见现有工具。