torbjorn/my-pal-mcp-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
* 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>
This commit is contained in:
PCITI
2025-06-12 12:10:27 +02:00
committed by GitHub
parent c7eeb68262
commit c5313b170a
36 changed files with 10222 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

380
docs/contributing/setup.md Normal file
View File

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