代码摘要器

一个使用 Gemini Flash 2.0 总结给定目录中代码文件的命令行工具。现在支持 MCP 服务器，可与 LLM 工具集成！

功能

• 递归处理目录中的代码文件
• 遵循 .gitignore 规则
• 跳过不相关的目录，如 node_modules、dist 等。
• 使用 Gemini Flash 2.0 总结代码文件
• 将摘要输出到文本文件
• 可配置的详细程度和摘要长度
• MCP 服务器，用于与 Claude Desktop 和其他 LLM 工具集成
• 模块化设计，易于集成到其他应用程序中
• 安全的 API 密钥管理
• MCP 服务器端点的身份验证
• 具有指数退避的重试机制，用于 LLM 调用
• 速率限制以防止滥用

要求

• Node.js 18+

安装

1. 克隆存储库

   git clone https://github.com/nicobailon/code-summarizer.git
   cd code-summarizer
   

2. 安装依赖项：

   npm install
   

3. 创建一个包含您的 Google API 密钥的 .env 文件：

   GOOGLE_API_KEY=your_api_key_here
   

4. 构建项目：

   npm run build
   

MCP 服务器设置和集成

代码摘要器包含一个模型上下文协议 (MCP) 服务器，允许 LLM 工具（如 Claude Desktop、Cursor AI 和 Cline）访问代码摘要和文件内容。

启动 MCP 服务器

# 启动 MCP 服务器
npm start -- server

默认情况下，服务器在端口 24312 上运行。您可以在配置中更改此设置：

# 设置自定义 MCP 服务器端口
npm start -- config set --port 8080

与 Claude Desktop 连接

1. 启动 code-summarizer MCP 服务器
2. 打开 Claude Desktop 并单击 Claude 菜单，然后单击“Settings...”
3. 导航到“Developer”部分
4. 在 ~/.claude/claude_desktop_config.json (macOS/Linux) 或 %USERPROFILE%\.claude\claude_desktop_config.json (Windows) 中创建一个文件，内容如下：

{
  "code-summarizer": {
    "command": "npx",
    "args": ["-y", "your-path-to-code-summarizer/bin/code-summarizer.js", "server"],
    "env": {
      "GOOGLE_API_KEY": "your_api_key_here"
    }
  }
}

5. 重新启动 Claude Desktop
6. 重新启动后，您可以要求 Claude 访问您的代码库，例如，“Summarize the files in my project”

Claude Desktop 的示例提示：

• "Can you summarize all the JavaScript files in my project?"
• "Please give me a high-level overview of my codebase."
• "Explain what the file 'src/config/config.ts' does."
• "Find all functions related to authentication in my code."

与 Cursor AI 连接

1. 启动 code-summarizer MCP 服务器
2. 在您的项目目录中创建一个 .cursor/mcp.json 文件：

{
  "mcpServers": {
    "code-summarizer": {
      "transport": "sse",
      "url": "http://localhost:24312/sse",
      "headers": {
        "x-api-key": "your_api_key_here"
      }
    }
  }
}

3. 重新启动 Cursor 或重新加载您的项目
4. 询问 Cursor 关于您的代码，例如，“Can you summarize my codebase?”

Cursor 的示例提示：

• "Summarize the structure of this codebase for me."
• "What are the key components in this project?"
• "Give me a detailed explanation of the MCP server implementation."
• "Help me understand how the retry mechanism works."

与 Cline 连接

1. 启动 code-summarizer MCP 服务器
2. 在 Cline 中，您可以使用命令添加 MCP 服务器：

/mcp add code-summarizer http://localhost:24312/sse

3. 然后使用您的 API 密钥进行身份验证：

/mcp config code-summarizer headers.x-api-key your_api_key_here

4. 然后您可以要求 Cline 使用 code-summarizer，例如，“Please summarize my code files”

Cline 的示例提示：

• "What does each file in my project do?"
• "Create a summary of all TypeScript files."
• "Explain the authentication flow in this codebase."
• "What are the main functions in the 'summarizer' directory?"

您可以使用 MCP 集成做什么

使用 MCP 集成，您可以：

1. 获取文件摘要：请求对特定文件功能的简明解释
2. 浏览目录：浏览您的代码库结构
3. 批量处理：一次总结多个文件
4. 有针对性的查询：在您的代码中查找特定模式或功能
5. 自定义摘要：控制详细程度和摘要长度
6. 更新设置：通过 MCP 界面更改配置选项

MCP 服务器以结构化的方式将您的代码库暴露给 LLM 工具，允许它们读取、导航和总结您的代码，而无需手动粘贴代码片段。

MCP 服务器集成详细信息

MCP 资源

• code://file/* - 访问单个代码文件
• code://directory/* - 列出目录中的代码文件
• summary://file/* - 获取特定文件的摘要
• summary://batch/* - 获取多个文件的摘要

MCP 工具

• summarize_file - 总结具有选项的单个文件
• summarize_directory - 总结具有选项的目录
• set_config - 更新配置选项

MCP 提示

• code_summary - 用于总结代码的提示模板
• directory_summary - 用于总结整个目录的提示模板

故障排除

常见的 MCP 连接问题

1. 连接被拒绝

   • 确保 MCP 服务器正在运行 (npm start -- server)
   • 验证端口在您的配置中是否正确
   • 检查是否存在阻止连接的防火墙问题

2. 身份验证错误

   • 验证您是否在标头中添加了正确的 API 密钥 (x-api-key)
   • 检查您的 API 密钥是否有效且格式正确
   • 确保正确设置了环境变量

3. 传输错误

   • 确保指定了正确的传输类型 (SSE)
   • 检查 URL 是否包含正确的端点 (/sse)
   • 验证客户端和服务器之间的网络连接

4. 权限问题

   • 确保 MCP 服务器具有对您的代码库的读取权限
   • 如果特定文件的摘要失败，请检查文件权限

5. Claude Desktop 找不到 MCP 服务器

   • 验证 claude_desktop_config.json 中的路径是否正确
   • 确保命令和 args 指向正确的位置
   • 检查 Claude Desktop 日志中是否存在任何配置错误

6. 速率限制

   • 如果您看到“请求过多”错误，请稍后重试
   • 考虑调整服务器代码中的速率限制设置

对于其他问题，请检查服务器日志或在 GitHub 存储库上打开一个问题。

用法

命令行界面

# 默认命令 (summarize)
npm start -- summarize [directory] [output-file] [options]

# 总结当前目录中的代码（输出到 summaries.txt）
npm start -- summarize

# 总结具有特定详细程度和最大长度的代码
npm start -- summarize --detail high --max-length 1000

# 显示帮助
npm start -- --help

配置管理

# 设置您的 API 密钥
npm start -- config set --api-key "your-api-key" 

# 设置默认详细程度和最大长度
npm start -- config set --detail-level high --max-length 1000

# 设置 MCP 服务器端口（默认：24312）
npm start -- config set --port 8080

# 显示当前配置
npm start -- config show

# 将配置重置为默认值
npm start -- config reset

API 身份验证

连接到 MCP 服务器时，您需要在请求标头中包含您的 API 密钥：

x-api-key: your_api_key_here

所有端点（/health 除外）都需要身份验证。

选项

• --detail, -d: 设置摘要的详细程度。选项为 'low'、'medium' 或 'high'。默认为 'medium'。
• --max-length, -l: 每个摘要的最大长度（以字符为单位）。默认为 500。

安全功能

API 密钥管理

• API 密钥安全存储，并优先使用环境变量而不是配置文件
• 在使用前验证密钥的格式是否正确
• API 密钥永远不会在日志或错误消息中公开
• 当通过环境变量提供 API 密钥时，配置文件不会存储 API 密钥

身份验证

• 所有 MCP 服务器端点（健康检查除外）都需要通过 API 密钥进行身份验证
• 身份验证使用 x-api-key 标头进行安全传输
• 记录失败的身份验证尝试以进行安全监控

速率限制

• 内置速率限制可防止滥用服务
• 默认值：每个 IP 地址每分钟 60 个请求
• 可通过服务器设置进行配置

错误处理

• 具有分类的结构化错误系统
• 敏感信息永远不会在错误消息中公开
• 为不同的故障场景返回正确的错误代码

LLM 调用弹性

• 自动重试，并为瞬时故障提供指数退避
• 可配置的重试设置，包括最大重试次数、延迟和退避因子
• 将抖动添加到重试计时中，以防止惊群问题
• 请求 ID 跟踪，用于跟踪系统中的问题

支持的文件类型

• TypeScript (.ts, .tsx)
• JavaScript (.js, .jsx)
• Python (.py)
• Java (.java)
• C++ (.cpp)
• C (.c)
• Go (.go)
• Ruby (.rb)
• PHP (.php)
• C# (.cs)
• Swift (.swift)
• Rust (.rs)
• Kotlin (.kt)
• Scala (.scala)
• Vue (.vue)
• HTML (.html)
• CSS (.css, .scss, .less)

工作原理

1. 该工具递归扫描指定的目录，遵循 .gitignore 规则。
2. 它根据支持的扩展名过滤文件。
3. 对于每个支持的文件，它读取内容并确定编程语言。
4. 它将代码发送到 Gemini Flash 2.0，并提示进行总结，包括详细程度和长度限制。
5. 收集摘要并将其写入指定的输出文件。

输出格式

输出文件将具有以下格式：

relative/path/to/file
Summary text here

relative/path/to/next/file
Next summary text here

项目结构

• index.ts: 主要 CLI 实现
• src/: 源代码目录
  • summarizer/: 核心摘要功能
  • mcp/: MCP 服务器实现
  • config/: 配置管理
• bin/: CLI 入口点
• config.json: 默认配置文件
• tsconfig.json: TypeScript 配置
• package.json: 项目依赖项和脚本
• .env.example: 用于设置环境变量的模板
• .gitignore: Git 中要忽略的文件和目录
• __tests__: 单元和集成测试
• __mocks__/mock-codebase: 用于测试的模拟代码库

环境变量

可以使用以下环境变量来配置应用程序：

变量	描述	默认值
GOOGLE_API_KEY	您的 Google Gemini API 密钥	无（必需）
PORT	MCP 服务器的端口	24312
ALLOWED_ORIGINS	允许的 CORS 来源的逗号分隔列表	http://localhost:3000
LOG_LEVEL	日志记录级别（error、warn、info、debug）	info

有关模板，请参见 .env.example。

开发

运行测试

# 运行所有测试
npm test

# 运行具有覆盖率的测试
npm test -- --coverage

# 测试 MCP 服务器设置
npm run test:setup

未来改进

• 支持更多文件类型
• 支持其他 LLM 提供商
• 与 Electron 应用程序集成以获得 GUI 界面
• 增强的 MCP 服务器功能
• 高级令牌使用情况跟踪
• 基于 OpenTelemetry 的可观察性
• 增强的审计日志记录功能
• 秘密扫描集成