# 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! 🐍✨