# MCP Code Refiner
> A powerful **second-layer LLM** MCP server that refines and reviews code using AI. Perfect for improving AI-generated code or enhancing human-written code through natural language feedback.
## What is This?
This is an [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that adds code refinement and review capabilities to any MCP client like Claude Desktop. It acts as a "second layer" AI that specializes in code improvement, working alongside your primary AI assistant.
**Use it to:**
- Refine code generated by ChatGPT, Claude, or any AI with natural language feedback
- Get comprehensive code reviews with security and performance analysis
- Iteratively improve code until it meets your standards
- Learn from AI-suggested improvements
## Features
- **Code Refinement** - Improve code with natural language feedback ("make it more logical", "add error handling")
- **Code Review** - AI-powered analysis for bugs, security, performance, and best practices
- **Multi-Model Support** - Choose between Gemini, Claude, or OpenAI models
- **Plug & Play** - Works with Claude Desktop and any MCP client
- **Smart Prompts** - Optimized prompts for high-quality, actionable results
- **Diff View** - See exactly what changes before applying them
## Quick Start
### Prerequisites
- Python 3.10 or higher
- At least one AI provider API key (Gemini recommended for free tier)
### 1. Clone and Install
```bash
git clone https://github.com/yourusername/mcp_code_review.git
cd mcp_code_review
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
pip install -r requirements.txt
```
### 2. Configure API Keys
Create a `.env` file from the example:
```bash
cp .env.example .env
```
Edit `.env` and add **at least ONE** API key:
```bash
# Recommended: Google Gemini (free tier available)
GOOGLE_API_KEY=your-gemini-api-key-here
# Alternative: Anthropic Claude
ANTHROPIC_API_KEY=your-anthropic-api-key-here
# Alternative: OpenAI
OPENAI_API_KEY=your-openai-api-key-here
```
**Get API keys from:**
- Gemini: https://ai.google.dev/
- Claude: https://console.anthropic.com/
- OpenAI: https://platform.openai.com/api-keys
### 3. Connect to Claude Desktop
Edit your Claude Desktop config file:
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
Add the server configuration:
```json
{
"mcpServers": {
"code-refiner": {
"command": "python",
"args": ["/absolute/path/to/mcp_code_review/mcp_server.py"],
"env": {
"GOOGLE_API_KEY": "your-gemini-api-key"
}
}
}
}
```
**Important:** Replace `/absolute/path/to/mcp_code_review/` with the actual path on your system.
Restart Claude Desktop to load the server.
## Usage
Once configured, just talk to Claude naturally in Claude Desktop. The tools are automatically available!
### Code Refinement
Improve existing code with natural language instructions:
**You:** "Refine ./my_script.py to make it more logical and add error handling"
**Claude will:**
1. Call `refine_code_tool` with your request
2. Show you a diff of proposed changes
3. Explain what was changed and why
4. Ask for your approval
5. Apply changes with `apply_refinement_tool` if you confirm
### Code Review
Get comprehensive code analysis:
**You:** "Review ./server.py for security issues and performance problems"
**Claude will:**
1. Call `review_code_tool` on the file
2. Show issues found with severity levels (high/medium/low)
3. Highlight code strengths
4. Provide an overall quality score
5. Suggest specific improvements
### Real-World Examples
**Refinement:**
- "Make ./app.py more performant by optimizing loops"
- "Simplify the logic in ./utils/helper.py"
- "Add comprehensive error handling to ./api/routes.py"
- "Refactor ./legacy_code.py to follow modern Python best practices"
- "Add type hints and docstrings to ./calculator.py"
**Review:**
- "Review ./authentication.py for security vulnerabilities"
- "Check ./database.py for SQL injection risks"
- "Analyze ./api_client.py for error handling issues"
- "Review ./main.py and suggest improvements"
## Available Models
Configure via `ai_provider` parameter or Claude will use the default (gemini).
### Gemini (Google)
- `gemini` - Gemini 2.0 Flash (fast, free tier)
- `gemini-pro` - Gemini 1.5 Pro (more capable)
### Claude (Anthropic)
- `claude` or `claude-sonnet` - Claude 3.5 Sonnet (high quality)
- `claude-opus` - Claude 3 Opus (most capable)
- `claude-haiku` - Claude 3.5 Haiku (fastest)
### OpenAI
- `openai` or `gpt-4o` - GPT-4o (balanced)
- `gpt-4` - GPT-4 Turbo
- `gpt-3.5` - GPT-3.5 Turbo (fastest)
## MCP Tools Reference
This server provides three MCP tools that Claude Desktop can call automatically:
### 1. `refine_code_tool`
**Purpose:** Improves existing code based on natural language feedback using a second-layer LLM.
**Parameters:**
- `user_request` (string, required) - What you want to improve (e.g., "make it more logical", "add error handling")
- `file_path` (string, required) - Path to the code file to refine
- `ai_provider` (string, optional) - AI model to use (default: "gemini")
**Returns:**
```json
{
"status": "success",
"explanation": "Added error handling and simplified logic...",
"diff": "--- original\n+++ refined\n...",
"refined_code": "def improved_function():\n ...",
"file_path": "./app.py"
}
```
### 2. `review_code_tool`
**Purpose:** Analyzes code for bugs, security vulnerabilities, performance issues, and quality.
**Parameters:**
- `file_path` (string, required) - Path to the code file to review
- `ai_provider` (string, optional) - AI model to use (default: "gemini")
**Returns:**
```json
{
"status": "success",
"issues": [
{
"severity": "high",
"category": "security",
"issue": "SQL injection vulnerability",
"line": 42,
"suggestion": "Use parameterized queries..."
}
],
"strengths": ["Good error handling", "Clear naming"],
"overall_assessment": "Code is functional but has security concerns...",
"score": 7
}
```
### 3. `apply_refinement_tool`
**Purpose:** Applies refined code to the file after user approval.
**Parameters:**
- `file_path` (string, required) - Path to the file to update
- `refined_code` (string, required) - The improved code from `refine_code_tool`
**Returns:**
```json
{
"status": "success",
"message": "Code successfully applied to ./app.py"
}
```
**Important:** Only use this after the user has reviewed and approved the changes!
## Testing
Test the server without Claude Desktop:
```bash
python client.py
```
This runs a simple test client to verify the server works.
## Project Structure
```
mcp_code_review/
├── mcp_server.py # Main MCP server entry point
├── client.py # Test client for local testing
├── requirements.txt # Python dependencies
├── .env.example # Environment variables template
├── .env # Your API keys (git-ignored)
│
├── tools/ # MCP tool implementations
│ ├── __init__.py
│ ├── file_ops.py # File read/write utilities
│ ├── code_refinement.py # Code refinement logic
│ └── code_review.py # Code review logic
│
├── prompts/ # AI prompt templates
│ ├── code_refinement.txt # Refinement prompt template
│ └── code_review.txt # Review prompt template
│
└── utils/ # Helper utilities
├── __init__.py
├── llm_client.py # LiteLLM wrapper for multi-provider support
└── diff_generator.py # Unified diff generation
```
## How It Works
This server implements a "second-layer LLM" architecture:
1. **You** interact with Claude Desktop (first-layer AI) using natural language
2. **Claude** understands your intent and calls the appropriate MCP tool
3. **MCP Server** receives the request and invokes a second-layer LLM specialized for code tasks
4. **Second-layer LLM** analyzes or refines the code using optimized prompts
5. **Results** are returned to Claude with diffs, explanations, and suggestions
6. **Claude** presents the results to you for review
7. **You** approve or reject the changes
8. **Changes** are applied only after your confirmation
This two-layer approach combines Claude's conversational abilities with specialized code analysis/refinement models.
## Use Cases
### 1. Refining AI-Generated Code
First LLM generates code → Use this to improve it
### 2. Code Review Assistant
Get AI-powered feedback on your code
### 3. Iterative Improvement
Keep refining until perfect
### 4. Learning Tool
See how AI would improve your code and learn from it
## Requirements
- Python 3.10 or higher
- At least one AI provider API key (Gemini recommended for free tier)
- Dependencies listed in `requirements.txt`:
- `fastmcp` - FastMCP framework
- `mcp` - Model Context Protocol SDK
- `litellm` - Multi-provider LLM wrapper
- `rich` - Terminal formatting
- `python-dotenv` - Environment variable management
## Troubleshooting
### Server Not Appearing in Claude Desktop
1. Check that the path in `claude_desktop_config.json` is absolute, not relative
2. Verify the Python path is correct (use `which python` in your activated venv)
3. Check Claude Desktop logs for errors:
- **macOS:** `~/Library/Logs/Claude/`
- **Windows:** `%APPDATA%\Claude\logs\`
4. Restart Claude Desktop after config changes
### API Key Errors
- Verify your API key is correct in the `.env` file
- Make sure the key is also in the `claude_desktop_config.json` env section
- Check that you have API credits/quota remaining
- Try using a different AI provider as a fallback
### File Path Issues
- Always use absolute paths or paths relative to where you run the command
- On Windows, use forward slashes `/` or escaped backslashes `\\`
- Verify the file exists: `ls /path/to/file.py`
### Module Import Errors
- Ensure virtual environment is activated
- Reinstall dependencies: `pip install -r requirements.txt --upgrade`
- Check Python version: `python --version` (must be 3.10+)
### Testing the Server
Run the test client to verify the server works:
```bash
python client.py
```
This bypasses Claude Desktop and tests the MCP server directly.
## Contributing
Contributions are welcome! Here's how you can help:
1. **Report bugs** - Open an issue with details about the problem
2. **Suggest features** - Share ideas for new capabilities
3. **Improve prompts** - The prompt templates in `prompts/` can always be refined
4. **Add AI providers** - Extend support for additional LLM providers
5. **Submit PRs** - Fix bugs, add features, improve documentation
## License
MIT License - see LICENSE file for details
## Acknowledgments
Built with:
- [FastMCP](https://github.com/jlowin/fastmcp) - FastMCP framework for building MCP servers
- [LiteLLM](https://docs.litellm.ai/) - Unified interface for multiple LLM providers
- [MCP Protocol](https://modelcontextprotocol.io/) - Model Context Protocol specification
## Resources
- [FastMCP Documentation](https://github.com/jlowin/fastmcp)
- [LiteLLM Documentation](https://docs.litellm.ai/)
- [MCP Protocol Specification](https://modelcontextprotocol.io/)
- [Claude Desktop Setup Guide](https://docs.anthropic.com/claude/docs/mcp)
---
**Questions or issues?** Open an issue on GitHub or check the troubleshooting section above.
