up
This commit is contained in:
Patryk Ciechanski
380
docs/contributing/setup.md
Normal file
380
docs/contributing/setup.md
Normal 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)
|
||||
233
docs/user-guides/configuration.md
Normal file
233
docs/user-guides/configuration.md
Normal file
@@ -0,0 +1,233 @@
|
||||
# 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`
|
||||
- **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)
|
||||
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