my-pal-mcp-server/docs/architecture/overview.md

# Gemini MCP Server Architecture Overview

## System Overview

The **Gemini MCP Server** implements a sophisticated Model Context Protocol (MCP) server architecture that provides Claude with access to Google's Gemini AI models through specialized tools. This enables advanced AI-assisted development workflows combining Claude's general capabilities with Gemini's deep analytical and creative thinking abilities.

## High-Level Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    Claude Interface                         │
│                 (Claude Desktop App)                        │
└─────────────────────┬───────────────────────────────────────┘
                      │ MCP Protocol (stdio)
┌─────────────────────▼───────────────────────────────────────┐
│                MCP Core Engine                              │
│  • AsyncIO Event Loop (server.py:45)                      │
│  • Tool Discovery & Registration                           │
│  • Request/Response Processing                              │
└─────────────────────┬───────────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────────┐
│                Tool Architecture                            │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐           │
│  │   chat      │ │ thinkdeep   │ │  analyze    │           │
│  │ (quick Q&A) │ │(deep think) │ │(code review)│           │
│  └─────────────┘ └─────────────┘ └─────────────┘           │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐           │
│  │ codereview  │ │   debug     │ │ precommit   │           │
│  │(quality)    │ │(root cause) │ │(validation) │           │
│  └─────────────┘ └─────────────┘ └─────────────┘           │
└─────────────────────┬───────────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────────┐
│               Support Services                              │
│  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐│
│  │Redis Conversation│ │Security Engine  │ │Gemini API      ││
│  │Memory & Threading│ │Multi-layer      │ │Integration     ││
│  │                  │ │Validation       │ │                ││
│  └─────────────────┘ └─────────────────┘ └─────────────────┘│
└─────────────────────────────────────────────────────────────┘
```

## Core Components

### 1. MCP Core Engine (server.py:45)

**Purpose**: Central coordination hub managing the MCP protocol implementation
**Key Components**:
- **AsyncIO Event Loop**: Handles concurrent tool execution and request processing
- **Tool Discovery**: Dynamic loading and registration via `@server.list_tools()` decorator
- **Protocol Management**: MCP message parsing, validation, and response formatting

**Architecture Pattern**: Event-driven architecture with asyncio for non-blocking operations

### 2. Tool System Architecture

**Purpose**: Modular plugin system for specialized AI capabilities
**Key Components**:
- **BaseTool Abstract Class** (`tools/base.py:25`): Common interface for all tools
- **Plugin Architecture**: Individual tool implementations in `tools/` directory
- **Tool Selection Matrix**: CLAUDE.md defines appropriate tool usage patterns

**Data Flow**:
```
Claude Request → MCP Engine → Tool Selection → Gemini API → Response Processing → Claude
```

**Tool Categories**:
- **Quick Response**: `chat` - immediate answers and brainstorming
- **Deep Analysis**: `thinkdeep` - complex architecture and strategic planning  
- **Code Quality**: `codereview` - security audits and bug detection
- **Investigation**: `debug` - root cause analysis and error investigation
- **Exploration**: `analyze` - codebase comprehension and dependency analysis
- **Validation**: `precommit` - automated quality gates

### 3. Security Architecture

**Purpose**: Multi-layer defense system protecting against malicious operations
**Key Components**:
- **Path Validation** (`utils/file_utils.py:45`): Prevents directory traversal attacks
- **Sandbox Enforcement**: PROJECT_ROOT containment for file operations
- **Docker Path Translation**: Host-to-container path mapping with WORKSPACE_ROOT
- **Absolute Path Requirement**: Eliminates relative path vulnerabilities

**Security Layers**:
1. **Input Validation**: Path sanitization and dangerous operation detection
2. **Container Isolation**: Docker environment with controlled file access
3. **Permission Boundaries**: Read-only access patterns with explicit write gates
4. **Error Recovery**: Graceful handling of unauthorized operations

### 4. Thinking Modes System

**Purpose**: Computational budget control for Gemini's analysis depth
**Implementation**: 
- **Token Allocation**: `minimal (128), low (2048), medium (8192), high (16384), max (32768)`
- **Dynamic Selection**: Tools adjust thinking depth based on task complexity
- **Resource Management**: Prevents token exhaustion on complex analysis

**Usage Pattern**:
```python
# tools/thinkdeep.py:67
thinking_mode = request.get('thinking_mode', 'high')
context_tokens = THINKING_MODE_TOKENS[thinking_mode]
```

### 5. Conversation System

**Purpose**: Cross-session context preservation and threading
**Key Components**:
- **Redis Persistence** (`utils/conversation_memory.py:30`): Thread storage and retrieval
- **Thread Reconstruction**: UUID-based conversation continuity
- **Cross-Tool Continuation**: `continuation_id` parameter for context flow
- **Follow-up Management**: Structured multi-turn conversation support

**Data Structures**:
```python
# utils/conversation_memory.py:45
class ThreadContext:
    thread_id: str
    tool_history: List[ToolExecution]
    conversation_files: List[str]
    context_tokens: int
```

## Integration Points

### Configuration Management (config.py)

**Critical Settings**:
- **`GEMINI_MODEL`** (config.py:24): Model selection for API calls
- **`MAX_CONTEXT_TOKENS`** (config.py:30): Token limits for conversation management
- **`REDIS_URL`** (config.py:60): Conversation memory backend
- **`PROJECT_ROOT`** (config.py:15): Security sandbox boundary

### Utility Services

**File Operations** (`utils/file_utils.py`):
- Token-aware reading with priority system
- Directory expansion with filtering
- Error-resistant content formatting

**Git Integration** (`utils/git_utils.py`):
- Repository state analysis for precommit validation
- Change detection for documentation updates
- Branch and commit tracking

**Token Management** (`utils/token_utils.py`):
- Context optimization and pruning
- File prioritization strategies
- Memory usage monitoring

## Data Flow Patterns

### 1. Tool Execution Flow

```
1. Claude sends MCP request with tool name and parameters
2. MCP Engine validates request and routes to appropriate tool
3. Tool loads conversation context from Redis (if continuation_id provided)
4. Tool processes request using Gemini API with thinking mode configuration
5. Tool stores results in conversation memory and returns formatted response
6. MCP Engine serializes response and sends to Claude via stdio
```

### 2. File Processing Pipeline

```
1. File paths received and validated against security rules
2. Docker path translation (host → container mapping)
3. Token budget allocation based on file size and context limits
4. Priority-based file reading (code files > documentation > logs)
5. Content formatting with line numbers and error handling
6. Context assembly with deduplication across conversation turns
```

### 3. Security Validation Chain

```
1. Path Input → Dangerous Path Detection → Rejection/Sanitization
2. Validated Path → Absolute Path Conversion → Sandbox Boundary Check
3. Bounded Path → Docker Translation → Container Path Generation
4. Safe Path → File Operation → Error-Resistant Content Return
```

## Performance Characteristics

### Scalability Factors

- **Concurrent Tool Execution**: AsyncIO enables parallel processing of multiple tool requests
- **Memory Efficiency**: Token-aware file processing prevents memory exhaustion
- **Context Optimization**: Conversation deduplication reduces redundant processing
- **Error Resilience**: Graceful degradation maintains functionality during failures

### Resource Management

- **Token Budgeting**: 40% context reservation (30% Memory Bank + 10% Memory MCP)
- **File Prioritization**: Direct code files prioritized over supporting documentation
- **Redis Optimization**: Thread-based storage with automatic cleanup
- **Gemini API Efficiency**: Thinking mode selection optimizes computational costs

## Extension Points

### Adding New Tools

1. **Inherit from BaseTool** (`tools/base.py:25`)
2. **Implement required methods**: `execute()`, `get_schema()`
3. **Register with MCP Engine**: Add to tool discovery system
4. **Update CLAUDE.md**: Define collaboration patterns and usage guidelines

### Security Extensions

1. **Custom Validators**: Add to `utils/file_utils.py` validation chain
2. **Path Translators**: Extend Docker path mapping for new mount points
3. **Permission Gates**: Implement granular access controls for sensitive operations

### Performance Optimizations

1. **Caching Layers**: Add Redis caching for frequently accessed files
2. **Context Compression**: Implement intelligent context summarization
3. **Parallel Processing**: Extend AsyncIO patterns for I/O-bound operations

---

This architecture provides a robust, secure, and extensible foundation for AI-assisted development workflows while maintaining clear separation of concerns and comprehensive error handling.