Code Summarizer MCP

# 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 1. Clone the repository ```bash git clone https://github.com/nicobailon/code-summarizer.git cd code-summarizer ``` 2. Install dependencies: ```bash npm install ``` 3. Create a `.env` file with your Google API key: ``` GOOGLE_API_KEY=your_api_key_here ``` 4. Build the project: ```bash 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 ```bash # Start the MCP server npm start -- server ``` By default, the server runs on port 24312. You can change this in your configuration: ```bash # Set custom MCP server port npm start -- config set --port 8080 ``` ### Connecting with Claude Desktop 1. Start the code-summarizer MCP server 2. Open Claude Desktop and click on the Claude menu, then "Settings..." 3. Navigate to the "Developer" section 4. Create a file at `~/.claude/claude_desktop_config.json` (macOS/Linux) or `%USERPROFILE%\.claude\claude_desktop_config.json` (Windows) with this content: ```json { "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. Restart Claude Desktop 6. 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 1. Start the code-summarizer MCP server 2. Create a `.cursor/mcp.json` file in your project directory: ```json { "mcpServers": { "code-summarizer": { "transport": "sse", "url": "http://localhost:24312/sse", "headers": { "x-api-key": "your_api_key_here" } } } } ``` 3. Restart Cursor or reload your project 4. 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 1. Start the code-summarizer MCP server 2. In Cline, you can add the MCP server with a command: ``` /mcp add code-summarizer http://localhost:24312/sse ``` 3. Then authenticate with your API key: ``` /mcp config code-summarizer headers.x-api-key your_api_key_here ``` 4. 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: 1. **Get file summaries**: Request concise explanations of what specific files do 2. **Explore directories**: Browse through your codebase structure 3. **Batch processing**: Summarize multiple files at once 4. **Targeted queries**: Find specific patterns or functionality in your code 5. **Customize summaries**: Control detail level and summary length 6. **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 1. **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 2. **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 3. **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 4. **Permission Issues** - Ensure the MCP server has read access to your codebase - Check file permissions if summarizing fails for specific files 5. **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 6. **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 ```bash # 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 ```bash # 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 1. The tool scans the specified directory recursively, respecting `.gitignore` rules. 2. It filters files based on supported extensions. 3. For each supported file, it reads the content and determines the programming language. 4. It sends the code to Gemini Flash 2.0 with a prompt to summarize, including detail level and length constraints. 5. 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 ```bash # 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