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

up main readme

Browse Source
This commit is contained in:
Patryk Ciechanski
2025-06-11 14:51:23 +02:00
parent 4655485c2f
commit 72b419a69f
1 changed files with 49 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files

104
README.md
View File

@@ -8,6 +8,8 @@
<br/> <br/>
> **📚 [Comprehensive Documentation Available](docs/)** - This README provides quick start instructions. For detailed guides, API references, architecture documentation, and development workflows, see our [complete documentation](docs/).
The ultimate development partner for Claude - a Model Context Protocol server that gives Claude access to Google's Gemini 2.5 Pro for extended thinking, code analysis, and problem-solving. **Automatically reads files and directories, passing their contents to Gemini for analysis within its 1M token context.** The ultimate development partner for Claude - a Model Context Protocol server that gives Claude access to Google's Gemini 2.5 Pro for extended thinking, code analysis, and problem-solving. **Automatically reads files and directories, passing their contents to Gemini for analysis within its 1M token context.**
**Features true AI orchestration with conversation continuity across tool usage** - start a task with one tool, continue with another, and maintain full context throughout. Claude and Gemini can collaborate seamlessly across multiple interactions and different tools, creating a unified development experience. **Features true AI orchestration with conversation continuity across tool usage** - start a task with one tool, continue with another, and maintain full context throughout. Claude and Gemini can collaborate seamlessly across multiple interactions and different tools, creating a unified development experience.
@@ -21,6 +23,12 @@ The ultimate development partner for Claude - a Model Context Protocol server th
- [Available Tools](#available-tools) - Overview of all tools - [Available Tools](#available-tools) - Overview of all tools
- [AI-to-AI Conversations](#ai-to-ai-conversation-threading) - Multi-turn conversations - [AI-to-AI Conversations](#ai-to-ai-conversation-threading) - Multi-turn conversations
- **📚 Detailed Documentation** ([View All](docs/))
- **For Users**: [Installation](docs/user-guides/installation.md) | [Configuration](docs/user-guides/configuration.md) | [Troubleshooting](docs/user-guides/troubleshooting.md)
- **For Developers**: [Setup](docs/contributing/setup.md) | [Workflows](docs/contributing/workflows.md) | [Code Style](docs/contributing/code-style.md) | [Testing](docs/contributing/testing.md)
- **For Architects**: [System Design](docs/architecture/overview.md) | [Components](docs/architecture/components.md) | [Data Flow](docs/architecture/data-flow.md)
- **API Reference**: [MCP Protocol](docs/api/mcp-protocol.md) | [Tool APIs](docs/api/tools/)
- **Tools Reference** - **Tools Reference**
- [`chat`](#1-chat---general-development-chat--collaborative-thinking) - Collaborative thinking - [`chat`](#1-chat---general-development-chat--collaborative-thinking) - Collaborative thinking
- [`thinkdeep`](#2-thinkdeep---extended-reasoning-partner) - Extended reasoning - [`thinkdeep`](#2-thinkdeep---extended-reasoning-partner) - Extended reasoning
@@ -940,98 +948,84 @@ To modify tool behavior, you can:
## Contributing ## Contributing
We welcome contributions! The modular architecture makes it easy to add new tools: We welcome contributions! This project follows comprehensive development workflows and quality standards.
**Quick Start for Contributors:**
1. Create a new tool in `tools/` 1. Create a new tool in `tools/`
2. Inherit from `BaseTool` 2. Inherit from `BaseTool`
3. Implement required methods (including `get_system_prompt()`) 3. Implement required methods (including `get_system_prompt()`)
4. Add your system prompt to `prompts/tool_prompts.py` 4. Add your system prompt to `prompts/tool_prompts.py`
5. Register your tool in `TOOLS` dict in `server.py` 5. Register your tool in `TOOLS` dict in `server.py`
**For detailed contribution guidelines, see:**
- **[Development Setup Guide](docs/contributing/setup.md)** - Environment setup and dependencies
- **[Development Workflows](docs/contributing/workflows.md)** - Git processes, Memory Bank integration, testing workflows
- **[Code Style Guide](docs/contributing/code-style.md)** - Python standards, type hints, security practices
- **[Testing Strategy](docs/contributing/testing.md)** - TDD approach, testing frameworks, quality assurance
- **[Repository Overview](docs/contributing/file-overview.md)** - Understanding the codebase structure
See existing tools for examples. See existing tools for examples.
## Testing ## Testing
### Unit Tests (No API Key Required) The project includes comprehensive testing strategies covering unit tests, integration tests, and quality assurance.
The project includes comprehensive unit tests that use mocks and don't require a Gemini API key:
### Quick Testing
```bash ```bash
# Run all unit tests # Run all unit tests (no API key required)
python -m pytest tests/ --ignore=tests/test_live_integration.py -v python -m pytest tests/ --ignore=tests/test_live_integration.py -v
# Run with coverage # Run with coverage
python -m pytest tests/ --ignore=tests/test_live_integration.py --cov=. --cov-report=html python -m pytest tests/ --ignore=tests/test_live_integration.py --cov=. --cov-report=html
```
### Live Integration Tests (API Key Required) # Live integration tests (API key required)
To test actual API integration:
```bash
# Set your API key
export GEMINI_API_KEY=your-api-key-here export GEMINI_API_KEY=your-api-key-here
# Run live integration tests
python tests/test_live_integration.py python tests/test_live_integration.py
``` ```
### GitHub Actions CI/CD ### CI/CD Pipeline
The project includes GitHub Actions workflows that: - **✅ Unit tests** - Automated, no API key needed
- **✅ Multi-Python support** - Tests Python 3.10, 3.11, 3.12
- **✅ Code quality checks** - Linting and formatting
- **🔒 Live tests** - Optional integration verification
- **✅ Run unit tests automatically** - No API key needed, uses mocks **For comprehensive testing documentation, see:**
- **✅ Test on Python 3.10, 3.11, 3.12** - Ensures compatibility - **[Testing Strategy Guide](docs/contributing/testing.md)** - TDD methodology, test categories, quality gates
- **✅ Run linting and formatting checks** - Maintains code quality - **[Development Workflows](docs/contributing/workflows.md)** - Testing integration with git processes
- **🔒 Run live tests only if API key is available** - Optional live verification
The CI pipeline works without any secrets and will pass all tests using mocked responses. Live integration tests only run if a `GEMINI_API_KEY` secret is configured in the repository.
## Troubleshooting ## Troubleshooting
### Docker Issues ### Common Issues
**"Connection failed" in Claude Desktop** **Docker Connection Problems:**
- Ensure Docker services are running: `docker compose ps`
- Check if the container name is correct: `docker ps` to see actual container names
- Verify your .env file has the correct GEMINI_API_KEY
**"GEMINI_API_KEY environment variable is required"**
- Edit your .env file and add your API key
- Restart services: `docker compose restart`
**Container fails to start**
- Check logs: `docker compose logs gemini-mcp`
- Ensure Docker has enough resources (memory/disk space)
- Try rebuilding: `docker compose build --no-cache`
**"spawn ENOENT" or execution issues**
- Verify the container is running: `docker compose ps`
- Check that Docker Desktop is running
- On Windows: Ensure WSL2 is properly configured for Docker
**Testing your Docker setup:**
```bash ```bash
# Check if services are running # Check services status
docker compose ps docker compose ps
# Test manual connection # Verify container connectivity
docker exec -i gemini-mcp-server-gemini-mcp-1 echo "Connection test" docker exec -i gemini-mcp-server echo "Connection test"
# View logs # View logs for errors
docker compose logs -f docker compose logs -f
``` ```
**Conversation threading not working?** **Configuration Issues:**
If you're not seeing follow-up questions from Gemini: - API key not set: Check your `.env` file
- File access issues: Verify mounted directories
- Redis connectivity: Test with `docker exec -it gemini-mcp-redis redis-cli ping`
**Debug Mode:**
```bash ```bash
# Check if Redis is running # Enable detailed logging
docker compose logs redis echo "LOG_LEVEL=DEBUG" >> .env
docker compose restart
# Test conversation memory system
docker exec -i gemini-mcp-server-gemini-mcp-1 python debug_conversation.py
# Check for threading errors in logs
docker compose logs gemini-mcp | grep "threading failed"
``` ```
**For comprehensive troubleshooting, see:**
- **[Troubleshooting Guide](docs/user-guides/troubleshooting.md)** - Complete solutions for common issues
- **[Configuration Guide](docs/user-guides/configuration.md)** - Proper setup and configuration options
- **[Installation Guide](docs/user-guides/installation.md)** - Setup verification and validation
## License ## License
MIT License - see LICENSE file for details. MIT License - see LICENSE file for details.