adding missing files docs

2025-06-11 14:40:50 +02:00
parent 95ced22973
commit edba019768
5 changed files with 1673 additions and 2 deletions
--- a/docs/contributing/file-overview.md
+++ b/docs/contributing/file-overview.md
@@ -0,0 +1,382 @@
+# 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
+
+```
+gemini-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.