AI导哈

代码文档自动生成服务

一款通过分析代码仓库目录结构和代码文件自动生成文档、测试计划和代码审查的MCP服务器工具，适用于开发团队提高代码管理效率。

  • by PARS-DOE
  • TypeScript
  • 本地部署
  • 6 星标
  • 更新于
在 GitHub 查看 PARS-DOE/autodocument

使用说明

自动记录MCP服务器

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

特性

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

安装

先决条件

安装步骤

# 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配置文件配置自动文档：

环境变量

  • 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）的人工智能助手，允许他们使用自动文档等外部工具。

Roo/Cline的设置

  1. 克隆并构建存储库 （按照上述安装步骤操作）

  2. 配置MCP服务器:

    对于Roo：

    在MCP服务器菜单中，编辑MCP设置，并使用克隆存储库的完整路径添加自动文档配置：

    使用克隆存储库的完整路径添加自动文档配置：

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

    对于Claude桌面应用程序：

    在以下位置编辑Claude桌面应用程序配置文件：

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

    使用克隆存储库的完整路径添加自动文档配置：

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

运作原理

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

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

建筑

该项目采用模块化架构：

  • 核心组件：配置管理和服务器实施
  • 爬虫模块：目录遍历和文件发现
  • 分析仪模块：代码文件分析和过滤
  • OpenRouter模块：基于LLM的内容生成的AI集成
  • 文档模块：文件编制过程的编排
  • 工具模块：适用于不同auto-*工具（文档、测试计划等）的可扩展系统
  • 提示配置：集中提示管理，便于定制

示例用法

命令行

# 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 文件。这使您能够：

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

提示配置与工具实现是分开的，这使得在不更改代码的情况下很容易尝试不同的提示。

可用工具

生成文档

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

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

自动测试计划

为代码存储库中的功能和组件生成测试计划：

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

作者视图

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

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

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

  • 准则的目的
  • 关键功能和类
  • 文件之间的关系
  • 与子组件集成

测试平面.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专用于公共领域

贡献

欢迎投稿！请随时提交拉取请求。

添加新工具

该架构旨在使添加新的auto-*工具变得容易：

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

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

相关 MCP