README.md•6.53 kB
# Python Code Review MCP Agent 🐍🔍
A comprehensive **Model Context Protocol (MCP)** server designed specifically for **backend developers** working with Python. This agent provides detailed **code quality** and **security analysis** with consistent, actionable reporting.
## 🎯 **Key Features**
### 🔒 **Security-First Analysis**
- **SQL Injection Detection** - String formatting, concatenation, f-strings
- **Command Injection Prevention** - os.system(), subprocess with shell=True
- **Code Injection Scanning** - eval(), exec() usage detection
- **Secrets Detection** - Hardcoded passwords, API keys, tokens
- **Crypto Security** - Weak random number generation, SSL issues
### 📊 **Code Quality Assessment**
- **PEP 8 Compliance** - Naming conventions, style guidelines
- **Exception Handling** - Bare except, broad exceptions
- **Performance Patterns** - Inefficient loops, list operations
- **Import Management** - Wildcard imports, multiple imports
- **Code Complexity** - Function length, maintainability
### 📋 **Detailed Reporting**
- **Executive Summaries** - Risk assessment, deployment readiness
- **Quality Scorecards** - 0-100 scoring for quality and security
- **Severity Levels** - Critical, High, Medium, Low prioritization
- **Actionable Suggestions** - Specific fix recommendations
- **Comparison Reports** - Before/after improvement tracking
## 🛠️ **Available MCP Tools**
### 1. `review_python_code`
Comprehensive analysis with detailed, summary, or security-focused reports.
```json
{
"code": "your_python_code_here",
"filename": "optional_filename.py",
"reportType": "detailed" // "detailed", "summary", or "security"
}
```
### 2. `security_audit`
Focused security vulnerability scanning with threat analysis.
```json
{
"code": "your_python_code_here",
"filename": "optional_filename.py"
}
```
### 3. `analyze_code_quality`
Deep code quality analysis with configurable focus areas.
```json
{
"code": "your_python_code_here",
"filename": "optional_filename.py",
"includeStyle": true,
"includeMaintainability": true
}
```
### 4. `compare_code_versions`
Compare original vs. revised code to track improvements.
```json
{
"originalCode": "original_version_here",
"revisedCode": "improved_version_here",
"filename": "optional_filename.py"
}
```
### 5. `get_improvement_suggestions`
Get targeted suggestions for specific areas of concern.
```json
{
"code": "your_python_code_here",
"filename": "optional_filename.py",
"focusArea": "security" // "security", "quality", "performance", "style", "all"
}
```
## 🚀 **Quick Start**
### Installation
```bash
npm install
npm run build
```
### Running Tests
```bash
npm test
```
### Starting the MCP Server
```bash
npm start
```
### Running Demo
```bash
node dist/demo.js
```
## ⚙️ **MCP Client Configuration**
Add to your MCP client configuration:
```json
{
"mcpServers": {
"python-code-review": {
"command": "node",
"args": ["/path/to/python_code_review_mcp/dist/index.js"]
}
}
}
```
## 📖 **Usage Examples**
### Security Analysis
*"Audit this Python Flask endpoint for security vulnerabilities"*
```python
@app.route('/user/<user_id>')
def get_user(user_id):
query = f"SELECT * FROM users WHERE id = {user_id}"
cursor.execute(query)
return cursor.fetchone()
```
**Result**: Detects SQL injection vulnerability, provides secure parameterized query solution.
### Code Quality Review
*"Review this data processing function for quality issues"*
```python
def process_data(items):
result = []
for i in range(len(items)):
result += [items[i].upper()]
return result
```
**Result**: Identifies performance issues, suggests enumerate() and list comprehensions.
### Improvement Tracking
*"Compare my original code with the improved version"*
**Result**: Shows quality score improvements, security enhancements, and resolved issues.
## 🎯 **Perfect for Backend Developers**
### 🏗️ **Framework Support**
- **Django** - Models, views, security best practices
- **Flask** - Route handlers, authentication, security
- **FastAPI** - Async patterns, data validation
- **SQLAlchemy** - Query security, ORM patterns
### 🔧 **Development Workflow**
- **Pre-commit Analysis** - Catch issues before they reach production
- **Code Review Assistant** - Comprehensive analysis for pull requests
- **Security Auditing** - Regular vulnerability assessments
- **Refactoring Guide** - Systematic improvement tracking
### 📊 **Quality Metrics**
- **Security Score** (0-100) - Vulnerability risk assessment
- **Quality Score** (0-100) - Code quality measurement
- **Issue Density** - Problems per 100 lines of code
- **Risk Level** - Overall deployment readiness
## 🧪 **Comprehensive Testing**
- **40/40 Tests Passing** - 100% test coverage
- **Security Detection** - All major vulnerability types
- **Quality Analysis** - PEP 8, best practices, performance
- **Report Generation** - Multiple formats and detail levels
- **Edge Cases** - Empty code, comments, mixed indentation
- **Real-World Examples** - Flask apps, Django models, data processing
## 🔍 **Detection Capabilities**
### 🚨 Critical Security Issues
- SQL injection vulnerabilities
- Command injection risks
- Code injection through eval/exec
- Hardcoded secrets and credentials
### ⚠️ High Priority Issues
- SSL verification disabled
- Subprocess with shell=True
- Broad exception handling
### 📋 Quality Improvements
- PEP 8 naming conventions
- Performance anti-patterns
- Import organization
- Documentation completeness
## 📈 **Scoring System**
### Security Score Calculation
- **100**: No security vulnerabilities detected
- **70-99**: Minor security concerns
- **30-69**: Moderate security risks
- **0-29**: Critical security vulnerabilities
### Quality Score Calculation
- **90-100**: Excellent code quality
- **80-89**: Good code quality
- **70-79**: Fair code quality
- **60-69**: Poor code quality
- **0-59**: Critical quality issues
## 🎉 **Production Ready**
- ✅ **Zero Dependencies** - No external APIs required
- ✅ **Fast Analysis** - Local pattern matching
- ✅ **Consistent Reports** - Standardized output format
- ✅ **TypeScript** - Full type safety and IntelliSense
- ✅ **Error Handling** - Graceful failure and recovery
- ✅ **MCP Standards** - Compatible with all MCP clients
Transform your Python code review process with intelligent, automated analysis focused on the specific needs of backend developers! 🐍✨