my-pal-mcp-server/docs/contributing/file-overview.md

# Repository File Overview

## Purpose

This document provides a comprehensive guide to the repository structure, explaining the purpose and role of each directory and key file within the Gemini MCP Server project.

## Repository Structure

```
zen-mcp-server/
├── CLAUDE.md                    # Collaboration framework and development guidelines
├── README.md                    # Project overview and quick start guide
├── LICENSE                      # Project license (MIT)
├── requirements.txt             # Python dependencies
├── pyproject.toml              # Poetry configuration and project metadata
├── pytest.ini                  # Test configuration
├── Dockerfile                   # Container image definition
├── docker-compose.yml          # Multi-service Docker orchestration
├── setup.py                     # Python package setup (legacy)
├── config.py                    # Centralized configuration management
├── server.py                    # Main MCP server entry point
├── gemini_server.py            # Gemini-specific server implementation
├── log_monitor.py              # Logging and monitoring utilities
├── setup-docker.sh            # Docker setup automation script
├── claude_config_example.json # Example Claude Desktop configuration
├── examples/                   # Configuration examples for different platforms
├── docs/                      # Complete project documentation
├── tools/                     # MCP tool implementations
├── utils/                     # Shared utility modules
├── prompts/                   # System prompts for different tool types
├── tests/                     # Comprehensive test suite
└── memory-bank/               # Memory Bank files for context preservation
```

## Core Configuration Files

### CLAUDE.md
**Purpose**: Defines the collaboration framework between Claude, Gemini, and human developers
**Key Components**:
- Tool selection matrix for appropriate AI collaboration
- Memory Bank integration protocols
- Mandatory collaboration patterns and workflows
- Quality gates and documentation standards

**When to Update**: When changing collaboration patterns, adding new tools, or modifying development workflows

### config.py
**Purpose**: Centralized configuration management for the MCP server
**Key Components**:
- Environment variable handling (`GEMINI_API_KEY`, `REDIS_URL`)
- Model configuration (`GEMINI_MODEL`, `MAX_CONTEXT_TOKENS`)
- Security settings (`PROJECT_ROOT`, path validation)
- Redis connection settings for conversation memory

**Dependencies**: Environment variables, Docker configuration
**Extension Points**: Add new configuration parameters for tools or features

### server.py
**Purpose**: Main MCP server implementation providing the protocol interface
**Key Components**:
- MCP protocol compliance (`@server.list_tools()`, `@server.call_tool()`)
- Tool registration and discovery system
- Request routing and response formatting
- Error handling and graceful degradation

**Dependencies**: `tools/` modules, `utils/` modules, MCP library
**Data Flow**: Claude → MCP Protocol → Tool Selection → Gemini API → Response

## Tool Architecture

### tools/ Directory
**Purpose**: Contains individual MCP tool implementations following plugin architecture

#### tools/base.py
**Purpose**: Abstract base class defining the tool interface contract
**Key Components**:
- `BaseTool` abstract class with `execute()` and `get_schema()` methods
- Standardized error handling patterns
- Response formatting utilities (`ToolOutput` dataclass)

**Extension Points**: Inherit from `BaseTool` to create new tools

#### Individual Tool Files

**tools/chat.py**
- **Purpose**: Quick questions, brainstorming, general collaboration
- **Thinking Mode**: Default 'medium' (8192 tokens)
- **Use Cases**: Immediate answers, idea exploration, simple code discussions

**tools/thinkdeep.py**
- **Purpose**: Complex architecture, system design, strategic planning
- **Thinking Mode**: Default 'high' (16384 tokens) 
- **Use Cases**: Major features, refactoring strategies, design decisions

**tools/analyze.py**
- **Purpose**: Code exploration, understanding existing systems
- **Thinking Mode**: Variable based on analysis scope
- **Use Cases**: Dependency analysis, pattern detection, codebase comprehension

**tools/codereview.py**
- **Purpose**: Code quality, security, bug detection
- **Thinking Mode**: Default 'medium' (8192 tokens)
- **Use Cases**: PR reviews, pre-commit validation, security audits

**tools/debug.py**
- **Purpose**: Root cause analysis, error investigation
- **Thinking Mode**: Default 'medium' (8192 tokens)
- **Use Cases**: Stack trace analysis, performance issues, bug diagnosis

**tools/precommit.py**
- **Purpose**: Automated quality gates before commits
- **Thinking Mode**: Default 'medium' (8192 tokens)
- **Use Cases**: Git repository validation, change analysis, quality assurance

#### tools/models.py
**Purpose**: Shared data models and Gemini API integration
**Key Components**:
- `ToolOutput` dataclass for standardized responses
- `GeminiClient` for API communication
- Thinking mode token allocations (`THINKING_MODE_TOKENS`)
- Pydantic models for request/response validation

**Dependencies**: `google-generativeai`, `pydantic`

## Utility Modules

### utils/ Directory
**Purpose**: Shared utilities used across multiple tools and components

#### utils/file_utils.py
**Purpose**: Secure file operations and content processing
**Key Components**:
- `validate_file_path()`: Multi-layer security validation
- `read_file_with_token_limit()`: Token-aware file reading
- `translate_docker_path()`: Host-to-container path mapping
- Priority-based file processing (source code > docs > logs)

**Security Features**:
- Directory traversal prevention
- Sandbox boundary enforcement (PROJECT_ROOT)
- Dangerous path pattern detection

**Data Flow**: File Request → Security Validation → Path Translation → Content Processing → Formatted Output

#### utils/git_utils.py
**Purpose**: Git repository operations for code analysis
**Key Components**:
- Repository state detection (staged, unstaged, committed changes)
- Branch comparison and diff analysis
- Commit history processing
- Change validation for precommit tool

**Dependencies**: `git` command-line tool
**Integration**: Primary used by `precommit` tool for change analysis

#### utils/conversation_memory.py
**Purpose**: Cross-session context preservation and threading
**Key Components**:
- `ThreadContext` dataclass for conversation state
- `ConversationMemory` class for Redis-based persistence
- Thread reconstruction and continuation support
- Automatic cleanup of expired conversations

**Data Flow**: Tool Execution → Context Storage → Redis Persistence → Context Retrieval → Thread Reconstruction

**Dependencies**: Redis server, `redis-py` library

#### utils/token_utils.py
**Purpose**: Token management and context optimization
**Key Components**:
- Token counting and estimation
- Context budget allocation
- Content truncation with structure preservation
- Priority-based token distribution

**Integration**: Used by all tools for managing Gemini API token limits

## System Prompts

### prompts/ Directory
**Purpose**: Standardized system prompts for different tool types

#### prompts/tool_prompts.py
**Purpose**: Template prompts for consistent tool behavior
**Key Components**:
- Base prompt templates for each tool type
- Context formatting patterns
- Error message templates
- Response structure guidelines

**Extension Points**: Add new prompt templates for new tools or specialized use cases

## Testing Infrastructure

### tests/ Directory
**Purpose**: Comprehensive test suite ensuring code quality and reliability

#### Test Organization
```
tests/
├── __init__.py                 # Test package initialization
├── conftest.py                # Shared test fixtures and configuration
├── test_server.py             # MCP server integration tests
├── test_tools.py              # Individual tool functionality tests
├── test_utils.py              # Utility module tests
├── test_config.py             # Configuration validation tests
└── specialized test files...   # Feature-specific test suites
```

#### Key Test Files

**conftest.py**
- **Purpose**: Shared pytest fixtures and test configuration
- **Components**: Mock clients, temporary directories, sample data

**test_server.py**
- **Purpose**: MCP protocol and server integration testing
- **Coverage**: Tool registration, request routing, error handling

**test_tools.py**
- **Purpose**: Individual tool functionality validation
- **Coverage**: Tool execution, parameter validation, response formatting

**test_utils.py**
- **Purpose**: Utility module testing
- **Coverage**: File operations, security validation, token management

## Memory Bank System

### memory-bank/ Directory
**Purpose**: Local file-based context preservation system

#### Memory Bank Files

**productContext.md**
- **Purpose**: High-level project overview and goals
- **Content**: Project description, key features, overall architecture
- **Update Triggers**: Fundamental project changes, feature additions

**activeContext.md**
- **Purpose**: Current development status and recent changes
- **Content**: Current focus, recent changes, open questions/issues
- **Update Triggers**: Session changes, progress updates

**progress.md**
- **Purpose**: Task tracking using structured format
- **Content**: Completed tasks, current tasks, next steps
- **Update Triggers**: Task completion, milestone achievements

**decisionLog.md**
- **Purpose**: Architectural decisions with rationale
- **Content**: Technical decisions, rationale, implementation details
- **Update Triggers**: Significant architectural choices, design decisions

**systemPatterns.md**
- **Purpose**: Recurring patterns and standards documentation
- **Content**: Coding patterns, architectural patterns, testing patterns
- **Update Triggers**: Pattern introduction, standard modifications

**Data Flow**: Development Activity → Memory Bank Updates → Context Preservation → Cross-Session Continuity

## Documentation Structure

### docs/ Directory
**Purpose**: Complete project documentation following CLAUDE.md standards

#### Documentation Categories

**docs/architecture/**
- `overview.md`: High-level system architecture and component relationships
- `components.md`: Detailed component descriptions and interactions
- `data-flow.md`: Data flow patterns and processing pipelines
- `decisions/`: Architecture Decision Records (ADRs)

**docs/api/**
- `mcp-protocol.md`: MCP protocol implementation details
- `tools/`: Individual tool API documentation

**docs/contributing/**
- `setup.md`: Development environment setup
- `workflows.md`: Development workflows and processes
- `code-style.md`: Coding standards and style guide
- `testing.md`: Testing strategies and requirements
- `file-overview.md`: This file - repository structure guide

**docs/user-guides/**
- `installation.md`: Installation and setup instructions
- `configuration.md`: Configuration options and examples
- `troubleshooting.md`: Common issues and solutions

## Configuration Examples

### examples/ Directory
**Purpose**: Platform-specific configuration examples for different deployment scenarios

**claude_config_macos.json**
- macOS-specific Claude Desktop configuration
- Local development setup patterns
- File path configurations for macOS

**claude_config_wsl.json**
- Windows Subsystem for Linux configuration
- Path translation patterns for WSL environment
- Docker integration considerations

**claude_config_docker_home.json**
- Docker-based deployment configuration
- Container path mapping examples
- Volume mount configurations

## Container Configuration

### Dockerfile
**Purpose**: Container image definition for consistent deployment
**Key Components**:
- Python 3.9 base image
- Dependency installation (requirements.txt)
- Application code copying
- Entry point configuration (`server.py`)

**Build Process**: Source Code → Dependency Installation → Application Setup → Runnable Container

### docker-compose.yml
**Purpose**: Multi-service orchestration for complete system deployment
**Services**:
- `gemini-server`: Main MCP server application
- `redis`: Conversation memory persistence
- Volume mounts for configuration and data persistence

**Data Flow**: Docker Compose → Service Orchestration → Network Configuration → Volume Mounting → System Startup

## Extension Guidelines

### Adding New Tools

1. **Create Tool Class**: Inherit from `BaseTool` in `tools/new_tool.py`
2. **Implement Interface**: Define `execute()` and `get_schema()` methods
3. **Add Registration**: Update `server.py` tool discovery
4. **Create Tests**: Add comprehensive tests in `tests/`
5. **Update Documentation**: Add API documentation in `docs/api/tools/`

### Adding New Utilities

1. **Create Module**: Add new utility in `utils/new_utility.py`
2. **Define Interface**: Clear function signatures with type hints
3. **Add Security**: Validate inputs and handle errors gracefully
4. **Write Tests**: Comprehensive unit tests with mocking
5. **Update Dependencies**: Document component interactions

### Modifying Configuration

1. **Update config.py**: Add new configuration parameters
2. **Environment Variables**: Define environment variable mappings
3. **Validation**: Add configuration validation logic
4. **Documentation**: Update configuration guide
5. **Examples**: Provide example configurations

## Dependencies & Integration Points

### External Dependencies
- **MCP Library**: Protocol implementation and compliance
- **Google Generative AI**: Gemini API integration
- **Redis**: Conversation memory persistence
- **Docker**: Containerization and deployment
- **pytest**: Testing framework

### Internal Integration Points
- **Tool Registration**: `server.py` ↔ `tools/` modules
- **Configuration**: `config.py` → All modules
- **File Operations**: `utils/file_utils.py` → All file-accessing tools
- **Memory Management**: `utils/conversation_memory.py` → All tools supporting continuation
- **Security**: `utils/file_utils.py` validation → All file operations

### Data Flow Integration
1. **Request Flow**: Claude → `server.py` → Tool Selection → `tools/` → `utils/` → Gemini API
2. **Response Flow**: Gemini API → `tools/` → `utils/` → `server.py` → Claude
3. **Memory Flow**: Tool Execution → `utils/conversation_memory.py` → Redis → Context Retrieval
4. **Security Flow**: File Request → `utils/file_utils.py` → Validation → Safe Processing

---

This file overview provides the foundation for understanding the repository structure and serves as a guide for contributors to navigate the codebase effectively and make informed architectural decisions.