Code Summarizer

代码摘要工具

一款命令行工具，可使用 Gemini Flash 2.0 总结指定目录中的代码文件。现已支持 MCP 服务，可与大模型工具集成！

功能

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

要求

• Node.js 18+

安装

1. 克隆仓库

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

2. 安装依赖：

   npm install
   

3. 创建 .env 文件并填入 Google API 密钥：

   GOOGLE_API_KEY=your_api_key_here
   

4. 构建项目：

   npm run build
   

MCP 服务设置与集成

代码摘要工具包含一个 Model Context Protocol（MCP）服务，允许 Claude Desktop、Cursor AI 和 Cline 等大模型工具访问代码摘要和文件内容。

启动 MCP 服务

# Start the MCP server
npm start -- server

默认情况下，服务运行在端口 24312。你可以在配置中修改端口：

# Set custom MCP server port
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 访问代码库，例如：“总结我项目中的文件”

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:24312/sse",
      "headers": {
        "x-api-key": "your_api_key_here"
      }
    }
  }
}

3. 重启 Cursor 或重新加载项目
4. 询问 Cursor 关于代码的问题，例如：“你能总结一下我的代码库吗？”

Cursor 提示词示例：

• “请为我总结这个代码库的结构。”
• “这个项目中有哪些关键组件？”
• “详细解释 MCP 服务的实现。”
• “帮我了解重试机制的工作原理。”

连接 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，例如：“请总结我的代码文件”

Cline 提示词示例：

• “我项目中的每个文件有什么作用？”
• “总结所有 TypeScript 文件。”
• “解释这个代码库中的身份验证流程。”
• “‘summarizer’ 目录中有哪些主要函数？”

MCP 集成可以实现的功能

使用 MCP 集成，你可以：

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

MCP 服务以结构化方式向大模型工具开放你的代码库，让它们能够读取、浏览并总结代码，无需手动粘贴代码片段。

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. 身份验证错误

   • 验证是否已在请求头（x-api-key）中添加正确的 API 密钥
   • 检查 API 密钥是否有效且格式正确
   • 确保环境变量设置正确

3. 传输错误

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

4. 权限问题

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

5. Claude Desktop 未找到 MCP 服务

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

6. 速率限制

   • 如果看到“请求过多”错误，请等待一段时间后重试
   • 考虑调整服务代码中的速率限制设置

如有其他问题，请查看服务日志，或在 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：设置摘要的详细程度。可选值为“low”“medium”或“high”。默认值为“medium”。
• --max-length、-l：每条摘要的最大字符数。默认值为 500。

安全功能

API 密钥管理

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

身份验证

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

速率限制

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

错误处理

• 采用分类的结构化错误系统
• 错误消息绝不会暴露敏感信息
• 针对不同的失败情况返回相应的错误代码

大模型调用韧性

• 遇到暂时性故障时，自动进行指数退避重试
• 重试设置可配置，包括最大重试次数、延迟时间和退避系数
• 重试时间会加入抖动，以防止惊群问题
• 跟踪请求 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 获取模板。

开发

运行测试

# Run all tests
npm test

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

# Test MCP server setup
npm run test:setup

后续改进

• 支持更多文件类型
• 支持其他大模型提供商
• 集成 Electron 应用以提供图形界面
• 增强 MCP 服务功能
• 高级令牌用量跟踪
• 基于 OpenTelemetry 的可观测性
• 增强审计日志功能
• 集成密钥扫描