星战科技xingzhan.cloud
返回市场
代码摘要器

代码摘要器

作者：nicobailon5 星标更新：2025-03-25
安装使用来源：spider==github.com

项目介绍

Code Summarizer

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

特性

  • 递归处理目录中的代码文件
  • 遵循.gitignore规则
  • 跳过无关目录如node_modules、dist等
  • 使用Gemini Flash 2.0对代码文件进行总结
  • 将总结结果输出到文本文件中
  • 可配置的详细程度和总结长度
  • 支持与Claude Desktop和其他LLM工具集成的MCP服务器
  • 模块化设计，便于集成到其他应用程序中
  • 安全的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服务器

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

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

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

连接到Claude Desktop

  1. 启动code-summarizer MCP服务器
  2. 打开Claude Desktop并点击Claude菜单，然后选择“设置...”
  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. 重启Claude Desktop
  2. 重启后，您可以要求Claude访问您的代码库，例如“总结我的项目中的文件”

Claude Desktop示例提示：

  • “你能总结我项目中的所有JavaScript文件吗？”
  • “请给我一个关于我代码库的高层次概述。”
  • “解释一下文件'src/config/config.ts'的作用。”
  • “在我的代码中找到所有与认证相关的函数。”

连接到Cursor AI

  1. 启动code-summarizer MCP服务器
  2. 在项目目录中创建一个.cursor/mcp.json文件：
{
  "mcpServers": {
    "code-summarizer": {
      "transport": "sse",
      "url": "http://localhost:22312/sse",
      "headers": {
        "x-api-key": "your_api_key_here"
      }
    }
  }
}
  1. 重启Cursor或重新加载项目
  2. 向Cursor询问有关您的代码的问题，例如“你能总结我的代码库吗？”

Cursor示例提示：

  • “为我总结这个代码库的结构。”
  • “这个项目的关键组件是什么？”
  • “给我一个关于MCP服务器实现的详细解释。”
  • “帮助我理解重试机制是如何工作的。”

连接到Cline

  1. 启动code-summarizer 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使用code-summarizer，例如“请总结我的代码文件”

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存储库中打开一个问题。

使用方法

命令行接口

# 默认命令（总结）
npm start -- summarize [目录] [输出文件] [选项]

# 总结当前目录中的代码（输出到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

所有端点（除了健康检查）都需要通过API密钥进行身份验证。

选项

  • --detail, -d：设置总结的详细程度。选项有'低'、'中'或'高'。默认是'中'。
  • --max-length, -l：每个总结的最大长度（字符）。默认是500。

安全特性

API密钥管理

  • 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. 收集总结并将它们写入指定的输出文件。

输出格式

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

相对路径/到/文件
总结文本在这里

相对路径/到/下一个文件
下一个总结文本在这里

项目结构

  • 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密钥无（必需）
PORTMCP服务器端口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的可观测性
  • 增强审计日志能力
  • 秘密扫描集成