docs+docker: Enhanced Docker configuration and workflow fixes (#4)

* addinte templates and user guide * up docs * up * up claude.md * add mb * umb * up workflow * up settings claude * adding detailed docs * adding missing files docs * add main readme for docs * up main readme * adding docs for tests * Complete documentation integration with test structure analysis link Adds link to comprehensive test structure documentation in main README.md, finalizing the progressive disclosure strategy for project documentation. This completes the documentation integration work that includes: - Architecture documentation - API reference documentation - Contributing guidelines - Detailed test analysis 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * removing folders from git * up * up * up gitignore * feat: Add automatic semantic versioning workflow - Create GitHub Actions workflow for automatic version bumping based on PR title prefixes - Add version bumping script (scripts/bump_version.py) for programmatic updates - Update PR template with semantic versioning guidelines - Document versioning workflow in contributing guide - Integrate with existing Docker build workflow via git tags This enables automatic version management: - feat: triggers MINOR version bump - fix: triggers PATCH version bump - breaking: triggers MAJOR version bump - docs/chore/test: no version bump 🤖 Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com> * fix: Separate Docker workflows for testing and publishing - Add docker-test.yml for PR validation (build test only) - Fix build_and_publish_docker.yml to trigger only on tags - Remove problematic sha prefix causing invalid tag format - Ensure proper workflow sequence: PR test → merge → version → publish 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * style: Fix black formatting issues in bump_version.py - Fix spacing and indentation to pass black formatter - Ensure code quality standards are met for CI workflow 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * style: Modernize type hints in bump_version.py - Replace typing.Tuple with modern tuple syntax - Remove deprecated typing imports per ruff suggestions - Maintain Python 3.10+ compatibility 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * fix: Remove invalid colon in bash else statement - Fix bash syntax error in auto-version workflow - Remove Python-style colon from else statement - Resolves exit code 127 in version bump determination 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * feat: Add Docker build combinations for non-versioning prefixes - Add support for prefix+docker combinations (docs+docker:, chore+docker:, etc.) - Enable Docker build for non-versioning changes when requested - Add repository_dispatch trigger for Docker workflow - Update Docker tagging for PR-based builds (pr-X, main-sha) - Update PR template with new prefix options This allows contributors to force Docker builds for documentation, maintenance, and other non-versioning changes when needed. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * docs: Add comprehensive PR prefix and automation documentation - Update CONTRIBUTING.md with detailed PR prefix system explanation - Add automation workflow documentation to docs/contributing/workflows.md - Create new user-friendly contributing guide at docs/user-guides/contributing-guide.md - Include Mermaid diagrams for workflow visualization - Document Docker testing combinations and image tagging strategy - Add best practices and common mistakes to avoid This provides clear guidance for contributors on using the automated versioning and Docker build system effectively. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * docs+docker: Complete documentation infrastructure with Docker automation testing (#2) * fix: Remove invalid colon in bash else statement - Fix bash syntax error in auto-version workflow - Remove Python-style colon from else statement - Resolves exit code 127 in version bump determination 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * feat: Add Docker build combinations for non-versioning prefixes - Add support for prefix+docker combinations (docs+docker:, chore+docker:, etc.) - Enable Docker build for non-versioning changes when requested - Add repository_dispatch trigger for Docker workflow - Update Docker tagging for PR-based builds (pr-X, main-sha) - Update PR template with new prefix options This allows contributors to force Docker builds for documentation, maintenance, and other non-versioning changes when needed. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * docs: Add comprehensive PR prefix and automation documentation - Update CONTRIBUTING.md with detailed PR prefix system explanation - Add automation workflow documentation to docs/contributing/workflows.md - Create new user-friendly contributing guide at docs/user-guides/contributing-guide.md - Include Mermaid diagrams for workflow visualization - Document Docker testing combinations and image tagging strategy - Add best practices and common mistakes to avoid This provides clear guidance for contributors on using the automated versioning and Docker build system effectively. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: Patryk Ciechanski <patryk.ciechanski@inetum.com> Co-authored-by: Claude <noreply@anthropic.com> * fix: Correct digest reference in Docker artifact attestation - Add id to build step to capture outputs - Fix subject-digest reference from steps.build.outputs.digest - Resolves 'One of subject-path or subject-digest must be provided' error 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * docs: Add comprehensive Docker image usage instructions - Add Option B (Published Docker Image) to main README.md - Update installation guide with published image as fastest option - Add comprehensive configuration examples for GHCR images - Document image tagging strategy (latest, versioned, PR builds) - Include version pinning examples for stability - Highlight benefits: instant setup, no build, cross-platform Users can now choose between: 1. Published image (fastest, no setup) - ghcr.io/patrykiti/gemini-mcp-server:latest 2. Local build (development, customization) - traditional setup 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * feat: Add automated Docker image usage instructions and PR comments - Generate comprehensive usage instructions in workflow summary after Docker build - Include exact docker pull commands with built image tags - Auto-generate Claude Desktop configuration examples - Add automatic PR comments with testing instructions for +docker builds - Show expected image tags (pr-X, main-sha) in PR comments - Include ready-to-use configuration snippets for immediate testing - Link to GitHub Container Registry and Actions for monitoring Now when Docker images are built, users get: - Step-by-step usage instructions in workflow summary - PR comments with exact pull commands and config - Copy-paste ready Claude Desktop configurations - Direct links to monitor build progress 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * feat: Add automatic README.md updating after Docker builds - Updates Docker image references in README.md and documentation files - Automatically commits and pushes changes after image builds - Handles both release builds (version tags) and development builds (PR numbers) - Ensures documentation always references the latest published images - Uses sed pattern matching to update ghcr.io image references 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * correcting * up * fix: GitHub Actions workflows semantic errors Fixed critical semantic and logic errors in auto-version and Docker workflows: Auto-version.yml fixes: - Removed duplicate echo statements for should_build_docker output - Fixed malformed if/else structure (else after else) - Removed redundant conditional blocks for docker: prefixes - Cleaned up duplicate lines in summary generation Build_and_publish_docker.yml fixes: - Replaced hardcoded 'patrykiti' with dynamic ${{ github.repository_owner }} - Enhanced regex pattern to support underscores in Docker tags: [a-zA-Z0-9\._-]* - Fixed sed patterns for dynamic repository owner detection These changes ensure workflows execute correctly and support any repository owner. 🤖 Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com> * docs: Add advanced Docker configuration options to README Added comprehensive configuration section with optional environment variables: Docker Configuration Features: - Advanced configuration example with all available env vars - Complete table of environment variables with descriptions - Practical examples for common configuration scenarios - Clear documentation of config.py options for Docker users Available Configuration Options: - DEFAULT_MODEL: Choose between Pro (quality) vs Flash (speed) - DEFAULT_THINKING_MODE_THINKDEEP: Control token costs with thinking depth - LOG_LEVEL: Debug logging for troubleshooting - MCP_PROJECT_ROOT: Security sandbox for file access - REDIS_URL: Custom Redis configuration Benefits: - Users can customize server behavior without rebuilding images - Better cost control through model and thinking mode selection - Enhanced security through project root restrictions - Improved debugging capabilities with configurable logging - Complete transparency of available configuration options This addresses user request for exposing config.py parameters via Docker environment variables. 🤖 Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: Patryk Ciechanski <patryk.ciechanski@inetum.com> Co-authored-by: Claude <noreply@anthropic.com>
2025-06-12 12:10:27 +02:00
parent c7eeb68262
commit c5313b170a
36 changed files with 10222 additions and 23 deletions
--- a/docs/contributing/code-style.md
+++ b/docs/contributing/code-style.md
@@ -0,0 +1,602 @@
+# Code Style Guide
+
+## Overview
+
+This document establishes coding standards and style guidelines for the Gemini MCP Server project. Consistent code style improves readability, maintainability, and collaboration efficiency.
+
+## Python Style Guidelines
+
+### PEP 8 Compliance
+
+**Base Standard**: Follow [PEP 8](https://peps.python.org/pep-0008/) as the foundation for all Python code.
+
+**Automated Formatting**: Use Black formatter with default settings:
+```bash
+black tools/ utils/ tests/ --line-length 88
+```
+
+**Line Length**: 88 characters (Black default)
+```python
+# Good
+result = some_function_with_long_name(
+    parameter_one, parameter_two, parameter_three
+)
+
+# Avoid
+result = some_function_with_long_name(parameter_one, parameter_two, parameter_three)
+```
+
+### Import Organization
+
+**Import Order** (enforced by isort):
+```python
+# 1. Standard library imports
+import asyncio
+import json
+import os
+from pathlib import Path
+from typing import Dict, List, Optional
+
+# 2. Third-party imports
+import redis
+from pydantic import BaseModel
+
+# 3. Local application imports
+from tools.base import BaseTool
+from utils.file_utils import validate_file_path
+```
+
+**Import Formatting**:
+```python
+# Good - Explicit imports
+from typing import Dict, List, Optional
+from utils.conversation_memory import ThreadContext, ConversationMemory
+
+# Avoid - Wildcard imports
+from utils.conversation_memory import *
+```
+
+### Naming Conventions
+
+**Functions and Variables**: snake_case
+```python
+def process_file_content(file_path: str) -> str:
+    context_tokens = calculate_token_count(content)
+    return formatted_content
+```
+
+**Classes**: PascalCase
+```python
+class GeminiClient:
+    pass
+
+class ThreadContext:
+    pass
+```
+
+**Constants**: UPPER_SNAKE_CASE
+```python
+MAX_CONTEXT_TOKENS = 1000000
+THINKING_MODE_TOKENS = {
+    'minimal': 128,
+    'low': 2048,
+    'medium': 8192
+}
+```
+
+**Private Methods**: Leading underscore
+```python
+class ToolBase:
+    def execute(self):
+        return self._process_internal_logic()
+    
+    def _process_internal_logic(self):
+        # Private implementation
+        pass
+```
+
+## Type Hints
+
+### Mandatory Type Hints
+
+**Function Signatures**: Always include type hints
+```python
+# Good
+def validate_file_path(file_path: str) -> bool:
+    return os.path.exists(file_path)
+
+async def process_request(request: dict) -> ToolOutput:
+    # Implementation
+    pass
+
+# Avoid
+def validate_file_path(file_path):
+    return os.path.exists(file_path)
+```
+
+**Complex Types**: Use typing module
+```python
+from typing import Dict, List, Optional, Union, Any
+
+def process_files(files: List[str]) -> Dict[str, Any]:
+    return {"processed": files}
+
+def get_config(key: str) -> Optional[str]:
+    return os.getenv(key)
+```
+
+**Generic Types**: Use TypeVar for reusable generics
+```python
+from typing import TypeVar, Generic
+
+T = TypeVar('T')
+
+class Repository(Generic[T]):
+    def get(self, id: str) -> Optional[T]:
+        # Implementation
+        pass
+```
+
+## Documentation Standards
+
+### Docstring Format
+
+**Use Google Style** docstrings:
+```python
+def execute_tool(name: str, arguments: dict, context: Optional[str] = None) -> ToolOutput:
+    """Execute a tool with given arguments and context.
+    
+    Args:
+        name: The name of the tool to execute
+        arguments: Tool-specific parameters and configuration
+        context: Optional conversation context for threading
+        
+    Returns:
+        ToolOutput containing the execution result and metadata
+        
+    Raises:
+        ToolNotFoundError: If the specified tool doesn't exist
+        ValidationError: If arguments don't match tool schema
+        
+    Example:
+        >>> output = execute_tool("chat", {"prompt": "Hello"})
+        >>> print(output.content)
+        "Hello! How can I help you today?"
+    """
+    # Implementation
+    pass
+```
+
+**Class Documentation**:
+```python
+class ConversationMemory:
+    """Manages conversation threading and context persistence.
+    
+    This class handles storing and retrieving conversation contexts
+    using Redis as the backend storage. It supports thread-based
+    organization and automatic cleanup of expired conversations.
+    
+    Attributes:
+        redis_client: Redis connection for storage operations
+        default_ttl: Default time-to-live for conversation threads
+        
+    Example:
+        >>> memory = ConversationMemory("redis://localhost:6379")
+        >>> context = ThreadContext("thread-123")
+        >>> await memory.store_thread(context)
+    """
+    
+    def __init__(self, redis_url: str, default_ttl: int = 86400):
+        """Initialize conversation memory with Redis connection.
+        
+        Args:
+            redis_url: Redis connection string
+            default_ttl: Default TTL in seconds (default: 24 hours)
+        """
+        pass
+```
+
+### Inline Comments
+
+**When to Comment**:
+```python
+# Good - Explain complex business logic
+def calculate_token_budget(files: List[str], total_budget: int) -> Dict[str, int]:
+    # Priority 1 files (source code) get 60% of budget
+    priority_1_budget = int(total_budget * 0.6)
+    
+    # Group files by priority based on extension
+    priority_groups = defaultdict(list)
+    for file in files:
+        ext = Path(file).suffix.lower()
+        priority = FILE_PRIORITIES.get(ext, 4)
+        priority_groups[priority].append(file)
+    
+    return allocate_budget_by_priority(priority_groups, total_budget)
+
+# Avoid - Stating the obvious
+def get_file_size(file_path: str) -> int:
+    # Get the size of the file
+    return os.path.getsize(file_path)
+```
+
+**Security and Performance Notes**:
+```python
+def validate_file_path(file_path: str) -> bool:
+    # Security: Prevent directory traversal attacks
+    if '..' in file_path or file_path.startswith('/etc/'):
+        return False
+    
+    # Performance: Early return for non-existent files
+    if not os.path.exists(file_path):
+        return False
+        
+    return True
+```
+
+## Error Handling
+
+### Exception Handling Patterns
+
+**Specific Exceptions**:
+```python
+# Good - Specific exception handling
+try:
+    with open(file_path, 'r') as f:
+        content = f.read()
+except FileNotFoundError:
+    logger.warning(f"File not found: {file_path}")
+    return None
+except PermissionError:
+    logger.error(f"Permission denied: {file_path}")
+    raise SecurityError(f"Access denied to {file_path}")
+except UnicodeDecodeError:
+    logger.warning(f"Encoding error in {file_path}")
+    return f"Error: Cannot decode file {file_path}"
+
+# Avoid - Bare except clauses
+try:
+    content = f.read()
+except:
+    return None
+```
+
+**Custom Exceptions**:
+```python
+class GeminiMCPError(Exception):
+    """Base exception for Gemini MCP Server errors."""
+    pass
+
+class ToolNotFoundError(GeminiMCPError):
+    """Raised when a requested tool is not found."""
+    pass
+
+class ValidationError(GeminiMCPError):
+    """Raised when input validation fails."""
+    pass
+```
+
+### Logging Standards
+
+**Logging Levels**:
+```python
+import logging
+
+logger = logging.getLogger(__name__)
+
+# DEBUG: Detailed diagnostic information
+logger.debug(f"Processing file: {file_path}, size: {file_size}")
+
+# INFO: General operational information  
+logger.info(f"Tool '{tool_name}' executed successfully")
+
+# WARNING: Something unexpected but recoverable
+logger.warning(f"File {file_path} exceeds recommended size limit")
+
+# ERROR: Error condition but application continues
+logger.error(f"Failed to process file {file_path}: {str(e)}")
+
+# CRITICAL: Serious error, application may not continue
+logger.critical(f"Redis connection failed: {connection_error}")
+```
+
+**Structured Logging**:
+```python
+# Good - Structured logging with context
+logger.info(
+    "Tool execution completed",
+    extra={
+        "tool_name": tool_name,
+        "execution_time": execution_time,
+        "files_processed": len(files),
+        "thinking_mode": thinking_mode
+    }
+)
+
+# Avoid - Unstructured string formatting
+logger.info(f"Tool {tool_name} took {execution_time}s to process {len(files)} files")
+```
+
+## Async/Await Patterns
+
+### Async Function Design
+
+**Async When Needed**:
+```python
+# Good - I/O operations should be async
+async def fetch_gemini_response(prompt: str) -> str:
+    async with aiohttp.ClientSession() as session:
+        async with session.post(GEMINI_API_URL, json=payload) as response:
+            return await response.text()
+
+# Good - CPU-bound work remains sync
+def parse_stack_trace(trace_text: str) -> List[StackFrame]:
+    # CPU-intensive parsing logic
+    return parsed_frames
+```
+
+**Async Context Managers**:
+```python
+class AsyncRedisClient:
+    async def __aenter__(self):
+        self.connection = await redis.connect(self.url)
+        return self
+    
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.connection.close()
+
+# Usage
+async with AsyncRedisClient(redis_url) as client:
+    await client.store_data(key, value)
+```
+
+## Security Best Practices
+
+### Input Validation
+
+**Path Validation**:
+```python
+def validate_file_path(file_path: str) -> bool:
+    """Validate file path for security and accessibility."""
+    # Convert to absolute path
+    abs_path = os.path.abspath(file_path)
+    
+    # Check for directory traversal
+    if not abs_path.startswith(PROJECT_ROOT):
+        raise SecurityError(f"Path outside project root: {abs_path}")
+    
+    # Check for dangerous patterns
+    dangerous_patterns = ['../', '~/', '/etc/', '/var/']
+    if any(pattern in file_path for pattern in dangerous_patterns):
+        raise SecurityError(f"Dangerous path pattern detected: {file_path}")
+    
+    return True
+```
+
+**Data Sanitization**:
+```python
+def sanitize_user_input(user_input: str) -> str:
+    """Sanitize user input to prevent injection attacks."""
+    # Remove null bytes
+    sanitized = user_input.replace('\x00', '')
+    
+    # Limit length
+    if len(sanitized) > MAX_INPUT_LENGTH:
+        sanitized = sanitized[:MAX_INPUT_LENGTH]
+    
+    # Remove control characters
+    sanitized = ''.join(char for char in sanitized if ord(char) >= 32)
+    
+    return sanitized
+```
+
+### Secret Management
+
+**Environment Variables**:
+```python
+# Good - Environment variable with validation
+GEMINI_API_KEY = os.getenv('GEMINI_API_KEY')
+if not GEMINI_API_KEY:
+    raise ConfigurationError("GEMINI_API_KEY environment variable required")
+
+# Avoid - Hardcoded secrets
+API_KEY = "sk-1234567890abcdef"  # Never do this
+```
+
+**Secret Logging Prevention**:
+```python
+def log_request_safely(request_data: dict) -> None:
+    """Log request data while excluding sensitive fields."""
+    safe_data = request_data.copy()
+    
+    # Remove sensitive fields
+    sensitive_fields = ['api_key', 'token', 'password', 'secret']
+    for field in sensitive_fields:
+        if field in safe_data:
+            safe_data[field] = '[REDACTED]'
+    
+    logger.info(f"Processing request: {safe_data}")
+```
+
+## Performance Guidelines
+
+### Memory Management
+
+**Generator Usage**:
+```python
+# Good - Memory efficient for large datasets
+def process_large_file(file_path: str) -> Generator[str, None, None]:
+    with open(file_path, 'r') as f:
+        for line in f:
+            yield process_line(line)
+
+# Avoid - Loading entire file into memory
+def process_large_file(file_path: str) -> List[str]:
+    with open(file_path, 'r') as f:
+        return [process_line(line) for line in f.readlines()]
+```
+
+**Context Managers**:
+```python
+# Good - Automatic resource cleanup
+class FileProcessor:
+    def __enter__(self):
+        self.temp_files = []
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        # Cleanup temporary files
+        for temp_file in self.temp_files:
+            os.unlink(temp_file)
+```
+
+### Caching Patterns
+
+**LRU Cache for Expensive Operations**:
+```python
+from functools import lru_cache
+
+@lru_cache(maxsize=128)
+def parse_file_content(file_path: str, file_hash: str) -> str:
+    """Parse file content with caching based on file hash."""
+    with open(file_path, 'r') as f:
+        return expensive_parsing_operation(f.read())
+```
+
+## Testing Standards
+
+### Test File Organization
+
+**Test Structure**:
+```python
+# tests/test_tools.py
+import pytest
+from unittest.mock import Mock, patch
+
+from tools.chat import ChatTool
+from tools.models import ToolOutput
+
+class TestChatTool:
+    """Test suite for ChatTool functionality."""
+    
+    def setup_method(self):
+        """Set up test fixtures before each test method."""
+        self.chat_tool = ChatTool()
+        self.mock_gemini_client = Mock()
+    
+    def test_basic_chat_execution(self):
+        """Test basic chat tool execution with simple prompt."""
+        # Arrange
+        request = {"prompt": "Hello"}
+        
+        # Act
+        result = self.chat_tool.execute(request)
+        
+        # Assert
+        assert isinstance(result, ToolOutput)
+        assert result.status == "success"
+    
+    @patch('tools.chat.GeminiClient')
+    def test_chat_with_mocked_api(self, mock_client):
+        """Test chat tool with mocked Gemini API responses."""
+        # Test implementation
+        pass
+```
+
+### Test Naming Conventions
+
+**Test Method Names**:
+```python
+def test_should_validate_file_path_when_path_is_safe():
+    """Test that safe file paths are correctly validated."""
+    pass
+
+def test_should_raise_security_error_when_path_contains_traversal():
+    """Test that directory traversal attempts raise SecurityError."""
+    pass
+
+def test_should_return_none_when_file_not_found():
+    """Test that missing files return None gracefully."""
+    pass
+```
+
+## Configuration Management
+
+### Environment-Based Configuration
+
+**Configuration Class**:
+```python
+class Config:
+    """Application configuration with validation."""
+    
+    def __init__(self):
+        self.gemini_api_key = self._require_env('GEMINI_API_KEY')
+        self.redis_url = os.getenv('REDIS_URL', 'redis://localhost:6379')
+        self.project_root = os.getenv('PROJECT_ROOT', '/workspace')
+        self.max_context_tokens = int(os.getenv('MAX_CONTEXT_TOKENS', '1000000'))
+        
+        # Validate configuration
+        self._validate_configuration()
+    
+    def _require_env(self, key: str) -> str:
+        """Require environment variable or raise error."""
+        value = os.getenv(key)
+        if not value:
+            raise ConfigurationError(f"Required environment variable: {key}")
+        return value
+    
+    def _validate_configuration(self) -> None:
+        """Validate configuration values."""
+        if not os.path.exists(self.project_root):
+            raise ConfigurationError(f"PROJECT_ROOT not found: {self.project_root}")
+```
+
+## Pre-commit Hooks
+
+### Automated Quality Checks
+
+**Required Tools**:
+```bash
+# Install development dependencies
+pip install black isort flake8 mypy pytest
+
+# Format code
+black tools/ utils/ tests/
+isort tools/ utils/ tests/
+
+# Check code quality
+flake8 tools/ utils/ tests/
+mypy tools/ utils/
+
+# Run tests
+pytest tests/ -v --cov=tools --cov=utils
+```
+
+**Pre-commit Configuration** (`.pre-commit-config.yaml`):
+```yaml
+repos:
+  - repo: https://github.com/psf/black
+    rev: 23.3.0
+    hooks:
+      - id: black
+        language_version: python3.9
+
+  - repo: https://github.com/pycqa/isort
+    rev: 5.12.0
+    hooks:
+      - id: isort
+
+  - repo: https://github.com/pycqa/flake8
+    rev: 6.0.0
+    hooks:
+      - id: flake8
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.3.0
+    hooks:
+      - id: mypy
+```
+
+---
+
+Following these code style guidelines ensures consistent, maintainable, and secure code across the Gemini MCP Server project. All team members should adhere to these standards and use the automated tools to enforce compliance.
--- 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.
--- a/docs/contributing/setup.md
+++ b/docs/contributing/setup.md
@@ -0,0 +1,380 @@
+# Development Environment Setup
+
+This guide helps you set up a development environment for contributing to the Gemini MCP Server.
+
+## Prerequisites
+
+### Required Software
+- **Python 3.11+** - [Download](https://www.python.org/downloads/)
+- **Docker Desktop** - [Download](https://www.docker.com/products/docker-desktop/)
+- **Git** - [Download](https://git-scm.com/downloads)
+- **Claude Desktop** - [Download](https://claude.ai/download) (for testing)
+
+### Recommended Tools
+- **VS Code** with Python extension
+- **PyCharm** or your preferred Python IDE
+- **pytest** for running tests
+- **black** and **ruff** for code formatting
+
+## Quick Setup
+
+### 1. Clone Repository
+
+```bash
+git clone https://github.com/BeehiveInnovations/gemini-mcp-server.git
+cd gemini-mcp-server
+```
+
+### 2. Choose Development Method
+
+#### Option A: Docker Development (Recommended)
+
+Best for consistency and avoiding local Python environment issues:
+
+```bash
+# One-command setup
+./setup-docker.sh
+
+# Development with auto-reload
+docker compose -f docker-compose.yml -f docker-compose.dev.yml up
+```
+
+#### Option B: Local Python Development
+
+For direct Python development and debugging:
+
+```bash
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Install development dependencies
+pip install -r requirements-dev.txt
+```
+
+### 3. Configuration
+
+```bash
+# Copy example environment file
+cp .env.example .env
+
+# Edit with your API key
+nano .env
+# Add: GEMINI_API_KEY=your-gemini-api-key-here
+```
+
+### 4. Verify Setup
+
+```bash
+# Run unit tests
+python -m pytest tests/ --ignore=tests/test_live_integration.py -v
+
+# Test with live API (requires API key)
+python tests/test_live_integration.py
+
+# Run linting
+black --check .
+ruff check .
+```
+
+## Development Workflows
+
+### Code Quality Tools
+
+```bash
+# Format code
+black .
+
+# Lint code
+ruff check .
+ruff check . --fix  # Auto-fix issues
+
+# Type checking
+mypy .
+
+# Run all quality checks
+./scripts/quality-check.sh  # If available
+```
+
+### Testing Strategy
+
+#### Unit Tests (No API Key Required)
+```bash
+# Run all unit tests
+python -m pytest tests/ --ignore=tests/test_live_integration.py -v
+
+# Run with coverage
+python -m pytest tests/ --ignore=tests/test_live_integration.py --cov=. --cov-report=html
+
+# Run specific test file
+python -m pytest tests/test_tools.py -v
+```
+
+#### Live Integration Tests (API Key Required)
+```bash
+# Set API key
+export GEMINI_API_KEY=your-api-key-here
+
+# Run live tests
+python tests/test_live_integration.py
+
+# Or specific live test
+python -m pytest tests/test_live_integration.py::test_chat_tool -v
+```
+
+### Adding New Tools
+
+1. **Create tool file**: `tools/your_tool.py`
+2. **Inherit from BaseTool**: Implement required methods
+3. **Add system prompt**: Include in `prompts/tool_prompts.py`
+4. **Register tool**: Add to `TOOLS` dict in `server.py`
+5. **Write tests**: Add unit tests with mocks
+6. **Test live**: Verify with actual API calls
+
+#### Tool Template
+
+```python
+# tools/your_tool.py
+from typing import Any, Optional
+from mcp.types import TextContent
+from pydantic import Field
+from .base import BaseTool, ToolRequest
+from prompts import YOUR_TOOL_PROMPT
+
+class YourToolRequest(ToolRequest):
+    """Request model for your tool"""
+    param1: str = Field(..., description="Required parameter")
+    param2: Optional[str] = Field(None, description="Optional parameter")
+
+class YourTool(BaseTool):
+    """Your tool description"""
+    
+    def get_name(self) -> str:
+        return "your_tool"
+    
+    def get_description(self) -> str:
+        return "Your tool description for Claude"
+    
+    def get_system_prompt(self) -> str:
+        return YOUR_TOOL_PROMPT
+    
+    def get_request_model(self):
+        return YourToolRequest
+    
+    async def prepare_prompt(self, request: YourToolRequest) -> str:
+        # Build your prompt here
+        return f"Your prompt with {request.param1}"
+```
+
+### Docker Development
+
+#### Development Compose File
+
+Create `docker-compose.dev.yml`:
+
+```yaml
+services:
+  gemini-mcp:
+    build:
+      context: .
+      dockerfile: Dockerfile.dev  # If you have a dev Dockerfile
+    volumes:
+      - .:/app  # Mount source code for hot reload
+    environment:
+      - LOG_LEVEL=DEBUG
+    command: ["python", "-m", "server", "--reload"]  # If you add reload support
+```
+
+#### Development Commands
+
+```bash
+# Start development environment
+docker compose -f docker-compose.yml -f docker-compose.dev.yml up
+
+# Run tests in container
+docker compose exec gemini-mcp python -m pytest tests/ -v
+
+# Access container shell
+docker compose exec gemini-mcp bash
+
+# View logs
+docker compose logs -f gemini-mcp
+```
+
+## IDE Configuration
+
+### VS Code
+
+**Recommended extensions:**
+- Python
+- Pylance
+- Black Formatter
+- Ruff
+- Docker
+
+**Settings** (`.vscode/settings.json`):
+```json
+{
+  "python.defaultInterpreterPath": "./venv/bin/python",
+  "python.formatting.provider": "black",
+  "python.linting.enabled": true,
+  "python.linting.ruffEnabled": true,
+  "python.testing.pytestEnabled": true,
+  "python.testing.pytestArgs": [
+    "tests/",
+    "--ignore=tests/test_live_integration.py"
+  ]
+}
+```
+
+### PyCharm
+
+1. **Configure interpreter**: Settings → Project → Python Interpreter
+2. **Set up test runner**: Settings → Tools → Python Integrated Tools → Testing
+3. **Configure code style**: Settings → Editor → Code Style → Python (use Black)
+
+## Debugging
+
+### Local Debugging
+
+```python
+# Add to your code for debugging
+import pdb; pdb.set_trace()
+
+# Or use your IDE's debugger
+```
+
+### Container Debugging
+
+```bash
+# Run container in debug mode
+docker compose exec gemini-mcp python -m pdb server.py
+
+# Or add debug prints
+LOG_LEVEL=DEBUG docker compose up
+```
+
+### Testing with Claude Desktop
+
+1. **Configure Claude Desktop** to use your development server
+2. **Use development container**:
+   ```json
+   {
+     "mcpServers": {
+       "gemini-dev": {
+         "command": "docker",
+         "args": [
+           "exec", "-i", "gemini-mcp-server", 
+           "python", "server.py"
+         ]
+       }
+     }
+   }
+   ```
+
+## Contributing Workflow
+
+### 1. Create Feature Branch
+
+```bash
+git checkout -b feature/your-feature-name
+```
+
+### 2. Make Changes
+
+Follow the coding standards and add tests for your changes.
+
+### 3. Run Quality Checks
+
+```bash
+# Format code
+black .
+
+# Check linting
+ruff check .
+
+# Run tests
+python -m pytest tests/ --ignore=tests/test_live_integration.py -v
+
+# Test with live API
+export GEMINI_API_KEY=your-key
+python tests/test_live_integration.py
+```
+
+### 4. Commit Changes
+
+```bash
+git add .
+git commit -m "feat: add new feature description"
+```
+
+### 5. Push and Create PR
+
+```bash
+git push origin feature/your-feature-name
+# Create PR on GitHub
+```
+
+## Performance Considerations
+
+### Profiling
+
+```python
+# Add profiling to your code
+import cProfile
+import pstats
+
+def profile_function():
+    profiler = cProfile.Profile()
+    profiler.enable()
+    # Your code here
+    profiler.disable()
+    stats = pstats.Stats(profiler)
+    stats.sort_stats('cumulative')
+    stats.print_stats()
+```
+
+### Memory Usage
+
+```bash
+# Monitor memory usage
+docker stats gemini-mcp-server
+
+# Profile memory in Python
+pip install memory-profiler
+python -m memory_profiler your_script.py
+```
+
+## Troubleshooting Development Issues
+
+### Common Issues
+
+1. **Import errors**: Check your Python path and virtual environment
+2. **API rate limits**: Use mocks in tests to avoid hitting limits
+3. **Docker issues**: Check Docker Desktop is running and has enough resources
+4. **Test failures**: Ensure you're using the correct Python version and dependencies
+
+### Clean Environment
+
+```bash
+# Reset Python environment
+rm -rf venv/
+python -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+
+# Reset Docker environment
+docker compose down -v
+docker system prune -f
+./setup-docker.sh
+```
+
+---
+
+**Next Steps:**
+- Read [Development Workflows](workflows.md)
+- Review [Code Style Guide](code-style.md)
+- Understand [Testing Strategy](testing.md)
--- a/docs/contributing/test-structure.md
+++ b/docs/contributing/test-structure.md
@@ -0,0 +1,470 @@
+# Test Structure Documentation
+
+## Overview
+
+This document provides a comprehensive analysis of the existing test structure in the Gemini MCP Server project. The test suite consists of **17 specialized test files** organized to validate all aspects of the system from unit-level functionality to complex AI collaboration workflows.
+
+## Test Organization
+
+### Test Directory Structure
+
+```
+tests/
+├── __init__.py                     # Package initialization
+├── conftest.py                     # Global test configuration and fixtures
+├── test_claude_continuation.py     # Claude continuation opportunities
+├── test_collaboration.py          # AI-to-AI collaboration features
+├── test_config.py                  # Configuration validation
+├── test_conversation_history_bug.py # Bug fix regression tests
+├── test_conversation_memory.py     # Redis-based conversation persistence
+├── test_cross_tool_continuation.py # Cross-tool conversation threading
+├── test_docker_path_integration.py # Docker environment path translation
+├── test_large_prompt_handling.py  # Large prompt detection and handling
+├── test_live_integration.py       # Live API testing (excluded from CI)
+├── test_precommit.py              # Pre-commit validation and git integration
+├── test_prompt_regression.py      # Normal prompt handling regression
+├── test_server.py                 # Main server functionality
+├── test_thinking_modes.py         # Thinking mode functionality
+├── test_tools.py                  # Individual tool implementations
+└── test_utils.py                  # Utility function testing
+```
+
+## Test Categories and Analysis
+
+### 1. Core Functionality Tests
+
+#### `test_server.py` - Main Server Functionality
+**Purpose**: Tests the core MCP server implementation and tool dispatch mechanism
+
+**Key Test Classes**:
+- **Server startup and initialization**
+- **Tool registration and availability**
+- **Request routing and handling**
+- **Error propagation and handling**
+
+**Example Coverage**:
+```python
+# Tests tool listing functionality
+def test_list_tools()
+
+# Tests tool execution pipeline
+async def test_call_tool()
+
+# Tests error handling for invalid tools
+async def test_call_invalid_tool()
+```
+
+#### `test_config.py` - Configuration Management
+**Purpose**: Validates configuration loading, environment variable handling, and settings validation
+
+**Key Areas**:
+- **Environment variable parsing**
+- **Default value handling**
+- **Configuration validation**
+- **Error handling for missing required config**
+
+#### `test_tools.py` - Tool Implementation Testing
+**Purpose**: Tests individual tool implementations with comprehensive input validation
+
+**Key Features**:
+- **Absolute path enforcement across all tools**
+- **Parameter validation for each tool**
+- **Error handling for malformed inputs**
+- **Tool-specific behavior validation**
+
+**Critical Security Testing**:
+```python
+# Tests that all tools enforce absolute paths
+async def test_tool_absolute_path_requirement()
+
+# Tests path traversal attack prevention
+async def test_tool_path_traversal_prevention()
+```
+
+#### `test_utils.py` - Utility Function Testing
+**Purpose**: Tests file utilities, token counting, and directory handling functions
+
+**Coverage Areas**:
+- **File reading and processing**
+- **Token counting and limits**
+- **Directory traversal and expansion**
+- **Path validation and security**
+
+### 2. Advanced Feature Tests
+
+#### `test_collaboration.py` - AI-to-AI Collaboration
+**Purpose**: Tests dynamic context requests and collaborative AI workflows
+
+**Key Scenarios**:
+- **Clarification request parsing**
+- **Dynamic context expansion**
+- **AI-to-AI communication protocols**
+- **Collaboration workflow validation**
+
+**Example Test**:
+```python
+async def test_clarification_request_parsing():
+    """Test parsing of AI clarification requests for additional context."""
+    # Validates that Gemini can request additional files/context
+    # and Claude can respond appropriately
+```
+
+#### `test_cross_tool_continuation.py` - Cross-Tool Threading
+**Purpose**: Tests conversation continuity across different tools
+
+**Critical Features**:
+- **Continuation ID persistence**
+- **Context preservation between tools**
+- **Thread management across tool switches**
+- **File context sharing between AI agents**
+
+#### `test_conversation_memory.py` - Memory Persistence
+**Purpose**: Tests Redis-based conversation storage and retrieval
+
+**Test Coverage**:
+- **Conversation storage and retrieval**
+- **Thread context management**
+- **TTL (time-to-live) handling**
+- **Memory cleanup and optimization**
+
+#### `test_thinking_modes.py` - Cognitive Load Management
+**Purpose**: Tests thinking mode functionality across all tools
+
+**Validation Areas**:
+- **Token budget enforcement**
+- **Mode selection and application**
+- **Performance characteristics**
+- **Quality vs. cost trade-offs**
+
+### 3. Specialized Testing
+
+#### `test_large_prompt_handling.py` - Scale Testing
+**Purpose**: Tests handling of prompts exceeding MCP token limits
+
+**Key Scenarios**:
+- **Large prompt detection (>50,000 characters)**
+- **Automatic file-based prompt handling**
+- **MCP token limit workarounds**
+- **Response capacity preservation**
+
+**Critical Flow Testing**:
+```python
+async def test_large_prompt_file_handling():
+    """Test that large prompts are automatically handled via file mechanism."""
+    # Validates the workaround for MCP's 25K token limit
+```
+
+#### `test_docker_path_integration.py` - Environment Testing
+**Purpose**: Tests Docker environment path translation and workspace mounting
+
+**Coverage**:
+- **Host-to-container path mapping**
+- **Workspace directory access**
+- **Cross-platform path handling**
+- **Security boundary enforcement**
+
+#### `test_precommit.py` - Quality Gate Testing
+**Purpose**: Tests pre-commit validation and git integration
+
+**Validation Areas**:
+- **Git repository discovery**
+- **Change detection and analysis**
+- **Multi-repository support**
+- **Security scanning of changes**
+
+### 4. Regression and Bug Fix Tests
+
+#### `test_conversation_history_bug.py` - Bug Fix Validation
+**Purpose**: Regression test for conversation history duplication bug
+
+**Specific Coverage**:
+- **Conversation deduplication**
+- **History consistency**
+- **Memory leak prevention**
+- **Thread integrity**
+
+#### `test_prompt_regression.py` - Normal Operation Validation
+**Purpose**: Ensures normal prompt handling continues to work correctly
+
+**Test Focus**:
+- **Standard prompt processing**
+- **Backward compatibility**
+- **Feature regression prevention**
+- **Performance baseline maintenance**
+
+#### `test_claude_continuation.py` - Session Management
+**Purpose**: Tests Claude continuation opportunities and session management
+
+**Key Areas**:
+- **Session state management**
+- **Continuation opportunity detection**
+- **Context preservation**
+- **Session cleanup and termination**
+
+### 5. Live Integration Testing
+
+#### `test_live_integration.py` - Real API Testing
+**Purpose**: Tests actual Gemini API integration (excluded from regular CI)
+
+**Requirements**:
+- Valid `GEMINI_API_KEY` environment variable
+- Network connectivity to Google AI services
+- Redis server for conversation memory testing
+
+**Test Categories**:
+- **Basic API request/response validation**
+- **Tool execution with real Gemini responses**
+- **Conversation threading with actual AI**
+- **Error handling with real API responses**
+
+**Exclusion from CI**:
+```python
+@pytest.mark.skipif(not os.getenv("GEMINI_API_KEY"), reason="API key required")
+class TestLiveIntegration:
+    """Tests requiring actual Gemini API access."""
+```
+
+## Test Configuration Analysis
+
+### `conftest.py` - Global Test Setup
+
+**Key Fixtures and Configuration**:
+
+#### Environment Isolation
+```python
+# Ensures tests run in isolated sandbox environment
+os.environ["MCP_PROJECT_ROOT"] = str(temp_dir)
+```
+
+#### Dummy API Keys
+```python
+# Provides safe dummy keys for testing without real credentials
+os.environ["GEMINI_API_KEY"] = "dummy-key-for-testing"
+```
+
+#### Cross-Platform Compatibility
+```python
+# Handles Windows async event loop configuration
+if platform.system() == "Windows":
+    asyncio.set_event_loop_policy(asyncio.WindowsProactorEventLoopPolicy())
+```
+
+#### Project Path Fixtures
+```python
+@pytest.fixture
+def project_path():
+    """Provides safe project path for file operations in tests."""
+```
+
+### `pytest.ini` - Test Runner Configuration
+
+**Key Settings**:
+```ini
+[pytest]
+testpaths = tests
+python_files = test_*.py
+python_classes = Test*
+python_functions = test_*
+asyncio_mode = auto
+addopts = 
+    -v
+    --strict-markers
+    --tb=short
+```
+
+## Mocking Strategies
+
+### 1. Gemini API Mocking
+
+**Pattern Used**:
+```python
+@patch("tools.base.BaseTool.create_model")
+async def test_tool_execution(self, mock_create_model):
+    mock_model = Mock()
+    mock_model.generate_content.return_value = Mock(
+        candidates=[Mock(content=Mock(parts=[Mock(text="Mocked response")]))]
+    )
+    mock_create_model.return_value = mock_model
+```
+
+**Benefits**:
+- **No API key required** for unit and integration tests
+- **Predictable responses** for consistent testing
+- **Fast execution** without network dependencies
+- **Cost-effective** testing without API charges
+
+### 2. Redis Memory Mocking
+
+**Pattern Used**:
+```python
+@patch("utils.conversation_memory.get_redis_client")
+def test_conversation_flow(self, mock_redis):
+    mock_client = Mock()
+    mock_redis.return_value = mock_client
+    # Test conversation persistence logic
+```
+
+**Advantages**:
+- **No Redis server required** for testing
+- **Controlled state** for predictable test scenarios
+- **Error simulation** for resilience testing
+
+### 3. File System Mocking
+
+**Pattern Used**:
+```python
+@patch("builtins.open", mock_open(read_data="test file content"))
+@patch("os.path.exists", return_value=True)
+def test_file_operations():
+    # Test file reading without actual files
+```
+
+**Security Benefits**:
+- **No file system access** during testing
+- **Path validation testing** without security risks
+- **Consistent test data** across environments
+
+## Security Testing Focus
+
+### Path Validation Testing
+
+**Critical Security Tests**:
+1. **Absolute path enforcement** - All tools must reject relative paths
+2. **Directory traversal prevention** - Block `../` and similar patterns
+3. **Symlink attack prevention** - Detect and block symbolic link attacks
+4. **Sandbox boundary enforcement** - Restrict access to allowed directories
+
+**Example Security Test**:
+```python
+async def test_path_traversal_attack_prevention():
+    """Test that directory traversal attacks are blocked."""
+    dangerous_paths = [
+        "../../../etc/passwd",
+        "/etc/shadow",
+        "~/../../root/.ssh/id_rsa"
+    ]
+    
+    for path in dangerous_paths:
+        with pytest.raises(SecurityError):
+            await tool.execute({"files": [path]})
+```
+
+### Docker Security Testing
+
+**Container Security Validation**:
+- **Workspace mounting** - Verify read-only access enforcement
+- **Path translation** - Test host-to-container path mapping
+- **Privilege boundaries** - Ensure container cannot escape sandbox
+
+## Test Execution Patterns
+
+### Parallel Test Execution
+
+**Strategy**: Tests are designed for parallel execution with proper isolation
+
+**Benefits**:
+- **Faster test suite** execution
+- **Resource efficiency** for CI/CD
+- **Scalable testing** for large codebases
+
+### Conditional Test Execution
+
+**Live Test Skipping**:
+```python
+@pytest.mark.skipif(not os.getenv("GEMINI_API_KEY"), reason="API key required")
+```
+
+**Platform-Specific Tests**:
+```python
+@pytest.mark.skipif(platform.system() == "Windows", reason="Unix-specific test")
+```
+
+## Test Quality Metrics
+
+### Coverage Analysis
+
+**Current Test Coverage by Category**:
+- ✅ **Tool Functionality**: All 7 tools comprehensively tested
+- ✅ **Server Operations**: Complete request/response cycle coverage
+- ✅ **Security Validation**: Path safety and access control testing
+- ✅ **Collaboration Features**: AI-to-AI communication patterns
+- ✅ **Memory Management**: Conversation persistence and threading
+- ✅ **Error Handling**: Graceful degradation and error recovery
+
+### Test Reliability
+
+**Design Characteristics**:
+- **Deterministic**: Tests produce consistent results
+- **Isolated**: No test dependencies or shared state
+- **Fast**: Unit tests complete in milliseconds
+- **Comprehensive**: Edge cases and error conditions covered
+
+## Integration with Development Workflow
+
+### Test-Driven Development Support
+
+**TDD Cycle Integration**:
+1. **Red**: Write failing test for new functionality
+2. **Green**: Implement minimal code to pass test
+3. **Refactor**: Improve code while maintaining test coverage
+
+### Pre-Commit Testing
+
+**Quality Gates**:
+- **Security validation** before commits
+- **Functionality regression** prevention
+- **Code quality** maintenance
+- **Performance baseline** protection
+
+### CI/CD Integration
+
+**GitHub Actions Workflow**:
+- **Multi-Python version** testing (3.10, 3.11, 3.12)
+- **Parallel test execution** for efficiency
+- **Selective live testing** when API keys available
+- **Coverage reporting** and quality gates
+
+## Best Practices Demonstrated
+
+### 1. Comprehensive Mocking
+Every external dependency is properly mocked for reliable testing
+
+### 2. Security-First Approach
+Strong emphasis on security validation and vulnerability prevention
+
+### 3. Collaboration Testing
+Extensive testing of AI-to-AI communication and workflow patterns
+
+### 4. Real-World Scenarios
+Tests cover actual usage patterns and edge cases
+
+### 5. Maintainable Structure
+Clear organization and focused test files for easy maintenance
+
+## Recommendations for Contributors
+
+### Adding New Tests
+
+1. **Follow Naming Conventions**: Use descriptive test names that explain the scenario
+2. **Maintain Isolation**: Mock all external dependencies
+3. **Test Security**: Include path validation and security checks
+4. **Cover Edge Cases**: Test error conditions and boundary cases
+5. **Document Purpose**: Use docstrings to explain test objectives
+
+### Test Quality Standards
+
+1. **Fast Execution**: Unit tests should complete in milliseconds
+2. **Predictable Results**: Tests should be deterministic
+3. **Clear Assertions**: Use descriptive assertion messages
+4. **Proper Cleanup**: Ensure tests don't leave side effects
+
+### Testing New Features
+
+1. **Start with Unit Tests**: Test individual components first
+2. **Add Integration Tests**: Test component interactions
+3. **Include Security Tests**: Validate security measures
+4. **Test Collaboration**: If relevant, test AI-to-AI workflows
+
+---
+
+This test structure demonstrates a mature, production-ready testing approach that ensures code quality, security, and reliability while supporting the collaborative AI development patterns that make this project unique.
--- a/docs/contributing/testing.md
+++ b/docs/contributing/testing.md
@@ -0,0 +1,690 @@
+# Testing Strategy & Guidelines
+
+## Overview
+
+This document outlines the comprehensive testing strategy for the Gemini MCP Server project, including unit testing, integration testing, and quality assurance practices that align with CLAUDE.md collaboration patterns.
+
+## Testing Philosophy
+
+### Test-Driven Development (TDD)
+
+**TDD Cycle**:
+1. **Red**: Write failing test for new functionality
+2. **Green**: Implement minimal code to pass the test
+3. **Refactor**: Improve code while maintaining test coverage
+4. **Repeat**: Continue cycle for all new features
+
+**Example TDD Flow**:
+```python
+# 1. Write failing test
+def test_chat_tool_should_process_simple_prompt():
+    tool = ChatTool()
+    result = tool.execute({"prompt": "Hello"})
+    assert result.status == "success"
+    assert "hello" in result.content.lower()
+
+# 2. Implement minimal functionality
+class ChatTool:
+    def execute(self, request):
+        return ToolOutput(content="Hello!", status="success")
+
+# 3. Refactor and enhance
+```
+
+### Testing Pyramid
+
+```
+    /\
+   /  \     E2E Tests (Few, High-Value)
+  /____\    Integration Tests (Some, Key Paths)  
+ /______\   Unit Tests (Many, Fast, Isolated)
+/________\  
+```
+
+**Distribution**:
+- **70% Unit Tests**: Fast, isolated, comprehensive coverage
+- **20% Integration Tests**: Component interaction validation
+- **10% End-to-End Tests**: Complete workflow validation
+
+## Test Categories
+
+### 1. Unit Tests
+
+**Purpose**: Test individual functions and classes in isolation
+
+**Location**: `tests/unit/`
+
+**Example Structure**:
+```python
+# tests/unit/test_file_utils.py
+import pytest
+from unittest.mock import Mock, patch, mock_open
+
+from utils.file_utils import validate_file_path, read_file_with_token_limit
+
+class TestFileUtils:
+    """Unit tests for file utility functions."""
+    
+    def test_validate_file_path_with_safe_path(self):
+        """Test that safe file paths pass validation."""
+        safe_path = "/workspace/tools/chat.py"
+        assert validate_file_path(safe_path) is True
+    
+    def test_validate_file_path_with_traversal_attack(self):
+        """Test that directory traversal attempts are blocked."""
+        dangerous_path = "/workspace/../../../etc/passwd"
+        with pytest.raises(SecurityError):
+            validate_file_path(dangerous_path)
+    
+    @patch('builtins.open', new_callable=mock_open, read_data="test content")
+    def test_read_file_with_token_limit(self, mock_file):
+        """Test file reading with token budget enforcement."""
+        content = read_file_with_token_limit("/test/file.py", max_tokens=100)
+        assert "test content" in content
+        mock_file.assert_called_once_with("/test/file.py", 'r', encoding='utf-8')
+```
+
+**Unit Test Guidelines**:
+- **Isolation**: Mock external dependencies (file system, network, database)
+- **Fast Execution**: Each test should complete in milliseconds
+- **Single Responsibility**: One test per behavior/scenario
+- **Descriptive Names**: Test names should describe the scenario and expected outcome
+
+### 2. Integration Tests
+
+**Purpose**: Test component interactions and system integration
+
+**Location**: `tests/integration/`
+
+**Example Structure**:
+```python
+# tests/integration/test_tool_execution.py
+import pytest
+import asyncio
+from unittest.mock import patch
+
+from server import call_tool
+from tools.chat import ChatTool
+from utils.conversation_memory import ConversationMemory
+
+class TestToolExecution:
+    """Integration tests for tool execution pipeline."""
+    
+    @pytest.fixture
+    def mock_redis(self):
+        """Mock Redis for conversation memory testing."""
+        with patch('redis.Redis') as mock:
+            yield mock
+    
+    @pytest.fixture
+    def conversation_memory(self, mock_redis):
+        """Create conversation memory with mocked Redis."""
+        return ConversationMemory("redis://mock")
+    
+    async def test_chat_tool_execution_with_memory(self, conversation_memory):
+        """Test chat tool execution with conversation memory integration."""
+        # Arrange
+        request = {
+            "name": "chat",
+            "arguments": {
+                "prompt": "Hello",
+                "continuation_id": "test-thread-123"
+            }
+        }
+        
+        # Act
+        result = await call_tool(request["name"], request["arguments"])
+        
+        # Assert
+        assert len(result) == 1
+        assert result[0].type == "text"
+        assert "hello" in result[0].text.lower()
+    
+    async def test_tool_execution_error_handling(self):
+        """Test error handling in tool execution pipeline."""
+        # Test with invalid tool name
+        with pytest.raises(ToolNotFoundError):
+            await call_tool("nonexistent_tool", {})
+```
+
+**Integration Test Guidelines**:
+- **Real Component Interaction**: Test actual component communication
+- **Mock External Services**: Mock external APIs (Gemini, Redis) for reliability
+- **Error Scenarios**: Test error propagation and handling
+- **Async Testing**: Use pytest-asyncio for async code testing
+
+### 3. Live Integration Tests
+
+**Purpose**: Test real API integration with external services
+
+**Location**: `tests/live/`
+
+**Requirements**: 
+- Valid `GEMINI_API_KEY` environment variable
+- Redis server running (for conversation memory tests)
+- Network connectivity
+
+**Example Structure**:
+```python
+# tests/live/test_gemini_integration.py
+import pytest
+import os
+
+from tools.chat import ChatTool
+from tools.models import GeminiClient
+
+@pytest.mark.live
+@pytest.mark.skipif(not os.getenv("GEMINI_API_KEY"), reason="API key required")
+class TestGeminiIntegration:
+    """Live tests requiring actual Gemini API access."""
+    
+    def setup_method(self):
+        """Set up for live testing."""
+        self.api_key = os.getenv("GEMINI_API_KEY")
+        self.client = GeminiClient(self.api_key)
+    
+    async def test_basic_gemini_request(self):
+        """Test basic Gemini API request/response."""
+        response = await self.client.generate_response(
+            prompt="Say 'test successful'",
+            thinking_mode="minimal"
+        )
+        assert "test successful" in response.lower()
+    
+    async def test_chat_tool_with_real_api(self):
+        """Test ChatTool with real Gemini API integration."""
+        tool = ChatTool()
+        result = await tool.execute({
+            "prompt": "What is 2+2?",
+            "thinking_mode": "minimal"
+        })
+        
+        assert result.status == "success"
+        assert "4" in result.content
+```
+
+**Live Test Guidelines**:
+- **Skip When Unavailable**: Skip if API keys or services unavailable
+- **Rate Limiting**: Respect API rate limits with delays
+- **Minimal Mode**: Use minimal thinking mode for speed
+- **Cleanup**: Clean up any created resources
+
+### 4. Security Tests
+
+**Purpose**: Validate security measures and vulnerability prevention
+
+**Location**: `tests/security/`
+
+**Example Structure**:
+```python
+# tests/security/test_path_validation.py
+import pytest
+
+from utils.file_utils import validate_file_path
+from exceptions import SecurityError
+
+class TestSecurityValidation:
+    """Security-focused tests for input validation."""
+    
+    @pytest.mark.parametrize("dangerous_path", [
+        "../../../etc/passwd",
+        "/etc/shadow", 
+        "~/../../root/.ssh/id_rsa",
+        "/var/log/auth.log",
+        "\\..\\..\\windows\\system32\\config\\sam"
+    ])
+    def test_dangerous_path_rejection(self, dangerous_path):
+        """Test that dangerous file paths are rejected."""
+        with pytest.raises(SecurityError):
+            validate_file_path(dangerous_path)
+    
+    def test_secret_sanitization_in_logs(self):
+        """Test that sensitive data is sanitized in log output."""
+        request_data = {
+            "prompt": "Hello",
+            "api_key": "sk-secret123",
+            "token": "bearer-token-456"
+        }
+        
+        sanitized = sanitize_for_logging(request_data)
+        
+        assert sanitized["api_key"] == "[REDACTED]"
+        assert sanitized["token"] == "[REDACTED]"
+        assert sanitized["prompt"] == "Hello"  # Non-sensitive data preserved
+```
+
+## Test Configuration
+
+### pytest Configuration
+
+**pytest.ini**:
+```ini
+[tool:pytest]
+testpaths = tests
+python_files = test_*.py *_test.py
+python_classes = Test*
+python_functions = test_*
+addopts = 
+    -v
+    --strict-markers
+    --disable-warnings
+    --cov=tools
+    --cov=utils
+    --cov-report=html
+    --cov-report=term-missing
+    --cov-fail-under=80
+
+markers =
+    unit: Unit tests (fast, isolated)
+    integration: Integration tests (component interaction)
+    live: Live tests requiring API keys and external services
+    security: Security-focused tests
+    slow: Tests that take more than 1 second
+```
+
+**conftest.py**:
+```python
+# tests/conftest.py
+import pytest
+import asyncio
+from unittest.mock import Mock, patch
+
+@pytest.fixture(scope="session")
+def event_loop():
+    """Create an instance of the default event loop for the test session."""
+    loop = asyncio.get_event_loop_policy().new_event_loop()
+    yield loop
+    loop.close()
+
+@pytest.fixture
+def mock_gemini_client():
+    """Mock Gemini client for testing without API calls."""
+    with patch('tools.models.GeminiClient') as mock:
+        mock_instance = Mock()
+        mock_instance.generate_response.return_value = "Mocked response"
+        mock.return_value = mock_instance
+        yield mock_instance
+
+@pytest.fixture
+def mock_redis():
+    """Mock Redis client for testing without Redis server."""
+    with patch('redis.Redis') as mock:
+        yield mock
+
+@pytest.fixture
+def sample_file_content():
+    """Sample file content for testing file processing."""
+    return """
+def example_function():
+    # This is a sample function
+    return "hello world"
+
+class ExampleClass:
+    def method(self):
+        pass
+"""
+
+@pytest.fixture
+def temp_project_directory(tmp_path):
+    """Create temporary project directory structure for testing."""
+    project_dir = tmp_path / "test_project"
+    project_dir.mkdir()
+    
+    # Create subdirectories
+    (project_dir / "tools").mkdir()
+    (project_dir / "utils").mkdir()
+    (project_dir / "tests").mkdir()
+    
+    # Create sample files
+    (project_dir / "tools" / "sample.py").write_text("# Sample tool")
+    (project_dir / "utils" / "helper.py").write_text("# Helper utility")
+    
+    return project_dir
+```
+
+## Test Data Management
+
+### Test Fixtures
+
+**File-based Fixtures**:
+```python
+# tests/fixtures/sample_code.py
+PYTHON_CODE_SAMPLE = '''
+import asyncio
+from typing import Dict, List
+
+async def process_data(items: List[str]) -> Dict[str, int]:
+    """Process a list of items and return counts."""
+    result = {}
+    for item in items:
+        result[item] = len(item)
+    return result
+'''
+
+JAVASCRIPT_CODE_SAMPLE = '''
+async function processData(items) {
+    const result = {};
+    for (const item of items) {
+        result[item] = item.length;
+    }
+    return result;
+}
+'''
+
+ERROR_LOGS_SAMPLE = '''
+2025-01-11 23:45:12 ERROR [tool_execution] Tool 'analyze' failed: File not found
+Traceback (most recent call last):
+  File "/app/tools/analyze.py", line 45, in execute
+    content = read_file(file_path)
+  File "/app/utils/file_utils.py", line 23, in read_file
+    with open(file_path, 'r') as f:
+FileNotFoundError: [Errno 2] No such file or directory: '/nonexistent/file.py'
+'''
+```
+
+### Mock Data Factories
+
+**ToolOutput Factory**:
+```python
+# tests/factories.py
+from dataclasses import dataclass
+from typing import Dict, Any, List
+
+def create_tool_output(
+    content: str = "Default response",
+    status: str = "success",
+    metadata: Dict[str, Any] = None,
+    files_processed: List[str] = None
+) -> ToolOutput:
+    """Factory for creating ToolOutput test instances."""
+    return ToolOutput(
+        content=content,
+        metadata=metadata or {},
+        files_processed=files_processed or [],
+        status=status
+    )
+
+def create_thread_context(
+    thread_id: str = "test-thread-123",
+    files: List[str] = None
+) -> ThreadContext:
+    """Factory for creating ThreadContext test instances."""
+    return ThreadContext(
+        thread_id=thread_id,
+        conversation_files=set(files or []),
+        tool_history=[],
+        context_tokens=0
+    )
+```
+
+## Mocking Strategies
+
+### External Service Mocking
+
+**Gemini API Mocking**:
+```python
+class MockGeminiClient:
+    """Mock Gemini client for testing."""
+    
+    def __init__(self, responses: Dict[str, str] = None):
+        self.responses = responses or {
+            "default": "This is a mocked response from Gemini"
+        }
+        self.call_count = 0
+    
+    async def generate_response(self, prompt: str, **kwargs) -> str:
+        """Mock response generation."""
+        self.call_count += 1
+        
+        # Return specific response for specific prompts
+        for key, response in self.responses.items():
+            if key in prompt.lower():
+                return response
+        
+        return self.responses.get("default", "Mock response")
+
+# Usage in tests
+@patch('tools.models.GeminiClient', MockGeminiClient)
+def test_with_mocked_gemini():
+    # Test implementation
+    pass
+```
+
+**File System Mocking**:
+```python
+@patch('builtins.open', mock_open(read_data="file content"))
+@patch('os.path.exists', return_value=True)
+@patch('os.path.getsize', return_value=1024)
+def test_file_operations():
+    """Test file operations with mocked file system."""
+    content = read_file("/mocked/file.py")
+    assert content == "file content"
+```
+
+## Performance Testing
+
+### Load Testing
+
+**Concurrent Tool Execution**:
+```python
+# tests/performance/test_load.py
+import asyncio
+import pytest
+import time
+
+@pytest.mark.slow
+class TestPerformance:
+    """Performance tests for system load handling."""
+    
+    async def test_concurrent_tool_execution(self):
+        """Test system performance under concurrent load."""
+        start_time = time.time()
+        
+        # Create 10 concurrent tool execution tasks
+        tasks = []
+        for i in range(10):
+            task = asyncio.create_task(
+                call_tool("chat", {"prompt": f"Request {i}"})
+            )
+            tasks.append(task)
+        
+        # Wait for all tasks to complete
+        results = await asyncio.gather(*tasks)
+        
+        end_time = time.time()
+        execution_time = end_time - start_time
+        
+        # Verify all requests succeeded
+        assert len(results) == 10
+        assert all(len(result) == 1 for result in results)
+        
+        # Performance assertion (adjust based on requirements)
+        assert execution_time < 30.0  # All requests should complete within 30s
+    
+    async def test_memory_usage_stability(self):
+        """Test that memory usage remains stable under load."""
+        import psutil
+        import gc
+        
+        process = psutil.Process()
+        initial_memory = process.memory_info().rss
+        
+        # Execute multiple operations
+        for i in range(100):
+            await call_tool("chat", {"prompt": f"Memory test {i}"})
+            
+            # Force garbage collection periodically
+            if i % 10 == 0:
+                gc.collect()
+        
+        final_memory = process.memory_info().rss
+        memory_growth = final_memory - initial_memory
+        
+        # Memory growth should be reasonable (adjust threshold as needed)
+        assert memory_growth < 100 * 1024 * 1024  # Less than 100MB growth
+```
+
+## Test Execution
+
+### Running Tests
+
+**Basic Test Execution**:
+```bash
+# Run all tests
+pytest
+
+# Run specific test categories
+pytest -m unit                    # Unit tests only
+pytest -m integration            # Integration tests only
+pytest -m "not live"             # All tests except live tests
+pytest -m "live and not slow"    # Live tests that are fast
+
+# Run with coverage
+pytest --cov=tools --cov=utils --cov-report=html
+
+# Run specific test file
+pytest tests/unit/test_file_utils.py -v
+
+# Run specific test method
+pytest tests/unit/test_file_utils.py::TestFileUtils::test_validate_file_path -v
+```
+
+**Continuous Integration**:
+```bash
+# CI test script
+#!/bin/bash
+set -e
+
+echo "Running unit tests..."
+pytest -m unit --cov=tools --cov=utils --cov-fail-under=80
+
+echo "Running integration tests..."
+pytest -m integration
+
+echo "Running security tests..."
+pytest -m security
+
+echo "Checking code quality..."
+flake8 tools/ utils/ tests/
+mypy tools/ utils/
+
+echo "All tests passed!"
+```
+
+### Test Reports
+
+**Coverage Reports**:
+```bash
+# Generate HTML coverage report
+pytest --cov=tools --cov=utils --cov-report=html
+open htmlcov/index.html
+
+# Generate terminal coverage report
+pytest --cov=tools --cov=utils --cov-report=term-missing
+```
+
+**Test Results Export**:
+```bash
+# Export test results to JUnit XML (for CI integration)
+pytest --junitxml=test-results.xml
+
+# Export test results with timing information
+pytest --durations=10  # Show 10 slowest tests
+```
+
+## Quality Metrics
+
+### Coverage Targets
+
+**Minimum Coverage Requirements**:
+- **Overall Coverage**: 80%
+- **Critical Modules**: 90% (security, file_utils, conversation_memory)
+- **Tool Modules**: 85%
+- **Utility Modules**: 80%
+
+**Coverage Enforcement**:
+```bash
+# Fail build if coverage drops below threshold
+pytest --cov-fail-under=80
+```
+
+### Test Quality Metrics
+
+**Test Suite Characteristics**:
+- **Fast Execution**: Unit test suite should complete in <30 seconds
+- **Reliable**: Tests should have <1% flaky failure rate
+- **Maintainable**: Test code should follow same quality standards as production code
+- **Comprehensive**: All critical paths and edge cases covered
+
+## Integration with Development Workflow
+
+### Pre-commit Testing
+
+**Git Hook Integration**:
+```bash
+#!/bin/sh
+# .git/hooks/pre-commit
+
+echo "Running pre-commit tests..."
+
+# Run fast tests before commit
+pytest -m "unit and not slow" --cov-fail-under=80
+
+if [ $? -ne 0 ]; then
+    echo "Tests failed. Commit blocked."
+    exit 1
+fi
+
+echo "Pre-commit tests passed."
+```
+
+### CI/CD Integration
+
+**GitHub Actions Workflow**:
+```yaml
+name: Test Suite
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [3.9, 3.10, 3.11]
+    
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+      
+      - name: Install dependencies
+        run: |
+          pip install -r requirements.txt
+          pip install pytest pytest-cov pytest-asyncio
+      
+      - name: Run unit tests
+        run: pytest -m unit --cov=tools --cov=utils --cov-fail-under=80
+      
+      - name: Run integration tests
+        run: pytest -m integration
+      
+      - name: Run security tests
+        run: pytest -m security
+      
+      - name: Upload coverage reports
+        uses: codecov/codecov-action@v3
+        with:
+          file: ./coverage.xml
+```
+
+## Detailed Test Structure Analysis
+
+For a comprehensive analysis of the existing test suite, including detailed breakdowns of all 17 test files, security testing patterns, and collaboration feature validation, see:
+
+**[Test Structure Documentation](test-structure.md)** - Complete analysis of existing test organization, mocking strategies, and quality assurance patterns
+
+---
+
+This comprehensive testing strategy ensures high-quality, reliable code while maintaining development velocity and supporting the collaborative patterns defined in CLAUDE.md.
--- a/docs/contributing/workflows.md
+++ b/docs/contributing/workflows.md
@@ -0,0 +1,622 @@
+# Development Workflows & Processes
+
+## Overview
+
+This document outlines the development workflows and processes for the Gemini MCP Server project, following the collaboration patterns defined in CLAUDE.md and integrating with the Memory Bank system for context preservation.
+
+## Pull Request Automation & Versioning
+
+### Automated Workflows
+
+The project implements automated versioning and Docker builds based on PR title prefixes, enabling seamless releases and testing.
+
+#### PR Title Prefix System
+
+**Version Bumping Prefixes** (creates releases):
+- `feat:` → Minor version bump (1.X.0) + Docker build + GitHub release
+- `fix:` → Patch version bump (1.0.X) + Docker build + GitHub release  
+- `breaking:` → Major version bump (X.0.0) + Docker build + GitHub release
+- `perf:` → Patch version bump + Docker build + GitHub release
+- `refactor:` → Patch version bump + Docker build + GitHub release
+
+**Non-Version Prefixes** (no releases):
+- `docs:` → Documentation changes only
+- `chore:` → Maintenance tasks
+- `test:` → Test updates
+- `ci:` → CI/CD pipeline changes
+- `style:` → Code formatting/style
+
+**Docker Build Combinations** (Docker without versioning):
+- `docker:` → Force Docker build only
+- `docs+docker:` → Documentation + Docker build
+- `chore+docker:` → Maintenance + Docker build
+- `test+docker:` → Test changes + Docker build
+- `ci+docker:` → CI changes + Docker build
+- `style+docker:` → Style changes + Docker build
+
+#### Workflow Execution Flow
+
+```mermaid
+flowchart TD
+    A[PR Created] --> B[docker-test.yml]
+    B --> C[test.yml] 
+    A --> C
+    
+    D[PR Merged] --> E[auto-version.yml]
+    E --> F{PR Title Analysis}
+    
+    F -->|feat:, fix:, etc.| G[Version Bump]
+    F -->|docker:, docs+docker:, etc.| H[Docker Build Flag]
+    F -->|docs:, chore:, etc.| I[No Action]
+    
+    G --> J[Create Git Tag]
+    J --> K[build_and_publish_docker.yml]
+    
+    H --> L[Repository Dispatch]
+    L --> K
+    
+    K --> M[Build & Push to GHCR]
+    
+    G --> N[Create GitHub Release]
+```
+
+#### Docker Image Tagging Strategy
+
+**For Version Releases:**
+- `v1.2.3` - Semantic version tag
+- `latest` - Latest stable release
+
+**For Docker-only Builds:**
+- `pr-{number}` - PR-specific tag (e.g., `pr-42`)
+- `main-{commit-sha}` - Commit-specific tag (e.g., `main-abc1234`)
+
+#### Implementation Details
+
+**Auto-version Workflow** (`.github/workflows/auto-version.yml`):
+1. Analyzes PR title for semantic prefix
+2. Updates `config.py` with new version
+3. Creates git tag and GitHub release
+4. Triggers Docker build via tag creation or repository dispatch
+
+**Docker Build Workflow** (`.github/workflows/build_and_publish_docker.yml`):
+1. Triggered by git tags or repository dispatch
+2. Builds multi-platform Docker images
+3. Pushes to GitHub Container Registry (GHCR)
+4. Handles different tagging strategies based on trigger
+
+**Docker Test Workflow** (`.github/workflows/docker-test.yml`):
+1. Runs on all PRs
+2. Validates Docker build without publishing
+3. Provides early feedback on containerization issues
+
+## Core Development Workflow
+
+### 1. Feature Development Process
+
+```mermaid
+flowchart TD
+    A[Issue/Feature Request] --> B[Planning Phase]
+    B --> C[Analysis Phase]
+    C --> D[Implementation Phase]
+    D --> E[Review Phase]
+    E --> F[Documentation Phase]
+    F --> G[Testing Phase]
+    G --> H[Validation Phase]
+    H --> I[Deployment]
+    
+    B --> B1[thinkdeep - Architecture Planning]
+    C --> C1[analyze - Codebase Understanding]
+    D --> D1[Code Implementation]
+    E --> E1[codereview - Quality Validation]
+    F --> F1[Documentation Updates]
+    G --> G1[Test Implementation]
+    H --> H1[precommit - Final Validation]
+```
+
+### 2. Tool Selection Matrix Integration
+
+**Planning Phase** - Use `thinkdeep`:
+```json
+{
+  "name": "thinkdeep",
+  "arguments": {
+    "current_analysis": "Need to implement new tool for X functionality",
+    "focus_areas": ["architecture", "integration", "security"],
+    "thinking_mode": "high"
+  }
+}
+```
+
+**Analysis Phase** - Use `analyze`:
+```json
+{
+  "name": "analyze", 
+  "arguments": {
+    "files": ["/workspace/tools/", "/workspace/utils/"],
+    "question": "Understand existing tool architecture for new implementation",
+    "analysis_type": "architecture"
+  }
+}
+```
+
+**Review Phase** - Use `codereview`:
+```json
+{
+  "name": "codereview",
+  "arguments": {
+    "files": ["/workspace/new-feature/"],
+    "context": "New tool implementation following established patterns",
+    "review_type": "full"
+  }
+}
+```
+
+**Validation Phase** - Use `precommit`:
+```json
+{
+  "name": "precommit",
+  "arguments": {
+    "path": "/workspace/",
+    "original_request": "Implement new X tool with Y capabilities"
+  }
+}
+```
+
+## Memory Bank Integration Workflow
+
+### Session Initialization
+
+**Every development session must start with Memory Bank check**:
+
+```bash
+# 1. Check Memory Bank status
+ls memory-bank/
+
+# 2. Read current context
+cat memory-bank/activeContext.md
+cat memory-bank/progress.md  
+cat memory-bank/decisionLog.md
+
+# 3. Update current focus if needed
+```
+
+### Progress Tracking
+
+**During development, update Memory Bank files**:
+
+**activeContext.md** - Current work status:
+```markdown
+## Current Focus
+[2025-01-11 23:30:00] - Implementing new debug tool feature for better error analysis
+Working on: Enhanced stack trace parsing for multi-language support
+
+## Recent Changes  
+[2025-01-11 23:15:00] - Completed comprehensive documentation following CLAUDE.md structure
+- docs/architecture/ completed (3 files)
+- docs/api/ completed (MCP protocol + 6 tool APIs)
+- Starting docs/contributing/ development workflow documentation
+```
+
+**progress.md** - Task completion tracking:
+```markdown
+## Current Tasks
+- 🔄 Creating docs/contributing/ workflow documentation
+- ✅ All tool API documentation completed
+- 🔄 Planning next enhancement: multi-language debug support
+
+## Completed Tasks  
+- ✅ Comprehensive architecture documentation (overview, components, data-flow)
+- ✅ Complete API documentation (MCP protocol + all 6 tools)
+- ✅ Memory Bank integration with CLAUDE.md collaboration rules
+```
+
+**decisionLog.md** - Architectural decisions:
+```markdown
+[2025-01-11 23:30:00] - Tool Documentation Structure
+Decision: Create individual API reference files for each tool rather than single comprehensive document
+Rationale: Better maintainability, easier navigation, clearer separation of concerns
+Implementation: docs/api/tools/ directory with dedicated files for chat, thinkdeep, analyze, codereview, debug, precommit
+```
+
+### UMB (Update Memory Bank) Protocol
+
+**Manual synchronization command**: `Update Memory Bank` or `UMB`
+
+**When to use UMB**:
+- End of development session
+- After major milestone completion
+- Before switching between different features
+- When context becomes fragmented
+
+**UMB Process**:
+1. Stop current activity
+2. Review complete chat history
+3. Update all Memory Bank files comprehensively
+4. Ensure cross-session continuity
+5. Document continuation points
+
+## Git Workflow
+
+### Branch Strategy
+
+**Branch Naming Convention**:
+```bash
+feature/tool-enhancement-debug-multilang
+feature/docs-api-reference
+bugfix/security-path-validation
+hotfix/memory-leak-conversation-storage
+```
+
+**Branch Lifecycle**:
+```bash
+# 1. Create feature branch
+git checkout -b feature/new-functionality
+
+# 2. Regular commits with descriptive messages
+git add .
+git commit -m "Implement core functionality for X feature
+
+- Add new utility functions
+- Update configuration handling  
+- Add comprehensive tests
+- Update documentation
+
+🤖 Generated with Claude Code
+Co-Authored-By: Claude <noreply@anthropic.com>"
+
+# 3. Pre-merge validation
+# Run precommit tool validation
+# Update documentation
+# Ensure Memory Bank is synchronized
+
+# 4. Create pull request
+gh pr create --title "Feature: New functionality" --body "..."
+```
+
+### Commit Message Standards
+
+**Format Template**:
+```
+<type>: <description>
+
+<body with detailed changes>
+
+🤖 Generated with Claude Code
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+**Commit Types**:
+- `feat`: New feature implementation
+- `fix`: Bug fixes and corrections
+- `docs`: Documentation updates
+- `refactor`: Code refactoring without functionality change
+- `test`: Test additions or modifications
+- `config`: Configuration and setup changes
+
+### Pre-Commit Validation
+
+**Mandatory validation before every commit**:
+
+```bash
+# 1. Run precommit tool
+claude-code-cli --tool precommit --path $(pwd)
+
+# 2. Address any critical/high issues
+# 3. Update documentation if code changes
+# 4. Ensure Memory Bank reflects changes
+# 5. Commit only after validation passes
+```
+
+## Code Review Process
+
+### Self-Review Checklist
+
+**Before requesting review**:
+- [ ] Run `codereview` tool on changes
+- [ ] Address all critical and high-severity issues
+- [ ] Update relevant documentation
+- [ ] Add/update tests for new functionality
+- [ ] Run full test suite locally
+- [ ] Update Memory Bank with decisions made
+- [ ] Ensure CLAUDE.md collaboration patterns followed
+
+### Peer Review Process
+
+**Review Preparation**:
+```json
+{
+  "name": "analyze",
+  "arguments": {
+    "files": ["/workspace/changed-files/"],
+    "question": "Prepare comprehensive context for code review",
+    "analysis_type": "general"
+  }
+}
+```
+
+**Review Execution**:
+```json
+{
+  "name": "codereview", 
+  "arguments": {
+    "files": ["/workspace/pull-request-files/"],
+    "context": "Pull request review for [feature description]",
+    "review_type": "full",
+    "thinking_mode": "high"
+  }
+}
+```
+
+**Double Validation Protocol** (for critical changes):
+1. **Primary Analysis** (Gemini): Deep code review using `codereview`
+2. **Adversarial Review** (Claude): Challenge findings, look for edge cases
+3. **Synthesis**: Combine insights and resolve disagreements
+4. **Memory Update**: Record key decisions and validation results
+
+## Documentation Workflow
+
+### Documentation-Driven Development
+
+**Every code change requires corresponding documentation updates**:
+
+1. **Architecture Changes**: Update `docs/architecture/`
+2. **API Changes**: Update `docs/api/` and tool references
+3. **Process Changes**: Update `docs/contributing/`
+4. **User-Facing Changes**: Update `docs/user-guides/`
+
+### Documentation Quality Standards
+
+**For Technical Audiences**:
+- Include specific file and line number references (`file_path:line_number`)
+- Explain architectural decisions and trade-offs
+- Provide concrete examples and code snippets
+- Document error scenarios and recovery strategies
+
+**For Non-Technical Audiences**:
+- Use plain language and explain technical terms
+- Start with problem statements and value propositions
+- Include practical usage scenarios
+- Provide troubleshooting guides
+
+### Documentation Review Process
+
+```json
+{
+  "name": "analyze",
+  "arguments": {
+    "files": ["/workspace/docs/"],
+    "question": "Review documentation completeness and accuracy against code changes",
+    "analysis_type": "quality"
+  }
+}
+```
+
+## Testing Workflow
+
+### Test Strategy
+
+**Test Categories**:
+1. **Unit Tests**: Individual tool functionality (`tests/test_tools.py`)
+2. **Integration Tests**: Tool interaction and MCP protocol (`tests/test_integration.py`)
+3. **Live Tests**: Real API integration (requires API keys)
+4. **Security Tests**: Input validation and security scenarios
+
+### Test Implementation Process
+
+**Test-Driven Development**:
+```bash
+# 1. Write failing tests for new functionality
+pytest tests/test_new_feature.py -v
+
+# 2. Implement functionality to pass tests
+# 3. Refactor while maintaining test coverage
+# 4. Add additional edge case tests
+# 5. Validate with full test suite
+pytest tests/ -v --cov=tools --cov=utils
+```
+
+### Continuous Integration
+
+**GitHub Actions Workflow**:
+```yaml
+name: Quality Assurance
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.9'
+      - name: Install dependencies
+        run: pip install -r requirements.txt
+      - name: Run tests
+        run: pytest tests/ -v --cov=tools --cov=utils
+      - name: Run precommit validation
+        run: claude-code-cli --tool precommit --path .
+```
+
+## Collaboration Patterns
+
+### Claude & Gemini Workflow Integration
+
+**Task Distribution**:
+- **Claude**: Immediate tasks, coordination, file operations, git management
+- **Gemini**: Deep analysis, strategic planning, comprehensive code review
+- **Both**: Documentation creation, problem-solving, architecture decisions
+
+**Communication Patterns**:
+```json
+// Claude initiates analysis
+{
+  "name": "analyze",
+  "arguments": {
+    "files": ["/workspace/complex-system/"],
+    "question": "Understand system for major refactoring",
+    "continuation_id": "analysis-session-uuid"
+  }
+}
+
+// Gemini provides deep insights
+// Claude uses insights for implementation decisions
+// Both collaborate on documentation and validation
+```
+
+### Cross-Tool Continuation
+
+**Maintain context across tool usage**:
+```json
+// 1. Initial exploration
+{
+  "name": "chat",
+  "arguments": {
+    "prompt": "How should we approach implementing caching?"
+  }
+}
+
+// 2. Deep strategic analysis  
+{
+  "name": "thinkdeep",
+  "arguments": {
+    "current_analysis": "Initial caching discussion insights...",
+    "continuation_id": "chat-session-uuid"
+  }
+}
+
+// 3. Implementation analysis
+{
+  "name": "analyze", 
+  "arguments": {
+    "files": ["/workspace/"],
+    "question": "Identify integration points for caching",
+    "continuation_id": "strategy-session-uuid"
+  }
+}
+```
+
+## Release Workflow
+
+### Automatic Versioning System
+
+**Semantic versioning is automatically managed based on PR title prefixes**:
+
+#### PR Title Conventions
+- `feat:` - New features → **MINOR** version bump (0.X.0)
+- `fix:` - Bug fixes → **PATCH** version bump (0.0.X)
+- `breaking:` or `BREAKING CHANGE:` - Breaking changes → **MAJOR** version bump (X.0.0)
+- `perf:` - Performance improvements → **PATCH** version bump
+- `refactor:` - Code refactoring → **PATCH** version bump
+- `docs:`, `chore:`, `test:`, `ci:`, `style:` - No version bump
+
+#### Automatic Version Workflow
+1. **Create PR with appropriate prefix**: `feat: Add new debugging capability`
+2. **PR gets reviewed and merged to main**
+3. **GitHub Action automatically**:
+   - Detects version bump type from PR title
+   - Updates version in `config.py`
+   - Updates `__updated__` timestamp
+   - Commits version change
+   - Creates git tag (e.g., `v3.3.0`)
+   - Generates GitHub release with PR description
+   - Triggers Docker build workflow
+
+#### Manual Version Bumping (if needed)
+```bash
+# Run the version bump script manually
+python scripts/bump_version.py <major|minor|patch>
+
+# Example: bump minor version
+python scripts/bump_version.py minor
+```
+
+### Pre-Release Validation
+
+**Comprehensive validation before release**:
+```bash
+# 1. Run full test suite
+pytest tests/ -v --cov=tools --cov=utils
+
+# 2. Security audit
+claude-code-cli --tool codereview \
+  --files /workspace/ \
+  --context "Security audit for release" \
+  --review-type security
+
+# 3. Performance validation  
+claude-code-cli --tool analyze \
+  --files /workspace/ \
+  --question "Identify performance issues for production" \
+  --analysis-type performance
+
+# 4. Documentation validation
+claude-code-cli --tool analyze \
+  --files /workspace/docs/ \
+  --question "Validate documentation completeness and accuracy"
+
+# 5. Final precommit validation
+claude-code-cli --tool precommit --path /workspace/
+```
+
+### Release Documentation
+
+**Automatic release notes are generated from PR descriptions**:
+1. **GitHub Release**: Created automatically with PR details
+2. **CHANGELOG.md**: Update manually for major releases
+3. **README.md**: Update installation instructions if needed
+4. **docs/**: Ensure documentation reflects new features
+
+### Deployment Process
+
+**Docker Image Workflow**:
+```bash
+# 1. Build and test image locally
+docker build -t gemini-mcp-server:latest .
+docker run --rm gemini-mcp-server:latest --version
+
+# 2. Push to registry (automated via GitHub Actions)
+# 3. Update deployment configurations
+# 4. Monitor deployment health
+```
+
+## Troubleshooting Workflow
+
+### Issue Investigation Process
+
+**Systematic debugging approach**:
+```json
+{
+  "name": "debug",
+  "arguments": {
+    "error_description": "Detailed problem description",
+    "error_context": "Stack traces, logs, environment info",
+    "files": ["/workspace/related-modules/"],
+    "thinking_mode": "high"
+  }
+}
+```
+
+### Memory Bank for Issue Tracking
+
+**Document issues and resolutions**:
+```markdown
+## decisionLog.md
+[2025-01-11 23:45:00] - Memory Leak Resolution
+Decision: Implement proper cleanup in conversation memory module
+Rationale: Redis connections not properly closed, causing memory growth
+Implementation: Added context managers and explicit cleanup in utils/conversation_memory.py:150
+```
+
+### Knowledge Base Maintenance
+
+**Update Memory Bank with solutions**:
+- Store successful debugging approaches
+- Document common issues and resolutions  
+- Maintain troubleshooting patterns
+- Cross-reference with architectural decisions
+
+---
+
+This development workflow ensures high-quality, collaborative development while maintaining consistency with CLAUDE.md patterns and preserving knowledge through the Memory Bank system.