my-pal-mcp-server/docs/contributing/setup.md

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
• Docker Desktop - Download
• Git - Download
• Claude Desktop - 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

git clone https://github.com/BeehiveInnovations/zen-mcp-server.git
cd zen-mcp-server

2. Choose Development Method

Option A: Docker Development (Recommended)

Best for consistency and avoiding local Python environment issues:

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

# 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

# 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

# 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

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

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

# 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

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

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

# 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):

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

# Add to your code for debugging
import pdb; pdb.set_trace()

# Or use your IDE's debugger

Container Debugging

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

   {
     "mcpServers": {
       "gemini-dev": {
         "command": "docker",
         "args": [
           "exec", "-i", "zen-mcp-server", 
           "python", "server.py"
         ]
       }
     }
   }
   

Contributing Workflow

1. Create Feature Branch

git checkout -b feature/your-feature-name

2. Make Changes

Follow the coding standards and add tests for your changes.

3. Run Quality Checks

# 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

git add .
git commit -m "feat: add new feature description"

5. Push and Create PR

git push origin feature/your-feature-name
# Create PR on GitHub

Performance Considerations

Profiling

# 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

# Monitor memory usage
docker stats zen-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

# 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
• Review Code Style Guide
• Understand Testing Strategy