From 4c15d2ac7b2c8290283495ba569e822a263367a0 Mon Sep 17 00:00:00 2001 From: Patryk Ciechanski Date: Wed, 11 Jun 2025 13:04:30 +0200 Subject: [PATCH] addinte templates and user guide --- .github/ISSUE_TEMPLATE/bug_report.yml | 80 ++++++ .github/ISSUE_TEMPLATE/config.yml | 11 + .github/ISSUE_TEMPLATE/documentation.yml | 67 +++++ .github/ISSUE_TEMPLATE/feature_request.yml | 51 ++++ .github/ISSUE_TEMPLATE/tool_addition.yml | 74 ++++++ .github/pull_request_template.md | 116 +++++++++ .../workflows/build_and_publish_docker.yml | 77 ++++++ .gitignore | 12 +- docs/docker-user-guide.md | 246 ++++++++++++++++++ 9 files changed, 733 insertions(+), 1 deletion(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/documentation.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/ISSUE_TEMPLATE/tool_addition.yml create mode 100644 .github/pull_request_template.md create mode 100644 .github/workflows/build_and_publish_docker.yml create mode 100644 docs/docker-user-guide.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..6142698 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,80 @@ +name: ๐Ÿž Bug Report +description: Create a report to help us improve +labels: ["bug", "needs-triage"] +body: + - type: markdown + attributes: + value: | + Thank you for taking the time to file a bug report! Please provide as much detail as possible to help us reproduce and fix the issue. + + - type: input + id: version + attributes: + label: Project Version + description: "Which version are you using? (e.g., Docker image tag like `latest` or `v1.2.3`, or a git commit SHA)" + placeholder: "e.g., ghcr.io/beehiveinnovations/gemini-mcp-server:latest" + validations: + required: true + + - type: textarea + id: description + attributes: + label: Bug Description + description: A clear and concise description of what the bug is. + placeholder: "When I run the `codereview` tool on a Python file with syntax errors, it hangs instead of reporting an error." + validations: + required: true + + - type: textarea + id: reproduction-steps + attributes: + label: Steps to Reproduce + description: "Provide the exact steps to reproduce the behavior. Include the full command you ran." + placeholder: | + 1. Create a file `test.py` with the content `def my_func(a,b)` + 2. Run the command: `docker exec -i gemini-mcp-server python server.py` + 3. Use Claude Desktop with gemini codereview tool on test.py + 4. Observe the behavior... + validations: + required: true + + - type: textarea + id: expected-behavior + attributes: + label: Expected Behavior + description: A clear and concise description of what you expected to happen. + placeholder: "I expected the tool to exit with an error message about the invalid Python syntax." + validations: + required: true + + - type: textarea + id: logs + attributes: + label: Relevant Log Output + description: "Please copy and paste any relevant log output. This will be automatically formatted into a code block." + render: shell + + - type: dropdown + id: environment + attributes: + label: Operating System + description: What operating system are you running the Docker client on? + options: + - Windows (via WSL2) + - Windows (via Docker Desktop) + - macOS (Intel) + - macOS (Apple Silicon) + - Linux + validations: + required: true + + - type: checkboxes + id: no-duplicate-issues + attributes: + label: Sanity Checks + description: "Before submitting, please confirm the following:" + options: + - label: I have searched the existing issues and this is not a duplicate. + required: true + - label: I have confirmed that my `GEMINI_API_KEY` is set correctly. + required: true \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..680e724 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,11 @@ +blank_issues_enabled: false +contact_links: + - name: ๐Ÿ’ฌ General Discussion + url: https://github.com/BeehiveInnovations/gemini-mcp-server/discussions + about: Ask questions, share ideas, or discuss usage patterns with the community + - name: ๐Ÿ“š Documentation + url: https://github.com/BeehiveInnovations/gemini-mcp-server/blob/main/README.md + about: Check the README for setup instructions and usage examples + - name: ๐Ÿค Contributing Guide + url: https://github.com/BeehiveInnovations/gemini-mcp-server/blob/main/CONTRIBUTING.md + about: Learn how to contribute to the project \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/documentation.yml b/.github/ISSUE_TEMPLATE/documentation.yml new file mode 100644 index 0000000..37359e8 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/documentation.yml @@ -0,0 +1,67 @@ +name: ๐Ÿ“– Documentation Improvement +description: Report an issue or suggest an improvement for the documentation +labels: ["documentation", "good first issue"] +body: + - type: input + id: location + attributes: + label: Documentation Location + description: "Which file or page has the issue? (e.g., README.md, CONTRIBUTING.md, CLAUDE.md)" + placeholder: "e.g., README.md" + validations: + required: true + + - type: dropdown + id: issue-type + attributes: + label: Type of Documentation Issue + description: What kind of documentation improvement is this? + options: + - Typo or grammar error + - Unclear or confusing explanation + - Outdated information + - Missing information + - Code example doesn't work + - Installation/setup instructions unclear + - Tool usage examples need improvement + - Other + validations: + required: true + + - type: textarea + id: problem + attributes: + label: What is wrong with the documentation? + description: "Please describe the problem. Be specific about what is unclear, incorrect, or missing." + placeholder: "The Docker setup command in the README is missing the `--pull=always` flag, which means users might use an outdated image version." + validations: + required: true + + - type: textarea + id: suggestion + attributes: + label: Suggested Improvement + description: "How can we make it better? If you can, please provide the exact text or changes you'd like to see." + placeholder: | + Change: + ``` + docker run ghcr.io/beehiveinnovations/gemini-mcp-server:latest + ``` + + To: + ``` + docker run --pull=always ghcr.io/beehiveinnovations/gemini-mcp-server:latest + ``` + + - type: dropdown + id: audience + attributes: + label: Target Audience + description: Which audience would benefit most from this improvement? + options: + - New users (first-time setup) + - Developers (contributing to the project) + - Advanced users (complex workflows) + - All users + validations: + required: true \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..cccde87 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,51 @@ +name: โœจ Feature Request +description: Suggest an idea for this project +labels: ["enhancement", "needs-triage"] +body: + - type: textarea + id: problem-description + attributes: + label: What problem is this feature trying to solve? + description: "A clear and concise description of the problem or user need. Why is this change needed?" + placeholder: "Currently, I can only use one Gemini tool at a time. I want to be able to chain multiple tools together (e.g., analyze -> codereview -> thinkdeep) in a single workflow." + validations: + required: true + + - type: textarea + id: proposed-solution + attributes: + label: Describe the solution you'd like + description: A clear and concise description of what you want to happen. How would it work from a user's perspective? + placeholder: "I'd like to be able to specify a workflow like 'analyze src/ then codereview the findings then use thinkdeep to suggest improvements' in a single command or configuration." + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: Describe alternatives you've considered + description: A clear and concise description of any alternative solutions or features you've considered. + placeholder: "I considered manually running each tool sequentially, but automatic workflow chaining would be more efficient and ensure context is preserved between steps." + + - type: dropdown + id: feature-type + attributes: + label: Feature Category + description: What type of enhancement is this? + options: + - New Gemini tool (chat, codereview, debug, etc.) + - Workflow improvement + - Integration enhancement + - Performance optimization + - User experience improvement + - Documentation enhancement + - Other + validations: + required: true + + - type: checkboxes + id: contribution + attributes: + label: Contribution + options: + - label: I am willing to submit a Pull Request to implement this feature. \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/tool_addition.yml b/.github/ISSUE_TEMPLATE/tool_addition.yml new file mode 100644 index 0000000..237904c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/tool_addition.yml @@ -0,0 +1,74 @@ +name: ๐Ÿ› ๏ธ New Gemini Tool Proposal +description: Propose a new Gemini MCP tool (e.g., `summarize`, `testgen`, `refactor`) +labels: ["enhancement", "new-tool"] +body: + - type: input + id: tool-name + attributes: + label: Proposed Tool Name + description: "What would the tool be called? (e.g., `summarize`, `testgen`, `refactor`)" + placeholder: "e.g., `docgen`" + validations: + required: true + + - type: textarea + id: purpose + attributes: + label: What is the primary purpose of this tool? + description: "Explain the tool's core function and the value it provides to developers using Claude + Gemini." + placeholder: "This tool will automatically generate comprehensive documentation from code, extracting class and function signatures, docstrings, and creating usage examples." + validations: + required: true + + - type: textarea + id: example-usage + attributes: + label: Example Usage in Claude Desktop + description: "Show how a user would invoke this tool through Claude and what the expected output would look like." + placeholder: | + **User prompt to Claude:** + "Use gemini to generate documentation for my entire src/ directory" + + **Expected Gemini tool behavior:** + - Analyze all Python files in src/ + - Extract classes, functions, and their docstrings + - Generate structured markdown documentation + - Include usage examples where possible + - Return organized documentation with table of contents + render: markdown + validations: + required: true + + - type: dropdown + id: tool-category + attributes: + label: Tool Category + description: What category does this tool fit into? + options: + - Code Analysis (like analyze) + - Code Quality (like codereview) + - Code Generation/Refactoring + - Documentation Generation + - Testing Support + - Debugging Support (like debug) + - Workflow Automation + - Architecture Planning (like thinkdeep) + - Other + validations: + required: true + + - type: textarea + id: system-prompt + attributes: + label: Proposed System Prompt (Optional) + description: "If you have ideas for how Gemini should be prompted for this tool, share them here." + placeholder: | + You are an expert technical documentation generator. Your task is to create comprehensive, user-friendly documentation from source code... + + - type: checkboxes + id: contribution + attributes: + label: Contribution + options: + - label: I am willing to submit a Pull Request to implement this new tool. + - label: I have checked that this tool doesn't overlap significantly with existing tools (analyze, codereview, debug, thinkdeep, chat). \ No newline at end of file diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..a0a51e2 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,116 @@ + + +## Related Issue + + + + + +Closes # + +## Type of Change + + + +- [ ] ๐Ÿž Bug fix (non-breaking change which fixes an issue) +- [ ] โœจ New feature (non-breaking change which adds functionality) +- [ ] ๐Ÿ› ๏ธ New Gemini tool (adds a new tool like `chat`, `codereview`, etc.) +- [ ] ๐Ÿ’ฅ Breaking change (fix or feature that would cause existing functionality to not work as expected) +- [ ] ๐Ÿ“– Documentation update +- [ ] ๐Ÿงน Refactor or chore (no user-facing changes) +- [ ] ๐Ÿ—๏ธ Infrastructure/CI changes + +## Description + + + +## Testing + + + +### Unit Tests (Required) +- [ ] I have added new unit tests to cover my changes +- [ ] I have run `python -m pytest tests/ --ignore=tests/test_live_integration.py -v` and all tests pass +- [ ] New tests use proper mocking and don't require API keys + +### Live Integration Tests (Recommended) +- [ ] I have tested this with a real Gemini API key using `python tests/test_live_integration.py` +- [ ] The changes work as expected with actual API calls +- [ ] I have tested this on [macOS/Linux/Windows (WSL2)] + +### Docker Testing (If Applicable) +- [ ] I have tested the Docker build: `docker build -t test-image .` +- [ ] I have tested the Docker functionality: `./setup-docker.sh` +- [ ] Docker integration works with the changes + +## Code Quality + + + +- [ ] My code follows the project's style guidelines (`black .` and `ruff check .`) +- [ ] I have run the linting tools and fixed any issues +- [ ] I have commented my code, particularly in hard-to-understand areas +- [ ] My changes generate no new warnings +- [ ] I have updated type hints where applicable + +## Documentation + + + +- [ ] I have made corresponding changes to the documentation +- [ ] I have updated the README.md if my changes affect usage +- [ ] I have updated CONTRIBUTING.md if my changes affect the development workflow +- [ ] For new tools: I have added usage examples and parameter documentation + +## Breaking Changes + + + +- [ ] This change is backwards compatible +- [ ] OR: I have documented the breaking changes and migration path below + + + +## Additional Context + + + +## Checklist for Maintainers + + + +- [ ] Code review completed +- [ ] All CI checks passing +- [ ] Breaking changes properly documented +- [ ] Version bump needed (if applicable) +- [ ] Documentation updated and accurate \ No newline at end of file diff --git a/.github/workflows/build_and_publish_docker.yml b/.github/workflows/build_and_publish_docker.yml new file mode 100644 index 0000000..9a65aa3 --- /dev/null +++ b/.github/workflows/build_and_publish_docker.yml @@ -0,0 +1,77 @@ +name: Build and Publish Docker Image to GHCR + +on: + push: + branches: [ main ] + tags: [ 'v*' ] + pull_request: + branches: [ main ] + +env: + REGISTRY: ghcr.io + IMAGE_NAME: ${{ github.repository }} + +jobs: + build-and-push: + runs-on: ubuntu-latest + permissions: + contents: read + packages: write + id-token: write + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + + - name: Log in to GitHub Container Registry + if: github.event_name != 'pull_request' + uses: docker/login-action@v3 + with: + registry: ${{ env.REGISTRY }} + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + + - name: Extract metadata (tags, labels) for Docker + id: meta + uses: docker/metadata-action@v5 + with: + images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }} + tags: | + type=ref,event=branch + type=ref,event=pr + type=ref,event=tag + type=sha,prefix={{branch}}- + type=raw,value=latest,enable={{is_default_branch}} + + - name: Build Docker image for PR + if: github.event_name == 'pull_request' + uses: docker/build-push-action@v5 + with: + context: . + push: false + tags: ${{ steps.meta.outputs.tags }} + labels: ${{ steps.meta.outputs.labels }} + cache-from: type=gha + cache-to: type=gha,mode=max + + - name: Build and push Docker image + if: github.event_name != 'pull_request' + uses: docker/build-push-action@v5 + with: + context: . + push: true + tags: ${{ steps.meta.outputs.tags }} + labels: ${{ steps.meta.outputs.labels }} + cache-from: type=gha + cache-to: type=gha,mode=max + + - name: Generate artifact attestation + if: github.event_name != 'pull_request' + uses: actions/attest-build-provenance@v1 + with: + subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME}} + subject-digest: ${{ steps.build.outputs.digest }} + push-to-registry: true \ No newline at end of file diff --git a/.gitignore b/.gitignore index ba48462..a4f611a 100644 --- a/.gitignore +++ b/.gitignore @@ -158,4 +158,14 @@ test_output/ .coverage htmlcov/ coverage.xml -.pytest_cache/ \ No newline at end of file +.pytest_cache/ + +# Additional files +run-gemini-mcp.sh +gemini-repo.md +.mcp.json +.claude +CLAUDE.md + +# Memory Bank (optional - can be committed for shared context) +memory-bank \ No newline at end of file diff --git a/docs/docker-user-guide.md b/docs/docker-user-guide.md new file mode 100644 index 0000000..1d95f9f --- /dev/null +++ b/docs/docker-user-guide.md @@ -0,0 +1,246 @@ +# ๐Ÿณ Docker User Guide: Using Gemini MCP Server + +This guide is for users who want to use the Gemini MCP Server with Claude Desktop **without cloning the repository**. You'll use the pre-built Docker image published to GitHub Container Registry. + +## ๐ŸŽฏ What You'll Get + +After following this guide, you'll have: +- โœ… Gemini MCP Server running with Claude Desktop +- โœ… Access to all Gemini tools: `chat`, `thinkdeep`, `codereview`, `debug`, `analyze`, `precommit` +- โœ… Automatic conversation threading between Claude and Gemini +- โœ… No need to manage Python dependencies or clone code + +## ๐Ÿ“‹ 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) + +### Platform Support +- โœ… **macOS** (Intel and Apple Silicon) +- โœ… **Linux** +- โœ… **Windows** (requires WSL2 for Claude Desktop) + +## ๐Ÿš€ Quick Setup (5 minutes) + +### Step 1: Start Redis (Required for AI Conversations) + +```bash +# Start Redis for conversation threading +docker run -d \ + --name gemini-redis \ + --restart unless-stopped \ + -p 6379:6379 \ + redis:latest +``` + +This creates a persistent Redis container that will survive system restarts. + +### Step 2: Start Gemini MCP Server + +```bash +# Create and start the MCP server +docker run -d \ + --name gemini-mcp-server \ + --restart unless-stopped \ + --network host \ + -e GEMINI_API_KEY="your-gemini-api-key-here" \ + -e REDIS_URL="redis://localhost:6379/0" \ + -v "$(pwd):/workspace" \ + ghcr.io/beehiveinnovations/gemini-mcp-server:latest +``` + +**Replace `your-gemini-api-key-here` with your actual API key.** + +**Command explained:** +- `-d`: Run in background +- `--restart unless-stopped`: Auto-restart container +- `--network host`: Connect to your local Redis +- `-e`: Set environment variables +- `-v "$(pwd):/workspace"`: Mount current directory for file access +- `ghcr.io/beehiveinnovations/gemini-mcp-server:latest`: The published image + +### Step 3: Configure Claude Desktop + +Find your Claude Desktop config file: +- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` +- **Windows (WSL)**: `/mnt/c/Users/USERNAME/AppData/Roaming/Claude/claude_desktop_config.json` + +Add this configuration: + +```json +{ + "mcpServers": { + "gemini": { + "command": "docker", + "args": [ + "exec", + "-i", + "gemini-mcp-server", + "python", + "server.py" + ] + } + } +} +``` + +### Step 4: Restart Claude Desktop + +Completely quit and restart Claude Desktop for changes to take effect. + +### Step 5: Test It Works + +Open Claude Desktop and try: +``` +"Use gemini to chat about Python best practices" +``` + +You should see Gemini respond through Claude! + +## ๐Ÿ› ๏ธ 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 current directory as `/workspace`. This means: + +- โœ… Gemini can read files in your current directory and subdirectories +- โœ… You can analyze entire projects: "Use gemini to analyze my src/ directory" +- โœ… Works with relative paths: "Use gemini to review ./main.py" + +## ๐Ÿ”ง Management Commands + +### Check Status +```bash +# See if containers are running +docker ps + +# Should show both 'gemini-redis' and 'gemini-mcp-server' +``` + +### View Logs +```bash +# Check MCP server logs +docker logs gemini-mcp-server + +# Follow logs in real-time +docker logs -f gemini-mcp-server +``` + +### Update to Latest Version +```bash +# Stop current container +docker stop gemini-mcp-server +docker rm gemini-mcp-server + +# Pull latest image and restart (repeat Step 2) +docker pull ghcr.io/beehiveinnovations/gemini-mcp-server:latest +# Then run the docker run command from Step 2 +``` + +### Stop Everything +```bash +# Stop containers (keeps Redis data) +docker stop gemini-mcp-server gemini-redis + +# Or remove everything completely +docker stop gemini-mcp-server gemini-redis +docker rm gemini-mcp-server gemini-redis +``` + +## ๐Ÿ”’ Security Notes + +1. **API Key**: Your Gemini API key is stored in the Docker container environment. Use a dedicated key for this purpose. + +2. **File Access**: The container can read files in your mounted directory. Don't mount sensitive directories unnecessarily. + +3. **Network**: The container uses host networking to connect to Redis. This is safe for local development. + +## ๐Ÿšจ Troubleshooting + +### "Connection failed" in Claude Desktop +```bash +# Check if containers are running +docker ps + +# Restart MCP server if needed +docker restart gemini-mcp-server + +# Check logs for errors +docker logs gemini-mcp-server +``` + +### "GEMINI_API_KEY environment variable is required" +```bash +# Stop and recreate container with correct API key +docker stop gemini-mcp-server +docker rm gemini-mcp-server +# Then run Step 2 again with the correct API key +``` + +### "Redis connection failed" +```bash +# Check if Redis is running +docker ps | grep redis + +# Start Redis if stopped +docker start gemini-redis + +# Or recreate Redis +docker rm -f gemini-redis +# Then run Step 1 again +``` + +### Tools not responding / hanging +```bash +# Check for resource constraints +docker stats + +# Restart everything +docker restart gemini-redis gemini-mcp-server +``` + +### Windows WSL2 Issues +- Ensure Docker Desktop is set to use WSL2 backend +- Run commands from within WSL2, not Windows Command Prompt +- Use WSL2 paths for file mounting + +## ๐ŸŽ‰ 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 - you can have extended conversations! + +2. **File Analysis**: Point Gemini at entire directories: "Use gemini to analyze my entire project 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. **Web Search**: Enable web search for current info: "Use gemini to debug this React error with web search enabled" + +--- + +**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) \ No newline at end of file