Code Summarizer MCP

代码摘要生成器

一个命令行工具，使用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

1. 安装依赖项：

   npm install

1. 创建一个 .env 使用您的Google API密钥文件：

   GOOGLE_API_KEY=your_api_key_here

1. 构建项目：

   npm run build

MCP服务器设置和集成

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

启动MCP服务器

# Start the MCP server
npm start -- server

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

# Set custom MCP server port
npm start -- config set --port 8080

与Claude Desktop连接

1. 启动代码汇总器MCP服务器
2. 打开克劳德桌面，点击克劳德菜单，然后选择“设置…”
3. 导航到“开发人员”部分
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"
    }
  }
}

1. 重新启动克劳德桌面
2. 重新启动后，您可以让Claude访问您的代码库，例如“总结我项目中的文件”

Claude Desktop的示例提示：

• “你能总结一下我项目中的所有JavaScript文件吗？”
• “请简要介绍一下我的代码库。”
• “解释文件'src/config/config.ts'的作用。”
• “在我的代码中查找与身份验证相关的所有函数。”

与Cursor AI连接

1. 启动代码汇总器MCP服务器
2. 创建一个 .cursor/mcp.json 项目目录中的文件：

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

1. 重新启动Cursor或重新加载项目
2. 向Cursor询问你的代码，例如，“你能总结一下我的代码库吗？”

光标提示示例：

• “为我总结一下这个代码库的结构。”
• “这个项目的关键组成部分是什么？”
• “请详细说明MCP服务器的实现。”
• “帮助我了解重试机制是如何工作的。”

与Cline建立联系

1. 启动代码汇总器MCP服务器
2. 在Cline中，您可以使用以下命令添加MCP服务器：

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

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

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

1. 然后，您可以要求Cline使用代码摘要器，例如，“请总结我的代码文件”

Cline的示例提示：

• “我的项目中的每个文件都做什么？”
• “创建所有TypeScript文件的摘要。”
• “解释此代码库中的身份验证流程。”
• “‘summarzer’目录的主要功能是什么？”

使用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) - 验证配置中的端口是否正确 - 检查阻止连接的防火墙问题

1. 身份验证错误

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

1. 传输错误

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

1. 权限问题

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

1. Claude Desktop找不到MCP服务器

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

1. 速率限制

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

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

用法

命令行接口

# Default command (summarize)
npm start -- summarize [directory] [output-file] [options]

# Summarize code in the current directory (output to summaries.txt)
npm start -- summarize

# Summarize code with specific detail level and max length
npm start -- summarize --detail high --max-length 1000

# Show help
npm start -- --help

配置管理

# Set your API key
npm start -- config set --api-key "your-api-key" 

# Set default detail level and max length
npm start -- config set --detail-level high --max-length 1000

# Set MCP server port (default: 24312)
npm start -- config set --port 8080

# Show current configuration
npm start -- config show

# Reset configuration to defaults
npm start -- config reset

API身份验证

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

x-api-key: your_api_key_here

所有端点（除 /health)需要身份验证。

选项

• --detail, -d：设置摘要的详细程度。选项有“低”、“中”或“高”。默认值为“中等”。
• --max-length, -l：每个摘要的最大长度（以字符为单位）。默认值为500。

安全功能

API密钥管理

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

认证

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

速率限制

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

错误处理

• 带分类的结构化错误系统
• 敏感信息永远不会在错误消息中暴露
• 针对不同的故障情况返回正确的错误代码

LLM呼叫弹性

• 针对瞬态故障，采用指数回退自动重试
• 可配置的重试设置，包括最大重试次数、延迟和回退系数
• Jitter增加了重试时间，以防止出现雷鸣般的牛群问题
• 请求ID跟踪，以跟踪整个系统中的问题

支持的文件类型

• TypeScript（.ts、.tsx）
• JavaScript（.js、.jsx）
• Python（.py）
• Java（.Java）
• C++（.cpp）
• C（.C）
• 去（.去）
• Ruby（.rb）
• PHP（.PHP）
• C#（.cs）
• Swift（.Swift）
• 锈蚀（.rs）
• 科特林（.kt）
• Scala（.scale）
• 视图（.vue）
• HTML（.HTML）
• CSS（.CSS、.scs、.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：用于测试的模拟代码库

环境变量

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

看 .env.example 对于模板。

发展

运行测试

# Run all tests
npm test

# Run tests with coverage
npm test -- --coverage

# Test MCP server setup
npm run test:setup

未来改进

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