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>
This commit is contained in:
PCITI
291
docs/user-guides/configuration.md
Normal file
291
docs/user-guides/configuration.md
Normal file
@@ -0,0 +1,291 @@
|
||||
# Configuration Guide
|
||||
|
||||
This guide covers all configuration options for the Gemini MCP Server.
|
||||
|
||||
## Environment Variables
|
||||
|
||||
### Required Configuration
|
||||
|
||||
| Variable | Description | Example |
|
||||
|----------|-------------|---------|
|
||||
| `GEMINI_API_KEY` | Your Gemini API key from Google AI Studio | `AIzaSyC...` |
|
||||
|
||||
### Optional Configuration
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `REDIS_URL` | `redis://localhost:6379/0` | Redis connection URL for conversation threading |
|
||||
| `WORKSPACE_ROOT` | `$HOME` | Root directory mounted as `/workspace` in container |
|
||||
| `LOG_LEVEL` | `INFO` | Logging verbosity: `DEBUG`, `INFO`, `WARNING`, `ERROR` |
|
||||
| `GEMINI_MODEL` | `gemini-2.5-pro-preview-06-05` | Gemini model to use |
|
||||
| `MAX_CONTEXT_TOKENS` | `1000000` | Maximum context window (1M tokens for Gemini Pro) |
|
||||
|
||||
## Claude Desktop Configuration
|
||||
|
||||
### MCP Server Configuration
|
||||
|
||||
Add to your Claude Desktop config file:
|
||||
|
||||
**Location:**
|
||||
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
||||
|
||||
### Configuration Options
|
||||
|
||||
#### Option 1: Published Docker Image (Recommended)
|
||||
|
||||
**Simplest setup using pre-built images from GitHub Container Registry:**
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"gemini": {
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"run", "--rm", "-i",
|
||||
"-e", "GEMINI_API_KEY",
|
||||
"ghcr.io/patrykiti/gemini-mcp-server:latest"
|
||||
],
|
||||
"env": {
|
||||
"GEMINI_API_KEY": "your-gemini-api-key-here"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Available Image Tags:**
|
||||
- `latest` - Most recent stable release (recommended)
|
||||
- `v1.2.0`, `v1.1.0` - Specific version tags
|
||||
- `pr-{number}` - Development builds from pull requests
|
||||
- `main-{commit-sha}` - Development builds from main branch
|
||||
|
||||
**Benefits:**
|
||||
- ✅ No local build required - instant setup
|
||||
- ✅ Automatically updated with releases
|
||||
- ✅ Smaller local footprint
|
||||
- ✅ Version pinning for stability
|
||||
- ✅ Cross-platform compatibility
|
||||
|
||||
**Version Pinning Example:**
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"gemini": {
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"run", "--rm", "-i",
|
||||
"-e", "GEMINI_API_KEY",
|
||||
"ghcr.io/patrykiti/gemini-mcp-server:v1.2.0"
|
||||
],
|
||||
"env": {
|
||||
"GEMINI_API_KEY": "your-gemini-api-key-here"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Option 2: Local Development Build
|
||||
- **Windows (WSL)**: `/mnt/c/Users/USERNAME/AppData/Roaming/Claude/claude_desktop_config.json`
|
||||
|
||||
**Configuration:**
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"gemini": {
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"exec",
|
||||
"-i",
|
||||
"gemini-mcp-server",
|
||||
"python",
|
||||
"server.py"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Alternative: Claude Code CLI
|
||||
|
||||
```bash
|
||||
# Add MCP server via CLI
|
||||
claude mcp add gemini -s user -- docker exec -i gemini-mcp-server python server.py
|
||||
|
||||
# List servers
|
||||
claude mcp list
|
||||
|
||||
# Remove server
|
||||
claude mcp remove gemini -s user
|
||||
```
|
||||
|
||||
## Docker Configuration
|
||||
|
||||
### Environment File (.env)
|
||||
|
||||
```bash
|
||||
# Required
|
||||
GEMINI_API_KEY=your-gemini-api-key-here
|
||||
|
||||
# Optional - Docker Compose defaults
|
||||
REDIS_URL=redis://redis:6379/0
|
||||
WORKSPACE_ROOT=/Users/yourname
|
||||
LOG_LEVEL=INFO
|
||||
```
|
||||
|
||||
### Docker Compose Overrides
|
||||
|
||||
Create `docker-compose.override.yml` for custom settings:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
gemini-mcp:
|
||||
environment:
|
||||
- LOG_LEVEL=DEBUG
|
||||
volumes:
|
||||
- /custom/path:/workspace:ro
|
||||
```
|
||||
|
||||
## Logging Configuration
|
||||
|
||||
### Log Levels
|
||||
|
||||
- **DEBUG**: Detailed operational messages, conversation threading, tool execution flow
|
||||
- **INFO**: General operational messages (default)
|
||||
- **WARNING**: Warnings and errors only
|
||||
- **ERROR**: Errors only
|
||||
|
||||
### Viewing Logs
|
||||
|
||||
```bash
|
||||
# Real-time logs
|
||||
docker compose logs -f gemini-mcp
|
||||
|
||||
# Specific service logs
|
||||
docker compose logs redis
|
||||
docker compose logs log-monitor
|
||||
```
|
||||
|
||||
## Security Configuration
|
||||
|
||||
### API Key Security
|
||||
|
||||
1. **Never commit API keys** to version control
|
||||
2. **Use environment variables** or `.env` files
|
||||
3. **Restrict key permissions** in Google AI Studio
|
||||
4. **Rotate keys periodically**
|
||||
|
||||
### File Access Security
|
||||
|
||||
The container mounts your home directory as read-only. To restrict access:
|
||||
|
||||
```yaml
|
||||
# In docker-compose.override.yml
|
||||
services:
|
||||
gemini-mcp:
|
||||
environment:
|
||||
- WORKSPACE_ROOT=/path/to/specific/project
|
||||
volumes:
|
||||
- /path/to/specific/project:/workspace:ro
|
||||
```
|
||||
|
||||
## Performance Configuration
|
||||
|
||||
### Memory Limits
|
||||
|
||||
```yaml
|
||||
# In docker-compose.override.yml
|
||||
services:
|
||||
gemini-mcp:
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
memory: 2G
|
||||
reservations:
|
||||
memory: 512M
|
||||
```
|
||||
|
||||
### Redis Configuration
|
||||
|
||||
Redis is pre-configured with optimal settings:
|
||||
- 512MB memory limit
|
||||
- LRU eviction policy
|
||||
- Persistence enabled (saves every 60 seconds if data changed)
|
||||
|
||||
To customize Redis:
|
||||
|
||||
```yaml
|
||||
# In docker-compose.override.yml
|
||||
services:
|
||||
redis:
|
||||
command: redis-server --maxmemory 1g --maxmemory-policy allkeys-lru
|
||||
```
|
||||
|
||||
## Troubleshooting Configuration
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **API Key Not Set**
|
||||
```bash
|
||||
# Check .env file
|
||||
cat .env | grep GEMINI_API_KEY
|
||||
```
|
||||
|
||||
2. **File Access Issues**
|
||||
```bash
|
||||
# Check mounted directory
|
||||
docker exec -it gemini-mcp-server ls -la /workspace
|
||||
```
|
||||
|
||||
3. **Redis Connection Issues**
|
||||
```bash
|
||||
# Test Redis connectivity
|
||||
docker exec -it gemini-mcp-redis redis-cli ping
|
||||
```
|
||||
|
||||
### Debug Mode
|
||||
|
||||
Enable debug logging for troubleshooting:
|
||||
|
||||
```bash
|
||||
# In .env file
|
||||
LOG_LEVEL=DEBUG
|
||||
|
||||
# Restart services
|
||||
docker compose restart
|
||||
```
|
||||
|
||||
## Advanced Configuration
|
||||
|
||||
### Custom Model Configuration
|
||||
|
||||
To use a different Gemini model, override in `.env`:
|
||||
|
||||
```bash
|
||||
GEMINI_MODEL=gemini-2.5-pro-latest
|
||||
```
|
||||
|
||||
### Network Configuration
|
||||
|
||||
For custom networking (advanced users):
|
||||
|
||||
```yaml
|
||||
# In docker-compose.override.yml
|
||||
networks:
|
||||
custom_network:
|
||||
driver: bridge
|
||||
|
||||
services:
|
||||
gemini-mcp:
|
||||
networks:
|
||||
- custom_network
|
||||
redis:
|
||||
networks:
|
||||
- custom_network
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**See Also:**
|
||||
- [Installation Guide](installation.md)
|
||||
- [Troubleshooting Guide](troubleshooting.md)
|
||||
181
docs/user-guides/contributing-guide.md
Normal file
181
docs/user-guides/contributing-guide.md
Normal file
@@ -0,0 +1,181 @@
|
||||
# Contributing Guide for Users
|
||||
|
||||
## Quick Start for Contributors
|
||||
|
||||
This guide helps new contributors understand how to contribute to the Gemini MCP Server project effectively.
|
||||
|
||||
## Pull Request Guidelines
|
||||
|
||||
### Understanding PR Title Automation
|
||||
|
||||
The project uses automated workflows based on your PR title. Choose the right prefix to get the appropriate automation:
|
||||
|
||||
#### 🚀 **For New Features & Bug Fixes** (creates releases):
|
||||
```
|
||||
feat: Add new chat streaming functionality
|
||||
fix: Resolve memory leak in conversation history
|
||||
breaking: Remove deprecated tool parameters
|
||||
perf: Optimize token usage calculation
|
||||
refactor: Simplify error handling logic
|
||||
```
|
||||
|
||||
**What happens:** Version bump + GitHub release + Docker image published
|
||||
|
||||
#### 📝 **For Documentation & Maintenance** (no releases):
|
||||
```
|
||||
docs: Update installation instructions
|
||||
chore: Update dependencies
|
||||
test: Add integration tests for analyze tool
|
||||
ci: Improve workflow error handling
|
||||
style: Fix code formatting issues
|
||||
```
|
||||
|
||||
**What happens:** Changes merged, no automation triggered
|
||||
|
||||
#### 🐳 **For Testing Docker Changes** (Docker without releases):
|
||||
```
|
||||
docker: Test new Dockerfile optimization
|
||||
docs+docker: Update Docker guide and test image
|
||||
chore+docker: Update base image and test
|
||||
test+docker: Add Docker integration tests
|
||||
ci+docker: Update Docker workflow and test
|
||||
style+docker: Fix Dockerfile formatting and test
|
||||
```
|
||||
|
||||
**What happens:** Docker image built and published (tagged with PR number)
|
||||
|
||||
### Choosing the Right Prefix
|
||||
|
||||
**Ask yourself:**
|
||||
1. **Does this add/change functionality?** → Use `feat:` or `fix:`
|
||||
2. **Is this breaking existing behavior?** → Use `breaking:`
|
||||
3. **Is this just documentation/maintenance?** → Use `docs:`, `chore:`, etc.
|
||||
4. **Do I need to test Docker changes?** → Add `+docker` to any non-version prefix
|
||||
|
||||
### Examples by Change Type
|
||||
|
||||
#### Adding a New Tool
|
||||
```
|
||||
feat: Add sentiment analysis tool for code comments
|
||||
```
|
||||
|
||||
#### Fixing a Bug
|
||||
```
|
||||
fix: Correct timeout handling in thinkdeep tool
|
||||
```
|
||||
|
||||
#### Updating Documentation
|
||||
```
|
||||
docs: Add troubleshooting guide for Windows installation
|
||||
```
|
||||
|
||||
#### Testing Docker Changes
|
||||
```
|
||||
docs+docker: Update Docker configuration and test deployment
|
||||
```
|
||||
|
||||
#### Major Breaking Changes
|
||||
```
|
||||
breaking: Change MCP protocol response format for better compatibility
|
||||
```
|
||||
|
||||
## Docker Testing for Contributors
|
||||
|
||||
### When to Use Docker Build Combinations
|
||||
|
||||
**Use `+docker` suffix when:**
|
||||
- You've modified Dockerfile, docker-compose.yml, or Docker-related configs
|
||||
- You want to test the containerized version of your changes
|
||||
- You're updating Docker documentation and want to verify it works
|
||||
- You're making CI/CD changes that affect Docker builds
|
||||
|
||||
**Don't use `+docker` when:**
|
||||
- Your changes don't affect containerization
|
||||
- You're only updating code documentation
|
||||
- You're making simple code style changes
|
||||
|
||||
### How Docker Testing Works
|
||||
|
||||
1. **PR Creation:** Docker build test runs automatically (no publishing)
|
||||
2. **PR Merge with `+docker`:** Docker image built and pushed to GHCR
|
||||
3. **Image Tags:** Your image will be tagged as:
|
||||
- `pr-{number}` (e.g., `pr-42`)
|
||||
- `main-{commit-sha}` (e.g., `main-abc1234`)
|
||||
|
||||
### Testing Your Docker Image
|
||||
|
||||
After your PR is merged with a `+docker` prefix:
|
||||
|
||||
```bash
|
||||
# Pull your test image
|
||||
docker pull ghcr.io/patrykiti/gemini-mcp-server:pr-42
|
||||
|
||||
# Or use the commit-based tag
|
||||
docker pull ghcr.io/patrykiti/gemini-mcp-server:main-abc1234
|
||||
|
||||
# Test it locally
|
||||
docker run -it --rm ghcr.io/patrykiti/gemini-mcp-server:pr-42
|
||||
```
|
||||
|
||||
## Workflow Summary
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A[Choose PR Title] --> B{Type of Change?}
|
||||
|
||||
B -->|New Feature/Bug Fix| C[feat:/fix: prefix]
|
||||
B -->|Documentation Only| D[docs: prefix]
|
||||
B -->|Need Docker Test| E[prefix+docker:]
|
||||
|
||||
C --> F[Version Bump + Release + Docker]
|
||||
D --> G[Merge Only]
|
||||
E --> H[Docker Build Only]
|
||||
|
||||
F --> I[Published Release]
|
||||
G --> J[Updated Docs]
|
||||
H --> K[Test Docker Image]
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Writing Good PR Titles
|
||||
- **Be specific:** `feat: Add rate limiting to chat tool` not `feat: Update chat`
|
||||
- **Use imperative mood:** `fix: Resolve timeout issue` not `fixes timeout issue`
|
||||
- **Keep it concise:** Aim for 50 characters or less
|
||||
- **Include scope when helpful:** `feat(precommit): Add Python syntax validation`
|
||||
|
||||
### Common Mistakes to Avoid
|
||||
- ❌ `Update README` → ✅ `docs: Update installation requirements`
|
||||
- ❌ `Fix bug` → ✅ `fix: Resolve memory leak in conversation threading`
|
||||
- ❌ `feat: Add feature` → ✅ `feat: Add multi-language support for code analysis`
|
||||
- ❌ `docs: Update Docker and test it` → ✅ `docs+docker: Update container setup guide`
|
||||
|
||||
### Testing Your Changes
|
||||
|
||||
Before submitting a PR:
|
||||
|
||||
1. **Run local tests:**
|
||||
```bash
|
||||
python -m pytest tests/ --ignore=tests/test_live_integration.py -v
|
||||
black --check .
|
||||
ruff check .
|
||||
```
|
||||
|
||||
2. **Test Docker locally (if applicable):**
|
||||
```bash
|
||||
docker build -t test-image .
|
||||
docker run -it --rm test-image
|
||||
```
|
||||
|
||||
3. **Verify documentation builds:**
|
||||
- Check that any new documentation renders correctly
|
||||
- Ensure links work and examples are accurate
|
||||
|
||||
## Getting Help
|
||||
|
||||
- **Stuck on prefix choice?** Look at recent merged PRs for examples
|
||||
- **Docker build failing?** Check the docker-test workflow results in your PR
|
||||
- **Questions about automation?** Open a discussion or ask in your PR comments
|
||||
- **Need API access for testing?** Live integration tests are optional for contributors
|
||||
|
||||
Remember: The automation is designed to help maintain consistency and quality. When in doubt, choose the most conservative prefix and ask for guidance in your PR!
|
||||
392
docs/user-guides/installation.md
Normal file
392
docs/user-guides/installation.md
Normal file
@@ -0,0 +1,392 @@
|
||||
# 🐳 Docker User Guide: Using Gemini MCP Server
|
||||
|
||||
This guide shows you how to use the Gemini MCP Server with Claude Desktop using the automated Docker setup. **Everything is handled automatically** - no manual Redis setup required!
|
||||
|
||||
## 🎯 What You'll Get
|
||||
|
||||
After following this guide, you'll have:
|
||||
- ✅ Gemini MCP Server running with Claude Desktop
|
||||
- ✅ Redis automatically configured for conversation threading
|
||||
- ✅ Access to all Gemini tools: `chat`, `thinkdeep`, `codereview`, `debug`, `analyze`, `precommit`
|
||||
- ✅ Persistent data storage that survives container restarts
|
||||
|
||||
## 📋 Prerequisites
|
||||
|
||||
### Required
|
||||
1. **Docker Desktop** - [Download here](https://www.docker.com/products/docker-desktop/)
|
||||
2. **Claude Desktop** - [Download here](https://claude.ai/download)
|
||||
3. **Gemini API Key** - [Get one here](https://makersuite.google.com/app/apikey)
|
||||
4. **Git** - For cloning the repository
|
||||
|
||||
### Platform Support
|
||||
- ✅ **macOS** (Intel and Apple Silicon)
|
||||
- ✅ **Linux**
|
||||
- ✅ **Windows** (requires WSL2 for Claude Desktop)
|
||||
|
||||
## 🚀 Setup Option 1: Published Docker Image (Fastest)
|
||||
|
||||
**Quick setup using pre-built image from GitHub Container Registry - no build required!**
|
||||
|
||||
### Step 1: Pull Published Image
|
||||
|
||||
```bash
|
||||
# Download the latest stable version
|
||||
docker pull ghcr.io/patrykiti/gemini-mcp-server:latest
|
||||
|
||||
# Optional: Pull a specific version
|
||||
docker pull ghcr.io/patrykiti/gemini-mcp-server:v1.2.0
|
||||
```
|
||||
|
||||
### Step 2: Configure Claude Desktop
|
||||
|
||||
**Find your Claude Desktop config file:**
|
||||
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
||||
- **Windows (WSL required)**: `/mnt/c/Users/USERNAME/AppData/Roaming/Claude/claude_desktop_config.json`
|
||||
|
||||
**Add this configuration:**
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"gemini": {
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"run", "--rm", "-i",
|
||||
"-e", "GEMINI_API_KEY",
|
||||
"ghcr.io/patrykiti/gemini-mcp-server:latest"
|
||||
],
|
||||
"env": {
|
||||
"GEMINI_API_KEY": "your-gemini-api-key-here"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 3: Update Available Tags
|
||||
|
||||
Available image tags:
|
||||
- `latest` - Most recent stable release
|
||||
- `v1.2.0`, `v1.1.0`, etc. - Specific version releases
|
||||
- `pr-{number}` - Development builds from pull requests
|
||||
- `main-{sha}` - Development builds from main branch
|
||||
|
||||
```bash
|
||||
# See all available tags
|
||||
docker search ghcr.io/patrykiti/gemini-mcp-server
|
||||
|
||||
# Or check GitHub Container Registry
|
||||
open https://github.com/PatrykIti/gemini-mcp-server/pkgs/container/gemini-mcp-server
|
||||
```
|
||||
|
||||
### Step 4: Test Installation
|
||||
|
||||
Restart Claude Desktop and try:
|
||||
```
|
||||
"Use gemini to say hello and confirm the connection works"
|
||||
```
|
||||
|
||||
**Benefits of Published Image:**
|
||||
- ✅ **Instant setup** - No build time, no source code needed
|
||||
- ✅ **Always updated** - Automatically built with every release
|
||||
- ✅ **Smaller footprint** - No development dependencies
|
||||
- ✅ **Version control** - Pin to specific versions for stability
|
||||
- ✅ **Cross-platform** - Works on any Docker-supported OS
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Setup Option 2: Local Build (For Development)
|
||||
|
||||
### Step 1: Clone Repository
|
||||
|
||||
```bash
|
||||
git clone https://github.com/BeehiveInnovations/gemini-mcp-server.git
|
||||
cd gemini-mcp-server
|
||||
```
|
||||
|
||||
### Step 2: One-Command Setup
|
||||
|
||||
```bash
|
||||
# Automated setup - builds images and starts all services
|
||||
./setup-docker.sh
|
||||
```
|
||||
|
||||
**What this script does automatically:**
|
||||
- ✅ Creates `.env` file with your API key (if `GEMINI_API_KEY` environment variable is set)
|
||||
- ✅ Builds the Gemini MCP Server Docker image
|
||||
- ✅ Starts Redis container for conversation threading
|
||||
- ✅ Starts MCP server container
|
||||
- ✅ Configures networking between containers
|
||||
- ✅ Shows you the exact Claude Desktop configuration
|
||||
|
||||
### Step 3: Add Your API Key (if needed)
|
||||
|
||||
If you see a message about updating your API key:
|
||||
|
||||
```bash
|
||||
# Edit .env file and replace placeholder with your actual key
|
||||
nano .env
|
||||
# Change: GEMINI_API_KEY=your-gemini-api-key-here
|
||||
# To: GEMINI_API_KEY=your_actual_api_key
|
||||
|
||||
# Restart services to apply changes
|
||||
docker compose restart
|
||||
```
|
||||
|
||||
### Step 4: Configure Claude Desktop
|
||||
|
||||
The setup script shows you the exact configuration. Add this to your Claude Desktop config:
|
||||
|
||||
**Find your config file:**
|
||||
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
||||
- **Windows (WSL)**: `/mnt/c/Users/USERNAME/AppData/Roaming/Claude/claude_desktop_config.json`
|
||||
|
||||
**Configuration:**
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"gemini": {
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"exec",
|
||||
"-i",
|
||||
"gemini-mcp-server",
|
||||
"python",
|
||||
"server.py"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 5: Restart Claude Desktop & Test
|
||||
|
||||
1. Completely quit and restart Claude Desktop
|
||||
2. Test with: `"Use gemini to chat about Python best practices"`
|
||||
|
||||
## 🚀 Setup Option 2: Published Docker Image (Advanced)
|
||||
|
||||
If you prefer to use the published image without cloning:
|
||||
|
||||
```bash
|
||||
# Create a directory for your work
|
||||
mkdir gemini-mcp-project && cd gemini-mcp-project
|
||||
|
||||
# Create minimal docker-compose.yml
|
||||
cat > docker-compose.yml << 'EOF'
|
||||
services:
|
||||
redis:
|
||||
image: redis:7-alpine
|
||||
container_name: gemini-mcp-redis
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- "6379:6379"
|
||||
volumes:
|
||||
- redis_data:/data
|
||||
|
||||
gemini-mcp:
|
||||
image: ghcr.io/beehiveinnovations/gemini-mcp-server:latest
|
||||
container_name: gemini-mcp-server
|
||||
restart: unless-stopped
|
||||
depends_on:
|
||||
- redis
|
||||
environment:
|
||||
- GEMINI_API_KEY=${GEMINI_API_KEY}
|
||||
- REDIS_URL=redis://redis:6379/0
|
||||
- WORKSPACE_ROOT=${HOME}
|
||||
volumes:
|
||||
- ${HOME}:/workspace:ro
|
||||
stdin_open: true
|
||||
tty: true
|
||||
|
||||
volumes:
|
||||
redis_data:
|
||||
EOF
|
||||
|
||||
# Create .env file
|
||||
echo "GEMINI_API_KEY=your-gemini-api-key-here" > .env
|
||||
|
||||
# Start services
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
## 🛠️ Available Tools
|
||||
|
||||
Once set up, you can use any of these tools naturally in Claude:
|
||||
|
||||
| Tool | Example Usage |
|
||||
|------|---------------|
|
||||
| **`chat`** | "Use gemini to brainstorm API design ideas" |
|
||||
| **`thinkdeep`** | "Use gemini to think deeper about this architecture" |
|
||||
| **`codereview`** | "Use gemini to review my Python code for security issues" |
|
||||
| **`debug`** | "Use gemini to debug this error: [paste stack trace]" |
|
||||
| **`analyze`** | "Use gemini to analyze my project structure" |
|
||||
| **`precommit`** | "Use gemini to validate my git changes before commit" |
|
||||
|
||||
## 📁 File Access
|
||||
|
||||
The Docker setup automatically mounts your home directory as `/workspace`. This means:
|
||||
|
||||
- ✅ Gemini can read files anywhere in your home directory
|
||||
- ✅ You can analyze entire projects: "Use gemini to analyze my ~/Projects/myapp/src/ directory"
|
||||
- ✅ Works with absolute paths: "Use gemini to review /Users/yourname/project/main.py"
|
||||
|
||||
## 🔧 Management Commands
|
||||
|
||||
### Check Status
|
||||
```bash
|
||||
# See if containers are running
|
||||
docker compose ps
|
||||
|
||||
# Should show both 'gemini-mcp-redis' and 'gemini-mcp-server' as 'Up'
|
||||
```
|
||||
|
||||
### View Logs
|
||||
```bash
|
||||
# Check MCP server logs
|
||||
docker compose logs gemini-mcp -f
|
||||
|
||||
# Check Redis logs
|
||||
docker compose logs redis -f
|
||||
|
||||
# View all logs
|
||||
docker compose logs -f
|
||||
```
|
||||
|
||||
### Update to Latest Version
|
||||
```bash
|
||||
# For cloned repository setup
|
||||
git pull origin main
|
||||
./setup-docker.sh
|
||||
|
||||
# For published image setup
|
||||
docker compose pull
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
### Stop/Start Services
|
||||
```bash
|
||||
# Stop containers (keeps data)
|
||||
docker compose stop
|
||||
|
||||
# Start containers again
|
||||
docker compose start
|
||||
|
||||
# Restart all services
|
||||
docker compose restart
|
||||
|
||||
# Stop and remove everything
|
||||
docker compose down
|
||||
|
||||
# Stop and remove everything including volumes (⚠️ deletes Redis data)
|
||||
docker compose down -v
|
||||
```
|
||||
|
||||
## 🔒 Security Notes
|
||||
|
||||
1. **API Key**: Your Gemini API key is stored in the container environment. The `.env` file is gitignored for security.
|
||||
|
||||
2. **File Access**: The container can read files in your home directory (mounted as read-only). This is necessary for file analysis.
|
||||
|
||||
3. **Network**: Redis runs on localhost:6379 but is only accessible to the MCP server container by default.
|
||||
|
||||
## 🚨 Troubleshooting
|
||||
|
||||
### "Connection failed" in Claude Desktop
|
||||
```bash
|
||||
# Check if containers are running
|
||||
docker compose ps
|
||||
|
||||
# Should show both containers as 'Up'
|
||||
# If not, check logs:
|
||||
docker compose logs gemini-mcp
|
||||
```
|
||||
|
||||
### "GEMINI_API_KEY environment variable is required"
|
||||
```bash
|
||||
# Edit your .env file
|
||||
nano .env
|
||||
# Update: GEMINI_API_KEY=your_actual_api_key
|
||||
|
||||
# Restart services
|
||||
docker compose restart
|
||||
```
|
||||
|
||||
### Containers won't start
|
||||
```bash
|
||||
# Check logs for specific errors
|
||||
docker compose logs
|
||||
|
||||
# Rebuild and restart
|
||||
docker compose down
|
||||
docker compose up --build -d
|
||||
```
|
||||
|
||||
### Tools not responding
|
||||
```bash
|
||||
# Check container resources
|
||||
docker stats
|
||||
|
||||
# Restart everything
|
||||
docker compose restart
|
||||
|
||||
# If still having issues, check Claude Desktop config
|
||||
```
|
||||
|
||||
### Permission issues (Linux)
|
||||
```bash
|
||||
# Ensure proper ownership
|
||||
sudo chown -R $USER:$USER .
|
||||
|
||||
# Make setup script executable
|
||||
chmod +x setup-docker.sh
|
||||
```
|
||||
|
||||
## 💡 How It Works (Technical Details)
|
||||
|
||||
The setup uses Docker Compose to orchestrate two services:
|
||||
|
||||
1. **Redis Container** (`gemini-mcp-redis`)
|
||||
- Official Redis 7 Alpine image
|
||||
- Automatic data persistence with Docker volume
|
||||
- Available at `redis:6379` within Docker network
|
||||
- Available at `localhost:6379` from host machine
|
||||
|
||||
2. **Gemini MCP Server** (`gemini-mcp-server`)
|
||||
- Built from local Dockerfile or pulled from GHCR
|
||||
- Automatically connects to Redis container
|
||||
- Your home directory mounted for file access
|
||||
- Configured with proper environment variables
|
||||
|
||||
**Key Benefits:**
|
||||
- 🔄 **Automatic Service Discovery**: No IP configuration needed
|
||||
- 💾 **Data Persistence**: Redis data survives container restarts
|
||||
- 🛡️ **Isolation**: Services run in isolated containers
|
||||
- 🚀 **Easy Updates**: Pull latest images with one command
|
||||
|
||||
## 🎉 What's Next?
|
||||
|
||||
Once you're set up:
|
||||
|
||||
1. **Explore the tools**: Try each tool to understand their specialties
|
||||
2. **Read the main README**: [Full documentation](../README.md) has advanced usage patterns
|
||||
3. **Join discussions**: [GitHub Discussions](https://github.com/BeehiveInnovations/gemini-mcp-server/discussions) for tips and tricks
|
||||
4. **Contribute**: Found a bug or want a feature? [Open an issue](https://github.com/BeehiveInnovations/gemini-mcp-server/issues)
|
||||
|
||||
## 💡 Pro Tips
|
||||
|
||||
1. **Conversation Threading**: Gemini remembers context across multiple interactions thanks to automatic Redis setup!
|
||||
|
||||
2. **File Analysis**: Point Gemini at entire directories: "Use gemini to analyze my entire ~/Projects/myapp for architectural improvements"
|
||||
|
||||
3. **Collaborative Workflows**: Combine tools: "Use gemini to analyze this code, then review it for security issues"
|
||||
|
||||
4. **Thinking Modes**: Control depth vs cost: "Use gemini with minimal thinking to quickly explain this function"
|
||||
|
||||
5. **Logs are your friend**: Always check `docker compose logs -f` if something seems wrong
|
||||
|
||||
---
|
||||
|
||||
**Need Help?**
|
||||
- 📖 [Full Documentation](../README.md)
|
||||
- 💬 [Community Discussions](https://github.com/BeehiveInnovations/gemini-mcp-server/discussions)
|
||||
- 🐛 [Report Issues](https://github.com/BeehiveInnovations/gemini-mcp-server/issues)
|
||||
412
docs/user-guides/troubleshooting.md
Normal file
412
docs/user-guides/troubleshooting.md
Normal file
@@ -0,0 +1,412 @@
|
||||
# Troubleshooting Guide
|
||||
|
||||
This guide helps you resolve common issues with the Gemini MCP Server.
|
||||
|
||||
## Quick Diagnostics
|
||||
|
||||
### Check System Status
|
||||
|
||||
```bash
|
||||
# Verify containers are running
|
||||
docker compose ps
|
||||
|
||||
# Check logs for errors
|
||||
docker compose logs -f
|
||||
|
||||
# Test API connectivity
|
||||
docker exec -it gemini-mcp-server python -c "import os; print('API Key set:', bool(os.getenv('GEMINI_API_KEY')))"
|
||||
```
|
||||
|
||||
## Common Issues
|
||||
|
||||
### 1. "Connection failed" in Claude Desktop
|
||||
|
||||
**Symptoms:**
|
||||
- Claude Desktop shows "Connection failed" when trying to use Gemini tools
|
||||
- MCP server appears disconnected
|
||||
|
||||
**Diagnosis:**
|
||||
```bash
|
||||
# Check if containers are running
|
||||
docker compose ps
|
||||
|
||||
# Should show both containers as 'Up'
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Containers not running:**
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
2. **Container name mismatch:**
|
||||
```bash
|
||||
# Check actual container name
|
||||
docker ps --format "{{.Names}}"
|
||||
|
||||
# Update Claude Desktop config if needed
|
||||
```
|
||||
|
||||
3. **Docker Desktop not running:**
|
||||
- Ensure Docker Desktop is started
|
||||
- Check Docker daemon status: `docker info`
|
||||
|
||||
### 2. "GEMINI_API_KEY environment variable is required"
|
||||
|
||||
**Symptoms:**
|
||||
- Server logs show API key error
|
||||
- Tools respond with authentication errors
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Check .env file:**
|
||||
```bash
|
||||
cat .env | grep GEMINI_API_KEY
|
||||
```
|
||||
|
||||
2. **Update API key:**
|
||||
```bash
|
||||
nano .env
|
||||
# Change: GEMINI_API_KEY=your_actual_api_key
|
||||
|
||||
# Restart services
|
||||
docker compose restart
|
||||
```
|
||||
|
||||
3. **Verify key is valid:**
|
||||
- Check [Google AI Studio](https://makersuite.google.com/app/apikey)
|
||||
- Ensure key has proper permissions
|
||||
|
||||
### 3. Redis Connection Issues
|
||||
|
||||
**Symptoms:**
|
||||
- Conversation threading not working
|
||||
- Error logs mention Redis connection failures
|
||||
|
||||
**Diagnosis:**
|
||||
```bash
|
||||
# Check Redis container
|
||||
docker compose ps redis
|
||||
|
||||
# Test Redis connectivity
|
||||
docker exec -it gemini-mcp-redis redis-cli ping
|
||||
# Should return: PONG
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Start Redis container:**
|
||||
```bash
|
||||
docker compose up -d redis
|
||||
```
|
||||
|
||||
2. **Reset Redis data:**
|
||||
```bash
|
||||
docker compose down
|
||||
docker volume rm gemini-mcp-server_redis_data
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
3. **Check Redis logs:**
|
||||
```bash
|
||||
docker compose logs redis
|
||||
```
|
||||
|
||||
### 4. Tools Not Responding / Hanging
|
||||
|
||||
**Symptoms:**
|
||||
- Gemini tools start but never complete
|
||||
- Long response times
|
||||
- Timeout errors
|
||||
|
||||
**Diagnosis:**
|
||||
```bash
|
||||
# Check resource usage
|
||||
docker stats
|
||||
|
||||
# Check for memory/CPU constraints
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Restart services:**
|
||||
```bash
|
||||
docker compose restart
|
||||
```
|
||||
|
||||
2. **Increase memory limits:**
|
||||
```yaml
|
||||
# In docker-compose.override.yml
|
||||
services:
|
||||
gemini-mcp:
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
memory: 4G
|
||||
```
|
||||
|
||||
3. **Check API rate limits:**
|
||||
- Verify your Gemini API quota
|
||||
- Consider using a paid API key for higher limits
|
||||
|
||||
### 5. File Access Issues
|
||||
|
||||
**Symptoms:**
|
||||
- "File not found" errors when using file paths
|
||||
- Permission denied errors
|
||||
|
||||
**Diagnosis:**
|
||||
```bash
|
||||
# Check mounted directory
|
||||
docker exec -it gemini-mcp-server ls -la /workspace
|
||||
|
||||
# Verify file permissions
|
||||
ls -la /path/to/your/file
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Use absolute paths:**
|
||||
```
|
||||
✅ /Users/yourname/project/file.py
|
||||
❌ ./file.py
|
||||
```
|
||||
|
||||
2. **Check file exists in mounted directory:**
|
||||
```bash
|
||||
# Files must be within WORKSPACE_ROOT (default: $HOME)
|
||||
echo $WORKSPACE_ROOT
|
||||
```
|
||||
|
||||
3. **Fix permissions (Linux):**
|
||||
```bash
|
||||
sudo chown -R $USER:$USER /path/to/your/files
|
||||
```
|
||||
|
||||
### 6. Port Conflicts
|
||||
|
||||
**Symptoms:**
|
||||
- "Port already in use" errors
|
||||
- Services fail to start
|
||||
|
||||
**Diagnosis:**
|
||||
```bash
|
||||
# Check what's using port 6379
|
||||
lsof -i :6379
|
||||
netstat -tulpn | grep 6379
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Stop conflicting services:**
|
||||
```bash
|
||||
# If you have local Redis running
|
||||
sudo systemctl stop redis
|
||||
# or
|
||||
brew services stop redis
|
||||
```
|
||||
|
||||
2. **Use different ports:**
|
||||
```yaml
|
||||
# In docker-compose.override.yml
|
||||
services:
|
||||
redis:
|
||||
ports:
|
||||
- "6380:6379"
|
||||
```
|
||||
|
||||
## Platform-Specific Issues
|
||||
|
||||
### Windows (WSL2)
|
||||
|
||||
**Common Issues:**
|
||||
- Docker Desktop WSL2 integration not enabled
|
||||
- File path format issues
|
||||
- Permission problems
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Enable WSL2 integration:**
|
||||
- Docker Desktop → Settings → Resources → WSL Integration
|
||||
- Enable integration for your WSL distribution
|
||||
|
||||
2. **Use WSL2 paths:**
|
||||
```bash
|
||||
# Run commands from within WSL2
|
||||
cd /mnt/c/Users/yourname/project
|
||||
./setup-docker.sh
|
||||
```
|
||||
|
||||
3. **File permissions:**
|
||||
```bash
|
||||
# In WSL2
|
||||
chmod +x setup-docker.sh
|
||||
```
|
||||
|
||||
### macOS
|
||||
|
||||
**Common Issues:**
|
||||
- Docker Desktop not allocated enough resources
|
||||
- File sharing permissions
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Increase Docker resources:**
|
||||
- Docker Desktop → Settings → Resources
|
||||
- Increase memory to at least 4GB
|
||||
|
||||
2. **File sharing:**
|
||||
- Docker Desktop → Settings → Resources → File Sharing
|
||||
- Ensure your project directory is included
|
||||
|
||||
### Linux
|
||||
|
||||
**Common Issues:**
|
||||
- Docker permission issues
|
||||
- systemd conflicts
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Docker permissions:**
|
||||
```bash
|
||||
sudo usermod -aG docker $USER
|
||||
# Log out and back in
|
||||
```
|
||||
|
||||
2. **Start Docker daemon:**
|
||||
```bash
|
||||
sudo systemctl start docker
|
||||
sudo systemctl enable docker
|
||||
```
|
||||
|
||||
## Advanced Troubleshooting
|
||||
|
||||
### Debug Mode
|
||||
|
||||
Enable detailed logging:
|
||||
|
||||
```bash
|
||||
# In .env file
|
||||
LOG_LEVEL=DEBUG
|
||||
|
||||
# Restart with verbose output
|
||||
docker compose down && docker compose up
|
||||
```
|
||||
|
||||
### Container Debugging
|
||||
|
||||
Access container for inspection:
|
||||
|
||||
```bash
|
||||
# Enter MCP server container
|
||||
docker exec -it gemini-mcp-server bash
|
||||
|
||||
# Check Python environment
|
||||
python --version
|
||||
pip list
|
||||
|
||||
# Test Gemini API directly
|
||||
python -c "
|
||||
import google.generativeai as genai
|
||||
import os
|
||||
genai.configure(api_key=os.getenv('GEMINI_API_KEY'))
|
||||
model = genai.GenerativeModel('gemini-pro')
|
||||
print('API connection test successful')
|
||||
"
|
||||
```
|
||||
|
||||
### Network Debugging
|
||||
|
||||
Check container networking:
|
||||
|
||||
```bash
|
||||
# Inspect Docker network
|
||||
docker network ls
|
||||
docker network inspect gemini-mcp-server_default
|
||||
|
||||
# Test container communication
|
||||
docker exec -it gemini-mcp-server ping redis
|
||||
```
|
||||
|
||||
### Clean Reset
|
||||
|
||||
Complete environment reset:
|
||||
|
||||
```bash
|
||||
# Stop everything
|
||||
docker compose down -v
|
||||
|
||||
# Remove images
|
||||
docker rmi $(docker images "gemini-mcp-server*" -q)
|
||||
|
||||
# Clean setup
|
||||
./setup-docker.sh
|
||||
```
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### Resource Monitoring
|
||||
|
||||
```bash
|
||||
# Monitor container resources
|
||||
docker stats
|
||||
|
||||
# Check system resources
|
||||
htop # or top
|
||||
df -h # disk space
|
||||
```
|
||||
|
||||
### Optimization Tips
|
||||
|
||||
1. **Allocate adequate memory:**
|
||||
- Minimum: 2GB for Docker Desktop
|
||||
- Recommended: 4GB+ for large projects
|
||||
|
||||
2. **Use SSD storage:**
|
||||
- Docker volumes perform better on SSDs
|
||||
|
||||
3. **Limit context size:**
|
||||
- Use specific file paths instead of entire directories
|
||||
- Utilize thinking modes to control token usage
|
||||
|
||||
## Getting Help
|
||||
|
||||
### Collect Debug Information
|
||||
|
||||
Before seeking help, collect:
|
||||
|
||||
```bash
|
||||
# System information
|
||||
docker --version
|
||||
docker compose --version
|
||||
uname -a
|
||||
|
||||
# Container status
|
||||
docker compose ps
|
||||
docker compose logs --tail=100
|
||||
|
||||
# Configuration
|
||||
cat .env | grep -v "GEMINI_API_KEY"
|
||||
```
|
||||
|
||||
### Support Channels
|
||||
|
||||
- 📖 [Documentation](../README.md)
|
||||
- 💬 [GitHub Discussions](https://github.com/BeehiveInnovations/gemini-mcp-server/discussions)
|
||||
- 🐛 [Issue Tracker](https://github.com/BeehiveInnovations/gemini-mcp-server/issues)
|
||||
|
||||
### Creating Bug Reports
|
||||
|
||||
Include in your bug report:
|
||||
1. System information (OS, Docker version)
|
||||
2. Steps to reproduce
|
||||
3. Expected vs actual behavior
|
||||
4. Relevant log output
|
||||
5. Configuration (without API keys)
|
||||
|
||||
---
|
||||
|
||||
**See Also:**
|
||||
- [Installation Guide](installation.md)
|
||||
- [Configuration Guide](configuration.md)
|
||||
Reference in New Issue
Block a user