my-pal-mcp-server/docs/api/mcp-protocol.md

# MCP Protocol Implementation

## Overview

The Gemini MCP Server implements the Model Context Protocol (MCP) specification, providing Claude with standardized access to Google's Gemini AI models through a secure, tool-based interface.

## Protocol Specification

### MCP Version
- **Implemented Version**: MCP v1.0
- **Transport**: stdio (standard input/output)
- **Serialization**: JSON-RPC 2.0
- **Authentication**: Environment-based API key management

### Core Protocol Flow

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}
```

**Response**:
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "chat",
        "description": "Quick questions and general collaboration",
        "inputSchema": {
          "type": "object",
          "properties": {
            "prompt": {"type": "string"},
            "continuation_id": {"type": "string", "optional": true}
          },
          "required": ["prompt"]
        }
      }
    ]
  }
}
```

## Tool Registration System

### Tool Discovery (`server.py:67`)

```python
@server.list_tools()
async def list_tools() -> list[types.Tool]:
    """Dynamic tool discovery and registration"""
    tools = []
    
    # Scan tools directory for available tools
    for tool_module in REGISTERED_TOOLS:
        tool_instance = tool_module()
        schema = tool_instance.get_schema()
        tools.append(schema)
    
    return tools
```

### Tool Schema Definition

Each tool must implement a standardized schema:

```python
def get_schema(self) -> types.Tool:
    return types.Tool(
        name="analyze",
        description="Code exploration and understanding",
        inputSchema={
            "type": "object",
            "properties": {
                "files": {
                    "type": "array",
                    "items": {"type": "string"},
                    "description": "Files or directories to analyze"
                },
                "question": {
                    "type": "string", 
                    "description": "What to analyze or look for"
                },
                "analysis_type": {
                    "type": "string",
                    "enum": ["architecture", "performance", "security", "quality", "general"],
                    "default": "general"
                },
                "thinking_mode": {
                    "type": "string",
                    "enum": ["minimal", "low", "medium", "high", "max"],
                    "default": "medium"
                },
                "continuation_id": {
                    "type": "string",
                    "description": "Thread continuation ID for multi-turn conversations"
                }
            },
            "required": ["files", "question"]
        }
    )
```

## Tool Execution Protocol

### Request Processing (`server.py:89`)

```python
@server.call_tool()
async def call_tool(name: str, arguments: dict) -> list[types.TextContent]:
    """Tool execution with comprehensive error handling"""
    
    try:
        # 1. Tool validation
        tool_class = TOOL_REGISTRY.get(name)
        if not tool_class:
            raise ToolNotFoundError(f"Tool '{name}' not found")
        
        # 2. Parameter validation
        tool_instance = tool_class()
        validated_args = tool_instance.validate_parameters(arguments)
        
        # 3. Security validation
        if 'files' in validated_args:
            validated_args['files'] = validate_file_paths(validated_args['files'])
        
        # 4. Tool execution
        result = await tool_instance.execute(validated_args)
        
        # 5. Response formatting
        return [types.TextContent(
            type="text",
            text=result.content
        )]
        
    except Exception as e:
        # Error response with context
        error_response = format_error_response(e, name, arguments)
        return [types.TextContent(
            type="text", 
            text=error_response
        )]
```

### Response Standardization

All tools return standardized `ToolOutput` objects:

```python
@dataclass
class ToolOutput:
    content: str
    metadata: Dict[str, Any]
    continuation_id: Optional[str] = None
    files_processed: List[str] = field(default_factory=list)
    thinking_tokens_used: int = 0
    status: str = "success"  # success, partial, error
    
    def to_mcp_response(self) -> str:
        """Convert to MCP-compatible response format"""
        response_parts = [self.content]
        
        if self.metadata:
            response_parts.append("\n## Metadata")
            for key, value in self.metadata.items():
                response_parts.append(f"- {key}: {value}")
        
        if self.files_processed:
            response_parts.append("\n## Files Processed")
            for file_path in self.files_processed:
                response_parts.append(f"- {file_path}")
        
        if self.continuation_id:
            response_parts.append(f"\n## Continuation ID: {self.continuation_id}")
        
        return '\n'.join(response_parts)
```

## Individual Tool APIs

### 1. Chat Tool

**Purpose**: Quick questions, brainstorming, general discussion

**API Specification**:
```json
{
  "name": "chat",
  "parameters": {
    "prompt": "string (required)",
    "continuation_id": "string (optional)",
    "temperature": "number (optional, 0.0-1.0, default: 0.5)",
    "thinking_mode": "string (optional, default: 'medium')"
  }
}
```

**Example Request**:
```json
{
  "method": "tools/call",
  "params": {
    "name": "chat",
    "arguments": {
      "prompt": "Explain the benefits of using MCP protocol",
      "thinking_mode": "low"
    }
  }
}
```

**Response Format**:
```json
{
  "result": [{
    "type": "text",
    "text": "The Model Context Protocol (MCP) provides several key benefits:\n\n1. **Standardization**: Unified interface across different AI tools...\n\n## Metadata\n- thinking_mode: low\n- tokens_used: 156\n- response_time: 1.2s"
  }]
}
```

### 2. ThinkDeep Tool

**Purpose**: Complex architecture, system design, strategic planning

**API Specification**:
```json
{
  "name": "thinkdeep", 
  "parameters": {
    "current_analysis": "string (required)",
    "problem_context": "string (optional)",
    "focus_areas": "array of strings (optional)",
    "thinking_mode": "string (optional, default: 'high')",
    "files": "array of strings (optional)",
    "continuation_id": "string (optional)"
  }
}
```

**Example Request**:
```json
{
  "method": "tools/call",
  "params": {
    "name": "thinkdeep",
    "arguments": {
      "current_analysis": "We have an MCP server with 6 specialized tools",
      "problem_context": "Need to scale to handle 100+ concurrent Claude sessions",
      "focus_areas": ["performance", "architecture", "resource_management"],
      "thinking_mode": "max"
    }
  }
}
```

### 3. Analyze Tool

**Purpose**: Code exploration, understanding existing systems

**API Specification**:
```json
{
  "name": "analyze",
  "parameters": {
    "files": "array of strings (required)",
    "question": "string (required)", 
    "analysis_type": "enum: architecture|performance|security|quality|general",
    "thinking_mode": "string (optional, default: 'medium')",
    "continuation_id": "string (optional)"
  }
}
```

**File Processing Behavior**:
- **Directories**: Recursively scanned for relevant files
- **Token Budget**: Allocated based on file priority (source code > docs > logs)
- **Security**: All paths validated and sandboxed to PROJECT_ROOT
- **Formatting**: Line numbers added for precise code references

### 4. CodeReview Tool

**Purpose**: Code quality, security, bug detection

**API Specification**:
```json
{
  "name": "codereview",
  "parameters": {
    "files": "array of strings (required)",
    "context": "string (required)",
    "review_type": "enum: full|security|performance|quick (default: full)",
    "severity_filter": "enum: critical|high|medium|all (default: all)", 
    "standards": "string (optional)",
    "thinking_mode": "string (optional, default: 'medium')"
  }
}
```

**Response Includes**:
- **Issue Categorization**: Critical → High → Medium → Low
- **Specific Fixes**: Concrete code suggestions with line numbers
- **Security Assessment**: Vulnerability detection and mitigation
- **Performance Analysis**: Optimization opportunities

### 5. Debug Tool

**Purpose**: Root cause analysis, error investigation

**API Specification**:
```json
{
  "name": "debug",
  "parameters": {
    "error_description": "string (required)",
    "error_context": "string (optional)", 
    "files": "array of strings (optional)",
    "previous_attempts": "string (optional)",
    "runtime_info": "string (optional)",
    "thinking_mode": "string (optional, default: 'medium')"
  }
}
```

**Diagnostic Capabilities**:
- **Stack Trace Analysis**: Multi-language error parsing
- **Root Cause Identification**: Systematic error investigation
- **Reproduction Steps**: Detailed debugging procedures
- **Fix Recommendations**: Prioritized solution approaches

### 6. Precommit Tool

**Purpose**: Automated quality gates, validation before commits

**API Specification**:
```json
{
  "name": "precommit",
  "parameters": {
    "path": "string (required, git repository root)",
    "include_staged": "boolean (default: true)",
    "include_unstaged": "boolean (default: true)",
    "review_type": "enum: full|security|performance|quick (default: full)",
    "original_request": "string (optional, user's intent)",
    "thinking_mode": "string (optional, default: 'medium')"
  }
}
```

**Validation Process**:
1. **Git Analysis**: Staged/unstaged changes detection
2. **Quality Review**: Comprehensive code analysis
3. **Security Scan**: Vulnerability and secret detection  
4. **Documentation Check**: Ensures docs match code changes
5. **Test Validation**: Recommends testing strategies
6. **Commit Readiness**: Go/no-go recommendation

## Error Handling & Status Codes

### Standard Error Responses

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": {
      "validation_errors": [
        {
          "field": "files",
          "error": "Path outside sandbox: /etc/passwd"
        }
      ]
    }
  }
}
```

### Error Categories

**Security Errors** (Code: -32001):
- Path traversal attempts
- Unauthorized file access
- Sandbox boundary violations

**Validation Errors** (Code: -32602):
- Missing required parameters
- Invalid parameter types
- Schema validation failures

**Tool Errors** (Code: -32603):
- Tool execution failures
- Gemini API errors
- Resource exhaustion

**System Errors** (Code: -32000):
- Redis connection failures
- File system errors
- Configuration issues

## Performance & Limits

### Request Limits

- **Maximum File Size**: 10MB per file
- **Maximum Files**: 50 files per request
- **Token Budget**: 1M tokens total context
- **Thinking Tokens**: 32K maximum per tool
- **Request Timeout**: 300 seconds

### Rate Limiting

```python
# Per-client rate limiting (future implementation)
RATE_LIMITS = {
    'chat': '10/minute',
    'analyze': '5/minute', 
    'thinkdeep': '3/minute',
    'codereview': '5/minute',
    'debug': '5/minute',
    'precommit': '3/minute'
}
```

### Optimization Features

- **File Deduplication**: Avoid reprocessing same files across conversation
- **Context Caching**: Redis-based conversation persistence
- **Priority Processing**: Source code files processed first
- **Concurrent Execution**: AsyncIO-based parallel processing

## Security Considerations

### Authentication
- **API Key**: Gemini API key via environment variable
- **No User Auth**: Runs in trusted Claude Desktop environment
- **Local Only**: No network exposure beyond Gemini API

### Data Protection
- **Sandbox Enforcement**: PROJECT_ROOT boundary enforcement
- **Path Validation**: Multi-layer dangerous path detection
- **Response Sanitization**: Automatic sensitive data removal
- **Temporary Storage**: Redis with TTL-based cleanup

### Access Controls
- **Read-Only Default**: Most operations are read-only
- **Explicit Write Gates**: Write operations require explicit confirmation
- **Docker Isolation**: Container-based runtime isolation

---

This MCP protocol implementation provides a secure, performant, and extensible foundation for AI-assisted development workflows while maintaining compatibility with Claude's expectations and requirements.