代码摘要器

一款使用 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) 服务器，允许 Claude Desktop、Cursor AI 和 Cline 等 LLM 工具访问代码摘要和文件内容。

启动 MCP 服务器

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

与 Claude Desktop 连接

1. 启动代码摘要器 MCP 服务器

2. 打开 Claude Desktop 并点击 Claude 菜单，然后点击“设置...”

3. 导航至“开发者”部分

4. 在~/.claude/claude_desktop_config.json (macOS/Linux) 或%USERPROFILE%\.claude\claude_desktop_config.json (Windows) 中创建一个文件，内容如下：

5. 重启Claude桌面

6. 重新启动后，您可以要求 Claude 访问您的代码库，例如“总结我的项目中的文件”

Claude Desktop 的示例提示：

• “你能总结一下我项目里的所有 JavaScript 文件吗？”

• “请给我一个关于我的代码库的总体概述。”

• “解释一下‘src/config/config.ts’文件的作用。”

• “在我的代码中查找所有与身份验证相关的函数。”

与 Cursor AI 连接

1. 启动代码摘要器 MCP 服务器

2. 在您的项目目录中创建一个.cursor/mcp.json文件：

3. 重新启动 Cursor 或重新加载您的项目

4. 向 Cursor 询问您的代码，例如“您能总结一下我的代码库吗？”

光标提示示例：

• “请为我总结一下这个代码库的结构。”

• “这个项目的关键组成部分是什么？”

• “请详细解释一下 MCP 服务器的实现。”

• “帮助我理解重试机制是如何工作的。”

与克莱恩联系

1. 启动代码摘要器 MCP 服务器

2. 在 Cline 中，您可以使用以下命令添加 MCP 服务器：

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

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

Cline 的示例提示：

• “我的项目中的每个文件有什么作用？”

• “创建所有 TypeScript 文件的摘要。”

• “解释此代码库中的身份验证流程。”

• “‘summarizer’目录下的主要功能是什么？”

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中的路径是否正确

   • 确保命令和参数指向正确的位置

   • 检查 Claude Desktop 日志中是否存在任何配置错误

6. 速率限制

   • 如果您看到“请求过多”错误，请等待并稍后重试

   • 考虑调整服务器代码中的速率限制设置

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

用法

命令行界面

配置管理

API 身份验证

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

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

选项

• --detail ， -d ：设置摘要的详细程度。选项包括“低”、“中”或“高”。默认为“中”。

• --max-length ， -l ：每个摘要的最大长度（以字符为单位）。默认值为 500。

安全功能

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）

• 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. 摘要被收集并写入指定的输出文件。

输出格式

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

项目结构

• 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了解模板。

发展

运行测试

未来的改进

• 支持更多文件类型

• 对替代法学硕士 (LLM) 提供商的支持

• 与 Electron 应用程序集成以实现 GUI 界面

• 增强的 MCP 服务器功能

• 高级令牌使用情况跟踪

• 基于 OpenTelemetry 的可观察性

• 增强的审计日志功能

• 秘密扫描集成