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

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

Response:

{
  "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)

@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:

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)

@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:

@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:

{
  "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:

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

Response Format:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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

{
  "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

# 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.