Code Summarizer

A command-line tool that summarizes code files in a given directory using Gemini Flash 2.0. Now with MCP server support for integration with LLM tools!

Features

Recursively processes code files in a directory
Respects .gitignore rules
Skips irrelevant directories like node_modules, dist, etc.
Summarizes code files using Gemini Flash 2.0
Outputs summaries to a text file
Configurable detail level and summary length
MCP server for integration with Claude Desktop and other LLM tools
Modular design for easy integration into other applications
Secure API key management
Authentication for MCP server endpoints
Retry mechanism with exponential backoff for LLM calls
Rate limiting to prevent abuse

Requirements

Node.js 18+

Installation

Clone the repository

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

Install dependencies:
```
npm install
```
Create a .env file with your Google API key:
```
GOOGLE_API_KEY=your_api_key_here
```
Build the project:
```
npm run build
```

MCP Server Setup and Integration

The code summarizer includes a Model Context Protocol (MCP) server that allows LLM tools like Claude Desktop, Cursor AI, and Cline to access code summaries and file content.

Starting the MCP Server

# Start the MCP server
npm start -- server

By default, the server runs on port 24312. You can change this in your configuration:

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

Connecting with Claude Desktop

Start the code-summarizer MCP server
Open Claude Desktop and click on the Claude menu, then "Settings..."
Navigate to the "Developer" section
Create a file at ~/.claude/claude_desktop_config.json (macOS/Linux) or %USERPROFILE%\.claude\claude_desktop_config.json (Windows) with this content:

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

Restart Claude Desktop
After restarting, you can ask Claude to access your codebase, e.g., "Summarize the files in my project"

Example prompts for 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."

Connecting with Cursor AI

Start the code-summarizer MCP server
Create a .cursor/mcp.json file in your project directory:

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

Restart Cursor or reload your project
Ask Cursor about your code, e.g., "Can you summarize my codebase?"

Example prompts for 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."

Connecting with Cline

Start the code-summarizer MCP server
In Cline, you can add the MCP server with a command:

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

Then authenticate with your API key:

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

You can then ask Cline to use the code-summarizer, e.g., "Please summarize my code files"

Example prompts for 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?"

What You Can Do with the MCP Integration

Using the MCP integration, you can:

Get file summaries: Request concise explanations of what specific files do
Explore directories: Browse through your codebase structure
Batch processing: Summarize multiple files at once
Targeted queries: Find specific patterns or functionality in your code
Customize summaries: Control detail level and summary length
Update settings: Change configuration options through the MCP interface

The MCP server exposes your codebase to the LLM tools in a structured way, allowing them to read, navigate, and summarize your code without having to paste code snippets manually.

MCP Server Integration Details

MCP Resources

code://file/* - Access individual code files
code://directory/* - List code files in a directory
summary://file/* - Get summary for a specific file
summary://batch/* - Get summaries for multiple files

MCP Tools

summarize_file - Summarize a single file with options
summarize_directory - Summarize a directory with options
set_config - Update configuration options

MCP Prompts

code_summary - Prompt template for summarizing code
directory_summary - Prompt template for summarizing entire directories

Troubleshooting

Common MCP Connection Issues

Connection Refused
- Make sure the MCP server is running (npm start -- server)
- Verify the port is correct in your configuration
- Check for firewall issues blocking the connection
Authentication Errors
- Verify you've added the correct API key in the headers (x-api-key)
- Check that your API key is valid and properly formatted
- Make sure environment variables are set correctly
Transport Errors
- Ensure the correct transport type is specified (SSE)
- Check that the URL includes the correct endpoint (/sse)
- Verify network connectivity between the client and server
Permission Issues
- Ensure the MCP server has read access to your codebase
- Check file permissions if summarizing fails for specific files
Claude Desktop Not Finding the MCP Server
- Verify the path in claude_desktop_config.json is correct
- Make sure the command and args point to the right location
- Check Claude Desktop logs for any configuration errors
Rate Limiting
- If you see "Too many requests" errors, wait and try again later
- Consider adjusting the rate limiting settings in the server code

For other issues, check the server logs or open an issue on the GitHub repository.

Usage

Command Line Interface

# 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

Configuration Management

# 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 Authentication

When connecting to the MCP server, you need to include your API key in the request headers:

x-api-key: your_api_key_here

All endpoints (except /health) require authentication.

Options

--detail, -d: Set the level of detail for summaries. Options are 'low', 'medium', or 'high'. Default is 'medium'.
--max-length, -l: Maximum length of each summary in characters. Default is 500.

Security Features

API Key Management

API keys are stored securely and prioritize environment variables over configuration files
Keys are validated for proper format before use
API keys are never exposed in logs or error messages
Configuration file doesn't store API keys when they're provided via environment variables

Authentication

All MCP server endpoints (except health check) require authentication via API key
Authentication uses the x-api-key header for secure transmission
Failed authentication attempts are logged for security monitoring

Rate Limiting

Built-in rate limiting prevents abuse of the service
Default: 60 requests per minute per IP address
Configurable through server settings

Error Handling

Structured error system with categorization
Sensitive information is never exposed in error messages
Proper error codes are returned for different failure scenarios

LLM Call Resilience

Automatic retry with exponential backoff for transient failures
Configurable retry settings including max retries, delays, and backoff factor
Jitter added to retry timing to prevent thundering herd problems
Request ID tracking for tracing issues across the system

Supported File Types

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)

How It Works

The tool scans the specified directory recursively, respecting .gitignore rules.
It filters files based on supported extensions.
For each supported file, it reads the content and determines the programming language.
It sends the code to Gemini Flash 2.0 with a prompt to summarize, including detail level and length constraints.
The summaries are collected and written to the specified output file.

Output Format

The output file will have the following format:

relative/path/to/file
Summary text here

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

Project Structure

index.ts: Main CLI implementation
src/: Source code directory
- summarizer/: Core summarization functionality
- mcp/: MCP server implementation
- config/: Configuration management
bin/: CLI entrypoint
config.json: Default configuration file
tsconfig.json: TypeScript configuration
package.json: Project dependencies and scripts
.env.example: Template for setting up environment variables
.gitignore: Files and directories to ignore in Git
__tests__: Unit and integration tests
__mocks__/mock-codebase: Mock codebase for testing

Environment Variables

The following environment variables can be used to configure the application:

Variable	Description	Default
`GOOGLE_API_KEY`	Your Google Gemini API key	None (required)
`PORT`	Port for the MCP server	24312
`ALLOWED_ORIGINS`	Comma-separated list of allowed CORS origins	http://localhost:3000
`LOG_LEVEL`	Logging level (error, warn, info, debug)	info

See .env.example for a template.

Development

Running Tests

# Run all tests
npm test

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

# Test MCP server setup
npm run test:setup

Future Improvements

Support for more file types
Support for alternative LLM providers
Integration with an Electron app for a GUI interface
Enhanced MCP server capabilities
Advanced token usage tracking
OpenTelemetry-based observability
Enhanced audit logging capabilities
Secret scanning integration

代码摘要器