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
@@ -1,18 +0,0 @@
|
||||
{
|
||||
"permissions": {
|
||||
"allow": [
|
||||
"mcp__gemini__review_code",
|
||||
"mcp__gemini__chat",
|
||||
"mcp__gemini__analyze",
|
||||
"Bash(find:*)",
|
||||
"mcp__gemini__review_changes",
|
||||
"Bash(python test_resolve.py:*)",
|
||||
"Bash(python3:*)",
|
||||
"Bash(cat:*)",
|
||||
"Bash(grep:*)",
|
||||
"Bash(source:*)",
|
||||
"Bash(rm:*)"
|
||||
],
|
||||
"deny": []
|
||||
}
|
||||
}
|
||||
80
.github/ISSUE_TEMPLATE/bug_report.yml
vendored
Normal file
80
.github/ISSUE_TEMPLATE/bug_report.yml
vendored
Normal file
@@ -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
|
||||
11
.github/ISSUE_TEMPLATE/config.yml
vendored
Normal file
11
.github/ISSUE_TEMPLATE/config.yml
vendored
Normal file
@@ -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
|
||||
67
.github/ISSUE_TEMPLATE/documentation.yml
vendored
Normal file
67
.github/ISSUE_TEMPLATE/documentation.yml
vendored
Normal file
@@ -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
|
||||
51
.github/ISSUE_TEMPLATE/feature_request.yml
vendored
Normal file
51
.github/ISSUE_TEMPLATE/feature_request.yml
vendored
Normal file
@@ -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.
|
||||
74
.github/ISSUE_TEMPLATE/tool_addition.yml
vendored
Normal file
74
.github/ISSUE_TEMPLATE/tool_addition.yml
vendored
Normal file
@@ -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).
|
||||
60
.github/pull_request_template.md
vendored
Normal file
60
.github/pull_request_template.md
vendored
Normal file
@@ -0,0 +1,60 @@
|
||||
## PR Title Format
|
||||
|
||||
**Please ensure your PR title follows one of these formats:**
|
||||
|
||||
### Version Bumping Prefixes (trigger Docker build + version bump):
|
||||
- `feat: <description>` - New features (triggers MINOR version bump)
|
||||
- `fix: <description>` - Bug fixes (triggers PATCH version bump)
|
||||
- `breaking: <description>` or `BREAKING CHANGE: <description>` - Breaking changes (triggers MAJOR version bump)
|
||||
- `perf: <description>` - Performance improvements (triggers PATCH version bump)
|
||||
- `refactor: <description>` - Code refactoring (triggers PATCH version bump)
|
||||
|
||||
### Non-Version Prefixes (no version bump):
|
||||
- `docs: <description>` - Documentation only
|
||||
- `chore: <description>` - Maintenance tasks
|
||||
- `test: <description>` - Test additions/changes
|
||||
- `ci: <description>` - CI/CD changes
|
||||
- `style: <description>` - Code style changes
|
||||
|
||||
### Docker Build Options:
|
||||
- `docker: <description>` - Force Docker build without version bump
|
||||
- `docs+docker: <description>` - Documentation + Docker build
|
||||
- `chore+docker: <description>` - Maintenance + Docker build
|
||||
- `test+docker: <description>` - Tests + Docker build
|
||||
- `ci+docker: <description>` - CI changes + Docker build
|
||||
- `style+docker: <description>` - Style changes + Docker build
|
||||
|
||||
## Description
|
||||
|
||||
Please provide a clear and concise description of what this PR does.
|
||||
|
||||
## Changes Made
|
||||
|
||||
- [ ] List the specific changes made
|
||||
- [ ] Include any breaking changes
|
||||
- [ ] Note any dependencies added/removed
|
||||
|
||||
## Testing
|
||||
|
||||
- [ ] Unit tests pass
|
||||
- [ ] Integration tests pass (if applicable)
|
||||
- [ ] Manual testing completed
|
||||
- [ ] Documentation updated (if needed)
|
||||
|
||||
## Related Issues
|
||||
|
||||
Fixes #(issue number)
|
||||
|
||||
## Checklist
|
||||
|
||||
- [ ] PR title follows the format guidelines above
|
||||
- [ ] Code follows the project's style guidelines
|
||||
- [ ] Self-review completed
|
||||
- [ ] Tests added/updated as needed
|
||||
- [ ] Documentation updated as needed
|
||||
- [ ] All tests passing
|
||||
- [ ] Ready for review
|
||||
|
||||
## Additional Notes
|
||||
|
||||
Any additional information that reviewers should know.
|
||||
247
.github/workflows/auto-version.yml
vendored
Normal file
247
.github/workflows/auto-version.yml
vendored
Normal file
@@ -0,0 +1,247 @@
|
||||
name: Auto Version
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
types: [closed]
|
||||
branches: [main]
|
||||
|
||||
jobs:
|
||||
version:
|
||||
# Only run if PR was merged (not just closed)
|
||||
if: github.event.pull_request.merged == true
|
||||
runs-on: ubuntu-latest
|
||||
permissions:
|
||||
contents: write
|
||||
pull-requests: read
|
||||
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 0
|
||||
token: ${{ secrets.GITHUB_TOKEN }}
|
||||
|
||||
- name: Setup Python
|
||||
uses: actions/setup-python@v4
|
||||
with:
|
||||
python-version: '3.9'
|
||||
|
||||
- name: Configure git
|
||||
run: |
|
||||
git config user.name "github-actions[bot]"
|
||||
git config user.email "github-actions[bot]@users.noreply.github.com"
|
||||
|
||||
- name: Determine version bump type
|
||||
id: bump_type
|
||||
run: |
|
||||
PR_TITLE="${{ github.event.pull_request.title }}"
|
||||
echo "PR Title: $PR_TITLE"
|
||||
|
||||
# Convert to lowercase for case-insensitive matching
|
||||
PR_TITLE_LOWER=$(echo "$PR_TITLE" | tr '[:upper:]' '[:lower:]')
|
||||
|
||||
# Determine bump type based on PR title prefix
|
||||
if [[ "$PR_TITLE_LOWER" =~ ^(breaking|breaking[[:space:]]change): ]]; then
|
||||
echo "Detected BREAKING CHANGE - major version bump"
|
||||
echo "bump_type=major" >> $GITHUB_OUTPUT
|
||||
echo "should_bump=true" >> $GITHUB_OUTPUT
|
||||
echo "should_build_docker=true" >> $GITHUB_OUTPUT
|
||||
elif [[ "$PR_TITLE_LOWER" =~ ^feat: ]]; then
|
||||
echo "Detected new feature - minor version bump"
|
||||
echo "bump_type=minor" >> $GITHUB_OUTPUT
|
||||
echo "should_bump=true" >> $GITHUB_OUTPUT
|
||||
echo "should_build_docker=true" >> $GITHUB_OUTPUT
|
||||
elif [[ "$PR_TITLE_LOWER" =~ ^(fix|perf|refactor): ]]; then
|
||||
echo "Detected fix/perf/refactor - patch version bump"
|
||||
echo "bump_type=patch" >> $GITHUB_OUTPUT
|
||||
echo "should_bump=true" >> $GITHUB_OUTPUT
|
||||
echo "should_build_docker=true" >> $GITHUB_OUTPUT
|
||||
elif [[ "$PR_TITLE_LOWER" =~ ^docker: ]]; then
|
||||
echo "Detected docker build request - no version bump but build Docker"
|
||||
echo "bump_type=none" >> $GITHUB_OUTPUT
|
||||
echo "should_bump=false" >> $GITHUB_OUTPUT
|
||||
echo "should_build_docker=true" >> $GITHUB_OUTPUT
|
||||
elif [[ "$PR_TITLE_LOWER" =~ ^(docs|chore|test|ci|style)\+docker: ]]; then
|
||||
echo "Detected non-versioned change with Docker build request"
|
||||
echo "bump_type=none" >> $GITHUB_OUTPUT
|
||||
echo "should_bump=false" >> $GITHUB_OUTPUT
|
||||
echo "should_build_docker=true" >> $GITHUB_OUTPUT
|
||||
elif [[ "$PR_TITLE_LOWER" =~ ^(docs|chore|test|ci|style): ]]; then
|
||||
echo "Detected non-versioned change - no version bump"
|
||||
echo "bump_type=none" >> $GITHUB_OUTPUT
|
||||
echo "should_bump=false" >> $GITHUB_OUTPUT
|
||||
echo "should_build_docker=false" >> $GITHUB_OUTPUT
|
||||
else
|
||||
echo "No recognized prefix - no version bump"
|
||||
echo "bump_type=none" >> $GITHUB_OUTPUT
|
||||
echo "should_bump=false" >> $GITHUB_OUTPUT
|
||||
echo "should_build_docker=false" >> $GITHUB_OUTPUT
|
||||
fi
|
||||
|
||||
- name: Get current version
|
||||
if: steps.bump_type.outputs.should_bump == 'true'
|
||||
id: current_version
|
||||
run: |
|
||||
CURRENT_VERSION=$(python -c "from config import __version__; print(__version__)")
|
||||
echo "Current version: $CURRENT_VERSION"
|
||||
echo "version=$CURRENT_VERSION" >> $GITHUB_OUTPUT
|
||||
|
||||
- name: Bump version
|
||||
if: steps.bump_type.outputs.should_bump == 'true'
|
||||
id: new_version
|
||||
run: |
|
||||
python scripts/bump_version.py ${{ steps.bump_type.outputs.bump_type }}
|
||||
NEW_VERSION=$(python -c "from config import __version__; print(__version__)")
|
||||
echo "New version: $NEW_VERSION"
|
||||
echo "version=$NEW_VERSION" >> $GITHUB_OUTPUT
|
||||
|
||||
- name: Commit version change
|
||||
if: steps.bump_type.outputs.should_bump == 'true'
|
||||
run: |
|
||||
git add config.py
|
||||
git commit -m "chore: bump version to ${{ steps.new_version.outputs.version }}
|
||||
|
||||
Automated version bump from PR #${{ github.event.pull_request.number }}
|
||||
${{ github.event.pull_request.title }}
|
||||
|
||||
Co-authored-by: ${{ github.event.pull_request.user.login }} <${{ github.event.pull_request.user.id }}+${{ github.event.pull_request.user.login }}@users.noreply.github.com>"
|
||||
git push
|
||||
|
||||
- name: Create git tag
|
||||
if: steps.bump_type.outputs.should_bump == 'true'
|
||||
run: |
|
||||
git tag -a "v${{ steps.new_version.outputs.version }}" -m "Release v${{ steps.new_version.outputs.version }}
|
||||
|
||||
Changes in this release:
|
||||
- ${{ github.event.pull_request.title }}
|
||||
|
||||
PR: #${{ github.event.pull_request.number }}
|
||||
Author: @${{ github.event.pull_request.user.login }}"
|
||||
git push origin "v${{ steps.new_version.outputs.version }}"
|
||||
|
||||
- name: Generate release notes
|
||||
if: steps.bump_type.outputs.should_bump == 'true'
|
||||
id: release_notes
|
||||
run: |
|
||||
# Extract PR body for release notes
|
||||
PR_BODY=$(cat << 'EOF'
|
||||
${{ github.event.pull_request.body }}
|
||||
EOF
|
||||
)
|
||||
|
||||
# Create release notes
|
||||
RELEASE_NOTES=$(cat << EOF
|
||||
## What's Changed
|
||||
|
||||
${{ github.event.pull_request.title }} by @${{ github.event.pull_request.user.login }} in #${{ github.event.pull_request.number }}
|
||||
|
||||
### Details
|
||||
|
||||
$PR_BODY
|
||||
|
||||
### Version Info
|
||||
- Previous version: ${{ steps.current_version.outputs.version }}
|
||||
- New version: ${{ steps.new_version.outputs.version }}
|
||||
- Bump type: ${{ steps.bump_type.outputs.bump_type }}
|
||||
|
||||
**Full Changelog**: https://github.com/${{ github.repository }}/compare/v${{ steps.current_version.outputs.version }}...v${{ steps.new_version.outputs.version }}
|
||||
EOF
|
||||
)
|
||||
|
||||
# Save to file for GitHub release
|
||||
echo "$RELEASE_NOTES" > release_notes.md
|
||||
|
||||
- name: Create GitHub release
|
||||
if: steps.bump_type.outputs.should_bump == 'true'
|
||||
uses: softprops/action-gh-release@v1
|
||||
with:
|
||||
tag_name: v${{ steps.new_version.outputs.version }}
|
||||
name: Release v${{ steps.new_version.outputs.version }}
|
||||
body_path: release_notes.md
|
||||
draft: false
|
||||
prerelease: false
|
||||
generate_release_notes: true
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
|
||||
- name: Trigger Docker build
|
||||
if: steps.bump_type.outputs.should_build_docker == 'true'
|
||||
run: |
|
||||
echo "🐳 Triggering Docker build and publish workflow"
|
||||
# The Docker workflow will be triggered by the tag creation (if version bumped)
|
||||
# or by repository_dispatch (if docker: prefix without version bump)
|
||||
if [ "${{ steps.bump_type.outputs.should_bump }}" == "false" ]; then
|
||||
# For docker: prefix without version bump, trigger via repository_dispatch
|
||||
curl -X POST \
|
||||
-H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" \
|
||||
-H "Accept: application/vnd.github.v3+json" \
|
||||
"https://api.github.com/repos/${{ github.repository }}/dispatches" \
|
||||
-d '{"event_type":"docker-build","client_payload":{"pr_number":"${{ github.event.pull_request.number }}","pr_title":"${{ github.event.pull_request.title }}","commit_sha":"${{ github.sha }}"}}'
|
||||
|
||||
# Add comment to PR about Docker build
|
||||
COMMENT_BODY="🐳 **Docker Image Build Triggered**
|
||||
|
||||
This PR triggered a Docker image build because of the \`+docker\` suffix in the title.
|
||||
|
||||
**Expected Image Tags:**
|
||||
- \`ghcr.io/${{ github.repository_owner }}/gemini-mcp-server:pr-${{ github.event.pull_request.number }}\`
|
||||
- \`ghcr.io/${{ github.repository_owner }}/gemini-mcp-server:main-${{ github.sha }}\`
|
||||
|
||||
**To test the image after build completes:**
|
||||
\`\`\`bash
|
||||
docker pull ghcr.io/${{ github.repository_owner }}/gemini-mcp-server:pr-${{ github.event.pull_request.number }}
|
||||
\`\`\`
|
||||
|
||||
**Claude Desktop config for testing:**
|
||||
\`\`\`json
|
||||
{
|
||||
\"mcpServers\": {
|
||||
\"gemini\": {
|
||||
\"command\": \"docker\",
|
||||
\"args\": [
|
||||
\"run\", \"--rm\", \"-i\",
|
||||
\"-e\", \"GEMINI_API_KEY\",
|
||||
\"ghcr.io/${{ github.repository_owner }}/gemini-mcp-server:pr-${{ github.event.pull_request.number }}\"
|
||||
],
|
||||
\"env\": {
|
||||
\"GEMINI_API_KEY\": \"your-api-key-here\"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
View the build progress in the [Actions tab](https://github.com/${{ github.repository }}/actions)."
|
||||
|
||||
curl -X POST \
|
||||
-H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" \
|
||||
-H "Accept: application/vnd.github.v3+json" \
|
||||
"https://api.github.com/repos/${{ github.repository }}/issues/${{ github.event.pull_request.number }}/comments" \
|
||||
-d "{\"body\":\"$COMMENT_BODY\"}"
|
||||
fi
|
||||
|
||||
- name: Summary
|
||||
run: |
|
||||
if [ "${{ steps.bump_type.outputs.should_bump }}" == "true" ]; then
|
||||
echo "### ✅ Version Bumped Successfully" >> $GITHUB_STEP_SUMMARY
|
||||
echo "" >> $GITHUB_STEP_SUMMARY
|
||||
echo "- **Previous version**: ${{ steps.current_version.outputs.version }}" >> $GITHUB_STEP_SUMMARY
|
||||
echo "- **New version**: ${{ steps.new_version.outputs.version }}" >> $GITHUB_STEP_SUMMARY
|
||||
echo "- **Bump type**: ${{ steps.bump_type.outputs.bump_type }}" >> $GITHUB_STEP_SUMMARY
|
||||
echo "- **Tag**: v${{ steps.new_version.outputs.version }}" >> $GITHUB_STEP_SUMMARY
|
||||
echo "- **PR**: #${{ github.event.pull_request.number }}" >> $GITHUB_STEP_SUMMARY
|
||||
echo "- **Docker**: Will build and publish with new tag" >> $GITHUB_STEP_SUMMARY
|
||||
elif [ "${{ steps.bump_type.outputs.should_build_docker }}" == "true" ]; then
|
||||
echo "### 🐳 Docker Build Requested" >> $GITHUB_STEP_SUMMARY
|
||||
echo "" >> $GITHUB_STEP_SUMMARY
|
||||
echo "No version bump but Docker image will be built and published." >> $GITHUB_STEP_SUMMARY
|
||||
echo "- **PR**: #${{ github.event.pull_request.number }}" >> $GITHUB_STEP_SUMMARY
|
||||
echo "- **Title**: ${{ github.event.pull_request.title }}" >> $GITHUB_STEP_SUMMARY
|
||||
echo "- **Docker tag**: Based on commit SHA" >> $GITHUB_STEP_SUMMARY
|
||||
else
|
||||
echo "### ℹ️ No Version Bump Required" >> $GITHUB_STEP_SUMMARY
|
||||
echo "" >> $GITHUB_STEP_SUMMARY
|
||||
echo "PR title prefix did not require a version bump." >> $GITHUB_STEP_SUMMARY
|
||||
echo "- **PR**: #${{ github.event.pull_request.number }}" >> $GITHUB_STEP_SUMMARY
|
||||
echo "- **Title**: ${{ github.event.pull_request.title }}" >> $GITHUB_STEP_SUMMARY
|
||||
fi
|
||||
177
.github/workflows/build_and_publish_docker.yml
vendored
Normal file
177
.github/workflows/build_and_publish_docker.yml
vendored
Normal file
@@ -0,0 +1,177 @@
|
||||
name: Build and Publish Docker Image to GHCR
|
||||
|
||||
on:
|
||||
push:
|
||||
tags: [ 'v*' ]
|
||||
repository_dispatch:
|
||||
types: [docker-build]
|
||||
|
||||
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
|
||||
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=tag
|
||||
type=raw,value=latest,enable={{is_default_branch}}
|
||||
type=sha,prefix=main-,enable=${{ github.event_name == 'repository_dispatch' }}
|
||||
type=raw,value=pr-${{ github.event.client_payload.pr_number }},enable=${{ github.event_name == 'repository_dispatch' && github.event.client_payload.pr_number != '' }}
|
||||
|
||||
- name: Build and push Docker image
|
||||
id: build
|
||||
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
|
||||
uses: actions/attest-build-provenance@v1
|
||||
with:
|
||||
subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME}}
|
||||
subject-digest: ${{ steps.build.outputs.digest }}
|
||||
push-to-registry: true
|
||||
|
||||
- name: Generate usage instructions
|
||||
run: |
|
||||
echo "## 🐳 Docker Image Published Successfully!" >> $GITHUB_STEP_SUMMARY
|
||||
echo "" >> $GITHUB_STEP_SUMMARY
|
||||
echo "**Image Registry:** GitHub Container Registry (GHCR)" >> $GITHUB_STEP_SUMMARY
|
||||
echo "**Built Tags:** ${{ steps.meta.outputs.tags }}" >> $GITHUB_STEP_SUMMARY
|
||||
echo "" >> $GITHUB_STEP_SUMMARY
|
||||
|
||||
# Extract the first tag for the main pull command
|
||||
MAIN_TAG=$(echo "${{ steps.meta.outputs.tags }}" | head -n1)
|
||||
|
||||
echo "### 📥 Pull the Image" >> $GITHUB_STEP_SUMMARY
|
||||
echo "\`\`\`bash" >> $GITHUB_STEP_SUMMARY
|
||||
echo "docker pull $MAIN_TAG" >> $GITHUB_STEP_SUMMARY
|
||||
echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
|
||||
echo "" >> $GITHUB_STEP_SUMMARY
|
||||
|
||||
echo "### ⚙️ Claude Desktop Configuration" >> $GITHUB_STEP_SUMMARY
|
||||
echo "\`\`\`json" >> $GITHUB_STEP_SUMMARY
|
||||
echo "{" >> $GITHUB_STEP_SUMMARY
|
||||
echo " \"mcpServers\": {" >> $GITHUB_STEP_SUMMARY
|
||||
echo " \"gemini\": {" >> $GITHUB_STEP_SUMMARY
|
||||
echo " \"command\": \"docker\"," >> $GITHUB_STEP_SUMMARY
|
||||
echo " \"args\": [" >> $GITHUB_STEP_SUMMARY
|
||||
echo " \"run\", \"--rm\", \"-i\"," >> $GITHUB_STEP_SUMMARY
|
||||
echo " \"-e\", \"GEMINI_API_KEY\"," >> $GITHUB_STEP_SUMMARY
|
||||
echo " \"$MAIN_TAG\"" >> $GITHUB_STEP_SUMMARY
|
||||
echo " ]," >> $GITHUB_STEP_SUMMARY
|
||||
echo " \"env\": {" >> $GITHUB_STEP_SUMMARY
|
||||
echo " \"GEMINI_API_KEY\": \"your-gemini-api-key-here\"" >> $GITHUB_STEP_SUMMARY
|
||||
echo " }" >> $GITHUB_STEP_SUMMARY
|
||||
echo " }" >> $GITHUB_STEP_SUMMARY
|
||||
echo " }" >> $GITHUB_STEP_SUMMARY
|
||||
echo "}" >> $GITHUB_STEP_SUMMARY
|
||||
echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
|
||||
echo "" >> $GITHUB_STEP_SUMMARY
|
||||
|
||||
echo "### 🏷️ All Available Tags" >> $GITHUB_STEP_SUMMARY
|
||||
echo "Built and pushed the following tags:" >> $GITHUB_STEP_SUMMARY
|
||||
echo "${{ steps.meta.outputs.tags }}" | sed 's/^/- `/' | sed 's/$/`/' >> $GITHUB_STEP_SUMMARY
|
||||
echo "" >> $GITHUB_STEP_SUMMARY
|
||||
|
||||
if [[ "${{ github.event_name }}" == "repository_dispatch" ]]; then
|
||||
echo "**Note:** This is a development build triggered by PR #${{ github.event.client_payload.pr_number }}" >> $GITHUB_STEP_SUMMARY
|
||||
echo "Use this image for testing the changes from that PR." >> $GITHUB_STEP_SUMMARY
|
||||
elif [[ "${{ github.ref_type }}" == "tag" ]]; then
|
||||
echo "**Note:** This is a release build from tag ${{ github.ref_name }}" >> $GITHUB_STEP_SUMMARY
|
||||
echo "This image represents a stable release version." >> $GITHUB_STEP_SUMMARY
|
||||
fi
|
||||
|
||||
echo "" >> $GITHUB_STEP_SUMMARY
|
||||
echo "### 📦 View in GitHub Container Registry" >> $GITHUB_STEP_SUMMARY
|
||||
echo "[View all versions and tags →](https://github.com/${{ github.repository }}/pkgs/container/gemini-mcp-server)" >> $GITHUB_STEP_SUMMARY
|
||||
|
||||
- name: Update README with latest image info
|
||||
if: github.ref_type == 'tag' || github.event_name == 'repository_dispatch'
|
||||
run: |
|
||||
# Extract the primary image tag for updating README
|
||||
if [[ "${{ github.ref_type }}" == "tag" ]]; then
|
||||
# For tag releases, use the version tag
|
||||
LATEST_TAG="${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.ref_name }}"
|
||||
UPDATE_TYPE="release"
|
||||
else
|
||||
# For repository_dispatch (PR builds), use the PR tag
|
||||
LATEST_TAG="${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:pr-${{ github.event.client_payload.pr_number }}"
|
||||
UPDATE_TYPE="development"
|
||||
fi
|
||||
|
||||
echo "Updating README.md with latest Docker image: $LATEST_TAG"
|
||||
|
||||
# Update README.md with the latest image tag
|
||||
sed -i.bak "s|ghcr\.io/${{ github.repository_owner }}/gemini-mcp-server:[a-zA-Z0-9\._-]*|$LATEST_TAG|g" README.md
|
||||
|
||||
# Also update docs/user-guides/installation.md
|
||||
sed -i.bak "s|ghcr\.io/${{ github.repository_owner }}/gemini-mcp-server:[a-zA-Z0-9\._-]*|$LATEST_TAG|g" docs/user-guides/installation.md
|
||||
|
||||
# Also update docs/user-guides/configuration.md
|
||||
sed -i.bak "s|ghcr\.io/${{ github.repository_owner }}/gemini-mcp-server:[a-zA-Z0-9\._-]*|$LATEST_TAG|g" docs/user-guides/configuration.md
|
||||
|
||||
# Check if there are any changes
|
||||
if git diff --quiet README.md docs/user-guides/installation.md docs/user-guides/configuration.md; then
|
||||
echo "No changes needed in documentation"
|
||||
else
|
||||
echo "Documentation updated with new image tag"
|
||||
|
||||
# Configure git for automated commit
|
||||
git config user.name "github-actions[bot]"
|
||||
git config user.email "github-actions[bot]@users.noreply.github.com"
|
||||
|
||||
# Add and commit changes
|
||||
git add README.md docs/user-guides/installation.md docs/user-guides/configuration.md
|
||||
|
||||
if [[ "$UPDATE_TYPE" == "release" ]]; then
|
||||
git commit -m "docs: Update Docker image references to ${{ github.ref_name }}
|
||||
|
||||
Automated update after Docker image publish for release ${{ github.ref_name }}.
|
||||
All documentation now references the latest stable image.
|
||||
|
||||
🤖 Automated by GitHub Actions"
|
||||
else
|
||||
git commit -m "docs: Update Docker image references for PR #${{ github.event.client_payload.pr_number }}
|
||||
|
||||
Automated update after Docker image publish for development build.
|
||||
Documentation updated to reference the latest development image.
|
||||
|
||||
🤖 Automated by GitHub Actions"
|
||||
fi
|
||||
|
||||
# Push changes back to the repository
|
||||
git push
|
||||
|
||||
echo "### 📝 Documentation Updated" >> $GITHUB_STEP_SUMMARY
|
||||
echo "README.md and user guides have been automatically updated with the new Docker image tag: \`$LATEST_TAG\`" >> $GITHUB_STEP_SUMMARY
|
||||
fi
|
||||
31
.github/workflows/docker-test.yml
vendored
Normal file
31
.github/workflows/docker-test.yml
vendored
Normal file
@@ -0,0 +1,31 @@
|
||||
name: Docker Build Test
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
branches: [ main ]
|
||||
|
||||
jobs:
|
||||
docker-build-test:
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Set up Docker Buildx
|
||||
uses: docker/setup-buildx-action@v3
|
||||
|
||||
- name: Test Docker build
|
||||
uses: docker/build-push-action@v5
|
||||
with:
|
||||
context: .
|
||||
push: false
|
||||
tags: test:latest
|
||||
cache-from: type=gha
|
||||
cache-to: type=gha,mode=max
|
||||
|
||||
- name: Build test summary
|
||||
run: |
|
||||
echo "### ✅ Docker Build Test Passed" >> $GITHUB_STEP_SUMMARY
|
||||
echo "" >> $GITHUB_STEP_SUMMARY
|
||||
echo "Docker image builds successfully and is ready for production." >> $GITHUB_STEP_SUMMARY
|
||||
13
.gitignore
vendored
13
.gitignore
vendored
@@ -160,6 +160,19 @@ htmlcov/
|
||||
coverage.xml
|
||||
.pytest_cache/
|
||||
|
||||
# Additional files
|
||||
run-gemini-mcp.sh
|
||||
gemini-repo.md
|
||||
.mcp.json
|
||||
.claude
|
||||
|
||||
# Memory Bank (optional - can be committed for shared context)
|
||||
memory-bank/
|
||||
|
||||
# Claude local settings
|
||||
@.claude/
|
||||
@memory-bank/
|
||||
CLAUDE.md
|
||||
# Test simulation artifacts (dynamically created during testing)
|
||||
test_simulation_files/.claude/
|
||||
|
||||
|
||||
200
CONTRIBUTING.md
Normal file
200
CONTRIBUTING.md
Normal file
@@ -0,0 +1,200 @@
|
||||
# Contributing to Gemini MCP Server
|
||||
|
||||
Thank you for your interest in contributing! This guide explains how to set up the development environment and contribute to the project.
|
||||
|
||||
## Development Setup
|
||||
|
||||
1. **Clone the repository**
|
||||
```bash
|
||||
git clone https://github.com/BeehiveInnovations/gemini-mcp-server.git
|
||||
cd gemini-mcp-server
|
||||
```
|
||||
|
||||
2. **Create virtual environment**
|
||||
```bash
|
||||
python -m venv venv
|
||||
source venv/bin/activate # On Windows: venv\Scripts\activate
|
||||
```
|
||||
|
||||
3. **Install dependencies**
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### Two Types of Tests
|
||||
|
||||
#### 1. Unit Tests (Mandatory - No API Key Required)
|
||||
- **Location**: `tests/test_*.py` (except `test_live_integration.py`)
|
||||
- **Purpose**: Test logic, mocking, and functionality without API calls
|
||||
- **Run with**: `python -m pytest tests/ --ignore=tests/test_live_integration.py -v`
|
||||
- **GitHub Actions**: ✅ Always runs
|
||||
- **Coverage**: Measures code coverage
|
||||
|
||||
#### 2. Live Integration Tests (Optional - API Key Required)
|
||||
- **Location**: `tests/test_live_integration.py`
|
||||
- **Purpose**: Verify actual API integration works
|
||||
- **Run with**: `python tests/test_live_integration.py` (requires `GEMINI_API_KEY`)
|
||||
- **GitHub Actions**: 🔒 Only runs if `GEMINI_API_KEY` secret is set
|
||||
|
||||
### Running Tests
|
||||
|
||||
```bash
|
||||
# Run all unit tests (CI-friendly, no API key needed)
|
||||
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 live integration tests (requires API key)
|
||||
export GEMINI_API_KEY=your-api-key-here
|
||||
python tests/test_live_integration.py
|
||||
```
|
||||
|
||||
## Code Quality
|
||||
|
||||
### Formatting and Linting
|
||||
```bash
|
||||
# Install development tools
|
||||
pip install black ruff
|
||||
|
||||
# Format code
|
||||
black .
|
||||
|
||||
# Lint code
|
||||
ruff check .
|
||||
```
|
||||
|
||||
### Pre-commit Checks
|
||||
Before submitting a PR, ensure:
|
||||
- [ ] All unit tests pass: `python -m pytest tests/ --ignore=tests/test_live_integration.py -v`
|
||||
- [ ] Code is formatted: `black --check .`
|
||||
- [ ] Code passes linting: `ruff check .`
|
||||
- [ ] Live tests work (if you have API access): `python tests/test_live_integration.py`
|
||||
|
||||
## Adding New Features
|
||||
|
||||
### Adding a New Tool
|
||||
|
||||
1. **Create tool file**: `tools/your_tool.py`
|
||||
2. **Inherit from BaseTool**: Implement all required methods
|
||||
3. **Add system prompt**: Include prompt in `prompts/tool_prompts.py`
|
||||
4. **Register tool**: Add to `TOOLS` dict in `server.py`
|
||||
5. **Write tests**: Add unit tests that use mocks
|
||||
6. **Test live**: Verify with live API calls
|
||||
|
||||
### Testing New Tools
|
||||
|
||||
```python
|
||||
# Unit test example (tools/test_your_tool.py)
|
||||
@pytest.mark.asyncio
|
||||
@patch("tools.base.BaseTool.create_model")
|
||||
async def test_your_tool(self, mock_create_model):
|
||||
mock_model = Mock()
|
||||
mock_model.generate_content.return_value = Mock(
|
||||
candidates=[Mock(content=Mock(parts=[Mock(text="Expected response")]))]
|
||||
)
|
||||
mock_create_model.return_value = mock_model
|
||||
|
||||
tool = YourTool()
|
||||
result = await tool.execute({"param": "value"})
|
||||
|
||||
assert len(result) == 1
|
||||
assert "Expected response" in result[0].text
|
||||
```
|
||||
|
||||
## CI/CD Pipeline
|
||||
|
||||
The GitHub Actions workflow:
|
||||
|
||||
1. **Unit Tests**: Run on all Python versions (3.10, 3.11, 3.12)
|
||||
2. **Linting**: Check code formatting and style
|
||||
3. **Live Tests**: Only run if `GEMINI_API_KEY` secret is available
|
||||
|
||||
### Key Features:
|
||||
- **✅ No API key required for PRs** - All contributors can run tests
|
||||
- **🔒 Live verification available** - Maintainers can verify API integration
|
||||
- **📊 Coverage reporting** - Track test coverage
|
||||
- **🐍 Multi-Python support** - Ensure compatibility
|
||||
|
||||
## Contribution Guidelines
|
||||
|
||||
### Pull Request Process
|
||||
|
||||
1. **Fork the repository**
|
||||
2. **Create a feature branch**: `git checkout -b feature/your-feature`
|
||||
3. **Make your changes**
|
||||
4. **Add/update tests**
|
||||
5. **Run tests locally**: Ensure unit tests pass
|
||||
6. **Choose appropriate PR title prefix** (see below)
|
||||
7. **Submit PR**: Include description of changes
|
||||
|
||||
### PR Title Prefixes and Automation
|
||||
|
||||
The project uses automated versioning and Docker builds based on PR title prefixes:
|
||||
|
||||
#### Version Bumping Prefixes (trigger version bump + Docker build):
|
||||
- `feat: <description>` - New features → **MINOR** version bump (1.X.0)
|
||||
- `fix: <description>` - Bug fixes → **PATCH** version bump (1.0.X)
|
||||
- `breaking: <description>` - Breaking changes → **MAJOR** version bump (X.0.0)
|
||||
- `perf: <description>` - Performance improvements → **PATCH** version bump
|
||||
- `refactor: <description>` - Code refactoring → **PATCH** version bump
|
||||
|
||||
#### Non-Version Prefixes (no version bump):
|
||||
- `docs: <description>` - Documentation only
|
||||
- `chore: <description>` - Maintenance tasks
|
||||
- `test: <description>` - Test additions/changes
|
||||
- `ci: <description>` - CI/CD changes
|
||||
- `style: <description>` - Code style changes
|
||||
|
||||
#### Docker Build Options:
|
||||
For contributors who want to test Docker builds without version bumps:
|
||||
- `docker: <description>` - Force Docker build only
|
||||
- `docs+docker: <description>` - Documentation + Docker build
|
||||
- `chore+docker: <description>` - Maintenance + Docker build
|
||||
- `test+docker: <description>` - Tests + Docker build
|
||||
- `ci+docker: <description>` - CI changes + Docker build
|
||||
- `style+docker: <description>` - Style changes + Docker build
|
||||
|
||||
#### What Happens When PR is Merged:
|
||||
|
||||
**For version bumping prefixes:**
|
||||
1. Version in `config.py` is automatically updated
|
||||
2. Git tag is created (e.g., `v1.2.0`)
|
||||
3. GitHub release is published
|
||||
4. Docker image is built and pushed to GHCR with version tag
|
||||
|
||||
**For Docker build prefixes:**
|
||||
1. Docker image is built and pushed to GHCR
|
||||
2. Image tagged with `pr-{number}` and `main-{commit-sha}`
|
||||
3. No version bump or release created
|
||||
|
||||
**For standard non-version prefixes:**
|
||||
1. Changes are merged without automation
|
||||
2. No version bump, Docker build, or release
|
||||
|
||||
### Code Standards
|
||||
|
||||
- **Follow existing patterns**: Look at existing tools for examples
|
||||
- **Add comprehensive tests**: Both unit tests (required) and live tests (recommended)
|
||||
- **Update documentation**: Update README if adding new features
|
||||
- **Use type hints**: All new code should include proper type annotations
|
||||
- **Keep it simple**: Follow SOLID principles and keep functions focused
|
||||
|
||||
### Security Considerations
|
||||
|
||||
- **Never commit API keys**: Use environment variables
|
||||
- **Validate inputs**: Always validate user inputs in tools
|
||||
- **Handle errors gracefully**: Provide meaningful error messages
|
||||
- **Follow security best practices**: Sanitize file paths, validate file access
|
||||
|
||||
## Getting Help
|
||||
|
||||
- **Issues**: Open an issue for bugs or feature requests
|
||||
- **Discussions**: Use GitHub Discussions for questions
|
||||
- **Documentation**: Check the README for usage examples
|
||||
|
||||
## License
|
||||
|
||||
By contributing, you agree that your contributions will be licensed under the MIT License.
|
||||
178
README.md
178
README.md
@@ -8,6 +8,8 @@ https://github.com/user-attachments/assets/8097e18e-b926-4d8b-ba14-a979e4c58bda
|
||||
|
||||
<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 partners for Claude - a Model Context Protocol server that gives Claude access to multiple AI models for enhanced code analysis,
|
||||
problem-solving, and collaborative development.
|
||||
|
||||
@@ -35,6 +37,12 @@ and review into consideration to aid with its pre-commit review.
|
||||
- [Available Tools](#available-tools) - Overview of all tools
|
||||
- [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**
|
||||
- [`chat`](#1-chat---general-development-chat--collaborative-thinking) - Collaborative thinking
|
||||
- [`thinkdeep`](#2-thinkdeep---extended-reasoning-partner) - Extended reasoning
|
||||
@@ -153,6 +161,9 @@ claude mcp remove gemini -s user
|
||||
Now run `claude` on the terminal for it to connect to the newly added mcp server. If you were already running a `claude` code session,
|
||||
please exit and start a new session.
|
||||
|
||||
#### Option A: Local Development Setup (using local Docker build)
|
||||
|
||||
The setup script shows you the exact configuration for local development:
|
||||
#### If Setting up for Claude Desktop
|
||||
|
||||
- Open Claude Desktop
|
||||
@@ -182,6 +193,103 @@ have produced a configuration for you to copy:
|
||||
}
|
||||
```
|
||||
|
||||
#### Option B: Published Docker Image (no local setup required)
|
||||
|
||||
**Quick setup using the published Docker image from GitHub Container Registry:**
|
||||
|
||||
```bash
|
||||
# Pull the latest published image
|
||||
docker pull ghcr.io/patrykiti/gemini-mcp-server:latest
|
||||
```
|
||||
|
||||
**Claude Desktop 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"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Advanced Configuration (Optional Parameters):**
|
||||
|
||||
You can customize the server behavior by adding additional environment variables:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"gemini": {
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"run", "--rm", "-i",
|
||||
"-e", "GEMINI_API_KEY",
|
||||
"-e", "DEFAULT_MODEL",
|
||||
"-e", "DEFAULT_THINKING_MODE_THINKDEEP",
|
||||
"-e", "LOG_LEVEL",
|
||||
"-e", "MCP_PROJECT_ROOT",
|
||||
"ghcr.io/patrykiti/gemini-mcp-server:latest"
|
||||
],
|
||||
"env": {
|
||||
"GEMINI_API_KEY": "your-gemini-api-key-here",
|
||||
"DEFAULT_MODEL": "gemini-2.0-flash-exp",
|
||||
"DEFAULT_THINKING_MODE_THINKDEEP": "medium",
|
||||
"LOG_LEVEL": "INFO",
|
||||
"MCP_PROJECT_ROOT": "/Users/yourusername/your-project"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Available Configuration Options:**
|
||||
|
||||
| Environment Variable | Default Value | Description |
|
||||
|---------------------|---------------|-------------|
|
||||
| `GEMINI_API_KEY` | *Required* | Your Google AI Studio API key |
|
||||
| `DEFAULT_MODEL` | `gemini-2.5-pro-preview-06-05` | Default model: `gemini-2.5-pro-preview-06-05` (Pro) or `gemini-2.0-flash-exp` (Flash) |
|
||||
| `DEFAULT_THINKING_MODE_THINKDEEP` | `high` | Default thinking depth: `minimal`, `low`, `medium`, `high`, `max` |
|
||||
| `LOG_LEVEL` | `INFO` | Logging verbosity: `DEBUG`, `INFO`, `WARNING`, `ERROR` |
|
||||
| `MCP_PROJECT_ROOT` | *Home directory* | Restrict file access to specific project directory |
|
||||
| `REDIS_URL` | `redis://localhost:6379/0` | Redis connection for conversation threading |
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Use faster Flash model by default
|
||||
"DEFAULT_MODEL": "gemini-2.0-flash-exp"
|
||||
|
||||
# Use lower thinking mode to save tokens
|
||||
"DEFAULT_THINKING_MODE_THINKDEEP": "medium"
|
||||
|
||||
# Enable debug logging for troubleshooting
|
||||
"LOG_LEVEL": "DEBUG"
|
||||
|
||||
# Restrict file access to your project directory
|
||||
"MCP_PROJECT_ROOT": "/Users/yourusername/my-project"
|
||||
```
|
||||
|
||||
**Benefits of using published image:**
|
||||
- ✅ **No local build required** - Download and run immediately
|
||||
- ✅ **Always latest stable version** - Automatically updated with releases
|
||||
- ✅ **Smaller local footprint** - No source code or build dependencies needed
|
||||
- ✅ **Easy updates** - Simply pull new image versions
|
||||
- ✅ **Cross-platform** - Works on any Docker-supported platform
|
||||
|
||||
**How it works:**
|
||||
- **Docker Compose services** run continuously in the background
|
||||
- **Redis** automatically handles conversation memory between requests
|
||||
- **AI-to-AI conversations** persist across multiple exchanges
|
||||
- **File access** through mounted workspace directory
|
||||
Paste the above into `claude_desktop_config.json`. If you have several other MCP servers listed, simply add this below the rest after a `,` comma:
|
||||
```json
|
||||
... other mcp servers ... ,
|
||||
@@ -846,12 +954,54 @@ To modify tool behavior, you can:
|
||||
2. Override `get_system_prompt()` in a tool class for tool-specific changes
|
||||
3. Use the `temperature` parameter to adjust response style (0.2 for focused, 0.7 for creative)
|
||||
|
||||
## Contributing
|
||||
|
||||
We welcome contributions! This project follows comprehensive development workflows and quality standards.
|
||||
|
||||
**Quick Start for Contributors:**
|
||||
1. Create a new tool in `tools/`
|
||||
2. Inherit from `BaseTool`
|
||||
3. Implement required methods (including `get_system_prompt()`)
|
||||
4. Add your system prompt to `prompts/tool_prompts.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.
|
||||
|
||||
## Testing
|
||||
|
||||
### Unit Tests (No API Key Required)
|
||||
The project includes comprehensive unit tests that use mocks and don't require a Gemini API key:
|
||||
The project includes comprehensive testing strategies covering unit tests, integration tests, and quality assurance.
|
||||
|
||||
### Quick Testing
|
||||
```bash
|
||||
# Run all unit tests (no API key required)
|
||||
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
|
||||
|
||||
# Live integration tests (API key required)
|
||||
export GEMINI_API_KEY=your-api-key-here
|
||||
python tests/test_live_integration.py
|
||||
```
|
||||
|
||||
### CI/CD Pipeline
|
||||
- **✅ 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
|
||||
|
||||
**For comprehensive testing documentation, see:**
|
||||
- **[Testing Strategy Guide](docs/contributing/testing.md)** - TDD methodology, test categories, quality gates
|
||||
- **[Test Structure Analysis](docs/contributing/test-structure.md)** - Detailed analysis of existing 17-file test suite
|
||||
- **[Development Workflows](docs/contributing/workflows.md)** - Testing integration with git processes
|
||||
|
||||
# Run all unit tests
|
||||
python -m pytest tests/ -v
|
||||
|
||||
@@ -898,8 +1048,9 @@ The CI pipeline works without any secrets and will pass all tests using mocked r
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Docker Issues
|
||||
### Common Issues
|
||||
|
||||
**Docker Connection Problems:**
|
||||
**"Connection failed" in Claude Desktop**
|
||||
- Ensure Docker services are running: `docker compose ps`
|
||||
- Check if the container name is correct: `docker ps` to see actual container names
|
||||
@@ -921,16 +1072,33 @@ The CI pipeline works without any secrets and will pass all tests using mocked r
|
||||
|
||||
**Testing your Docker setup:**
|
||||
```bash
|
||||
# Check if services are running
|
||||
# Check services status
|
||||
docker compose ps
|
||||
|
||||
# Test manual connection
|
||||
docker exec -i zen-mcp-server echo "Connection test"
|
||||
|
||||
# View logs
|
||||
# View logs for errors
|
||||
docker compose logs -f
|
||||
```
|
||||
|
||||
**Configuration Issues:**
|
||||
- API key not set: Check your `.env` file
|
||||
- File access issues: Verify mounted directories
|
||||
- Redis connectivity: Test with `docker exec -it zen-mcp-redis redis-cli ping`
|
||||
|
||||
**Debug Mode:**
|
||||
```bash
|
||||
# Enable detailed logging
|
||||
echo "LOG_LEVEL=DEBUG" >> .env
|
||||
docker compose restart
|
||||
```
|
||||
|
||||
**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
|
||||
|
||||
MIT License - see LICENSE file for details.
|
||||
|
||||
161
docs/README.md
Normal file
161
docs/README.md
Normal file
@@ -0,0 +1,161 @@
|
||||
# Gemini MCP Server Documentation
|
||||
|
||||
Welcome to the comprehensive documentation for the **Gemini MCP Server** - a sophisticated Model Context Protocol server that enables Claude to access Google's Gemini AI models through specialized tools for AI-assisted development workflows.
|
||||
|
||||
## 📖 Documentation Overview
|
||||
|
||||
This documentation is organized into four main categories to serve different audiences and use cases:
|
||||
|
||||
### 🚀 For End Users
|
||||
- **[Installation Guide](user-guides/installation.md)** - Set up the server locally or with Docker
|
||||
- **[Configuration](user-guides/configuration.md)** - Configure the server for your environment
|
||||
- **[Troubleshooting](user-guides/troubleshooting.md)** - Common issues and solutions
|
||||
|
||||
### 🛠️ For Developers
|
||||
- **[Development Setup](contributing/setup.md)** - Set up your development environment
|
||||
- **[Development Workflows](contributing/workflows.md)** - Git workflows, testing, and collaboration patterns
|
||||
- **[Code Style Guide](contributing/code-style.md)** - Coding standards and best practices
|
||||
- **[Testing Strategy](contributing/testing.md)** - Testing approaches and quality assurance
|
||||
- **[Test Structure Analysis](contributing/test-structure.md)** - Detailed analysis of existing test suite
|
||||
- **[Repository Overview](contributing/file-overview.md)** - Understanding the codebase structure
|
||||
|
||||
### 🏗️ For System Architects
|
||||
- **[Architecture Overview](architecture/overview.md)** - High-level system design and components
|
||||
- **[Component Details](architecture/components.md)** - Detailed component descriptions and interactions
|
||||
- **[Data Flow Patterns](architecture/data-flow.md)** - How data moves through the system
|
||||
- **[Architecture Decisions](architecture/decisions/)** - Architecture Decision Records (ADRs)
|
||||
|
||||
### 🔧 For API Users
|
||||
- **[MCP Protocol](api/mcp-protocol.md)** - Model Context Protocol implementation details
|
||||
- **[Tool Reference](api/tools/)** - Individual tool API documentation
|
||||
|
||||
## 🎯 Quick Start Paths
|
||||
|
||||
### New User Journey
|
||||
1. **[Install the Server](user-guides/installation.md)** → Get up and running quickly
|
||||
2. **[Configure Your Setup](user-guides/configuration.md)** → Customize for your environment
|
||||
3. **[Start Using Tools](#tool-reference)** → Explore AI-assisted workflows
|
||||
4. **[Troubleshoot Issues](user-guides/troubleshooting.md)** → Resolve common problems
|
||||
|
||||
### Developer Journey
|
||||
1. **[Set Up Development](contributing/setup.md)** → Prepare your dev environment
|
||||
2. **[Understand the Codebase](contributing/file-overview.md)** → Navigate the repository
|
||||
3. **[Follow Workflows](contributing/workflows.md)** → Git, testing, and collaboration
|
||||
4. **[Code Quality Standards](contributing/code-style.md)** → Maintain code quality
|
||||
|
||||
### Architect Journey
|
||||
1. **[System Overview](architecture/overview.md)** → Understand the high-level design
|
||||
2. **[Component Architecture](architecture/components.md)** → Deep dive into system parts
|
||||
3. **[Data Flow Analysis](architecture/data-flow.md)** → Trace information flow
|
||||
4. **[Decision Context](architecture/decisions/)** → Understand design choices
|
||||
|
||||
## 🛠️ Tool Reference
|
||||
|
||||
The server provides six specialized tools for different AI collaboration scenarios:
|
||||
|
||||
| Tool | Purpose | Best For | Documentation |
|
||||
|------|---------|----------|---------------|
|
||||
| **[chat](api/tools/chat.md)** | Quick questions, brainstorming | Immediate answers, idea exploration | Low complexity, fast iteration |
|
||||
| **[thinkdeep](api/tools/thinkdeep.md)** | Complex analysis, strategic planning | Architecture decisions, system design | High complexity, deep analysis |
|
||||
| **[analyze](api/tools/analyze.md)** | Code exploration, system understanding | Codebase comprehension, dependency analysis | Medium complexity, systematic exploration |
|
||||
| **[codereview](api/tools/codereview.md)** | Code quality, security, bug detection | PR reviews, security audits | Quality assurance, comprehensive validation |
|
||||
| **[debug](api/tools/debug.md)** | Root cause analysis, error investigation | Bug fixing, performance issues | Problem-solving, systematic debugging |
|
||||
| **[precommit](api/tools/precommit.md)** | Automated quality gates | Pre-commit validation, change analysis | Quality gates, automated validation |
|
||||
|
||||
### Tool Selection Guide
|
||||
|
||||
**For Quick Tasks**: Start with [chat](api/tools/chat.md) for immediate answers and brainstorming
|
||||
**For Complex Planning**: Use [thinkdeep](api/tools/thinkdeep.md) for architecture and strategic decisions
|
||||
**For Code Understanding**: Use [analyze](api/tools/analyze.md) to explore and understand existing code
|
||||
**For Quality Assurance**: Use [codereview](api/tools/codereview.md) and [precommit](api/tools/precommit.md) for validation
|
||||
**For Problem Solving**: Use [debug](api/tools/debug.md) for systematic error investigation
|
||||
|
||||
## 🔄 Collaboration Framework
|
||||
|
||||
This project follows the **[CLAUDE.md Collaboration Framework](../CLAUDE.md)** which defines:
|
||||
- **Tool Selection Matrix**: Guidelines for choosing the right tool for each task
|
||||
- **Memory Bank Integration**: Context preservation across development sessions
|
||||
- **Quality Gates**: Mandatory validation and review processes
|
||||
- **Documentation Standards**: Comprehensive documentation requirements
|
||||
|
||||
### Key Collaboration Patterns
|
||||
- **Complex Tasks (>3 steps)**: Always use TodoWrite to plan and track progress
|
||||
- **Architecture Decisions**: Must involve `thinkdeep` for exploration before implementation
|
||||
- **Code Reviews**: All significant changes require `codereview` analysis before committing
|
||||
- **Documentation Updates**: Any code change must include corresponding documentation updates
|
||||
|
||||
## 📚 Additional Resources
|
||||
|
||||
### Configuration Examples
|
||||
- **[macOS Setup](../examples/claude_config_macos.json)** - Local development on macOS
|
||||
- **[WSL Setup](../examples/claude_config_wsl.json)** - Windows Subsystem for Linux
|
||||
- **[Docker Setup](../examples/claude_config_docker_home.json)** - Container-based deployment
|
||||
|
||||
### Project Information
|
||||
- **[Main README](../README.md)** - Project overview and quick start
|
||||
- **[Contributing Guidelines](../CONTRIBUTING.md)** - How to contribute to the project
|
||||
- **[Quick Contributing Guide](user-guides/contributing-guide.md)** - Simple guide for new contributors
|
||||
- **[License](../LICENSE)** - MIT License details
|
||||
- **[Collaboration Framework](../CLAUDE.md)** - Development collaboration patterns
|
||||
|
||||
### Memory Bank System
|
||||
The project uses a **Memory Bank** system for context preservation:
|
||||
- **[Product Context](../memory-bank/productContext.md)** - Project goals and architecture
|
||||
- **[Active Context](../memory-bank/activeContext.md)** - Current development status
|
||||
- **[Decision Log](../memory-bank/decisionLog.md)** - Architectural decisions and rationale
|
||||
- **[Progress Tracking](../memory-bank/progress.md)** - Task completion and milestones
|
||||
|
||||
## 🎨 Documentation Standards
|
||||
|
||||
### For Technical Audiences
|
||||
- **Code Context**: All explanations include specific file and line number references (`file_path:line_number`)
|
||||
- **Architecture Focus**: Explain *why* decisions were made, not just *what* was implemented
|
||||
- **Data Flow**: Trace data through the system with concrete examples
|
||||
- **Error Scenarios**: Document failure modes and recovery strategies
|
||||
|
||||
### For Non-Technical Audiences
|
||||
- **Plain Language**: Avoid jargon, explain technical terms when necessary
|
||||
- **Purpose-Driven**: Start with "what problem does this solve?"
|
||||
- **Visual Aids**: Use diagrams and flowcharts where helpful
|
||||
- **Practical Examples**: Show real usage scenarios
|
||||
|
||||
## 🔍 Finding What You Need
|
||||
|
||||
### By Role
|
||||
- **System Administrators**: Start with [Installation](user-guides/installation.md) and [Configuration](user-guides/configuration.md)
|
||||
- **End Users**: Begin with [Tool Reference](#tool-reference) and [Quick Start](#new-user-journey)
|
||||
- **Developers**: Follow the [Developer Journey](#developer-journey) starting with [Development Setup](contributing/setup.md)
|
||||
- **Architects**: Review [Architecture Overview](architecture/overview.md) and [System Design](architecture/components.md)
|
||||
|
||||
### By Task
|
||||
- **Setting Up**: [Installation](user-guides/installation.md) → [Configuration](user-guides/configuration.md)
|
||||
- **Using Tools**: [Tool Reference](#tool-reference) → Specific tool documentation
|
||||
- **Developing**: [Setup](contributing/setup.md) → [Workflows](contributing/workflows.md) → [Code Style](contributing/code-style.md)
|
||||
- **Understanding Architecture**: [Overview](architecture/overview.md) → [Components](architecture/components.md) → [Data Flow](architecture/data-flow.md)
|
||||
- **Troubleshooting**: [Troubleshooting Guide](user-guides/troubleshooting.md) or relevant tool documentation
|
||||
|
||||
### By Problem Type
|
||||
- **Installation Issues**: [Installation Guide](user-guides/installation.md) and [Troubleshooting](user-guides/troubleshooting.md)
|
||||
- **Configuration Problems**: [Configuration Guide](user-guides/configuration.md)
|
||||
- **Tool Behavior Questions**: Specific [Tool Documentation](api/tools/)
|
||||
- **Development Questions**: [Contributing Guides](contributing/)
|
||||
- **Architecture Questions**: [Architecture Documentation](architecture/)
|
||||
|
||||
## 📝 Contributing to Documentation
|
||||
|
||||
This documentation follows the standards defined in [CLAUDE.md](../CLAUDE.md):
|
||||
|
||||
1. **Accuracy**: Documentation must reflect actual code behavior
|
||||
2. **Completeness**: Cover all user-facing functionality
|
||||
3. **Accessibility**: Understandable by intended audience
|
||||
4. **Currency**: Updated with every related code change
|
||||
|
||||
To contribute:
|
||||
1. Follow the [Development Workflows](contributing/workflows.md)
|
||||
2. Maintain [Code Style Standards](contributing/code-style.md)
|
||||
3. Include comprehensive [Testing](contributing/testing.md)
|
||||
4. Update relevant documentation sections
|
||||
|
||||
---
|
||||
|
||||
**Need Help?** Check the [Troubleshooting Guide](user-guides/troubleshooting.md) or explore the specific documentation section for your use case. For development questions, start with the [Contributing Guidelines](contributing/setup.md).
|
||||
460
docs/api/mcp-protocol.md
Normal file
460
docs/api/mcp-protocol.md
Normal file
@@ -0,0 +1,460 @@
|
||||
# MCP Protocol Implementation
|
||||
|
||||
## Overview
|
||||
|
||||
The Gemini MCP Server implements the Model Context Protocol (MCP) specification, providing Claude with standardized access to Google's Gemini AI models through a secure, tool-based interface.
|
||||
|
||||
## Protocol Specification
|
||||
|
||||
### MCP Version
|
||||
- **Implemented Version**: MCP v1.0
|
||||
- **Transport**: stdio (standard input/output)
|
||||
- **Serialization**: JSON-RPC 2.0
|
||||
- **Authentication**: Environment-based API key management
|
||||
|
||||
### Core Protocol Flow
|
||||
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 1,
|
||||
"method": "tools/list",
|
||||
"params": {}
|
||||
}
|
||||
```
|
||||
|
||||
**Response**:
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 1,
|
||||
"result": {
|
||||
"tools": [
|
||||
{
|
||||
"name": "chat",
|
||||
"description": "Quick questions and general collaboration",
|
||||
"inputSchema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"prompt": {"type": "string"},
|
||||
"continuation_id": {"type": "string", "optional": true}
|
||||
},
|
||||
"required": ["prompt"]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Tool Registration System
|
||||
|
||||
### Tool Discovery (`server.py:67`)
|
||||
|
||||
```python
|
||||
@server.list_tools()
|
||||
async def list_tools() -> list[types.Tool]:
|
||||
"""Dynamic tool discovery and registration"""
|
||||
tools = []
|
||||
|
||||
# Scan tools directory for available tools
|
||||
for tool_module in REGISTERED_TOOLS:
|
||||
tool_instance = tool_module()
|
||||
schema = tool_instance.get_schema()
|
||||
tools.append(schema)
|
||||
|
||||
return tools
|
||||
```
|
||||
|
||||
### Tool Schema Definition
|
||||
|
||||
Each tool must implement a standardized schema:
|
||||
|
||||
```python
|
||||
def get_schema(self) -> types.Tool:
|
||||
return types.Tool(
|
||||
name="analyze",
|
||||
description="Code exploration and understanding",
|
||||
inputSchema={
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"files": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"description": "Files or directories to analyze"
|
||||
},
|
||||
"question": {
|
||||
"type": "string",
|
||||
"description": "What to analyze or look for"
|
||||
},
|
||||
"analysis_type": {
|
||||
"type": "string",
|
||||
"enum": ["architecture", "performance", "security", "quality", "general"],
|
||||
"default": "general"
|
||||
},
|
||||
"thinking_mode": {
|
||||
"type": "string",
|
||||
"enum": ["minimal", "low", "medium", "high", "max"],
|
||||
"default": "medium"
|
||||
},
|
||||
"continuation_id": {
|
||||
"type": "string",
|
||||
"description": "Thread continuation ID for multi-turn conversations"
|
||||
}
|
||||
},
|
||||
"required": ["files", "question"]
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
## Tool Execution Protocol
|
||||
|
||||
### Request Processing (`server.py:89`)
|
||||
|
||||
```python
|
||||
@server.call_tool()
|
||||
async def call_tool(name: str, arguments: dict) -> list[types.TextContent]:
|
||||
"""Tool execution with comprehensive error handling"""
|
||||
|
||||
try:
|
||||
# 1. Tool validation
|
||||
tool_class = TOOL_REGISTRY.get(name)
|
||||
if not tool_class:
|
||||
raise ToolNotFoundError(f"Tool '{name}' not found")
|
||||
|
||||
# 2. Parameter validation
|
||||
tool_instance = tool_class()
|
||||
validated_args = tool_instance.validate_parameters(arguments)
|
||||
|
||||
# 3. Security validation
|
||||
if 'files' in validated_args:
|
||||
validated_args['files'] = validate_file_paths(validated_args['files'])
|
||||
|
||||
# 4. Tool execution
|
||||
result = await tool_instance.execute(validated_args)
|
||||
|
||||
# 5. Response formatting
|
||||
return [types.TextContent(
|
||||
type="text",
|
||||
text=result.content
|
||||
)]
|
||||
|
||||
except Exception as e:
|
||||
# Error response with context
|
||||
error_response = format_error_response(e, name, arguments)
|
||||
return [types.TextContent(
|
||||
type="text",
|
||||
text=error_response
|
||||
)]
|
||||
```
|
||||
|
||||
### Response Standardization
|
||||
|
||||
All tools return standardized `ToolOutput` objects:
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class ToolOutput:
|
||||
content: str
|
||||
metadata: Dict[str, Any]
|
||||
continuation_id: Optional[str] = None
|
||||
files_processed: List[str] = field(default_factory=list)
|
||||
thinking_tokens_used: int = 0
|
||||
status: str = "success" # success, partial, error
|
||||
|
||||
def to_mcp_response(self) -> str:
|
||||
"""Convert to MCP-compatible response format"""
|
||||
response_parts = [self.content]
|
||||
|
||||
if self.metadata:
|
||||
response_parts.append("\n## Metadata")
|
||||
for key, value in self.metadata.items():
|
||||
response_parts.append(f"- {key}: {value}")
|
||||
|
||||
if self.files_processed:
|
||||
response_parts.append("\n## Files Processed")
|
||||
for file_path in self.files_processed:
|
||||
response_parts.append(f"- {file_path}")
|
||||
|
||||
if self.continuation_id:
|
||||
response_parts.append(f"\n## Continuation ID: {self.continuation_id}")
|
||||
|
||||
return '\n'.join(response_parts)
|
||||
```
|
||||
|
||||
## Individual Tool APIs
|
||||
|
||||
### 1. Chat Tool
|
||||
|
||||
**Purpose**: Quick questions, brainstorming, general discussion
|
||||
|
||||
**API Specification**:
|
||||
```json
|
||||
{
|
||||
"name": "chat",
|
||||
"parameters": {
|
||||
"prompt": "string (required)",
|
||||
"continuation_id": "string (optional)",
|
||||
"temperature": "number (optional, 0.0-1.0, default: 0.5)",
|
||||
"thinking_mode": "string (optional, default: 'medium')"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Example Request**:
|
||||
```json
|
||||
{
|
||||
"method": "tools/call",
|
||||
"params": {
|
||||
"name": "chat",
|
||||
"arguments": {
|
||||
"prompt": "Explain the benefits of using MCP protocol",
|
||||
"thinking_mode": "low"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Response Format**:
|
||||
```json
|
||||
{
|
||||
"result": [{
|
||||
"type": "text",
|
||||
"text": "The Model Context Protocol (MCP) provides several key benefits:\n\n1. **Standardization**: Unified interface across different AI tools...\n\n## Metadata\n- thinking_mode: low\n- tokens_used: 156\n- response_time: 1.2s"
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
### 2. ThinkDeep Tool
|
||||
|
||||
**Purpose**: Complex architecture, system design, strategic planning
|
||||
|
||||
**API Specification**:
|
||||
```json
|
||||
{
|
||||
"name": "thinkdeep",
|
||||
"parameters": {
|
||||
"current_analysis": "string (required)",
|
||||
"problem_context": "string (optional)",
|
||||
"focus_areas": "array of strings (optional)",
|
||||
"thinking_mode": "string (optional, default: 'high')",
|
||||
"files": "array of strings (optional)",
|
||||
"continuation_id": "string (optional)"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Example Request**:
|
||||
```json
|
||||
{
|
||||
"method": "tools/call",
|
||||
"params": {
|
||||
"name": "thinkdeep",
|
||||
"arguments": {
|
||||
"current_analysis": "We have an MCP server with 6 specialized tools",
|
||||
"problem_context": "Need to scale to handle 100+ concurrent Claude sessions",
|
||||
"focus_areas": ["performance", "architecture", "resource_management"],
|
||||
"thinking_mode": "max"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Analyze Tool
|
||||
|
||||
**Purpose**: Code exploration, understanding existing systems
|
||||
|
||||
**API Specification**:
|
||||
```json
|
||||
{
|
||||
"name": "analyze",
|
||||
"parameters": {
|
||||
"files": "array of strings (required)",
|
||||
"question": "string (required)",
|
||||
"analysis_type": "enum: architecture|performance|security|quality|general",
|
||||
"thinking_mode": "string (optional, default: 'medium')",
|
||||
"continuation_id": "string (optional)"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**File Processing Behavior**:
|
||||
- **Directories**: Recursively scanned for relevant files
|
||||
- **Token Budget**: Allocated based on file priority (source code > docs > logs)
|
||||
- **Security**: All paths validated and sandboxed to PROJECT_ROOT
|
||||
- **Formatting**: Line numbers added for precise code references
|
||||
|
||||
### 4. CodeReview Tool
|
||||
|
||||
**Purpose**: Code quality, security, bug detection
|
||||
|
||||
**API Specification**:
|
||||
```json
|
||||
{
|
||||
"name": "codereview",
|
||||
"parameters": {
|
||||
"files": "array of strings (required)",
|
||||
"context": "string (required)",
|
||||
"review_type": "enum: full|security|performance|quick (default: full)",
|
||||
"severity_filter": "enum: critical|high|medium|all (default: all)",
|
||||
"standards": "string (optional)",
|
||||
"thinking_mode": "string (optional, default: 'medium')"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Response Includes**:
|
||||
- **Issue Categorization**: Critical → High → Medium → Low
|
||||
- **Specific Fixes**: Concrete code suggestions with line numbers
|
||||
- **Security Assessment**: Vulnerability detection and mitigation
|
||||
- **Performance Analysis**: Optimization opportunities
|
||||
|
||||
### 5. Debug Tool
|
||||
|
||||
**Purpose**: Root cause analysis, error investigation
|
||||
|
||||
**API Specification**:
|
||||
```json
|
||||
{
|
||||
"name": "debug",
|
||||
"parameters": {
|
||||
"error_description": "string (required)",
|
||||
"error_context": "string (optional)",
|
||||
"files": "array of strings (optional)",
|
||||
"previous_attempts": "string (optional)",
|
||||
"runtime_info": "string (optional)",
|
||||
"thinking_mode": "string (optional, default: 'medium')"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Diagnostic Capabilities**:
|
||||
- **Stack Trace Analysis**: Multi-language error parsing
|
||||
- **Root Cause Identification**: Systematic error investigation
|
||||
- **Reproduction Steps**: Detailed debugging procedures
|
||||
- **Fix Recommendations**: Prioritized solution approaches
|
||||
|
||||
### 6. Precommit Tool
|
||||
|
||||
**Purpose**: Automated quality gates, validation before commits
|
||||
|
||||
**API Specification**:
|
||||
```json
|
||||
{
|
||||
"name": "precommit",
|
||||
"parameters": {
|
||||
"path": "string (required, git repository root)",
|
||||
"include_staged": "boolean (default: true)",
|
||||
"include_unstaged": "boolean (default: true)",
|
||||
"review_type": "enum: full|security|performance|quick (default: full)",
|
||||
"original_request": "string (optional, user's intent)",
|
||||
"thinking_mode": "string (optional, default: 'medium')"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Validation Process**:
|
||||
1. **Git Analysis**: Staged/unstaged changes detection
|
||||
2. **Quality Review**: Comprehensive code analysis
|
||||
3. **Security Scan**: Vulnerability and secret detection
|
||||
4. **Documentation Check**: Ensures docs match code changes
|
||||
5. **Test Validation**: Recommends testing strategies
|
||||
6. **Commit Readiness**: Go/no-go recommendation
|
||||
|
||||
## Error Handling & Status Codes
|
||||
|
||||
### Standard Error Responses
|
||||
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 1,
|
||||
"error": {
|
||||
"code": -32602,
|
||||
"message": "Invalid params",
|
||||
"data": {
|
||||
"validation_errors": [
|
||||
{
|
||||
"field": "files",
|
||||
"error": "Path outside sandbox: /etc/passwd"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Error Categories
|
||||
|
||||
**Security Errors** (Code: -32001):
|
||||
- Path traversal attempts
|
||||
- Unauthorized file access
|
||||
- Sandbox boundary violations
|
||||
|
||||
**Validation Errors** (Code: -32602):
|
||||
- Missing required parameters
|
||||
- Invalid parameter types
|
||||
- Schema validation failures
|
||||
|
||||
**Tool Errors** (Code: -32603):
|
||||
- Tool execution failures
|
||||
- Gemini API errors
|
||||
- Resource exhaustion
|
||||
|
||||
**System Errors** (Code: -32000):
|
||||
- Redis connection failures
|
||||
- File system errors
|
||||
- Configuration issues
|
||||
|
||||
## Performance & Limits
|
||||
|
||||
### Request Limits
|
||||
|
||||
- **Maximum File Size**: 10MB per file
|
||||
- **Maximum Files**: 50 files per request
|
||||
- **Token Budget**: 1M tokens total context
|
||||
- **Thinking Tokens**: 32K maximum per tool
|
||||
- **Request Timeout**: 300 seconds
|
||||
|
||||
### Rate Limiting
|
||||
|
||||
```python
|
||||
# Per-client rate limiting (future implementation)
|
||||
RATE_LIMITS = {
|
||||
'chat': '10/minute',
|
||||
'analyze': '5/minute',
|
||||
'thinkdeep': '3/minute',
|
||||
'codereview': '5/minute',
|
||||
'debug': '5/minute',
|
||||
'precommit': '3/minute'
|
||||
}
|
||||
```
|
||||
|
||||
### Optimization Features
|
||||
|
||||
- **File Deduplication**: Avoid reprocessing same files across conversation
|
||||
- **Context Caching**: Redis-based conversation persistence
|
||||
- **Priority Processing**: Source code files processed first
|
||||
- **Concurrent Execution**: AsyncIO-based parallel processing
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Authentication
|
||||
- **API Key**: Gemini API key via environment variable
|
||||
- **No User Auth**: Runs in trusted Claude Desktop environment
|
||||
- **Local Only**: No network exposure beyond Gemini API
|
||||
|
||||
### Data Protection
|
||||
- **Sandbox Enforcement**: PROJECT_ROOT boundary enforcement
|
||||
- **Path Validation**: Multi-layer dangerous path detection
|
||||
- **Response Sanitization**: Automatic sensitive data removal
|
||||
- **Temporary Storage**: Redis with TTL-based cleanup
|
||||
|
||||
### Access Controls
|
||||
- **Read-Only Default**: Most operations are read-only
|
||||
- **Explicit Write Gates**: Write operations require explicit confirmation
|
||||
- **Docker Isolation**: Container-based runtime isolation
|
||||
|
||||
---
|
||||
|
||||
This MCP protocol implementation provides a secure, performant, and extensible foundation for AI-assisted development workflows while maintaining compatibility with Claude's expectations and requirements.
|
||||
583
docs/api/tools/analyze.md
Normal file
583
docs/api/tools/analyze.md
Normal file
@@ -0,0 +1,583 @@
|
||||
# Analyze Tool API Reference
|
||||
|
||||
## Overview
|
||||
|
||||
The **Analyze Tool** provides comprehensive codebase exploration and understanding capabilities. It's designed for in-depth analysis of existing systems, dependency mapping, pattern detection, and architectural comprehension.
|
||||
|
||||
## Tool Schema
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "analyze",
|
||||
"description": "Code exploration and understanding of existing systems",
|
||||
"inputSchema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"files": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"description": "Files or directories that might be related to the issue"
|
||||
},
|
||||
"question": {
|
||||
"type": "string",
|
||||
"description": "What to analyze or look for"
|
||||
},
|
||||
"analysis_type": {
|
||||
"type": "string",
|
||||
"enum": ["architecture", "performance", "security", "quality", "general"],
|
||||
"default": "general",
|
||||
"description": "Type of analysis to perform"
|
||||
},
|
||||
"output_format": {
|
||||
"type": "string",
|
||||
"enum": ["summary", "detailed", "actionable"],
|
||||
"default": "detailed",
|
||||
"description": "How to format the output"
|
||||
},
|
||||
"thinking_mode": {
|
||||
"type": "string",
|
||||
"enum": ["minimal", "low", "medium", "high", "max"],
|
||||
"default": "medium",
|
||||
"description": "Thinking depth for analysis"
|
||||
},
|
||||
"temperature": {
|
||||
"type": "number",
|
||||
"minimum": 0,
|
||||
"maximum": 1,
|
||||
"default": 0.2,
|
||||
"description": "Temperature for consistency in analysis"
|
||||
},
|
||||
"continuation_id": {
|
||||
"type": "string",
|
||||
"description": "Thread continuation ID for multi-turn conversations",
|
||||
"optional": true
|
||||
}
|
||||
},
|
||||
"required": ["files", "question"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Usage Patterns
|
||||
|
||||
### 1. Architecture Analysis
|
||||
|
||||
**Ideal For**:
|
||||
- Understanding system design patterns
|
||||
- Mapping component relationships
|
||||
- Identifying architectural anti-patterns
|
||||
- Documentation of existing systems
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
{
|
||||
"name": "analyze",
|
||||
"arguments": {
|
||||
"files": ["/workspace/src/", "/workspace/config/"],
|
||||
"question": "Analyze the overall architecture pattern and component relationships",
|
||||
"analysis_type": "architecture",
|
||||
"thinking_mode": "high",
|
||||
"output_format": "detailed"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Response Includes**:
|
||||
- System architecture overview
|
||||
- Component interaction diagrams
|
||||
- Data flow patterns
|
||||
- Integration points and dependencies
|
||||
- Design pattern identification
|
||||
|
||||
### 2. Performance Analysis
|
||||
|
||||
**Ideal For**:
|
||||
- Identifying performance bottlenecks
|
||||
- Resource usage patterns
|
||||
- Optimization opportunities
|
||||
- Scalability assessment
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
{
|
||||
"name": "analyze",
|
||||
"arguments": {
|
||||
"files": ["/workspace/api/", "/workspace/database/"],
|
||||
"question": "Identify performance bottlenecks and optimization opportunities",
|
||||
"analysis_type": "performance",
|
||||
"thinking_mode": "high"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Response Includes**:
|
||||
- Performance hotspots identification
|
||||
- Resource usage analysis
|
||||
- Caching opportunities
|
||||
- Database query optimization
|
||||
- Concurrency and parallelization suggestions
|
||||
|
||||
### 3. Security Analysis
|
||||
|
||||
**Ideal For**:
|
||||
- Security vulnerability assessment
|
||||
- Authentication/authorization review
|
||||
- Input validation analysis
|
||||
- Secure coding practice evaluation
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
{
|
||||
"name": "analyze",
|
||||
"arguments": {
|
||||
"files": ["/workspace/auth/", "/workspace/api/"],
|
||||
"question": "Assess security vulnerabilities and authentication patterns",
|
||||
"analysis_type": "security",
|
||||
"thinking_mode": "high"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Response Includes**:
|
||||
- Security vulnerability inventory
|
||||
- Authentication mechanism analysis
|
||||
- Input validation assessment
|
||||
- Data exposure risks
|
||||
- Secure coding recommendations
|
||||
|
||||
### 4. Code Quality Analysis
|
||||
|
||||
**Ideal For**:
|
||||
- Code maintainability assessment
|
||||
- Technical debt identification
|
||||
- Refactoring opportunities
|
||||
- Testing coverage evaluation
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
{
|
||||
"name": "analyze",
|
||||
"arguments": {
|
||||
"files": ["/workspace/src/"],
|
||||
"question": "Evaluate code quality, maintainability, and refactoring needs",
|
||||
"analysis_type": "quality",
|
||||
"thinking_mode": "medium"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Response Includes**:
|
||||
- Code quality metrics
|
||||
- Maintainability assessment
|
||||
- Technical debt inventory
|
||||
- Refactoring prioritization
|
||||
- Testing strategy recommendations
|
||||
|
||||
### 5. Dependency Analysis
|
||||
|
||||
**Ideal For**:
|
||||
- Understanding module dependencies
|
||||
- Circular dependency detection
|
||||
- Third-party library analysis
|
||||
- Dependency graph visualization
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
{
|
||||
"name": "analyze",
|
||||
"arguments": {
|
||||
"files": ["/workspace/package.json", "/workspace/requirements.txt", "/workspace/src/"],
|
||||
"question": "Map dependencies and identify potential issues",
|
||||
"analysis_type": "general",
|
||||
"output_format": "actionable"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Parameter Details
|
||||
|
||||
### files (required)
|
||||
- **Type**: array of strings
|
||||
- **Purpose**: Specifies which files/directories to analyze
|
||||
- **Behavior**:
|
||||
- **Individual Files**: Direct analysis of specified files
|
||||
- **Directories**: Recursive scanning with intelligent filtering
|
||||
- **Mixed Input**: Combines files and directories in single analysis
|
||||
- **Priority Processing**: Source code files processed before documentation
|
||||
|
||||
**Best Practices**:
|
||||
- Use specific paths for focused analysis
|
||||
- Include configuration files for complete context
|
||||
- Limit scope to relevant components for performance
|
||||
- Use absolute paths for reliability
|
||||
|
||||
### question (required)
|
||||
- **Type**: string
|
||||
- **Purpose**: Defines the analysis focus and expected outcomes
|
||||
- **Effective Question Patterns**:
|
||||
- **Exploratory**: "How does the authentication system work?"
|
||||
- **Diagnostic**: "Why is the API response time slow?"
|
||||
- **Evaluative**: "How maintainable is this codebase?"
|
||||
- **Comparative**: "What are the trade-offs in this design?"
|
||||
|
||||
### analysis_type (optional)
|
||||
- **Type**: string enum
|
||||
- **Default**: "general"
|
||||
- **Purpose**: Tailors analysis approach and output format
|
||||
|
||||
**Analysis Types**:
|
||||
|
||||
**architecture**:
|
||||
- Focus on system design and component relationships
|
||||
- Identifies patterns, anti-patterns, and architectural decisions
|
||||
- Maps data flow and integration points
|
||||
- Evaluates scalability and extensibility
|
||||
|
||||
**performance**:
|
||||
- Identifies bottlenecks and optimization opportunities
|
||||
- Analyzes resource usage and efficiency
|
||||
- Evaluates caching strategies and database performance
|
||||
- Assesses concurrency and parallelization
|
||||
|
||||
**security**:
|
||||
- Vulnerability assessment and threat modeling
|
||||
- Authentication and authorization analysis
|
||||
- Input validation and data protection review
|
||||
- Secure coding practice evaluation
|
||||
|
||||
**quality**:
|
||||
- Code maintainability and readability assessment
|
||||
- Technical debt identification and prioritization
|
||||
- Testing coverage and strategy evaluation
|
||||
- Refactoring opportunity analysis
|
||||
|
||||
**general**:
|
||||
- Balanced analysis covering multiple aspects
|
||||
- Good for initial exploration and broad understanding
|
||||
- Flexible approach adapting to content and question
|
||||
|
||||
### output_format (optional)
|
||||
- **Type**: string enum
|
||||
- **Default**: "detailed"
|
||||
- **Purpose**: Controls response structure and depth
|
||||
|
||||
**Format Types**:
|
||||
|
||||
**summary**:
|
||||
- High-level findings in 2-3 paragraphs
|
||||
- Key insights and primary recommendations
|
||||
- Executive summary style for quick understanding
|
||||
|
||||
**detailed** (recommended):
|
||||
- Comprehensive analysis with examples
|
||||
- Code references with line numbers
|
||||
- Multiple perspectives and alternatives
|
||||
- Actionable recommendations with context
|
||||
|
||||
**actionable**:
|
||||
- Focused on specific next steps
|
||||
- Prioritized recommendations
|
||||
- Implementation guidance
|
||||
- Clear success criteria
|
||||
|
||||
### thinking_mode (optional)
|
||||
- **Type**: string enum
|
||||
- **Default**: "medium"
|
||||
- **Purpose**: Controls analysis depth and computational budget
|
||||
|
||||
**Recommendations by Analysis Scope**:
|
||||
- **low** (2048 tokens): Small files, focused questions
|
||||
- **medium** (8192 tokens): Standard analysis, moderate complexity
|
||||
- **high** (16384 tokens): Comprehensive analysis, complex systems
|
||||
- **max** (32768 tokens): Deep research, critical system analysis
|
||||
|
||||
## Response Format
|
||||
|
||||
### Detailed Analysis Structure
|
||||
|
||||
```json
|
||||
{
|
||||
"content": "# Architecture Analysis Report\n\n## System Overview\n[High-level architecture summary]\n\n## Component Analysis\n[Detailed component breakdown with file references]\n\n## Design Patterns\n[Identified patterns and their implementations]\n\n## Integration Points\n[External dependencies and API interfaces]\n\n## Recommendations\n[Specific improvement suggestions]\n\n## Technical Debt\n[Areas requiring attention]\n\n## Next Steps\n[Prioritized action items]",
|
||||
"metadata": {
|
||||
"analysis_type": "architecture",
|
||||
"files_analyzed": 23,
|
||||
"lines_of_code": 5420,
|
||||
"patterns_identified": ["MVC", "Observer", "Factory"],
|
||||
"complexity_score": "medium",
|
||||
"confidence_level": "high"
|
||||
},
|
||||
"files_processed": [
|
||||
"/workspace/src/main.py:1-150",
|
||||
"/workspace/config/settings.py:1-75"
|
||||
],
|
||||
"continuation_id": "arch-analysis-uuid",
|
||||
"status": "success"
|
||||
}
|
||||
```
|
||||
|
||||
### Code Reference Format
|
||||
|
||||
Analysis responses include precise code references:
|
||||
|
||||
```
|
||||
## Authentication Implementation
|
||||
|
||||
The authentication system uses JWT tokens with RSA256 signing:
|
||||
|
||||
**Token Generation** (`src/auth/jwt_handler.py:45-67`):
|
||||
- RSA private key loading from environment
|
||||
- Token expiration set to 24 hours
|
||||
- User claims include role and permissions
|
||||
|
||||
**Token Validation** (`src/middleware/auth.py:23-41`):
|
||||
- Public key verification
|
||||
- Expiration checking
|
||||
- Role-based access control
|
||||
|
||||
**Security Concerns**:
|
||||
1. No token refresh mechanism (jwt_handler.py:45)
|
||||
2. Hardcoded secret fallback (jwt_handler.py:52)
|
||||
3. Missing rate limiting on auth endpoints (auth.py:15)
|
||||
```
|
||||
|
||||
## Advanced Usage Patterns
|
||||
|
||||
### 1. Progressive Analysis
|
||||
|
||||
**Phase 1: System Overview**
|
||||
```json
|
||||
{
|
||||
"name": "analyze",
|
||||
"arguments": {
|
||||
"files": ["/workspace/"],
|
||||
"question": "Provide high-level architecture overview",
|
||||
"analysis_type": "architecture",
|
||||
"output_format": "summary",
|
||||
"thinking_mode": "low"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Phase 2: Deep Dive**
|
||||
```json
|
||||
{
|
||||
"name": "analyze",
|
||||
"arguments": {
|
||||
"files": ["/workspace/core/", "/workspace/api/"],
|
||||
"question": "Analyze core components and API design in detail",
|
||||
"analysis_type": "architecture",
|
||||
"output_format": "detailed",
|
||||
"thinking_mode": "high",
|
||||
"continuation_id": "overview-analysis-id"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Comparative Analysis
|
||||
|
||||
**Current State Analysis**:
|
||||
```json
|
||||
{
|
||||
"name": "analyze",
|
||||
"arguments": {
|
||||
"files": ["/workspace/legacy/"],
|
||||
"question": "Document current system architecture and limitations",
|
||||
"analysis_type": "architecture"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Target State Analysis**:
|
||||
```json
|
||||
{
|
||||
"name": "analyze",
|
||||
"arguments": {
|
||||
"files": ["/workspace/new-design/"],
|
||||
"question": "Analyze proposed architecture and compare with legacy system",
|
||||
"analysis_type": "architecture",
|
||||
"continuation_id": "current-state-id"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Multi-Perspective Analysis
|
||||
|
||||
**Technical Analysis**:
|
||||
```json
|
||||
{
|
||||
"name": "analyze",
|
||||
"arguments": {
|
||||
"files": ["/workspace/"],
|
||||
"question": "Technical implementation analysis",
|
||||
"analysis_type": "quality",
|
||||
"thinking_mode": "high"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Performance Analysis**:
|
||||
```json
|
||||
{
|
||||
"name": "analyze",
|
||||
"arguments": {
|
||||
"files": ["/workspace/"],
|
||||
"question": "Performance characteristics and optimization opportunities",
|
||||
"analysis_type": "performance",
|
||||
"continuation_id": "technical-analysis-id"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Security Analysis**:
|
||||
```json
|
||||
{
|
||||
"name": "analyze",
|
||||
"arguments": {
|
||||
"files": ["/workspace/"],
|
||||
"question": "Security posture and vulnerability assessment",
|
||||
"analysis_type": "security",
|
||||
"continuation_id": "technical-analysis-id"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## File Processing Behavior
|
||||
|
||||
### Directory Processing
|
||||
|
||||
**Recursive Scanning**:
|
||||
- Automatically discovers relevant files in subdirectories
|
||||
- Applies intelligent filtering based on file types
|
||||
- Prioritizes source code over documentation and logs
|
||||
- Respects `.gitignore` patterns when present
|
||||
|
||||
**File Type Prioritization**:
|
||||
1. **Source Code** (.py, .js, .ts, .java, etc.) - 60% of token budget
|
||||
2. **Configuration** (.json, .yaml, .toml, etc.) - 25% of token budget
|
||||
3. **Documentation** (.md, .txt, .rst, etc.) - 10% of token budget
|
||||
4. **Other Files** (.log, .tmp, etc.) - 5% of token budget
|
||||
|
||||
### Content Processing
|
||||
|
||||
**Smart Truncation**:
|
||||
- Preserves file structure and important sections
|
||||
- Maintains code context and comments
|
||||
- Includes file headers and key functions
|
||||
- Adds truncation markers with statistics
|
||||
|
||||
**Line Number References**:
|
||||
- All code examples include precise line numbers
|
||||
- Enables easy navigation to specific locations
|
||||
- Supports IDE integration and quick access
|
||||
- Maintains accuracy across file versions
|
||||
|
||||
## Integration with Other Tools
|
||||
|
||||
### Analyze → ThinkDeep Flow
|
||||
|
||||
```json
|
||||
// 1. Comprehensive analysis
|
||||
{
|
||||
"name": "analyze",
|
||||
"arguments": {
|
||||
"files": ["/workspace/"],
|
||||
"question": "Understand current architecture and identify improvement areas",
|
||||
"analysis_type": "architecture"
|
||||
}
|
||||
}
|
||||
|
||||
// 2. Strategic planning based on findings
|
||||
{
|
||||
"name": "thinkdeep",
|
||||
"arguments": {
|
||||
"current_analysis": "Analysis findings: monolithic architecture with performance bottlenecks...",
|
||||
"focus_areas": ["modernization", "scalability", "migration_strategy"],
|
||||
"continuation_id": "architecture-analysis-id"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Analyze → CodeReview Flow
|
||||
|
||||
```json
|
||||
// 1. System understanding
|
||||
{
|
||||
"name": "analyze",
|
||||
"arguments": {
|
||||
"files": ["/workspace/auth/"],
|
||||
"question": "Understand authentication implementation patterns",
|
||||
"analysis_type": "security"
|
||||
}
|
||||
}
|
||||
|
||||
// 2. Detailed code review
|
||||
{
|
||||
"name": "codereview",
|
||||
"arguments": {
|
||||
"files": ["/workspace/auth/"],
|
||||
"context": "Analysis revealed potential security concerns in authentication",
|
||||
"review_type": "security",
|
||||
"continuation_id": "auth-analysis-id"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Performance Characteristics
|
||||
|
||||
### Analysis Speed by File Count
|
||||
- **1-10 files**: 2-5 seconds
|
||||
- **11-50 files**: 5-15 seconds
|
||||
- **51-200 files**: 15-45 seconds
|
||||
- **200+ files**: 45-120 seconds (consider breaking into smaller scopes)
|
||||
|
||||
### Memory Usage
|
||||
- **Small projects** (<1MB): ~100MB
|
||||
- **Medium projects** (1-10MB): ~300MB
|
||||
- **Large projects** (10-100MB): ~800MB
|
||||
- **Enterprise projects** (>100MB): May require multiple focused analyses
|
||||
|
||||
### Quality Indicators
|
||||
- **Coverage**: Percentage of files analyzed vs total files
|
||||
- **Depth**: Number of insights per file analyzed
|
||||
- **Accuracy**: Precision of code references and explanations
|
||||
- **Actionability**: Specificity of recommendations
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Effective Analysis Questions
|
||||
|
||||
**Specific and Focused**:
|
||||
```
|
||||
✅ "How does the caching layer integrate with the database access patterns?"
|
||||
✅ "What are the security implications of the current API authentication?"
|
||||
✅ "Where are the performance bottlenecks in the request processing pipeline?"
|
||||
|
||||
❌ "Analyze this code"
|
||||
❌ "Is this good?"
|
||||
❌ "What should I know?"
|
||||
```
|
||||
|
||||
**Context-Rich Questions**:
|
||||
```
|
||||
✅ "Given that we need to scale to 10x current traffic, what are the architectural constraints?"
|
||||
✅ "For a team of junior developers, what are the maintainability concerns?"
|
||||
✅ "Considering SOX compliance requirements, what are the audit trail gaps?"
|
||||
```
|
||||
|
||||
### Scope Management
|
||||
|
||||
1. **Start Broad, Then Focus**: Begin with high-level analysis, drill down to specific areas
|
||||
2. **Logical Grouping**: Analyze related components together for better context
|
||||
3. **Iterative Refinement**: Use continuation to build deeper understanding
|
||||
4. **Balance Depth and Breadth**: Match thinking mode to analysis scope
|
||||
|
||||
### File Selection Strategy
|
||||
|
||||
1. **Core First**: Start with main application files and entry points
|
||||
2. **Configuration Included**: Always include config files for complete context
|
||||
3. **Test Analysis**: Include tests to understand expected behavior
|
||||
4. **Documentation Review**: Add docs to understand intended design
|
||||
|
||||
---
|
||||
|
||||
The Analyze Tool serves as your code comprehension partner, providing deep insights into existing systems and enabling informed decision-making for development and modernization efforts.
|
||||
353
docs/api/tools/chat.md
Normal file
353
docs/api/tools/chat.md
Normal file
@@ -0,0 +1,353 @@
|
||||
# Chat Tool API Reference
|
||||
|
||||
## Overview
|
||||
|
||||
The **Chat Tool** provides immediate access to Gemini's conversational capabilities for quick questions, brainstorming sessions, and general collaboration. It's designed for rapid iteration and exploration of ideas without the computational overhead of deeper analysis tools.
|
||||
|
||||
## Tool Schema
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "chat",
|
||||
"description": "Quick questions, brainstorming, simple code snippets",
|
||||
"inputSchema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"prompt": {
|
||||
"type": "string",
|
||||
"description": "Your question, topic, or current thinking to discuss with Gemini"
|
||||
},
|
||||
"continuation_id": {
|
||||
"type": "string",
|
||||
"description": "Thread continuation ID for multi-turn conversations",
|
||||
"optional": true
|
||||
},
|
||||
"temperature": {
|
||||
"type": "number",
|
||||
"description": "Response creativity (0-1, default 0.5)",
|
||||
"minimum": 0,
|
||||
"maximum": 1,
|
||||
"default": 0.5
|
||||
},
|
||||
"thinking_mode": {
|
||||
"type": "string",
|
||||
"description": "Thinking depth: minimal|low|medium|high|max",
|
||||
"enum": ["minimal", "low", "medium", "high", "max"],
|
||||
"default": "medium"
|
||||
},
|
||||
"files": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"description": "Optional files for context (must be absolute paths)",
|
||||
"optional": true
|
||||
}
|
||||
},
|
||||
"required": ["prompt"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Usage Patterns
|
||||
|
||||
### 1. Quick Questions
|
||||
|
||||
**Ideal For**:
|
||||
- Clarifying concepts or terminology
|
||||
- Getting immediate explanations
|
||||
- Understanding code snippets
|
||||
- Exploring ideas rapidly
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
{
|
||||
"name": "chat",
|
||||
"arguments": {
|
||||
"prompt": "What's the difference between async and await in Python?",
|
||||
"thinking_mode": "low"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Brainstorming Sessions
|
||||
|
||||
**Ideal For**:
|
||||
- Generating multiple solution approaches
|
||||
- Exploring design alternatives
|
||||
- Creative problem solving
|
||||
- Architecture discussions
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
{
|
||||
"name": "chat",
|
||||
"arguments": {
|
||||
"prompt": "I need to design a caching layer for my MCP server. What are some approaches I should consider?",
|
||||
"temperature": 0.7,
|
||||
"thinking_mode": "medium"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Code Discussions
|
||||
|
||||
**Ideal For**:
|
||||
- Reviewing small code snippets
|
||||
- Understanding implementation patterns
|
||||
- Getting quick feedback
|
||||
- Exploring API designs
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
{
|
||||
"name": "chat",
|
||||
"arguments": {
|
||||
"prompt": "Review this error handling pattern and suggest improvements",
|
||||
"files": ["/workspace/utils/error_handling.py"],
|
||||
"thinking_mode": "medium"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Multi-Turn Conversations
|
||||
|
||||
**Ideal For**:
|
||||
- Building on previous discussions
|
||||
- Iterative refinement of ideas
|
||||
- Context-aware follow-ups
|
||||
- Continuous collaboration
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
{
|
||||
"name": "chat",
|
||||
"arguments": {
|
||||
"prompt": "Based on our previous discussion about caching, how would you implement cache invalidation?",
|
||||
"continuation_id": "550e8400-e29b-41d4-a716-446655440000"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Parameter Details
|
||||
|
||||
### prompt (required)
|
||||
- **Type**: string
|
||||
- **Purpose**: The main input for Gemini to process
|
||||
- **Best Practices**:
|
||||
- Be specific and clear about what you need
|
||||
- Include relevant context in the prompt itself
|
||||
- Ask focused questions for better responses
|
||||
- Use conversational language for brainstorming
|
||||
|
||||
### continuation_id (optional)
|
||||
- **Type**: string (UUID format)
|
||||
- **Purpose**: Links to previous conversation context
|
||||
- **Behavior**:
|
||||
- If provided, loads conversation history from Redis
|
||||
- Maintains context across multiple tool calls
|
||||
- Enables follow-up questions and refinement
|
||||
- Automatically generated on first call if not provided
|
||||
|
||||
### temperature (optional)
|
||||
- **Type**: number (0.0 - 1.0)
|
||||
- **Default**: 0.5
|
||||
- **Purpose**: Controls response creativity and variability
|
||||
- **Guidelines**:
|
||||
- **0.0-0.3**: Focused, deterministic responses (technical questions)
|
||||
- **0.4-0.6**: Balanced creativity and accuracy (general discussion)
|
||||
- **0.7-1.0**: High creativity (brainstorming, exploration)
|
||||
|
||||
### thinking_mode (optional)
|
||||
- **Type**: string enum
|
||||
- **Default**: "medium"
|
||||
- **Purpose**: Controls computational budget for analysis depth
|
||||
- **Options**:
|
||||
- **minimal** (128 tokens): Quick yes/no, simple clarifications
|
||||
- **low** (2048 tokens): Basic explanations, straightforward questions
|
||||
- **medium** (8192 tokens): Standard discussions, moderate complexity
|
||||
- **high** (16384 tokens): Deep explanations, complex topics
|
||||
- **max** (32768 tokens): Maximum depth, research-level discussions
|
||||
|
||||
### files (optional)
|
||||
- **Type**: array of strings
|
||||
- **Purpose**: Provides file context for discussion
|
||||
- **Constraints**:
|
||||
- Must be absolute paths
|
||||
- Subject to sandbox validation (PROJECT_ROOT)
|
||||
- Limited to 50 files per request
|
||||
- Total content limited by thinking_mode token budget
|
||||
|
||||
## Response Format
|
||||
|
||||
### Standard Response Structure
|
||||
|
||||
```json
|
||||
{
|
||||
"content": "Main response content...",
|
||||
"metadata": {
|
||||
"thinking_mode": "medium",
|
||||
"temperature": 0.5,
|
||||
"tokens_used": 2156,
|
||||
"response_time": "1.2s",
|
||||
"files_processed": 3
|
||||
},
|
||||
"continuation_id": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"files_processed": [
|
||||
"/workspace/utils/error_handling.py"
|
||||
],
|
||||
"status": "success"
|
||||
}
|
||||
```
|
||||
|
||||
### Response Content Types
|
||||
|
||||
**Explanatory Responses**:
|
||||
- Clear, structured explanations
|
||||
- Step-by-step breakdowns
|
||||
- Code examples with annotations
|
||||
- Concept comparisons and contrasts
|
||||
|
||||
**Brainstorming Responses**:
|
||||
- Multiple approach options
|
||||
- Pros/cons analysis
|
||||
- Creative alternatives
|
||||
- Implementation considerations
|
||||
|
||||
**Code Discussion Responses**:
|
||||
- Specific line-by-line feedback
|
||||
- Pattern recognition and naming
|
||||
- Improvement suggestions
|
||||
- Best practice recommendations
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Common Errors
|
||||
|
||||
**Invalid Temperature**:
|
||||
```json
|
||||
{
|
||||
"error": "Invalid temperature value: 1.5. Must be between 0.0 and 1.0"
|
||||
}
|
||||
```
|
||||
|
||||
**File Access Error**:
|
||||
```json
|
||||
{
|
||||
"error": "File access denied: /etc/passwd. Path outside project sandbox."
|
||||
}
|
||||
```
|
||||
|
||||
**Token Limit Exceeded**:
|
||||
```json
|
||||
{
|
||||
"error": "Content exceeds token limit for thinking_mode 'low'. Consider using 'medium' or 'high'."
|
||||
}
|
||||
```
|
||||
|
||||
### Error Recovery Strategies
|
||||
|
||||
1. **Parameter Validation**: Adjust invalid parameters to acceptable ranges
|
||||
2. **File Filtering**: Remove inaccessible files and continue with available ones
|
||||
3. **Token Management**: Truncate large content while preserving structure
|
||||
4. **Graceful Degradation**: Provide partial responses when possible
|
||||
|
||||
## Performance Characteristics
|
||||
|
||||
### Response Times
|
||||
- **minimal mode**: ~0.5-1s (simple questions)
|
||||
- **low mode**: ~1-2s (basic explanations)
|
||||
- **medium mode**: ~2-4s (standard discussions)
|
||||
- **high mode**: ~4-8s (deep analysis)
|
||||
- **max mode**: ~8-15s (research-level)
|
||||
|
||||
### Resource Usage
|
||||
- **Memory**: ~50-200MB per conversation thread
|
||||
- **Network**: Minimal (only Gemini API calls)
|
||||
- **Storage**: Redis conversation persistence (24h TTL)
|
||||
- **CPU**: Low (primarily I/O bound)
|
||||
|
||||
### Optimization Tips
|
||||
|
||||
1. **Use Appropriate Thinking Mode**: Don't over-engineer simple questions
|
||||
2. **Leverage Continuation**: Build on previous context rather than repeating
|
||||
3. **Focus Prompts**: Specific questions get better responses
|
||||
4. **Batch Related Questions**: Use conversation threading for related topics
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Effective Prompting
|
||||
|
||||
**Good Examples**:
|
||||
```
|
||||
"Explain the trade-offs between Redis and in-memory caching for an MCP server"
|
||||
"Help me brainstorm error handling strategies for async file operations"
|
||||
"What are the security implications of this authentication pattern?"
|
||||
```
|
||||
|
||||
**Avoid**:
|
||||
```
|
||||
"Help me" (too vague)
|
||||
"Fix this code" (without context)
|
||||
"What should I do?" (open-ended without scope)
|
||||
```
|
||||
|
||||
### Conversation Management
|
||||
|
||||
1. **Use Continuation IDs**: Maintain context across related discussions
|
||||
2. **Logical Grouping**: Keep related topics in same conversation thread
|
||||
3. **Clear Transitions**: Explicitly state when changing topics
|
||||
4. **Context Refresh**: Occasionally summarize progress in long conversations
|
||||
|
||||
### File Usage
|
||||
|
||||
1. **Relevant Files Only**: Include only files directly related to discussion
|
||||
2. **Prioritize Source Code**: Code files provide more value than logs
|
||||
3. **Reasonable Scope**: 5-10 files maximum for focused discussions
|
||||
4. **Absolute Paths**: Always use full paths for reliability
|
||||
|
||||
## Integration Examples
|
||||
|
||||
### With Other Tools
|
||||
|
||||
**Chat → Analyze Flow**:
|
||||
```json
|
||||
// 1. Quick discussion
|
||||
{"name": "chat", "arguments": {"prompt": "Should I refactor this module?"}}
|
||||
|
||||
// 2. Deep analysis based on chat insights
|
||||
{"name": "analyze", "arguments": {
|
||||
"files": ["/workspace/module.py"],
|
||||
"question": "Analyze refactoring opportunities based on maintainability",
|
||||
"continuation_id": "previous-chat-thread-id"
|
||||
}}
|
||||
```
|
||||
|
||||
**Chat → ThinkDeep Flow**:
|
||||
```json
|
||||
// 1. Initial exploration
|
||||
{"name": "chat", "arguments": {"prompt": "I need to scale my API to handle 1000 RPS"}}
|
||||
|
||||
// 2. Strategic planning
|
||||
{"name": "thinkdeep", "arguments": {
|
||||
"current_analysis": "Need to scale API to 1000 RPS",
|
||||
"focus_areas": ["performance", "architecture", "caching"],
|
||||
"continuation_id": "previous-chat-thread-id"
|
||||
}}
|
||||
```
|
||||
|
||||
### Workflow Integration
|
||||
|
||||
**Development Workflow**:
|
||||
1. **Chat**: Quick question about implementation approach
|
||||
2. **Analyze**: Deep dive into existing codebase
|
||||
3. **Chat**: Discussion of findings and next steps
|
||||
4. **CodeReview**: Quality validation of changes
|
||||
|
||||
**Learning Workflow**:
|
||||
1. **Chat**: Ask about unfamiliar concepts
|
||||
2. **Chat**: Request examples and clarifications
|
||||
3. **Chat**: Discuss practical applications
|
||||
4. **Analyze**: Study real codebase examples
|
||||
|
||||
---
|
||||
|
||||
The Chat Tool serves as the primary interface for rapid AI collaboration, providing immediate access to Gemini's knowledge while maintaining conversation context and enabling seamless integration with deeper analysis tools.
|
||||
418
docs/api/tools/codereview.md
Normal file
418
docs/api/tools/codereview.md
Normal file
@@ -0,0 +1,418 @@
|
||||
# CodeReview Tool API Reference
|
||||
|
||||
## Overview
|
||||
|
||||
The **CodeReview Tool** provides comprehensive code quality, security, and bug detection analysis. Based on Gemini's deep analytical capabilities, it performs systematic code review with severity-based issue categorization and specific fix recommendations.
|
||||
|
||||
## Tool Schema
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "codereview",
|
||||
"description": "Code quality, security, bug detection",
|
||||
"inputSchema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"files": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"description": "Code files or directories to review"
|
||||
},
|
||||
"context": {
|
||||
"type": "string",
|
||||
"description": "User's summary of what the code does, expected behavior, constraints, and review objectives"
|
||||
},
|
||||
"review_type": {
|
||||
"type": "string",
|
||||
"enum": ["full", "security", "performance", "quick"],
|
||||
"default": "full",
|
||||
"description": "Type of review to perform"
|
||||
},
|
||||
"severity_filter": {
|
||||
"type": "string",
|
||||
"enum": ["critical", "high", "medium", "all"],
|
||||
"default": "all",
|
||||
"description": "Minimum severity level to report"
|
||||
},
|
||||
"standards": {
|
||||
"type": "string",
|
||||
"description": "Coding standards to enforce",
|
||||
"optional": true
|
||||
},
|
||||
"thinking_mode": {
|
||||
"type": "string",
|
||||
"enum": ["minimal", "low", "medium", "high", "max"],
|
||||
"default": "medium",
|
||||
"description": "Thinking depth for analysis"
|
||||
},
|
||||
"temperature": {
|
||||
"type": "number",
|
||||
"minimum": 0,
|
||||
"maximum": 1,
|
||||
"default": 0.2,
|
||||
"description": "Temperature for consistency in analysis"
|
||||
},
|
||||
"continuation_id": {
|
||||
"type": "string",
|
||||
"description": "Thread continuation ID for multi-turn conversations",
|
||||
"optional": true
|
||||
}
|
||||
},
|
||||
"required": ["files", "context"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Review Types
|
||||
|
||||
### 1. Full Review (default)
|
||||
|
||||
**Comprehensive analysis covering**:
|
||||
- **Security**: Vulnerability detection, authentication flaws, input validation
|
||||
- **Performance**: Bottlenecks, resource usage, optimization opportunities
|
||||
- **Quality**: Maintainability, readability, technical debt
|
||||
- **Bugs**: Logic errors, edge cases, exception handling
|
||||
- **Standards**: Coding conventions, best practices, style consistency
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
{
|
||||
"name": "codereview",
|
||||
"arguments": {
|
||||
"files": ["/workspace/src/auth/", "/workspace/src/api/"],
|
||||
"context": "Authentication and API modules for user management system. Handles JWT tokens, password hashing, and role-based access control.",
|
||||
"review_type": "full",
|
||||
"thinking_mode": "high"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Security Review
|
||||
|
||||
**Focused security assessment**:
|
||||
- **Authentication**: Token handling, session management, password security
|
||||
- **Authorization**: Access controls, privilege escalation, RBAC implementation
|
||||
- **Input Validation**: SQL injection, XSS, command injection vulnerabilities
|
||||
- **Data Protection**: Encryption, sensitive data exposure, logging security
|
||||
- **Configuration**: Security headers, SSL/TLS, environment variables
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
{
|
||||
"name": "codereview",
|
||||
"arguments": {
|
||||
"files": ["/workspace/auth/", "/workspace/middleware/"],
|
||||
"context": "Security review for production deployment. System handles PII data and financial transactions.",
|
||||
"review_type": "security",
|
||||
"severity_filter": "high",
|
||||
"thinking_mode": "high"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Performance Review
|
||||
|
||||
**Performance-focused analysis**:
|
||||
- **Algorithms**: Time/space complexity, optimization opportunities
|
||||
- **Database**: Query efficiency, N+1 problems, indexing strategies
|
||||
- **Caching**: Cache utilization, invalidation strategies, cache stampede
|
||||
- **Concurrency**: Thread safety, deadlocks, race conditions
|
||||
- **Resource Management**: Memory leaks, connection pooling, file handling
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
{
|
||||
"name": "codereview",
|
||||
"arguments": {
|
||||
"files": ["/workspace/api/", "/workspace/database/"],
|
||||
"context": "API layer experiencing high latency under load. Database queries taking 2-5 seconds average.",
|
||||
"review_type": "performance",
|
||||
"thinking_mode": "high"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Quick Review
|
||||
|
||||
**Rapid assessment focusing on**:
|
||||
- **Critical Issues**: Severe bugs and security vulnerabilities only
|
||||
- **Code Smells**: Obvious anti-patterns and maintainability issues
|
||||
- **Quick Wins**: Easy-to-fix improvements with high impact
|
||||
- **Standards**: Basic coding convention violations
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
{
|
||||
"name": "codereview",
|
||||
"arguments": {
|
||||
"files": ["/workspace/feature/new-payment-flow.py"],
|
||||
"context": "Quick review of new payment processing feature before merge",
|
||||
"review_type": "quick",
|
||||
"severity_filter": "high"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Severity Classification
|
||||
|
||||
### Critical Issues
|
||||
- **Security vulnerabilities** with immediate exploitation risk
|
||||
- **Data corruption** or loss potential
|
||||
- **System crashes** or availability impacts
|
||||
- **Compliance violations** (GDPR, SOX, HIPAA)
|
||||
|
||||
**Example Finding**:
|
||||
```
|
||||
🔴 CRITICAL - SQL Injection Vulnerability
|
||||
File: api/users.py:45
|
||||
Code: f"SELECT * FROM users WHERE id = {user_id}"
|
||||
Impact: Complete database compromise possible
|
||||
Fix: Use parameterized queries: cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,))
|
||||
```
|
||||
|
||||
### High Severity Issues
|
||||
- **Authentication bypasses** or privilege escalation
|
||||
- **Performance bottlenecks** affecting user experience
|
||||
- **Logic errors** in critical business flows
|
||||
- **Resource leaks** causing system degradation
|
||||
|
||||
**Example Finding**:
|
||||
```
|
||||
🟠 HIGH - Authentication Bypass
|
||||
File: middleware/auth.py:23
|
||||
Code: if token and jwt.decode(token, verify=False):
|
||||
Impact: JWT signature verification disabled
|
||||
Fix: Enable verification: jwt.decode(token, secret_key, algorithms=["HS256"])
|
||||
```
|
||||
|
||||
### Medium Severity Issues
|
||||
- **Code maintainability** problems
|
||||
- **Minor security** hardening opportunities
|
||||
- **Performance optimizations** for better efficiency
|
||||
- **Error handling** improvements
|
||||
|
||||
**Example Finding**:
|
||||
```
|
||||
🟡 MEDIUM - Error Information Disclosure
|
||||
File: api/auth.py:67
|
||||
Code: return {"error": str(e)}
|
||||
Impact: Sensitive error details exposed to clients
|
||||
Fix: Log full error, return generic message: logger.error(str(e)); return {"error": "Authentication failed"}
|
||||
```
|
||||
|
||||
### Low Severity Issues
|
||||
- **Code style** and convention violations
|
||||
- **Documentation** gaps
|
||||
- **Minor optimizations** with minimal impact
|
||||
- **Code duplication** opportunities
|
||||
|
||||
## Response Format
|
||||
|
||||
### Structured Review Report
|
||||
|
||||
```json
|
||||
{
|
||||
"content": "# Code Review Report\n\n## Executive Summary\n- **Files Reviewed**: 12\n- **Issues Found**: 23 (3 Critical, 7 High, 9 Medium, 4 Low)\n- **Overall Quality**: Moderate - Requires attention before production\n\n## Critical Issues (3)\n\n### 🔴 SQL Injection in User Query\n**File**: `api/users.py:45`\n**Severity**: Critical\n**Issue**: Unsafe string interpolation in SQL query\n```python\n# Current (vulnerable)\nquery = f\"SELECT * FROM users WHERE id = {user_id}\"\n\n# Fixed (secure)\nquery = \"SELECT * FROM users WHERE id = %s\"\ncursor.execute(query, (user_id,))\n```\n**Impact**: Complete database compromise\n**Priority**: Fix immediately\n\n## Security Assessment\n- Authentication mechanism: JWT with proper signing ✅\n- Input validation: Missing in 3 endpoints ❌\n- Error handling: Overly verbose error messages ❌\n\n## Performance Analysis\n- Database queries: 2 N+1 query problems identified\n- Caching: No caching layer implemented\n- Algorithm efficiency: Sorting algorithm in user_search O(n²)\n\n## Recommendations\n1. **Immediate**: Fix critical SQL injection vulnerabilities\n2. **Short-term**: Implement input validation middleware\n3. **Medium-term**: Add caching layer for frequently accessed data\n4. **Long-term**: Refactor sorting algorithms for better performance",
|
||||
"metadata": {
|
||||
"review_type": "full",
|
||||
"files_reviewed": 12,
|
||||
"lines_of_code": 3420,
|
||||
"issues_by_severity": {
|
||||
"critical": 3,
|
||||
"high": 7,
|
||||
"medium": 9,
|
||||
"low": 4
|
||||
},
|
||||
"security_score": 6.5,
|
||||
"maintainability_score": 7.2,
|
||||
"performance_score": 5.8,
|
||||
"overall_quality": "moderate"
|
||||
},
|
||||
"continuation_id": "review-550e8400",
|
||||
"status": "success"
|
||||
}
|
||||
```
|
||||
|
||||
### Issue Categorization
|
||||
|
||||
**Security Issues**:
|
||||
- Authentication and authorization flaws
|
||||
- Input validation vulnerabilities
|
||||
- Data exposure and privacy concerns
|
||||
- Cryptographic implementation errors
|
||||
|
||||
**Performance Issues**:
|
||||
- Algorithm inefficiencies
|
||||
- Database optimization opportunities
|
||||
- Memory and resource management
|
||||
- Concurrency and scaling concerns
|
||||
|
||||
**Quality Issues**:
|
||||
- Code maintainability problems
|
||||
- Technical debt accumulation
|
||||
- Testing coverage gaps
|
||||
- Documentation deficiencies
|
||||
|
||||
**Bug Issues**:
|
||||
- Logic errors and edge cases
|
||||
- Exception handling problems
|
||||
- Race conditions and timing issues
|
||||
- Integration and compatibility problems
|
||||
|
||||
## Advanced Usage Patterns
|
||||
|
||||
### 1. Pre-Commit Review
|
||||
|
||||
**Before committing changes**:
|
||||
```json
|
||||
{
|
||||
"name": "codereview",
|
||||
"arguments": {
|
||||
"files": ["/workspace/modified_files.txt"],
|
||||
"context": "Pre-commit review of changes for user authentication feature",
|
||||
"review_type": "full",
|
||||
"severity_filter": "medium",
|
||||
"standards": "PEP 8, security-first coding practices"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Security Audit
|
||||
|
||||
**Comprehensive security assessment**:
|
||||
```json
|
||||
{
|
||||
"name": "codereview",
|
||||
"arguments": {
|
||||
"files": ["/workspace/"],
|
||||
"context": "Security audit for SOC 2 compliance. System processes payment data and PII.",
|
||||
"review_type": "security",
|
||||
"severity_filter": "critical",
|
||||
"thinking_mode": "max",
|
||||
"standards": "OWASP Top 10, PCI DSS requirements"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Performance Optimization
|
||||
|
||||
**Performance-focused review**:
|
||||
```json
|
||||
{
|
||||
"name": "codereview",
|
||||
"arguments": {
|
||||
"files": ["/workspace/api/", "/workspace/database/"],
|
||||
"context": "API response times increased 300% with scale. Need performance optimization.",
|
||||
"review_type": "performance",
|
||||
"thinking_mode": "high"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Legacy Code Assessment
|
||||
|
||||
**Technical debt evaluation**:
|
||||
```json
|
||||
{
|
||||
"name": "codereview",
|
||||
"arguments": {
|
||||
"files": ["/workspace/legacy/"],
|
||||
"context": "Legacy system modernization assessment. Code is 5+ years old, limited documentation.",
|
||||
"review_type": "full",
|
||||
"thinking_mode": "high",
|
||||
"standards": "Modern Python practices, type hints, async patterns"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Integration with CLAUDE.md Collaboration
|
||||
|
||||
### Double Validation Protocol
|
||||
|
||||
**Primary Analysis** (Gemini):
|
||||
```json
|
||||
{
|
||||
"name": "codereview",
|
||||
"arguments": {
|
||||
"files": ["/workspace/security/"],
|
||||
"context": "Security-critical authentication module review",
|
||||
"review_type": "security",
|
||||
"thinking_mode": "high"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Adversarial Review** (Claude):
|
||||
- Challenge findings and look for edge cases
|
||||
- Validate assumptions about security implications
|
||||
- Cross-reference with security best practices
|
||||
- Identify potential false positives or missed issues
|
||||
|
||||
### Memory-Driven Context
|
||||
|
||||
**Context Retrieval**:
|
||||
```python
|
||||
# Before review, query memory for related context
|
||||
previous_findings = memory.search_nodes("security review authentication")
|
||||
architectural_decisions = memory.search_nodes("authentication architecture")
|
||||
```
|
||||
|
||||
**Findings Storage**:
|
||||
```python
|
||||
# Store review findings for future reference
|
||||
memory.create_entities([{
|
||||
"name": "Security Review - Authentication Module",
|
||||
"entityType": "quality_records",
|
||||
"observations": ["3 critical vulnerabilities found", "JWT implementation secure", "Input validation missing"]
|
||||
}])
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Effective Context Provision
|
||||
|
||||
**Comprehensive Context**:
|
||||
```json
|
||||
{
|
||||
"context": "E-commerce checkout flow handling payment processing. Requirements: PCI DSS compliance, 99.9% uptime, <200ms response time. Known issues: occasional payment failures under high load. Recent changes: added new payment provider integration. Team: 3 senior, 2 junior developers. Timeline: Production deployment in 2 weeks."
|
||||
}
|
||||
```
|
||||
|
||||
**Technical Context**:
|
||||
```json
|
||||
{
|
||||
"context": "Microservice architecture with Docker containers. Tech stack: Python 3.9, FastAPI, PostgreSQL, Redis. Load balancer: NGINX. Monitoring: Prometheus/Grafana. Authentication: OAuth 2.0 with JWT. Expected load: 1000 RPS peak."
|
||||
}
|
||||
```
|
||||
|
||||
### Review Scope Management
|
||||
|
||||
1. **Start with Critical Paths**: Review security and performance-critical code first
|
||||
2. **Incremental Reviews**: Review code in logical chunks rather than entire codebase
|
||||
3. **Context-Aware**: Always provide business context and technical constraints
|
||||
4. **Follow-up Reviews**: Use continuation for iterative improvement tracking
|
||||
|
||||
### Issue Prioritization
|
||||
|
||||
1. **Security First**: Address critical security issues immediately
|
||||
2. **Business Impact**: Prioritize issues affecting user experience or revenue
|
||||
3. **Technical Debt**: Balance new features with technical debt reduction
|
||||
4. **Team Capacity**: Consider team skills and available time for fixes
|
||||
|
||||
### Quality Gates
|
||||
|
||||
**Pre-Commit Gates**:
|
||||
- No critical or high severity issues
|
||||
- All security vulnerabilities addressed
|
||||
- Performance regressions identified and planned
|
||||
- Code style and standards compliance
|
||||
|
||||
**Pre-Production Gates**:
|
||||
- Comprehensive security review completed
|
||||
- Performance benchmarks met
|
||||
- Documentation updated
|
||||
- Monitoring and alerting configured
|
||||
|
||||
---
|
||||
|
||||
The CodeReview Tool provides systematic, thorough code analysis that integrates seamlessly with development workflows while maintaining high standards for security, performance, and maintainability.
|
||||
408
docs/api/tools/debug.md
Normal file
408
docs/api/tools/debug.md
Normal file
@@ -0,0 +1,408 @@
|
||||
# Debug Tool API Reference
|
||||
|
||||
## Overview
|
||||
|
||||
The **Debug Tool** provides expert-level debugging and root cause analysis capabilities. Leveraging Gemini's analytical power, it systematically investigates errors, analyzes stack traces, and provides comprehensive debugging strategies with 1M token capacity for handling large diagnostic files.
|
||||
|
||||
## Tool Schema
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "debug",
|
||||
"description": "Root cause analysis, error investigation",
|
||||
"inputSchema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"error_description": {
|
||||
"type": "string",
|
||||
"description": "Error message, symptoms, or issue description"
|
||||
},
|
||||
"error_context": {
|
||||
"type": "string",
|
||||
"description": "Stack trace, logs, or additional error context",
|
||||
"optional": true
|
||||
},
|
||||
"files": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"description": "Files or directories that might be related to the issue",
|
||||
"optional": true
|
||||
},
|
||||
"previous_attempts": {
|
||||
"type": "string",
|
||||
"description": "What has been tried already",
|
||||
"optional": true
|
||||
},
|
||||
"runtime_info": {
|
||||
"type": "string",
|
||||
"description": "Environment, versions, or runtime information",
|
||||
"optional": true
|
||||
},
|
||||
"thinking_mode": {
|
||||
"type": "string",
|
||||
"enum": ["minimal", "low", "medium", "high", "max"],
|
||||
"default": "medium",
|
||||
"description": "Thinking depth for analysis"
|
||||
},
|
||||
"temperature": {
|
||||
"type": "number",
|
||||
"minimum": 0,
|
||||
"maximum": 1,
|
||||
"default": 0.2,
|
||||
"description": "Temperature for accuracy in debugging"
|
||||
},
|
||||
"continuation_id": {
|
||||
"type": "string",
|
||||
"description": "Thread continuation ID for multi-turn conversations",
|
||||
"optional": true
|
||||
}
|
||||
},
|
||||
"required": ["error_description"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Debugging Capabilities
|
||||
|
||||
### 1. Stack Trace Analysis
|
||||
|
||||
**Multi-language stack trace parsing and analysis**:
|
||||
- **Python**: Exception hierarchies, traceback analysis, module resolution
|
||||
- **JavaScript**: Error objects, async stack traces, source map support
|
||||
- **Java**: Exception chains, thread dumps, JVM analysis
|
||||
- **C/C++**: Core dumps, segmentation faults, memory corruption
|
||||
- **Go**: Panic analysis, goroutine dumps, race condition detection
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
{
|
||||
"name": "debug",
|
||||
"arguments": {
|
||||
"error_description": "Application crashes with segmentation fault during user login",
|
||||
"error_context": "Traceback (most recent call last):\n File \"/app/auth/login.py\", line 45, in authenticate_user\n result = hash_password(password)\n File \"/app/utils/crypto.py\", line 23, in hash_password\n return bcrypt.hashpw(password.encode(), salt)\nSegmentationFault: 11",
|
||||
"files": ["/workspace/auth/", "/workspace/utils/crypto.py"],
|
||||
"runtime_info": "Python 3.9.7, bcrypt 3.2.0, Ubuntu 20.04, Docker container"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Performance Issue Investigation
|
||||
|
||||
**Systematic performance debugging**:
|
||||
- **Memory Leaks**: Heap analysis, reference tracking, garbage collection
|
||||
- **CPU Bottlenecks**: Profiling data analysis, hot path identification
|
||||
- **I/O Problems**: Database queries, file operations, network latency
|
||||
- **Concurrency Issues**: Deadlocks, race conditions, thread contention
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
{
|
||||
"name": "debug",
|
||||
"arguments": {
|
||||
"error_description": "API response time degraded from 200ms to 5-10 seconds after recent deployment",
|
||||
"error_context": "Memory usage climbing steadily. No obvious errors in logs. CPU usage normal.",
|
||||
"files": ["/workspace/api/", "/workspace/database/queries.py"],
|
||||
"previous_attempts": "Restarted services, checked database indexes, reviewed recent code changes",
|
||||
"runtime_info": "FastAPI 0.68.0, PostgreSQL 13, Redis 6.2, K8s deployment"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Integration & Configuration Issues
|
||||
|
||||
**System integration debugging**:
|
||||
- **Database Connections**: Connection pooling, timeout issues, authentication
|
||||
- **External APIs**: Network connectivity, authentication, rate limiting
|
||||
- **Configuration**: Environment variables, file permissions, service discovery
|
||||
- **Deployment**: Container issues, orchestration problems, resource constraints
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
{
|
||||
"name": "debug",
|
||||
"arguments": {
|
||||
"error_description": "Microservice intermittently fails to connect to database with 'connection timeout' errors",
|
||||
"error_context": "Error occurs approximately every 10-15 minutes. Database is accessible from other services. Connection pool shows available connections.",
|
||||
"files": ["/workspace/config/database.py", "/workspace/docker-compose.yml"],
|
||||
"runtime_info": "Docker Compose, PostgreSQL 13 in separate container, connection pool size: 20"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Logic & Business Rule Errors
|
||||
|
||||
**Business logic debugging**:
|
||||
- **Edge Cases**: Boundary conditions, null handling, empty collections
|
||||
- **State Management**: Inconsistent state, race conditions, data integrity
|
||||
- **Algorithm Issues**: Incorrect implementations, complexity problems
|
||||
- **Data Flow**: Transformation errors, validation failures, format issues
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
{
|
||||
"name": "debug",
|
||||
"arguments": {
|
||||
"error_description": "E-commerce cart total calculation occasionally shows incorrect amounts during checkout",
|
||||
"error_context": "Users report seeing different totals on cart page vs checkout page. Issue seems random but affects ~2% of transactions.",
|
||||
"files": ["/workspace/cart/", "/workspace/pricing/"],
|
||||
"previous_attempts": "Added logging to cart calculations, reviewed tax calculation logic",
|
||||
"runtime_info": "High-traffic e-commerce site, multiple discount types, international tax rules"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Response Format
|
||||
|
||||
### Comprehensive Debug Report
|
||||
|
||||
```json
|
||||
{
|
||||
"content": "# Debug Analysis Report\n\n## Problem Summary\n**Issue**: Segmentation fault during user authentication\n**Severity**: Critical - Application crashes\n**Scope**: Authentication module, affects all user logins\n\n## Root Cause Analysis\n\n### Primary Cause\n**Buffer overflow in bcrypt library** (`utils/crypto.py:23`)\n\n**Technical Details**:\n- bcrypt 3.2.0 has known vulnerability CVE-2023-xxxxx\n- `hash_password()` function passes unvalidated user input\n- Long passwords (>72 chars) trigger buffer overflow\n- Crash occurs in C extension, not caught by Python exception handling\n\n### Contributing Factors\n1. **Missing Input Validation** (`auth/login.py:42`)\n - No password length validation before hashing\n - No sanitization of special characters\n\n2. **Outdated Dependencies** (`requirements.txt:15`)\n - bcrypt 3.2.0 (vulnerable) vs 4.0.1 (patched)\n - No automated dependency scanning\n\n## Evidence Analysis\n\n### Stack Trace Breakdown\n```\nFile \"/app/auth/login.py\", line 45, in authenticate_user\n result = hash_password(password)\n```\n**Analysis**: Call originates from user input processing\n\n```\nFile \"/app/utils/crypto.py\", line 23, in hash_password\n return bcrypt.hashpw(password.encode(), salt)\n```\n**Analysis**: Crash occurs in bcrypt native code, indicates memory corruption\n\n### Code Analysis\n**Vulnerable Code** (`utils/crypto.py:20-25`):\n```python\ndef hash_password(password: str) -> str:\n salt = bcrypt.gensalt()\n # VULNERABILITY: No input validation\n return bcrypt.hashpw(password.encode(), salt) # Line 23 - crash point\n```\n\n## Reproduction Steps\n1. Send POST request to `/auth/login` with password > 72 characters\n2. Application processes authentication request\n3. `hash_password()` called with long password\n4. bcrypt.hashpw() triggers buffer overflow\n5. Segmentation fault occurs, container restarts\n\n## Immediate Fix\n\n### 1. Input Validation (Deploy immediately)\n```python\ndef hash_password(password: str) -> str:\n # Add input validation\n if len(password) > 72:\n raise ValueError(\"Password too long\")\n if not password:\n raise ValueError(\"Password cannot be empty\")\n \n salt = bcrypt.gensalt()\n return bcrypt.hashpw(password.encode(), salt)\n```\n\n### 2. Dependency Update\n```bash\n# Update requirements.txt\nbcrypt>=4.0.1 # Patched version\n\n# Rebuild and redeploy\ndocker build --no-cache .\n```\n\n## Long-term Solutions\n\n### 1. Comprehensive Input Validation\n- Implement request validation middleware\n- Add schema validation for all user inputs\n- Set maximum field lengths application-wide\n\n### 2. Security Hardening\n- Regular dependency scanning (Snyk, OWASP)\n- Automated security testing in CI/CD\n- Runtime application security monitoring\n\n### 3. Error Handling\n- Graceful handling of crypto operations\n- Proper exception propagation\n- User-friendly error messages\n\n## Testing Strategy\n\n### 1. Regression Tests\n```python\ndef test_long_password_handling():\n with pytest.raises(ValueError):\n hash_password('x' * 100) # Should raise, not crash\n\ndef test_empty_password_handling():\n with pytest.raises(ValueError):\n hash_password('')\n```\n\n### 2. Security Tests\n- Fuzzing tests for authentication endpoints\n- Boundary value testing for all inputs\n- Load testing with various input combinations\n\n## Monitoring & Prevention\n\n### 1. Enhanced Logging\n```python\ndef hash_password(password: str) -> str:\n logger.info(f\"Hashing password, length: {len(password)}\")\n # ... validation and hashing\n logger.info(\"Password hashing completed successfully\")\n```\n\n### 2. Alerting\n- Container restart alerts\n- Authentication failure rate monitoring\n- Dependency vulnerability scanning\n\n## Verification Steps\n1. Apply input validation patch\n2. Update bcrypt dependency\n3. Run regression test suite\n4. Deploy to staging environment\n5. Perform security testing\n6. Monitor for crashes (should be eliminated)\n7. Deploy to production with rollback plan",
|
||||
"metadata": {
|
||||
"error_type": "security_vulnerability",
|
||||
"severity": "critical",
|
||||
"root_cause": "buffer_overflow_in_dependency",
|
||||
"fix_complexity": "low",
|
||||
"estimated_fix_time": "2-4 hours",
|
||||
"risk_level": "high",
|
||||
"confidence_level": "high"
|
||||
},
|
||||
"diagnostic_data": {
|
||||
"stack_trace_analyzed": true,
|
||||
"vulnerability_identified": "CVE-2023-xxxxx",
|
||||
"affected_components": ["auth/login.py", "utils/crypto.py"],
|
||||
"reproduction_confirmed": true
|
||||
},
|
||||
"continuation_id": "debug-session-uuid",
|
||||
"status": "success"
|
||||
}
|
||||
```
|
||||
|
||||
## Advanced Debugging Patterns
|
||||
|
||||
### 1. Systematic Investigation Process
|
||||
|
||||
**Phase 1: Problem Definition**
|
||||
```json
|
||||
{
|
||||
"name": "debug",
|
||||
"arguments": {
|
||||
"error_description": "Application experiencing intermittent 500 errors",
|
||||
"error_context": "Initial error logs and basic observations",
|
||||
"thinking_mode": "low"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Phase 2: Deep Analysis**
|
||||
```json
|
||||
{
|
||||
"name": "debug",
|
||||
"arguments": {
|
||||
"error_description": "Refined problem statement based on initial analysis",
|
||||
"error_context": "Complete stack traces, detailed logs, profiling data",
|
||||
"files": ["/workspace/affected_modules/"],
|
||||
"continuation_id": "phase1-analysis-id",
|
||||
"thinking_mode": "high"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Phase 3: Solution Validation**
|
||||
```json
|
||||
{
|
||||
"name": "debug",
|
||||
"arguments": {
|
||||
"error_description": "Proposed solution validation and testing strategy",
|
||||
"previous_attempts": "Previous analysis findings and proposed fixes",
|
||||
"continuation_id": "phase2-analysis-id",
|
||||
"thinking_mode": "medium"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Multi-System Integration Debugging
|
||||
|
||||
**Component Isolation**:
|
||||
```json
|
||||
{
|
||||
"name": "debug",
|
||||
"arguments": {
|
||||
"error_description": "Order processing pipeline failing at random points",
|
||||
"files": ["/workspace/order-service/", "/workspace/payment-service/", "/workspace/inventory-service/"],
|
||||
"runtime_info": "Microservices architecture, message queues, distributed database",
|
||||
"thinking_mode": "high"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Data Flow Analysis**:
|
||||
```json
|
||||
{
|
||||
"name": "debug",
|
||||
"arguments": {
|
||||
"error_description": "Continuing order pipeline analysis with focus on data flow",
|
||||
"error_context": "Request/response logs, message queue contents, database state",
|
||||
"continuation_id": "component-analysis-id"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Performance Debugging Workflow
|
||||
|
||||
**Resource Analysis**:
|
||||
```json
|
||||
{
|
||||
"name": "debug",
|
||||
"arguments": {
|
||||
"error_description": "Memory usage climbing steadily leading to OOM kills",
|
||||
"error_context": "Memory profiling data, heap dumps, GC logs",
|
||||
"files": ["/workspace/memory-intensive-modules/"],
|
||||
"thinking_mode": "high"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Optimization Strategy**:
|
||||
```json
|
||||
{
|
||||
"name": "debug",
|
||||
"arguments": {
|
||||
"error_description": "Memory leak root cause identified, need optimization strategy",
|
||||
"previous_attempts": "Profiling analysis completed, leak sources identified",
|
||||
"continuation_id": "memory-analysis-id"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Large File Analysis Capabilities
|
||||
|
||||
### 1M Token Context Window
|
||||
|
||||
**Comprehensive Log Analysis**:
|
||||
- **Large Log Files**: Full application logs, database logs, system logs
|
||||
- **Memory Dumps**: Complete heap dumps and stack traces
|
||||
- **Profiling Data**: Detailed performance profiling outputs
|
||||
- **Multiple File Types**: Logs, configs, source code, database dumps
|
||||
|
||||
**Example with Large Files**:
|
||||
```json
|
||||
{
|
||||
"name": "debug",
|
||||
"arguments": {
|
||||
"error_description": "Production system crash analysis",
|
||||
"files": [
|
||||
"/workspace/logs/application.log", // 50MB log file
|
||||
"/workspace/logs/database.log", // 30MB log file
|
||||
"/workspace/dumps/heap_dump.txt", // 100MB heap dump
|
||||
"/workspace/traces/stack_trace.log" // 20MB stack trace
|
||||
],
|
||||
"thinking_mode": "max"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Smart File Processing
|
||||
|
||||
**Priority-Based Processing**:
|
||||
1. **Stack Traces**: Immediate analysis for crash cause
|
||||
2. **Error Logs**: Recent errors and patterns
|
||||
3. **Application Logs**: Business logic flow analysis
|
||||
4. **System Logs**: Infrastructure and environment issues
|
||||
|
||||
**Content Analysis**:
|
||||
- **Pattern Recognition**: Recurring errors and trends
|
||||
- **Timeline Analysis**: Event correlation and sequence
|
||||
- **Performance Metrics**: Response times, resource usage
|
||||
- **Dependency Tracking**: External service interactions
|
||||
|
||||
## Integration with Development Workflow
|
||||
|
||||
### 1. CI/CD Integration
|
||||
|
||||
**Automated Debugging**:
|
||||
```json
|
||||
{
|
||||
"name": "debug",
|
||||
"arguments": {
|
||||
"error_description": "Build failure in CI pipeline",
|
||||
"error_context": "CI logs, test output, build artifacts",
|
||||
"files": ["/workspace/.github/workflows/", "/workspace/tests/"],
|
||||
"runtime_info": "GitHub Actions, Docker build, pytest"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Production Incident Response
|
||||
|
||||
**Incident Analysis**:
|
||||
```json
|
||||
{
|
||||
"name": "debug",
|
||||
"arguments": {
|
||||
"error_description": "Production outage - service unavailable",
|
||||
"error_context": "Monitoring alerts, service logs, infrastructure metrics",
|
||||
"files": ["/workspace/monitoring/", "/workspace/logs/"],
|
||||
"runtime_info": "Kubernetes cluster, multiple replicas, load balancer",
|
||||
"thinking_mode": "max"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Code Review Integration
|
||||
|
||||
**Bug Investigation**:
|
||||
```json
|
||||
{
|
||||
"name": "debug",
|
||||
"arguments": {
|
||||
"error_description": "Regression introduced in recent PR",
|
||||
"files": ["/workspace/modified_files/"],
|
||||
"previous_attempts": "Code review completed, tests passing, issue found in production",
|
||||
"runtime_info": "Recent deployment, feature flag enabled"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Effective Error Reporting
|
||||
|
||||
**Comprehensive Error Description**:
|
||||
```
|
||||
Error Description:
|
||||
- What happened: Application crashes during user registration
|
||||
- When: Occurs intermittently, ~10% of registration attempts
|
||||
- Where: Registration form submission, after email validation
|
||||
- Who: Affects both new and existing users
|
||||
- Impact: Users cannot complete registration, data loss possible
|
||||
```
|
||||
|
||||
**Detailed Context Provision**:
|
||||
```
|
||||
Error Context:
|
||||
- Stack trace: [Full stack trace with line numbers]
|
||||
- Request data: [Sanitized request payload]
|
||||
- Environment state: [Memory usage, CPU load, active connections]
|
||||
- Timing: [Request timestamps, duration, timeout values]
|
||||
- Dependencies: [Database state, external API responses]
|
||||
```
|
||||
|
||||
### Debugging Workflow
|
||||
|
||||
1. **Collect Comprehensive Information**: Gather all available diagnostic data
|
||||
2. **Isolate the Problem**: Narrow down to specific components or operations
|
||||
3. **Analyze Dependencies**: Consider external systems and interactions
|
||||
4. **Validate Hypotheses**: Test theories with evidence and reproduction
|
||||
5. **Document Findings**: Create detailed reports for future reference
|
||||
|
||||
### Performance Optimization
|
||||
|
||||
1. **Use Appropriate Thinking Mode**: Match complexity to issue severity
|
||||
2. **Leverage Large Context**: Include comprehensive diagnostic files
|
||||
3. **Iterative Analysis**: Use continuation for complex debugging sessions
|
||||
4. **Cross-Reference**: Compare with similar issues and solutions
|
||||
|
||||
---
|
||||
|
||||
The Debug Tool provides systematic, expert-level debugging capabilities that can handle complex production issues while maintaining accuracy and providing actionable solutions for rapid incident resolution.
|
||||
449
docs/api/tools/precommit.md
Normal file
449
docs/api/tools/precommit.md
Normal file
@@ -0,0 +1,449 @@
|
||||
# Precommit Tool API Reference
|
||||
|
||||
## Overview
|
||||
|
||||
The **Precommit Tool** provides comprehensive automated quality gates and validation before commits. It performs deep analysis of git repositories, validates changes against architectural decisions, and ensures code quality standards are met before committing to version control.
|
||||
|
||||
## Tool Schema
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "precommit",
|
||||
"description": "Automated quality gates before commits",
|
||||
"inputSchema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"path": {
|
||||
"type": "string",
|
||||
"description": "Starting directory to search for git repositories (must be absolute path)"
|
||||
},
|
||||
"include_staged": {
|
||||
"type": "boolean",
|
||||
"default": true,
|
||||
"description": "Include staged changes in the review"
|
||||
},
|
||||
"include_unstaged": {
|
||||
"type": "boolean",
|
||||
"default": true,
|
||||
"description": "Include uncommitted (unstaged) changes in the review"
|
||||
},
|
||||
"compare_to": {
|
||||
"type": "string",
|
||||
"description": "Optional: A git ref (branch, tag, commit hash) to compare against",
|
||||
"optional": true
|
||||
},
|
||||
"review_type": {
|
||||
"type": "string",
|
||||
"enum": ["full", "security", "performance", "quick"],
|
||||
"default": "full",
|
||||
"description": "Type of review to perform on the changes"
|
||||
},
|
||||
"severity_filter": {
|
||||
"type": "string",
|
||||
"enum": ["critical", "high", "medium", "all"],
|
||||
"default": "all",
|
||||
"description": "Minimum severity level to report on the changes"
|
||||
},
|
||||
"original_request": {
|
||||
"type": "string",
|
||||
"description": "The original user request description for the changes",
|
||||
"optional": true
|
||||
},
|
||||
"focus_on": {
|
||||
"type": "string",
|
||||
"description": "Specific aspects to focus on (e.g., 'logic for user authentication', 'database query efficiency')",
|
||||
"optional": true
|
||||
},
|
||||
"thinking_mode": {
|
||||
"type": "string",
|
||||
"enum": ["minimal", "low", "medium", "high", "max"],
|
||||
"default": "medium",
|
||||
"description": "Thinking depth for the analysis"
|
||||
},
|
||||
"files": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"description": "Optional files or directories to provide as context",
|
||||
"optional": true
|
||||
},
|
||||
"continuation_id": {
|
||||
"type": "string",
|
||||
"description": "Thread continuation ID for multi-turn conversations",
|
||||
"optional": true
|
||||
}
|
||||
},
|
||||
"required": ["path"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Validation Process
|
||||
|
||||
### 1. Git Repository Analysis
|
||||
|
||||
**Repository Discovery**:
|
||||
- **Recursive Search**: Finds all git repositories within specified path
|
||||
- **Multi-Repository Support**: Handles monorepos and nested repositories
|
||||
- **Branch Detection**: Identifies current branch and tracking status
|
||||
- **Change Detection**: Analyzes staged, unstaged, and committed changes
|
||||
|
||||
**Git State Assessment**:
|
||||
```python
|
||||
# Repository state analysis
|
||||
{
|
||||
"repository_path": "/workspace/project",
|
||||
"current_branch": "feature/user-authentication",
|
||||
"tracking_branch": "origin/main",
|
||||
"ahead_by": 3,
|
||||
"behind_by": 0,
|
||||
"staged_files": 5,
|
||||
"unstaged_files": 2,
|
||||
"untracked_files": 1
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Change Analysis Pipeline
|
||||
|
||||
**Staged Changes Review**:
|
||||
```bash
|
||||
# Git diff analysis for staged changes
|
||||
git diff --staged --name-only
|
||||
git diff --staged --unified=3
|
||||
```
|
||||
|
||||
**Unstaged Changes Review**:
|
||||
```bash
|
||||
# Working directory changes analysis
|
||||
git diff --name-only
|
||||
git diff --unified=3
|
||||
```
|
||||
|
||||
**Commit History Analysis**:
|
||||
```bash
|
||||
# Compare against target branch
|
||||
git diff main...HEAD --name-only
|
||||
git log --oneline main..HEAD
|
||||
```
|
||||
|
||||
### 3. Quality Gate Validation
|
||||
|
||||
**Security Validation**:
|
||||
- **Secret Detection**: Scans for API keys, passwords, tokens
|
||||
- **Vulnerability Assessment**: Identifies security anti-patterns
|
||||
- **Input Validation**: Reviews user input handling
|
||||
- **Authentication Changes**: Validates auth/authz modifications
|
||||
|
||||
**Performance Validation**:
|
||||
- **Algorithm Analysis**: Reviews complexity and efficiency
|
||||
- **Database Changes**: Validates query performance and indexing
|
||||
- **Resource Usage**: Identifies potential memory or CPU issues
|
||||
- **Caching Strategy**: Reviews caching implementation changes
|
||||
|
||||
**Quality Validation**:
|
||||
- **Code Standards**: Enforces coding conventions and style
|
||||
- **Documentation**: Ensures code changes include documentation updates
|
||||
- **Testing**: Validates test coverage and quality
|
||||
- **Technical Debt**: Identifies new debt introduction
|
||||
|
||||
**Architecture Validation**:
|
||||
- **Design Patterns**: Ensures consistency with architectural decisions
|
||||
- **Dependencies**: Reviews new dependencies and their impact
|
||||
- **Integration**: Validates service integration changes
|
||||
- **Breaking Changes**: Identifies potential breaking changes
|
||||
|
||||
## Usage Patterns
|
||||
|
||||
### 1. Standard Pre-Commit Validation
|
||||
|
||||
**Complete validation before committing**:
|
||||
```json
|
||||
{
|
||||
"name": "precommit",
|
||||
"arguments": {
|
||||
"path": "/workspace/project",
|
||||
"include_staged": true,
|
||||
"include_unstaged": false,
|
||||
"review_type": "full",
|
||||
"original_request": "Implemented user authentication with JWT tokens"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Security-Focused Validation
|
||||
|
||||
**Security audit before sensitive commits**:
|
||||
```json
|
||||
{
|
||||
"name": "precommit",
|
||||
"arguments": {
|
||||
"path": "/workspace/security-module",
|
||||
"review_type": "security",
|
||||
"severity_filter": "high",
|
||||
"focus_on": "authentication mechanisms and input validation",
|
||||
"thinking_mode": "high"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Feature Branch Validation
|
||||
|
||||
**Comprehensive review before merge**:
|
||||
```json
|
||||
{
|
||||
"name": "precommit",
|
||||
"arguments": {
|
||||
"path": "/workspace/project",
|
||||
"compare_to": "main",
|
||||
"review_type": "full",
|
||||
"original_request": "Complete user management feature with CRUD operations",
|
||||
"thinking_mode": "high"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Performance Impact Assessment
|
||||
|
||||
**Performance validation for critical changes**:
|
||||
```json
|
||||
{
|
||||
"name": "precommit",
|
||||
"arguments": {
|
||||
"path": "/workspace/api-module",
|
||||
"review_type": "performance",
|
||||
"focus_on": "database queries and API response times",
|
||||
"compare_to": "main"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 5. Documentation Sync Validation
|
||||
|
||||
**Ensure documentation matches code changes**:
|
||||
```json
|
||||
{
|
||||
"name": "precommit",
|
||||
"arguments": {
|
||||
"path": "/workspace/",
|
||||
"focus_on": "documentation completeness and accuracy",
|
||||
"files": ["/workspace/docs/", "/workspace/README.md"],
|
||||
"original_request": "Updated API endpoints and added new features"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Response Format
|
||||
|
||||
### Comprehensive Validation Report
|
||||
|
||||
```json
|
||||
{
|
||||
"content": "# Pre-Commit Validation Report\n\n## Repository Analysis\n**Repository**: `/workspace/user-auth-service`\n**Branch**: `feature/jwt-authentication`\n**Changes**: 8 files modified, 245 lines added, 67 lines deleted\n**Commit Readiness**: ⚠️ **CONDITIONAL** - Address medium-severity issues\n\n## Change Summary\n### Files Modified (8)\n- `src/auth/jwt_handler.py` (new file, 89 lines)\n- `src/auth/middleware.py` (modified, +45/-12)\n- `src/models/user.py` (modified, +23/-8)\n- `tests/test_auth.py` (modified, +67/-15)\n- `requirements.txt` (modified, +3/-0)\n- `config/settings.py` (modified, +12/-5)\n- `docs/api/authentication.md` (modified, +18/-3)\n- `README.md` (modified, +6/-2)\n\n## Security Analysis ✅ PASSED\n\n### Strengths Identified\n- JWT implementation uses industry-standard `PyJWT` library\n- Proper secret key management via environment variables\n- Token expiration properly configured (24 hours)\n- Password hashing uses secure bcrypt with proper salt rounds\n\n### Security Validations\n- ✅ No hardcoded secrets detected\n- ✅ Input validation implemented for authentication endpoints\n- ✅ Proper error handling without information disclosure\n- ✅ HTTPS enforcement in middleware\n\n## Performance Analysis ⚠️ REVIEW REQUIRED\n\n### Medium Priority Issues (2)\n\n**🟡 Database Query Optimization** (`src/models/user.py:45`)\n```python\n# Current implementation\ndef get_user_by_email(email):\n return User.objects.filter(email=email).first()\n\n# Recommendation: Add database index\n# class User(models.Model):\n# email = models.EmailField(unique=True, db_index=True)\n```\n**Impact**: Authentication queries may be slow without email index\n**Priority**: Medium\n**Fix Time**: 5 minutes (migration required)\n\n**🟡 JWT Token Validation Caching** (`src/auth/jwt_handler.py:67`)\n```python\n# Consider implementing token validation caching\n# to reduce repeated signature verification overhead\n```\n**Impact**: Repeated JWT validation on every request\n**Priority**: Medium\n**Fix Time**: 30 minutes (optional optimization)\n\n## Code Quality Analysis ✅ PASSED\n\n### Quality Metrics\n- **Test Coverage**: 89% (target: 80%) ✅\n- **Code Complexity**: Low-Medium ✅ \n- **Documentation**: Complete API docs updated ✅\n- **Type Hints**: 95% coverage ✅\n\n### New Dependencies Validated\n```\nPyJWT==2.8.0 # Well-maintained, security-focused\nbcrypt==4.0.1 # Latest stable, no known vulnerabilities\npython-dotenv==1.0.0 # Standard environment management\n```\n**Dependency Assessment**: ✅ All dependencies are secure and well-maintained\n\n## Architecture Compliance ✅ PASSED\n\n### Design Pattern Validation\n- ✅ Follows established authentication middleware pattern\n- ✅ Proper separation of concerns (handler/middleware/models)\n- ✅ Consistent error handling approach\n- ✅ RESTful API design maintained\n\n### Integration Validation\n- ✅ Backward compatibility maintained\n- ✅ No breaking changes to existing API endpoints\n- ✅ Proper database migration provided\n- ✅ Environment configuration properly documented\n\n## Documentation Review ✅ PASSED\n\n### Documentation Updates\n- ✅ API documentation updated with authentication endpoints\n- ✅ README.md includes setup instructions for JWT\n- ✅ Environment variable documentation complete\n- ✅ Code comments adequate for complex authentication logic\n\n## Testing Validation ✅ PASSED\n\n### Test Coverage Analysis\n```\nFile Coverage\nsrc/auth/jwt_handler.py 92%\nsrc/auth/middleware.py 87%\nsrc/models/user.py 94%\ntests/test_auth.py 100%\n```\n\n### Test Quality\n- ✅ Unit tests for JWT token generation/validation\n- ✅ Integration tests for authentication endpoints\n- ✅ Edge case testing (expired tokens, invalid signatures)\n- ✅ Error condition testing\n\n## Final Recommendation\n\n### ✅ **APPROVED FOR COMMIT** with minor optimizations\n\n**Required Actions**: None (all critical issues resolved)\n\n**Recommended Actions**:\n1. **Add email index** to User model for better performance\n2. **Consider JWT caching** for high-traffic scenarios\n\n**Commit Confidence**: High (92%)\n\n### Suggested Commit Message\n```\nImplement JWT authentication system\n\n- Add JWT token generation and validation\n- Implement authentication middleware\n- Add secure password hashing with bcrypt\n- Update API documentation\n- Add comprehensive test coverage (89%)\n\nTesting: All tests pass, no breaking changes\nSecurity: No vulnerabilities detected\nPerformance: Minor optimization opportunities identified\n```\n\n## Next Steps\n1. **Immediate**: Commit current changes (approved)\n2. **Short-term**: Add database index for email field\n3. **Future**: Implement JWT validation caching for performance\n4. **Monitoring**: Track authentication performance metrics post-deployment",
|
||||
"metadata": {
|
||||
"repository_path": "/workspace/user-auth-service",
|
||||
"commit_readiness": "approved_with_recommendations",
|
||||
"files_analyzed": 8,
|
||||
"lines_changed": 178,
|
||||
"security_score": 9.2,
|
||||
"performance_score": 7.8,
|
||||
"quality_score": 9.1,
|
||||
"overall_confidence": 92,
|
||||
"validation_time": "12.3s"
|
||||
},
|
||||
"git_analysis": {
|
||||
"current_branch": "feature/jwt-authentication",
|
||||
"staged_files": 8,
|
||||
"unstaged_files": 0,
|
||||
"commits_ahead": 3,
|
||||
"target_branch": "main"
|
||||
},
|
||||
"continuation_id": "precommit-validation-uuid",
|
||||
"status": "success"
|
||||
}
|
||||
```
|
||||
|
||||
### Commit Readiness Levels
|
||||
|
||||
**✅ APPROVED**:
|
||||
- No critical or high-severity issues
|
||||
- All quality gates passed
|
||||
- Documentation complete
|
||||
- Tests comprehensive
|
||||
|
||||
**⚠️ CONDITIONAL**:
|
||||
- Medium-severity issues present
|
||||
- Some quality concerns
|
||||
- Recommendations for improvement
|
||||
- Can commit with awareness of trade-offs
|
||||
|
||||
**❌ BLOCKED**:
|
||||
- Critical security vulnerabilities
|
||||
- High-severity performance issues
|
||||
- Insufficient test coverage
|
||||
- Breaking changes without proper migration
|
||||
|
||||
## Advanced Usage Patterns
|
||||
|
||||
### 1. Cross-Repository Validation
|
||||
|
||||
**Monorepo validation**:
|
||||
```json
|
||||
{
|
||||
"name": "precommit",
|
||||
"arguments": {
|
||||
"path": "/workspace/monorepo",
|
||||
"focus_on": "cross-service impact analysis",
|
||||
"files": ["/workspace/shared-libs/", "/workspace/service-contracts/"],
|
||||
"thinking_mode": "high"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Compliance Validation
|
||||
|
||||
**Regulatory compliance check**:
|
||||
```json
|
||||
{
|
||||
"name": "precommit",
|
||||
"arguments": {
|
||||
"path": "/workspace/financial-service",
|
||||
"review_type": "security",
|
||||
"severity_filter": "critical",
|
||||
"focus_on": "PCI DSS compliance and data protection",
|
||||
"thinking_mode": "max"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Migration Safety Validation
|
||||
|
||||
**Database migration validation**:
|
||||
```json
|
||||
{
|
||||
"name": "precommit",
|
||||
"arguments": {
|
||||
"path": "/workspace/api-service",
|
||||
"focus_on": "database migration safety and backward compatibility",
|
||||
"files": ["/workspace/migrations/", "/workspace/models/"],
|
||||
"original_request": "Database schema changes for user profiles feature"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Integration Testing Validation
|
||||
|
||||
**Service integration changes**:
|
||||
```json
|
||||
{
|
||||
"name": "precommit",
|
||||
"arguments": {
|
||||
"path": "/workspace/microservices",
|
||||
"focus_on": "service contract changes and API compatibility",
|
||||
"compare_to": "main",
|
||||
"review_type": "full"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Integration with CI/CD
|
||||
|
||||
### Git Hook Integration
|
||||
|
||||
**Pre-commit hook implementation**:
|
||||
```bash
|
||||
#!/bin/sh
|
||||
# .git/hooks/pre-commit
|
||||
|
||||
echo "Running pre-commit validation..."
|
||||
|
||||
# Call precommit tool via MCP
|
||||
claude-code-cli --tool precommit --path "$(pwd)" --review-type full
|
||||
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "Pre-commit validation failed. Commit blocked."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "Pre-commit validation passed. Proceeding with commit."
|
||||
```
|
||||
|
||||
### GitHub Actions Integration
|
||||
|
||||
**CI workflow with precommit validation**:
|
||||
```yaml
|
||||
name: Pre-commit Validation
|
||||
on: [pull_request]
|
||||
|
||||
jobs:
|
||||
validate:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- name: Run Precommit Validation
|
||||
run: |
|
||||
claude-code-cli --tool precommit \
|
||||
--path ${{ github.workspace }} \
|
||||
--compare-to origin/main \
|
||||
--review-type full
|
||||
```
|
||||
|
||||
## Memory Bank Integration
|
||||
|
||||
### Architectural Decision Alignment
|
||||
|
||||
**Query past architectural decisions**:
|
||||
```python
|
||||
# Check alignment with architectural principles
|
||||
architectural_decisions = memory.search_nodes("architecture security authentication")
|
||||
design_patterns = memory.search_nodes("design patterns authentication")
|
||||
```
|
||||
|
||||
**Validate against established patterns**:
|
||||
```python
|
||||
# Ensure changes follow established patterns
|
||||
validation_results = memory.search_nodes("validation authentication security")
|
||||
previous_reviews = memory.search_nodes("code review authentication")
|
||||
```
|
||||
|
||||
### Context Preservation
|
||||
|
||||
**Store validation findings**:
|
||||
```python
|
||||
# Store precommit validation results
|
||||
memory.create_entities([{
|
||||
"name": "Precommit Validation - JWT Authentication",
|
||||
"entityType": "quality_records",
|
||||
"observations": [
|
||||
"Security validation passed with high confidence",
|
||||
"Performance optimizations recommended but not blocking",
|
||||
"Documentation complete and accurate",
|
||||
"Test coverage exceeds target threshold"
|
||||
]
|
||||
}])
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Effective Validation Strategy
|
||||
|
||||
1. **Regular Validation**: Use precommit for every commit, not just major changes
|
||||
2. **Contextual Focus**: Provide original request context for better validation
|
||||
3. **Incremental Analysis**: Use continuation for complex multi-part features
|
||||
4. **Severity Appropriate**: Match thinking mode to change complexity and risk
|
||||
|
||||
### Repository Management
|
||||
|
||||
1. **Clean Working Directory**: Ensure clean state before validation
|
||||
2. **Targeted Analysis**: Focus on changed files and their dependencies
|
||||
3. **Branch Strategy**: Compare against appropriate target branch
|
||||
4. **Documentation Sync**: Always validate documentation completeness
|
||||
|
||||
### Quality Gates
|
||||
|
||||
1. **Security First**: Never compromise on security findings
|
||||
2. **Performance Aware**: Consider performance impact of all changes
|
||||
3. **Test Coverage**: Maintain or improve test coverage with changes
|
||||
4. **Documentation Currency**: Keep documentation synchronized with code
|
||||
|
||||
---
|
||||
|
||||
The Precommit Tool provides comprehensive, automated quality assurance that integrates seamlessly with development workflows while maintaining high standards for security, performance, and code quality.
|
||||
476
docs/api/tools/thinkdeep.md
Normal file
476
docs/api/tools/thinkdeep.md
Normal file
@@ -0,0 +1,476 @@
|
||||
# ThinkDeep Tool API Reference
|
||||
|
||||
## Overview
|
||||
|
||||
The **ThinkDeep Tool** provides access to Gemini's maximum analytical capabilities for complex architecture decisions, system design, and strategic planning. It's designed for comprehensive analysis that requires deep computational thinking and extensive reasoning.
|
||||
|
||||
## Tool Schema
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "thinkdeep",
|
||||
"description": "Complex architecture, system design, strategic planning",
|
||||
"inputSchema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"current_analysis": {
|
||||
"type": "string",
|
||||
"description": "Your current thinking/analysis to extend and validate"
|
||||
},
|
||||
"problem_context": {
|
||||
"type": "string",
|
||||
"description": "Additional context about the problem or goal",
|
||||
"optional": true
|
||||
},
|
||||
"focus_areas": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"description": "Specific aspects to focus on (architecture, performance, security, etc.)",
|
||||
"optional": true
|
||||
},
|
||||
"files": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"description": "Optional file paths or directories for additional context",
|
||||
"optional": true
|
||||
},
|
||||
"thinking_mode": {
|
||||
"type": "string",
|
||||
"enum": ["minimal", "low", "medium", "high", "max"],
|
||||
"default": "high",
|
||||
"description": "Thinking depth for analysis"
|
||||
},
|
||||
"temperature": {
|
||||
"type": "number",
|
||||
"minimum": 0,
|
||||
"maximum": 1,
|
||||
"default": 0.7,
|
||||
"description": "Temperature for creative thinking"
|
||||
},
|
||||
"continuation_id": {
|
||||
"type": "string",
|
||||
"description": "Thread continuation ID for multi-turn conversations",
|
||||
"optional": true
|
||||
}
|
||||
},
|
||||
"required": ["current_analysis"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Usage Patterns
|
||||
|
||||
### 1. Architecture Decision Making
|
||||
|
||||
**Ideal For**:
|
||||
- Evaluating architectural alternatives
|
||||
- Designing system components
|
||||
- Planning scalability strategies
|
||||
- Technology selection decisions
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
{
|
||||
"name": "thinkdeep",
|
||||
"arguments": {
|
||||
"current_analysis": "We have an MCP server that needs to handle 100+ concurrent Claude sessions. Currently using single-threaded processing with Redis for conversation memory.",
|
||||
"problem_context": "Growing user base requires better performance and reliability. Budget allows for infrastructure changes.",
|
||||
"focus_areas": ["scalability", "performance", "reliability", "cost"],
|
||||
"thinking_mode": "max"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. System Design Exploration
|
||||
|
||||
**Ideal For**:
|
||||
- Complex system architecture
|
||||
- Integration pattern analysis
|
||||
- Security architecture design
|
||||
- Performance optimization strategies
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
{
|
||||
"name": "thinkdeep",
|
||||
"arguments": {
|
||||
"current_analysis": "Need to design a secure file processing pipeline that handles user uploads, virus scanning, content analysis, and storage with audit trails.",
|
||||
"focus_areas": ["security", "performance", "compliance", "monitoring"],
|
||||
"files": ["/workspace/security/", "/workspace/processing/"],
|
||||
"thinking_mode": "high"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Strategic Technical Planning
|
||||
|
||||
**Ideal For**:
|
||||
- Long-term technical roadmaps
|
||||
- Migration strategies
|
||||
- Technology modernization
|
||||
- Risk assessment and mitigation
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
{
|
||||
"name": "thinkdeep",
|
||||
"arguments": {
|
||||
"current_analysis": "Legacy monolithic application needs migration to microservices. 500K+ LOC, 50+ developers, critical business system with 99.9% uptime requirement.",
|
||||
"problem_context": "Must maintain business continuity while modernizing. Team has limited microservices experience.",
|
||||
"focus_areas": ["migration_strategy", "risk_mitigation", "team_training", "timeline"],
|
||||
"thinking_mode": "max",
|
||||
"temperature": 0.3
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Problem Solving & Innovation
|
||||
|
||||
**Ideal For**:
|
||||
- Novel technical challenges
|
||||
- Creative solution development
|
||||
- Cross-domain problem analysis
|
||||
- Innovation opportunities
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
{
|
||||
"name": "thinkdeep",
|
||||
"arguments": {
|
||||
"current_analysis": "AI model serving platform needs to optimize GPU utilization across heterogeneous hardware while minimizing latency and maximizing throughput.",
|
||||
"focus_areas": ["resource_optimization", "scheduling", "performance", "cost_efficiency"],
|
||||
"thinking_mode": "max",
|
||||
"temperature": 0.8
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Parameter Details
|
||||
|
||||
### current_analysis (required)
|
||||
- **Type**: string
|
||||
- **Purpose**: Starting point for deep analysis and extension
|
||||
- **Best Practices**:
|
||||
- Provide comprehensive background and context
|
||||
- Include current understanding and assumptions
|
||||
- Mention constraints and requirements
|
||||
- Reference specific challenges or decision points
|
||||
|
||||
**Example Structure**:
|
||||
```
|
||||
Current Analysis:
|
||||
- Problem: [Clear problem statement]
|
||||
- Context: [Business/technical context]
|
||||
- Current State: [What exists now]
|
||||
- Requirements: [What needs to be achieved]
|
||||
- Constraints: [Technical, business, resource limitations]
|
||||
- Open Questions: [Specific areas needing analysis]
|
||||
```
|
||||
|
||||
### problem_context (optional)
|
||||
- **Type**: string
|
||||
- **Purpose**: Additional contextual information
|
||||
- **Usage**:
|
||||
- Business requirements and priorities
|
||||
- Technical constraints and dependencies
|
||||
- Team capabilities and limitations
|
||||
- Timeline and budget considerations
|
||||
|
||||
### focus_areas (optional)
|
||||
- **Type**: array of strings
|
||||
- **Purpose**: Directs analysis toward specific aspects
|
||||
- **Common Values**:
|
||||
- **Technical**: `architecture`, `performance`, `scalability`, `security`
|
||||
- **Operational**: `reliability`, `monitoring`, `deployment`, `maintenance`
|
||||
- **Business**: `cost`, `timeline`, `risk`, `compliance`
|
||||
- **Team**: `skills`, `training`, `processes`, `communication`
|
||||
|
||||
### thinking_mode (optional)
|
||||
- **Type**: string enum
|
||||
- **Default**: "high"
|
||||
- **Purpose**: Controls depth and computational budget
|
||||
- **Recommendations by Use Case**:
|
||||
- **high** (16384 tokens): Standard complex analysis
|
||||
- **max** (32768 tokens): Critical decisions, comprehensive research
|
||||
- **medium** (8192 tokens): Moderate complexity, time-sensitive decisions
|
||||
- **low** (2048 tokens): Quick strategic input (unusual for thinkdeep)
|
||||
|
||||
### temperature (optional)
|
||||
- **Type**: number (0.0 - 1.0)
|
||||
- **Default**: 0.7
|
||||
- **Purpose**: Balances analytical rigor with creative exploration
|
||||
- **Guidelines**:
|
||||
- **0.0-0.3**: High accuracy, conservative recommendations (critical systems)
|
||||
- **0.4-0.7**: Balanced analysis with creative alternatives (most use cases)
|
||||
- **0.8-1.0**: High creativity, innovative solutions (research, innovation)
|
||||
|
||||
## Response Format
|
||||
|
||||
### Comprehensive Analysis Structure
|
||||
|
||||
```json
|
||||
{
|
||||
"content": "# Deep Analysis Report\n\n## Executive Summary\n[High-level findings and recommendations]\n\n## Current State Analysis\n[Detailed assessment of existing situation]\n\n## Alternative Approaches\n[Multiple solution paths with trade-offs]\n\n## Recommended Strategy\n[Specific recommendations with rationale]\n\n## Implementation Roadmap\n[Phased approach with milestones]\n\n## Risk Assessment\n[Potential challenges and mitigation strategies]\n\n## Success Metrics\n[Measurable outcomes and KPIs]\n\n## Next Steps\n[Immediate actions and decision points]",
|
||||
"metadata": {
|
||||
"thinking_mode": "high",
|
||||
"analysis_depth": "comprehensive",
|
||||
"alternatives_considered": 5,
|
||||
"focus_areas": ["architecture", "performance", "scalability"],
|
||||
"confidence_level": "high",
|
||||
"tokens_used": 15840,
|
||||
"analysis_time": "8.2s"
|
||||
},
|
||||
"continuation_id": "arch-analysis-550e8400",
|
||||
"status": "success"
|
||||
}
|
||||
```
|
||||
|
||||
### Analysis Components
|
||||
|
||||
**Executive Summary**:
|
||||
- Key findings in 2-3 sentences
|
||||
- Primary recommendation
|
||||
- Critical decision points
|
||||
- Success probability assessment
|
||||
|
||||
**Current State Analysis**:
|
||||
- Strengths and weaknesses of existing approach
|
||||
- Technical debt and architectural issues
|
||||
- Performance bottlenecks and limitations
|
||||
- Security and compliance gaps
|
||||
|
||||
**Alternative Approaches**:
|
||||
- 3-5 distinct solution paths
|
||||
- Trade-off analysis for each option
|
||||
- Resource requirements and timelines
|
||||
- Risk profiles and success factors
|
||||
|
||||
**Recommended Strategy**:
|
||||
- Detailed recommendation with clear rationale
|
||||
- Step-by-step implementation approach
|
||||
- Resource allocation and timeline
|
||||
- Success criteria and validation methods
|
||||
|
||||
**Risk Assessment**:
|
||||
- Technical risks and mitigation strategies
|
||||
- Business risks and contingency plans
|
||||
- Team and organizational challenges
|
||||
- External dependencies and uncertainties
|
||||
|
||||
## Advanced Usage Patterns
|
||||
|
||||
### 1. Multi-Phase Analysis
|
||||
|
||||
**Phase 1: Problem Exploration**
|
||||
```json
|
||||
{
|
||||
"name": "thinkdeep",
|
||||
"arguments": {
|
||||
"current_analysis": "Initial problem statement and context",
|
||||
"focus_areas": ["problem_definition", "requirements_analysis"],
|
||||
"thinking_mode": "high"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Phase 2: Solution Development**
|
||||
```json
|
||||
{
|
||||
"name": "thinkdeep",
|
||||
"arguments": {
|
||||
"current_analysis": "Previous analysis findings + refined problem definition",
|
||||
"focus_areas": ["solution_design", "architecture", "implementation"],
|
||||
"continuation_id": "previous-analysis-id",
|
||||
"thinking_mode": "max"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Phase 3: Implementation Planning**
|
||||
```json
|
||||
{
|
||||
"name": "thinkdeep",
|
||||
"arguments": {
|
||||
"current_analysis": "Chosen solution approach + design details",
|
||||
"focus_areas": ["implementation_strategy", "risk_mitigation", "timeline"],
|
||||
"continuation_id": "previous-analysis-id",
|
||||
"thinking_mode": "high"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Adversarial Analysis
|
||||
|
||||
**Primary Analysis**:
|
||||
```json
|
||||
{
|
||||
"name": "thinkdeep",
|
||||
"arguments": {
|
||||
"current_analysis": "Proposed solution with detailed rationale",
|
||||
"focus_areas": ["solution_validation", "feasibility"],
|
||||
"thinking_mode": "high",
|
||||
"temperature": 0.4
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Devil's Advocate Review**:
|
||||
```json
|
||||
{
|
||||
"name": "thinkdeep",
|
||||
"arguments": {
|
||||
"current_analysis": "Previous analysis + instruction to challenge assumptions and find flaws",
|
||||
"focus_areas": ["risk_analysis", "failure_modes", "alternative_perspectives"],
|
||||
"continuation_id": "primary-analysis-id",
|
||||
"thinking_mode": "high",
|
||||
"temperature": 0.6
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Collaborative Decision Making
|
||||
|
||||
**Technical Analysis**:
|
||||
```json
|
||||
{
|
||||
"name": "thinkdeep",
|
||||
"arguments": {
|
||||
"current_analysis": "Technical requirements and constraints",
|
||||
"focus_areas": ["technical_feasibility", "architecture", "performance"],
|
||||
"thinking_mode": "high"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Business Analysis**:
|
||||
```json
|
||||
{
|
||||
"name": "thinkdeep",
|
||||
"arguments": {
|
||||
"current_analysis": "Technical findings + business context",
|
||||
"focus_areas": ["business_value", "cost_benefit", "strategic_alignment"],
|
||||
"continuation_id": "technical-analysis-id",
|
||||
"thinking_mode": "high"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Integration with Other Tools
|
||||
|
||||
### ThinkDeep → CodeReview Flow
|
||||
|
||||
```json
|
||||
// 1. Strategic analysis
|
||||
{
|
||||
"name": "thinkdeep",
|
||||
"arguments": {
|
||||
"current_analysis": "Need to refactor authentication system for better security",
|
||||
"focus_areas": ["security", "architecture"]
|
||||
}
|
||||
}
|
||||
|
||||
// 2. Detailed code review based on strategic insights
|
||||
{
|
||||
"name": "codereview",
|
||||
"arguments": {
|
||||
"files": ["/workspace/auth/"],
|
||||
"context": "Strategic analysis identified need for security-focused refactoring",
|
||||
"review_type": "security",
|
||||
"continuation_id": "strategic-analysis-id"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### ThinkDeep → Analyze Flow
|
||||
|
||||
```json
|
||||
// 1. High-level strategy
|
||||
{
|
||||
"name": "thinkdeep",
|
||||
"arguments": {
|
||||
"current_analysis": "System performance issues under high load",
|
||||
"focus_areas": ["performance", "scalability"]
|
||||
}
|
||||
}
|
||||
|
||||
// 2. Detailed codebase analysis
|
||||
{
|
||||
"name": "analyze",
|
||||
"arguments": {
|
||||
"files": ["/workspace/"],
|
||||
"question": "Identify performance bottlenecks based on strategic analysis",
|
||||
"analysis_type": "performance",
|
||||
"continuation_id": "strategy-analysis-id"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Performance Characteristics
|
||||
|
||||
### Response Times by Thinking Mode
|
||||
- **medium**: 4-8 seconds (unusual for thinkdeep)
|
||||
- **high**: 8-15 seconds (recommended default)
|
||||
- **max**: 15-30 seconds (comprehensive analysis)
|
||||
|
||||
### Quality Indicators
|
||||
- **Depth**: Number of alternatives considered
|
||||
- **Breadth**: Range of focus areas covered
|
||||
- **Precision**: Specificity of recommendations
|
||||
- **Actionability**: Clarity of next steps
|
||||
|
||||
### Resource Usage
|
||||
- **Memory**: 200-500MB per analysis session
|
||||
- **Network**: High (extensive Gemini API usage)
|
||||
- **Storage**: Redis conversation persistence (48h TTL for complex analyses)
|
||||
- **CPU**: Low (primarily network I/O bound)
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Effective Analysis Prompts
|
||||
|
||||
**Provide Rich Context**:
|
||||
```
|
||||
Current Analysis:
|
||||
We're designing a real-time collaborative editing system like Google Docs.
|
||||
Key requirements:
|
||||
- Support 1000+ concurrent users per document
|
||||
- Sub-100ms latency for edits
|
||||
- Conflict resolution for simultaneous edits
|
||||
- Offline support with sync
|
||||
|
||||
Current challenges:
|
||||
- Operational Transform vs CRDT decision
|
||||
- Server architecture (centralized vs distributed)
|
||||
- Client-side performance with large documents
|
||||
- Database design for version history
|
||||
|
||||
Constraints:
|
||||
- Team of 8 developers (2 senior, 6 mid-level)
|
||||
- 6-month timeline
|
||||
- Cloud-first deployment (AWS/Azure)
|
||||
- Must integrate with existing authentication system
|
||||
```
|
||||
|
||||
**Focus on Decisions**:
|
||||
- Frame analysis around specific decisions that need to be made
|
||||
- Include decision criteria and trade-offs
|
||||
- Mention stakeholders and their priorities
|
||||
- Reference timeline and resource constraints
|
||||
|
||||
### Conversation Management
|
||||
|
||||
1. **Use Continuation for Related Analyses**: Build complex understanding over multiple calls
|
||||
2. **Reference Previous Insights**: Explicitly connect new analysis to previous findings
|
||||
3. **Validate Assumptions**: Use follow-up calls to challenge and refine thinking
|
||||
4. **Document Decisions**: Capture key insights for future reference
|
||||
|
||||
### Quality Optimization
|
||||
|
||||
1. **Match Thinking Mode to Complexity**: Use 'max' only for truly complex decisions
|
||||
2. **Balance Temperature**: Lower for critical systems, higher for innovation
|
||||
3. **Iterative Refinement**: Multiple focused analyses often better than single broad one
|
||||
4. **Cross-Validation**: Use adversarial analysis for critical decisions
|
||||
|
||||
---
|
||||
|
||||
The ThinkDeep Tool serves as your strategic thinking partner, providing comprehensive analysis and creative problem-solving capabilities for the most challenging technical and architectural decisions.
|
||||
379
docs/architecture/components.md
Normal file
379
docs/architecture/components.md
Normal file
@@ -0,0 +1,379 @@
|
||||
# System Components & Interactions
|
||||
|
||||
## Component Architecture
|
||||
|
||||
The Gemini MCP Server is built on a modular component architecture that enables sophisticated AI collaboration patterns while maintaining security and performance.
|
||||
|
||||
## Core Components
|
||||
|
||||
### 1. MCP Protocol Engine
|
||||
|
||||
**Location**: `server.py:45-120`
|
||||
**Purpose**: Central communication hub implementing Model Context Protocol specification
|
||||
|
||||
**Key Responsibilities**:
|
||||
- **Protocol Compliance**: Implements MCP v1.0 specification for Claude integration
|
||||
- **Message Routing**: Dispatches requests to appropriate tool handlers
|
||||
- **Error Handling**: Graceful degradation and error response formatting
|
||||
- **Lifecycle Management**: Server startup, shutdown, and resource cleanup
|
||||
|
||||
**Implementation Details**:
|
||||
```python
|
||||
# server.py:67
|
||||
@server.list_tools()
|
||||
async def list_tools() -> list[types.Tool]:
|
||||
"""Dynamic tool discovery and registration"""
|
||||
return [tool.get_schema() for tool in REGISTERED_TOOLS]
|
||||
|
||||
@server.call_tool()
|
||||
async def call_tool(name: str, arguments: dict) -> list[types.TextContent]:
|
||||
"""Tool execution with error handling and response formatting"""
|
||||
```
|
||||
|
||||
**Dependencies**:
|
||||
- `mcp` library for protocol implementation
|
||||
- `asyncio` for concurrent request processing
|
||||
- Tool registry for dynamic handler discovery
|
||||
|
||||
### 2. Tool Architecture System
|
||||
|
||||
**Location**: `tools/` directory
|
||||
**Purpose**: Modular plugin system for specialized AI capabilities
|
||||
|
||||
#### BaseTool Abstract Class (`tools/base.py:25`)
|
||||
|
||||
**Interface Contract**:
|
||||
```python
|
||||
class BaseTool(ABC):
|
||||
@abstractmethod
|
||||
async def execute(self, request: dict) -> ToolOutput:
|
||||
"""Core tool execution logic"""
|
||||
|
||||
@abstractmethod
|
||||
def get_schema(self) -> types.Tool:
|
||||
"""MCP tool schema definition"""
|
||||
|
||||
def _format_response(self, content: str, metadata: dict) -> ToolOutput:
|
||||
"""Standardized response formatting"""
|
||||
```
|
||||
|
||||
#### Individual Tool Components
|
||||
|
||||
**Chat Tool** (`tools/chat.py:30`)
|
||||
- **Purpose**: Quick questions and general collaboration
|
||||
- **Thinking Mode**: Default 'medium' (8192 tokens)
|
||||
- **Use Cases**: Brainstorming, simple explanations, immediate answers
|
||||
|
||||
**ThinkDeep Tool** (`tools/thinkdeep.py:45`)
|
||||
- **Purpose**: Complex analysis and strategic planning
|
||||
- **Thinking Mode**: Default 'high' (16384 tokens)
|
||||
- **Use Cases**: Architecture decisions, design exploration, comprehensive analysis
|
||||
|
||||
**CodeReview Tool** (`tools/codereview.py:60`)
|
||||
- **Purpose**: Code quality and security analysis
|
||||
- **Thinking Mode**: Default 'medium' (8192 tokens)
|
||||
- **Use Cases**: Bug detection, security audits, quality validation
|
||||
|
||||
**Analyze Tool** (`tools/analyze.py:75`)
|
||||
- **Purpose**: Codebase exploration and understanding
|
||||
- **Thinking Mode**: Variable based on scope
|
||||
- **Use Cases**: Dependency analysis, pattern detection, system comprehension
|
||||
|
||||
**Debug Tool** (`tools/debug.py:90`)
|
||||
- **Purpose**: Error investigation and root cause analysis
|
||||
- **Thinking Mode**: Default 'medium' (8192 tokens)
|
||||
- **Use Cases**: Stack trace analysis, bug diagnosis, performance issues
|
||||
|
||||
**Precommit Tool** (`tools/precommit.py:105`)
|
||||
- **Purpose**: Automated quality gates and validation
|
||||
- **Thinking Mode**: Default 'medium' (8192 tokens)
|
||||
- **Use Cases**: Pre-commit validation, change analysis, quality assurance
|
||||
|
||||
### 3. Security Engine
|
||||
|
||||
**Location**: `utils/file_utils.py:45-120`
|
||||
**Purpose**: Multi-layer security validation and enforcement
|
||||
|
||||
#### Security Components
|
||||
|
||||
**Path Validation System**:
|
||||
```python
|
||||
# utils/file_utils.py:67
|
||||
def validate_file_path(file_path: str) -> bool:
|
||||
"""Multi-layer path security validation"""
|
||||
# 1. Dangerous path detection
|
||||
dangerous_patterns = ['../', '~/', '/etc/', '/var/', '/usr/']
|
||||
if any(pattern in file_path for pattern in dangerous_patterns):
|
||||
return False
|
||||
|
||||
# 2. Absolute path requirement
|
||||
if not os.path.isabs(file_path):
|
||||
return False
|
||||
|
||||
# 3. Sandbox boundary enforcement
|
||||
return file_path.startswith(PROJECT_ROOT)
|
||||
```
|
||||
|
||||
**Docker Path Translation**:
|
||||
```python
|
||||
# utils/file_utils.py:89
|
||||
def translate_docker_path(host_path: str) -> str:
|
||||
"""Convert host paths to container paths for Docker environment"""
|
||||
if host_path.startswith(WORKSPACE_ROOT):
|
||||
return host_path.replace(WORKSPACE_ROOT, '/workspace', 1)
|
||||
return host_path
|
||||
```
|
||||
|
||||
**Security Layers**:
|
||||
1. **Input Sanitization**: Path cleaning and normalization
|
||||
2. **Pattern Matching**: Dangerous path detection and blocking
|
||||
3. **Boundary Enforcement**: PROJECT_ROOT containment validation
|
||||
4. **Container Translation**: Safe host-to-container path mapping
|
||||
|
||||
### 4. Conversation Memory System
|
||||
|
||||
**Location**: `utils/conversation_memory.py:30-150`
|
||||
**Purpose**: Cross-session context preservation and threading
|
||||
|
||||
#### Memory Components
|
||||
|
||||
**Thread Context Management**:
|
||||
```python
|
||||
# utils/conversation_memory.py:45
|
||||
class ThreadContext:
|
||||
thread_id: str
|
||||
tool_history: List[ToolExecution]
|
||||
conversation_files: Set[str]
|
||||
context_tokens: int
|
||||
created_at: datetime
|
||||
last_accessed: datetime
|
||||
```
|
||||
|
||||
**Redis Integration**:
|
||||
```python
|
||||
# utils/conversation_memory.py:78
|
||||
class ConversationMemory:
|
||||
def __init__(self, redis_url: str):
|
||||
self.redis = redis.from_url(redis_url)
|
||||
|
||||
async def store_thread(self, context: ThreadContext) -> None:
|
||||
"""Persist conversation thread to Redis"""
|
||||
|
||||
async def retrieve_thread(self, thread_id: str) -> Optional[ThreadContext]:
|
||||
"""Reconstruct conversation from storage"""
|
||||
|
||||
async def cleanup_expired_threads(self) -> int:
|
||||
"""Remove old conversations to manage memory"""
|
||||
```
|
||||
|
||||
**Memory Features**:
|
||||
- **Thread Persistence**: UUID-based conversation storage
|
||||
- **Context Reconstruction**: Full conversation history retrieval
|
||||
- **File Deduplication**: Efficient storage of repeated file references
|
||||
- **Automatic Cleanup**: Time-based thread expiration
|
||||
|
||||
### 5. File Processing Pipeline
|
||||
|
||||
**Location**: `utils/file_utils.py:120-200`
|
||||
**Purpose**: Token-aware file reading and content optimization
|
||||
|
||||
#### Processing Components
|
||||
|
||||
**Priority System**:
|
||||
```python
|
||||
# utils/file_utils.py:134
|
||||
FILE_PRIORITIES = {
|
||||
'.py': 1, # Python source code (highest priority)
|
||||
'.js': 1, # JavaScript source
|
||||
'.ts': 1, # TypeScript source
|
||||
'.md': 2, # Documentation
|
||||
'.txt': 3, # Text files
|
||||
'.log': 4, # Log files (lowest priority)
|
||||
}
|
||||
```
|
||||
|
||||
**Token Management**:
|
||||
```python
|
||||
# utils/file_utils.py:156
|
||||
def read_file_with_token_limit(file_path: str, max_tokens: int) -> str:
|
||||
"""Read file content with token budget enforcement"""
|
||||
try:
|
||||
with open(file_path, 'r', encoding='utf-8') as f:
|
||||
content = f.read()
|
||||
|
||||
# Token estimation and truncation
|
||||
estimated_tokens = len(content) // 4 # Rough estimation
|
||||
if estimated_tokens > max_tokens:
|
||||
# Truncate with preservation of structure
|
||||
content = content[:max_tokens * 4]
|
||||
|
||||
return format_file_content(content, file_path)
|
||||
except Exception as e:
|
||||
return f"Error reading {file_path}: {str(e)}"
|
||||
```
|
||||
|
||||
**Content Formatting**:
|
||||
- **Line Numbers**: Added for precise code references
|
||||
- **Error Handling**: Graceful failure with informative messages
|
||||
- **Structure Preservation**: Maintains code formatting and indentation
|
||||
|
||||
### 6. Gemini API Integration
|
||||
|
||||
**Location**: `tools/models.py:25-80`
|
||||
**Purpose**: Standardized interface to Google's Gemini models
|
||||
|
||||
#### Integration Components
|
||||
|
||||
**API Client**:
|
||||
```python
|
||||
# tools/models.py:34
|
||||
class GeminiClient:
|
||||
def __init__(self, api_key: str, model: str = "gemini-2.0-flash-thinking-exp"):
|
||||
self.client = genai.GenerativeModel(model)
|
||||
self.api_key = api_key
|
||||
|
||||
async def generate_response(self,
|
||||
prompt: str,
|
||||
thinking_mode: str = 'medium',
|
||||
files: List[str] = None) -> str:
|
||||
"""Generate response with thinking mode and file context"""
|
||||
```
|
||||
|
||||
**Model Configuration**:
|
||||
```python
|
||||
# config.py:24
|
||||
GEMINI_MODEL = os.getenv('GEMINI_MODEL', 'gemini-2.0-flash-thinking-exp')
|
||||
MAX_CONTEXT_TOKENS = int(os.getenv('MAX_CONTEXT_TOKENS', '1000000'))
|
||||
```
|
||||
|
||||
**Thinking Mode Management**:
|
||||
```python
|
||||
# tools/models.py:67
|
||||
THINKING_MODE_TOKENS = {
|
||||
'minimal': 128,
|
||||
'low': 2048,
|
||||
'medium': 8192,
|
||||
'high': 16384,
|
||||
'max': 32768
|
||||
}
|
||||
```
|
||||
|
||||
## Component Interactions
|
||||
|
||||
### 1. Request Processing Flow
|
||||
|
||||
```
|
||||
Claude Request
|
||||
↓
|
||||
MCP Protocol Engine (server.py:67)
|
||||
↓ (validate & route)
|
||||
Tool Selection & Loading
|
||||
↓
|
||||
Security Validation (utils/file_utils.py:67)
|
||||
↓ (if files involved)
|
||||
File Processing Pipeline (utils/file_utils.py:134)
|
||||
↓
|
||||
Conversation Context Loading (utils/conversation_memory.py:78)
|
||||
↓ (if continuation_id provided)
|
||||
Gemini API Integration (tools/models.py:34)
|
||||
↓
|
||||
Response Processing & Formatting
|
||||
↓
|
||||
Conversation Storage (utils/conversation_memory.py:78)
|
||||
↓
|
||||
MCP Response to Claude
|
||||
```
|
||||
|
||||
### 2. Security Integration Points
|
||||
|
||||
**Pre-Tool Execution**:
|
||||
- Path validation before any file operations
|
||||
- Sandbox boundary enforcement
|
||||
- Docker path translation for container environments
|
||||
|
||||
**During Tool Execution**:
|
||||
- Token budget enforcement to prevent memory exhaustion
|
||||
- File access logging and monitoring
|
||||
- Error containment and graceful degradation
|
||||
|
||||
**Post-Tool Execution**:
|
||||
- Response sanitization
|
||||
- Conversation storage with access controls
|
||||
- Resource cleanup and memory management
|
||||
|
||||
### 3. Memory System Integration
|
||||
|
||||
**Thread Creation**:
|
||||
```python
|
||||
# New conversation
|
||||
thread_id = str(uuid.uuid4())
|
||||
context = ThreadContext(thread_id=thread_id, ...)
|
||||
await memory.store_thread(context)
|
||||
```
|
||||
|
||||
**Thread Continuation**:
|
||||
```python
|
||||
# Continuing conversation
|
||||
if continuation_id:
|
||||
context = await memory.retrieve_thread(continuation_id)
|
||||
# Merge new request with existing context
|
||||
```
|
||||
|
||||
**Cross-Tool Communication**:
|
||||
```python
|
||||
# Tool A stores findings
|
||||
await memory.add_tool_execution(thread_id, tool_execution)
|
||||
|
||||
# Tool B retrieves context
|
||||
context = await memory.retrieve_thread(thread_id)
|
||||
previous_findings = context.get_tool_outputs('analyze')
|
||||
```
|
||||
|
||||
## Configuration & Dependencies
|
||||
|
||||
### Environment Configuration
|
||||
|
||||
**Required Settings** (`config.py`):
|
||||
```python
|
||||
GEMINI_API_KEY = os.getenv('GEMINI_API_KEY') # Required
|
||||
GEMINI_MODEL = os.getenv('GEMINI_MODEL', 'gemini-2.0-flash-thinking-exp')
|
||||
PROJECT_ROOT = os.getenv('PROJECT_ROOT', '/workspace')
|
||||
REDIS_URL = os.getenv('REDIS_URL', 'redis://localhost:6379')
|
||||
MAX_CONTEXT_TOKENS = int(os.getenv('MAX_CONTEXT_TOKENS', '1000000'))
|
||||
```
|
||||
|
||||
### Component Dependencies
|
||||
|
||||
**Core Dependencies**:
|
||||
- `mcp`: MCP protocol implementation
|
||||
- `google-generativeai`: Gemini API client
|
||||
- `redis`: Conversation persistence
|
||||
- `asyncio`: Concurrent processing
|
||||
|
||||
**Security Dependencies**:
|
||||
- `pathlib`: Path manipulation and validation
|
||||
- `os`: File system operations and environment access
|
||||
|
||||
**Tool Dependencies**:
|
||||
- `pydantic`: Data validation and serialization
|
||||
- `typing`: Type hints and contract definition
|
||||
|
||||
## Extension Architecture
|
||||
|
||||
### Adding New Components
|
||||
|
||||
1. **Tool Components**: Inherit from BaseTool and implement required interface
|
||||
2. **Security Components**: Extend validation chain in file_utils.py
|
||||
3. **Memory Components**: Add new storage backends via interface abstraction
|
||||
4. **Processing Components**: Extend file pipeline with new content types
|
||||
|
||||
### Integration Patterns
|
||||
|
||||
- **Plugin Architecture**: Dynamic discovery and registration
|
||||
- **Interface Segregation**: Clear contracts between components
|
||||
- **Dependency Injection**: Configuration-driven component assembly
|
||||
- **Error Boundaries**: Isolated failure handling per component
|
||||
|
||||
---
|
||||
|
||||
This component architecture provides a robust foundation for AI collaboration while maintaining security, performance, and extensibility requirements.
|
||||
545
docs/architecture/data-flow.md
Normal file
545
docs/architecture/data-flow.md
Normal file
@@ -0,0 +1,545 @@
|
||||
# Data Flow & Processing Patterns
|
||||
|
||||
## Overview
|
||||
|
||||
The Gemini MCP Server implements sophisticated data flow patterns that enable secure, efficient, and contextually-aware AI collaboration. This document traces data movement through the system with concrete examples and performance considerations.
|
||||
|
||||
## Primary Data Flow Patterns
|
||||
|
||||
### 1. Standard Tool Execution Flow
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant C as Claude
|
||||
participant M as MCP Engine
|
||||
participant S as Security Layer
|
||||
participant T as Tool Handler
|
||||
participant G as Gemini API
|
||||
participant R as Redis Memory
|
||||
|
||||
C->>M: MCP Request (tool_name, params)
|
||||
M->>M: Validate Request Schema
|
||||
M->>S: Security Validation
|
||||
S->>S: Path Validation & Sanitization
|
||||
S->>T: Secure Parameters
|
||||
T->>R: Load Conversation Context
|
||||
R-->>T: Thread Context (if exists)
|
||||
T->>T: Process Files & Context
|
||||
T->>G: Formatted Prompt + Context
|
||||
G-->>T: AI Response
|
||||
T->>R: Store Execution Result
|
||||
T->>M: Formatted Tool Output
|
||||
M->>C: MCP Response
|
||||
```
|
||||
|
||||
**Example Request Flow**:
|
||||
```json
|
||||
// Claude → MCP Engine
|
||||
{
|
||||
"method": "tools/call",
|
||||
"params": {
|
||||
"name": "analyze",
|
||||
"arguments": {
|
||||
"files": ["/workspace/tools/analyze.py"],
|
||||
"question": "Explain the architecture pattern",
|
||||
"continuation_id": "550e8400-e29b-41d4-a716-446655440000"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. File Processing Pipeline
|
||||
|
||||
#### Stage 1: Security Validation (`utils/file_utils.py:67`)
|
||||
|
||||
```python
|
||||
# Input: ["/workspace/tools/analyze.py", "../../../etc/passwd"]
|
||||
def validate_file_paths(file_paths: List[str]) -> List[str]:
|
||||
validated = []
|
||||
for path in file_paths:
|
||||
# 1. Dangerous pattern detection
|
||||
if any(danger in path for danger in ['../', '~/', '/etc/', '/var/']):
|
||||
logger.warning(f"Blocked dangerous path: {path}")
|
||||
continue
|
||||
|
||||
# 2. Absolute path requirement
|
||||
if not os.path.isabs(path):
|
||||
path = os.path.abspath(path)
|
||||
|
||||
# 3. Sandbox boundary check
|
||||
if not path.startswith(PROJECT_ROOT):
|
||||
logger.warning(f"Path outside sandbox: {path}")
|
||||
continue
|
||||
|
||||
validated.append(path)
|
||||
|
||||
return validated
|
||||
# Output: ["/workspace/tools/analyze.py"]
|
||||
```
|
||||
|
||||
#### Stage 2: Docker Path Translation (`utils/file_utils.py:89`)
|
||||
|
||||
```python
|
||||
# Host Environment: /Users/user/project/tools/analyze.py
|
||||
# Container Environment: /workspace/tools/analyze.py
|
||||
def translate_paths_for_environment(paths: List[str]) -> List[str]:
|
||||
translated = []
|
||||
for path in paths:
|
||||
if WORKSPACE_ROOT and path.startswith(WORKSPACE_ROOT):
|
||||
container_path = path.replace(WORKSPACE_ROOT, '/workspace', 1)
|
||||
translated.append(container_path)
|
||||
else:
|
||||
translated.append(path)
|
||||
return translated
|
||||
```
|
||||
|
||||
#### Stage 3: Priority-Based Processing (`utils/file_utils.py:134`)
|
||||
|
||||
```python
|
||||
# File Priority Matrix
|
||||
FILE_PRIORITIES = {
|
||||
'.py': 1, # Source code (highest priority)
|
||||
'.js': 1, '.ts': 1, '.tsx': 1,
|
||||
'.md': 2, # Documentation
|
||||
'.json': 2, '.yaml': 2, '.yml': 2,
|
||||
'.txt': 3, # Text files
|
||||
'.log': 4, # Logs (lowest priority)
|
||||
}
|
||||
|
||||
# Token Budget Allocation
|
||||
def allocate_token_budget(files: List[str], total_budget: int) -> Dict[str, int]:
|
||||
# Priority 1 files get 60% of budget
|
||||
# Priority 2 files get 30% of budget
|
||||
# Priority 3+ files get 10% of budget
|
||||
|
||||
priority_groups = defaultdict(list)
|
||||
for file in files:
|
||||
ext = Path(file).suffix.lower()
|
||||
priority = FILE_PRIORITIES.get(ext, 4)
|
||||
priority_groups[priority].append(file)
|
||||
|
||||
allocations = {}
|
||||
if priority_groups[1]: # Source code files
|
||||
code_budget = int(total_budget * 0.6)
|
||||
per_file = code_budget // len(priority_groups[1])
|
||||
for file in priority_groups[1]:
|
||||
allocations[file] = per_file
|
||||
|
||||
if priority_groups[2]: # Documentation files
|
||||
doc_budget = int(total_budget * 0.3)
|
||||
per_file = doc_budget // len(priority_groups[2])
|
||||
for file in priority_groups[2]:
|
||||
allocations[file] = per_file
|
||||
|
||||
return allocations
|
||||
```
|
||||
|
||||
#### Stage 4: Content Processing & Formatting
|
||||
|
||||
```python
|
||||
def process_file_content(file_path: str, token_limit: int) -> str:
|
||||
try:
|
||||
with open(file_path, 'r', encoding='utf-8') as f:
|
||||
content = f.read()
|
||||
|
||||
# Token estimation (rough: 1 token ≈ 4 characters)
|
||||
estimated_tokens = len(content) // 4
|
||||
|
||||
if estimated_tokens > token_limit:
|
||||
# Smart truncation preserving structure
|
||||
lines = content.split('\n')
|
||||
truncated_lines = []
|
||||
current_tokens = 0
|
||||
|
||||
for line in lines:
|
||||
line_tokens = len(line) // 4
|
||||
if current_tokens + line_tokens > token_limit:
|
||||
break
|
||||
truncated_lines.append(line)
|
||||
current_tokens += line_tokens
|
||||
|
||||
content = '\n'.join(truncated_lines)
|
||||
content += f"\n\n... [Truncated at {token_limit} tokens]"
|
||||
|
||||
# Format with line numbers for precise references
|
||||
lines = content.split('\n')
|
||||
formatted_lines = []
|
||||
for i, line in enumerate(lines, 1):
|
||||
formatted_lines.append(f"{i:6d}\t{line}")
|
||||
|
||||
return '\n'.join(formatted_lines)
|
||||
|
||||
except Exception as e:
|
||||
return f"Error reading {file_path}: {str(e)}"
|
||||
```
|
||||
|
||||
### 3. Conversation Memory Flow
|
||||
|
||||
#### Context Storage Pattern (`utils/conversation_memory.py:78`)
|
||||
|
||||
```python
|
||||
# Tool execution creates persistent context
|
||||
async def store_tool_execution(thread_id: str, tool_execution: ToolExecution):
|
||||
context = await self.retrieve_thread(thread_id) or ThreadContext(thread_id)
|
||||
|
||||
# Add new execution to history
|
||||
context.tool_history.append(tool_execution)
|
||||
|
||||
# Update file set (deduplication)
|
||||
if tool_execution.files:
|
||||
context.conversation_files.update(tool_execution.files)
|
||||
|
||||
# Update token tracking
|
||||
context.context_tokens += tool_execution.response_tokens
|
||||
context.last_accessed = datetime.now()
|
||||
|
||||
# Persist to Redis
|
||||
await self.redis.setex(
|
||||
f"thread:{thread_id}",
|
||||
timedelta(hours=24), # 24-hour expiration
|
||||
context.to_json()
|
||||
)
|
||||
```
|
||||
|
||||
#### Context Retrieval & Reconstruction
|
||||
|
||||
```python
|
||||
async def build_conversation_context(thread_id: str) -> str:
|
||||
context = await self.retrieve_thread(thread_id)
|
||||
if not context:
|
||||
return ""
|
||||
|
||||
# Build conversation summary
|
||||
summary_parts = []
|
||||
|
||||
# Add file context (deduplicated)
|
||||
if context.conversation_files:
|
||||
summary_parts.append("## Previous Files Analyzed:")
|
||||
for file_path in sorted(context.conversation_files):
|
||||
summary_parts.append(f"- {file_path}")
|
||||
|
||||
# Add tool execution history
|
||||
if context.tool_history:
|
||||
summary_parts.append("\n## Previous Analysis:")
|
||||
for execution in context.tool_history[-3:]: # Last 3 executions
|
||||
summary_parts.append(f"**{execution.tool_name}**: {execution.summary}")
|
||||
|
||||
return '\n'.join(summary_parts)
|
||||
```
|
||||
|
||||
### 4. Thinking Mode Processing
|
||||
|
||||
#### Dynamic Token Allocation (`tools/models.py:67`)
|
||||
|
||||
```python
|
||||
# Thinking mode determines computational budget
|
||||
THINKING_MODE_TOKENS = {
|
||||
'minimal': 128, # Quick answers, simple questions
|
||||
'low': 2048, # Basic analysis, straightforward tasks
|
||||
'medium': 8192, # Standard analysis, moderate complexity
|
||||
'high': 16384, # Deep analysis, complex problems
|
||||
'max': 32768 # Maximum depth, critical decisions
|
||||
}
|
||||
|
||||
def prepare_gemini_request(prompt: str, thinking_mode: str, files: List[str]) -> dict:
|
||||
# Calculate total context budget
|
||||
thinking_tokens = THINKING_MODE_TOKENS.get(thinking_mode, 8192)
|
||||
file_tokens = MAX_CONTEXT_TOKENS - thinking_tokens - 1000 # Reserve for response
|
||||
|
||||
# Process files within budget
|
||||
file_content = process_files_with_budget(files, file_tokens)
|
||||
|
||||
# Construct final prompt
|
||||
full_prompt = f"""
|
||||
{prompt}
|
||||
|
||||
## Available Context ({thinking_tokens} thinking tokens allocated)
|
||||
|
||||
{file_content}
|
||||
|
||||
Please analyze using {thinking_mode} thinking mode.
|
||||
"""
|
||||
|
||||
return {
|
||||
'prompt': full_prompt,
|
||||
'max_tokens': thinking_tokens,
|
||||
'temperature': 0.2 if thinking_mode in ['high', 'max'] else 0.5
|
||||
}
|
||||
```
|
||||
|
||||
## Advanced Data Flow Patterns
|
||||
|
||||
### 1. Cross-Tool Continuation Flow
|
||||
|
||||
```python
|
||||
# Tool A (analyze) creates foundation
|
||||
analyze_result = await analyze_tool.execute({
|
||||
'files': ['/workspace/tools/'],
|
||||
'question': 'What is the architecture pattern?'
|
||||
})
|
||||
|
||||
# Store context with continuation capability
|
||||
thread_id = str(uuid.uuid4())
|
||||
await memory.store_tool_execution(thread_id, ToolExecution(
|
||||
tool_name='analyze',
|
||||
files=['/workspace/tools/'],
|
||||
summary='Identified MCP plugin architecture pattern',
|
||||
continuation_id=thread_id
|
||||
))
|
||||
|
||||
# Tool B (thinkdeep) continues analysis
|
||||
thinkdeep_result = await thinkdeep_tool.execute({
|
||||
'current_analysis': analyze_result.content,
|
||||
'focus_areas': ['scalability', 'security'],
|
||||
'continuation_id': thread_id # Links to previous context
|
||||
})
|
||||
```
|
||||
|
||||
### 2. Error Recovery & Graceful Degradation
|
||||
|
||||
```python
|
||||
def resilient_file_processing(files: List[str]) -> str:
|
||||
"""Process files with graceful error handling"""
|
||||
results = []
|
||||
|
||||
for file_path in files:
|
||||
try:
|
||||
content = read_file_safely(file_path)
|
||||
results.append(f"=== {file_path} ===\n{content}")
|
||||
except PermissionError:
|
||||
results.append(f"=== {file_path} ===\nERROR: Permission denied")
|
||||
except FileNotFoundError:
|
||||
results.append(f"=== {file_path} ===\nERROR: File not found")
|
||||
except UnicodeDecodeError:
|
||||
# Try binary file detection
|
||||
try:
|
||||
with open(file_path, 'rb') as f:
|
||||
header = f.read(16)
|
||||
if is_binary_file(header):
|
||||
results.append(f"=== {file_path} ===\nBinary file (skipped)")
|
||||
else:
|
||||
results.append(f"=== {file_path} ===\nERROR: Encoding issue")
|
||||
except:
|
||||
results.append(f"=== {file_path} ===\nERROR: Unreadable file")
|
||||
except Exception as e:
|
||||
results.append(f"=== {file_path} ===\nERROR: {str(e)}")
|
||||
|
||||
return '\n\n'.join(results)
|
||||
```
|
||||
|
||||
### 3. Performance Optimization Patterns
|
||||
|
||||
#### Concurrent File Processing
|
||||
|
||||
```python
|
||||
async def process_files_concurrently(files: List[str], token_budget: int) -> str:
|
||||
"""Process multiple files concurrently with shared budget"""
|
||||
|
||||
# Allocate budget per file
|
||||
allocations = allocate_token_budget(files, token_budget)
|
||||
|
||||
# Create processing tasks
|
||||
tasks = []
|
||||
for file_path in files:
|
||||
task = asyncio.create_task(
|
||||
process_single_file(file_path, allocations.get(file_path, 1000))
|
||||
)
|
||||
tasks.append(task)
|
||||
|
||||
# Wait for all files to complete
|
||||
results = await asyncio.gather(*tasks, return_exceptions=True)
|
||||
|
||||
# Combine results, handling exceptions
|
||||
processed_content = []
|
||||
for i, result in enumerate(results):
|
||||
if isinstance(result, Exception):
|
||||
processed_content.append(f"Error processing {files[i]}: {result}")
|
||||
else:
|
||||
processed_content.append(result)
|
||||
|
||||
return '\n\n'.join(processed_content)
|
||||
```
|
||||
|
||||
#### Intelligent Caching
|
||||
|
||||
```python
|
||||
class FileContentCache:
|
||||
def __init__(self, max_size: int = 100):
|
||||
self.cache = {}
|
||||
self.access_times = {}
|
||||
self.max_size = max_size
|
||||
|
||||
async def get_file_content(self, file_path: str, token_limit: int) -> str:
|
||||
# Create cache key including token limit
|
||||
cache_key = f"{file_path}:{token_limit}"
|
||||
|
||||
# Check cache hit
|
||||
if cache_key in self.cache:
|
||||
self.access_times[cache_key] = time.time()
|
||||
return self.cache[cache_key]
|
||||
|
||||
# Process file and cache result
|
||||
content = await process_file_content(file_path, token_limit)
|
||||
|
||||
# Evict oldest entries if cache full
|
||||
if len(self.cache) >= self.max_size:
|
||||
oldest_key = min(self.access_times.keys(),
|
||||
key=lambda k: self.access_times[k])
|
||||
del self.cache[oldest_key]
|
||||
del self.access_times[oldest_key]
|
||||
|
||||
# Store in cache
|
||||
self.cache[cache_key] = content
|
||||
self.access_times[cache_key] = time.time()
|
||||
|
||||
return content
|
||||
```
|
||||
|
||||
## Data Persistence Patterns
|
||||
|
||||
### 1. Redis Thread Storage
|
||||
|
||||
```python
|
||||
# Thread context serialization
|
||||
class ThreadContext:
|
||||
def to_json(self) -> str:
|
||||
return json.dumps({
|
||||
'thread_id': self.thread_id,
|
||||
'tool_history': [ex.to_dict() for ex in self.tool_history],
|
||||
'conversation_files': list(self.conversation_files),
|
||||
'context_tokens': self.context_tokens,
|
||||
'created_at': self.created_at.isoformat(),
|
||||
'last_accessed': self.last_accessed.isoformat()
|
||||
})
|
||||
|
||||
@classmethod
|
||||
def from_json(cls, json_str: str) -> 'ThreadContext':
|
||||
data = json.loads(json_str)
|
||||
context = cls(data['thread_id'])
|
||||
context.tool_history = [
|
||||
ToolExecution.from_dict(ex) for ex in data['tool_history']
|
||||
]
|
||||
context.conversation_files = set(data['conversation_files'])
|
||||
context.context_tokens = data['context_tokens']
|
||||
context.created_at = datetime.fromisoformat(data['created_at'])
|
||||
context.last_accessed = datetime.fromisoformat(data['last_accessed'])
|
||||
return context
|
||||
```
|
||||
|
||||
### 2. Configuration State Management
|
||||
|
||||
```python
|
||||
# Environment-based configuration with validation
|
||||
class Config:
|
||||
def __init__(self):
|
||||
self.gemini_api_key = self._require_env('GEMINI_API_KEY')
|
||||
self.gemini_model = os.getenv('GEMINI_MODEL', 'gemini-2.0-flash-thinking-exp')
|
||||
self.project_root = os.getenv('PROJECT_ROOT', '/workspace')
|
||||
self.redis_url = os.getenv('REDIS_URL', 'redis://localhost:6379')
|
||||
self.max_context_tokens = int(os.getenv('MAX_CONTEXT_TOKENS', '1000000'))
|
||||
|
||||
# Validate critical paths
|
||||
if not os.path.exists(self.project_root):
|
||||
raise ConfigError(f"PROJECT_ROOT does not exist: {self.project_root}")
|
||||
|
||||
def _require_env(self, key: str) -> str:
|
||||
value = os.getenv(key)
|
||||
if not value:
|
||||
raise ConfigError(f"Required environment variable not set: {key}")
|
||||
return value
|
||||
```
|
||||
|
||||
## Security Data Flow
|
||||
|
||||
### 1. Request Sanitization Pipeline
|
||||
|
||||
```python
|
||||
def sanitize_request_data(request: dict) -> dict:
|
||||
"""Multi-layer request sanitization"""
|
||||
sanitized = {}
|
||||
|
||||
# 1. Schema validation
|
||||
validated_data = RequestSchema.parse_obj(request)
|
||||
|
||||
# 2. Path sanitization
|
||||
if 'files' in validated_data:
|
||||
sanitized['files'] = [
|
||||
sanitize_file_path(path) for path in validated_data['files']
|
||||
]
|
||||
|
||||
# 3. Content filtering
|
||||
if 'prompt' in validated_data:
|
||||
sanitized['prompt'] = filter_sensitive_content(validated_data['prompt'])
|
||||
|
||||
# 4. Parameter validation
|
||||
for key, value in validated_data.items():
|
||||
if key not in ['files', 'prompt']:
|
||||
sanitized[key] = validate_parameter(key, value)
|
||||
|
||||
return sanitized
|
||||
```
|
||||
|
||||
### 2. Response Sanitization
|
||||
|
||||
```python
|
||||
def sanitize_response_data(response: str) -> str:
|
||||
"""Remove sensitive information from responses"""
|
||||
|
||||
# Remove potential API keys, tokens, passwords
|
||||
sensitive_patterns = [
|
||||
r'api[_-]?key["\s:=]+[a-zA-Z0-9-_]{20,}',
|
||||
r'token["\s:=]+[a-zA-Z0-9-_]{20,}',
|
||||
r'password["\s:=]+\S+',
|
||||
r'/home/[^/\s]+', # User paths
|
||||
r'[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}', # Emails
|
||||
]
|
||||
|
||||
sanitized = response
|
||||
for pattern in sensitive_patterns:
|
||||
sanitized = re.sub(pattern, '[REDACTED]', sanitized, flags=re.IGNORECASE)
|
||||
|
||||
return sanitized
|
||||
```
|
||||
|
||||
## Performance Monitoring & Metrics
|
||||
|
||||
### 1. Request Processing Metrics
|
||||
|
||||
```python
|
||||
class PerformanceMetrics:
|
||||
def __init__(self):
|
||||
self.request_times = []
|
||||
self.file_processing_times = []
|
||||
self.memory_usage = []
|
||||
self.error_counts = defaultdict(int)
|
||||
|
||||
async def track_request(self, tool_name: str, files: List[str]):
|
||||
start_time = time.time()
|
||||
start_memory = psutil.Process().memory_info().rss
|
||||
|
||||
try:
|
||||
# Process request...
|
||||
yield
|
||||
|
||||
except Exception as e:
|
||||
self.error_counts[f"{tool_name}:{type(e).__name__}"] += 1
|
||||
raise
|
||||
finally:
|
||||
# Record metrics
|
||||
end_time = time.time()
|
||||
end_memory = psutil.Process().memory_info().rss
|
||||
|
||||
self.request_times.append({
|
||||
'tool': tool_name,
|
||||
'duration': end_time - start_time,
|
||||
'file_count': len(files),
|
||||
'timestamp': datetime.now()
|
||||
})
|
||||
|
||||
self.memory_usage.append({
|
||||
'memory_delta': end_memory - start_memory,
|
||||
'timestamp': datetime.now()
|
||||
})
|
||||
```
|
||||
|
||||
This comprehensive data flow documentation provides the foundation for understanding how information moves through the Gemini MCP Server, enabling effective debugging, optimization, and extension of the system.
|
||||
225
docs/architecture/overview.md
Normal file
225
docs/architecture/overview.md
Normal file
@@ -0,0 +1,225 @@
|
||||
# Gemini MCP Server Architecture Overview
|
||||
|
||||
## System Overview
|
||||
|
||||
The **Gemini MCP Server** implements a sophisticated Model Context Protocol (MCP) server architecture that provides Claude with access to Google's Gemini AI models through specialized tools. This enables advanced AI-assisted development workflows combining Claude's general capabilities with Gemini's deep analytical and creative thinking abilities.
|
||||
|
||||
## High-Level Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Claude Interface │
|
||||
│ (Claude Desktop App) │
|
||||
└─────────────────────┬───────────────────────────────────────┘
|
||||
│ MCP Protocol (stdio)
|
||||
┌─────────────────────▼───────────────────────────────────────┐
|
||||
│ MCP Core Engine │
|
||||
│ • AsyncIO Event Loop (server.py:45) │
|
||||
│ • Tool Discovery & Registration │
|
||||
│ • Request/Response Processing │
|
||||
└─────────────────────┬───────────────────────────────────────┘
|
||||
│
|
||||
┌─────────────────────▼───────────────────────────────────────┐
|
||||
│ Tool Architecture │
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||||
│ │ chat │ │ thinkdeep │ │ analyze │ │
|
||||
│ │ (quick Q&A) │ │(deep think) │ │(code review)│ │
|
||||
│ └─────────────┘ └─────────────┘ └─────────────┘ │
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||||
│ │ codereview │ │ debug │ │ precommit │ │
|
||||
│ │(quality) │ │(root cause) │ │(validation) │ │
|
||||
│ └─────────────┘ └─────────────┘ └─────────────┘ │
|
||||
└─────────────────────┬───────────────────────────────────────┘
|
||||
│
|
||||
┌─────────────────────▼───────────────────────────────────────┐
|
||||
│ Support Services │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐│
|
||||
│ │Redis Conversation│ │Security Engine │ │Gemini API ││
|
||||
│ │Memory & Threading│ │Multi-layer │ │Integration ││
|
||||
│ │ │ │Validation │ │ ││
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘│
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Core Components
|
||||
|
||||
### 1. MCP Core Engine (server.py:45)
|
||||
|
||||
**Purpose**: Central coordination hub managing the MCP protocol implementation
|
||||
**Key Components**:
|
||||
- **AsyncIO Event Loop**: Handles concurrent tool execution and request processing
|
||||
- **Tool Discovery**: Dynamic loading and registration via `@server.list_tools()` decorator
|
||||
- **Protocol Management**: MCP message parsing, validation, and response formatting
|
||||
|
||||
**Architecture Pattern**: Event-driven architecture with asyncio for non-blocking operations
|
||||
|
||||
### 2. Tool System Architecture
|
||||
|
||||
**Purpose**: Modular plugin system for specialized AI capabilities
|
||||
**Key Components**:
|
||||
- **BaseTool Abstract Class** (`tools/base.py:25`): Common interface for all tools
|
||||
- **Plugin Architecture**: Individual tool implementations in `tools/` directory
|
||||
- **Tool Selection Matrix**: CLAUDE.md defines appropriate tool usage patterns
|
||||
|
||||
**Data Flow**:
|
||||
```
|
||||
Claude Request → MCP Engine → Tool Selection → Gemini API → Response Processing → Claude
|
||||
```
|
||||
|
||||
**Tool Categories**:
|
||||
- **Quick Response**: `chat` - immediate answers and brainstorming
|
||||
- **Deep Analysis**: `thinkdeep` - complex architecture and strategic planning
|
||||
- **Code Quality**: `codereview` - security audits and bug detection
|
||||
- **Investigation**: `debug` - root cause analysis and error investigation
|
||||
- **Exploration**: `analyze` - codebase comprehension and dependency analysis
|
||||
- **Validation**: `precommit` - automated quality gates
|
||||
|
||||
### 3. Security Architecture
|
||||
|
||||
**Purpose**: Multi-layer defense system protecting against malicious operations
|
||||
**Key Components**:
|
||||
- **Path Validation** (`utils/file_utils.py:45`): Prevents directory traversal attacks
|
||||
- **Sandbox Enforcement**: PROJECT_ROOT containment for file operations
|
||||
- **Docker Path Translation**: Host-to-container path mapping with WORKSPACE_ROOT
|
||||
- **Absolute Path Requirement**: Eliminates relative path vulnerabilities
|
||||
|
||||
**Security Layers**:
|
||||
1. **Input Validation**: Path sanitization and dangerous operation detection
|
||||
2. **Container Isolation**: Docker environment with controlled file access
|
||||
3. **Permission Boundaries**: Read-only access patterns with explicit write gates
|
||||
4. **Error Recovery**: Graceful handling of unauthorized operations
|
||||
|
||||
### 4. Thinking Modes System
|
||||
|
||||
**Purpose**: Computational budget control for Gemini's analysis depth
|
||||
**Implementation**:
|
||||
- **Token Allocation**: `minimal (128), low (2048), medium (8192), high (16384), max (32768)`
|
||||
- **Dynamic Selection**: Tools adjust thinking depth based on task complexity
|
||||
- **Resource Management**: Prevents token exhaustion on complex analysis
|
||||
|
||||
**Usage Pattern**:
|
||||
```python
|
||||
# tools/thinkdeep.py:67
|
||||
thinking_mode = request.get('thinking_mode', 'high')
|
||||
context_tokens = THINKING_MODE_TOKENS[thinking_mode]
|
||||
```
|
||||
|
||||
### 5. Conversation System
|
||||
|
||||
**Purpose**: Cross-session context preservation and threading
|
||||
**Key Components**:
|
||||
- **Redis Persistence** (`utils/conversation_memory.py:30`): Thread storage and retrieval
|
||||
- **Thread Reconstruction**: UUID-based conversation continuity
|
||||
- **Cross-Tool Continuation**: `continuation_id` parameter for context flow
|
||||
- **Follow-up Management**: Structured multi-turn conversation support
|
||||
|
||||
**Data Structures**:
|
||||
```python
|
||||
# utils/conversation_memory.py:45
|
||||
class ThreadContext:
|
||||
thread_id: str
|
||||
tool_history: List[ToolExecution]
|
||||
conversation_files: List[str]
|
||||
context_tokens: int
|
||||
```
|
||||
|
||||
## Integration Points
|
||||
|
||||
### Configuration Management (config.py)
|
||||
|
||||
**Critical Settings**:
|
||||
- **`GEMINI_MODEL`** (config.py:24): Model selection for API calls
|
||||
- **`MAX_CONTEXT_TOKENS`** (config.py:30): Token limits for conversation management
|
||||
- **`REDIS_URL`** (config.py:60): Conversation memory backend
|
||||
- **`PROJECT_ROOT`** (config.py:15): Security sandbox boundary
|
||||
|
||||
### Utility Services
|
||||
|
||||
**File Operations** (`utils/file_utils.py`):
|
||||
- Token-aware reading with priority system
|
||||
- Directory expansion with filtering
|
||||
- Error-resistant content formatting
|
||||
|
||||
**Git Integration** (`utils/git_utils.py`):
|
||||
- Repository state analysis for precommit validation
|
||||
- Change detection for documentation updates
|
||||
- Branch and commit tracking
|
||||
|
||||
**Token Management** (`utils/token_utils.py`):
|
||||
- Context optimization and pruning
|
||||
- File prioritization strategies
|
||||
- Memory usage monitoring
|
||||
|
||||
## Data Flow Patterns
|
||||
|
||||
### 1. Tool Execution Flow
|
||||
|
||||
```
|
||||
1. Claude sends MCP request with tool name and parameters
|
||||
2. MCP Engine validates request and routes to appropriate tool
|
||||
3. Tool loads conversation context from Redis (if continuation_id provided)
|
||||
4. Tool processes request using Gemini API with thinking mode configuration
|
||||
5. Tool stores results in conversation memory and returns formatted response
|
||||
6. MCP Engine serializes response and sends to Claude via stdio
|
||||
```
|
||||
|
||||
### 2. File Processing Pipeline
|
||||
|
||||
```
|
||||
1. File paths received and validated against security rules
|
||||
2. Docker path translation (host → container mapping)
|
||||
3. Token budget allocation based on file size and context limits
|
||||
4. Priority-based file reading (code files > documentation > logs)
|
||||
5. Content formatting with line numbers and error handling
|
||||
6. Context assembly with deduplication across conversation turns
|
||||
```
|
||||
|
||||
### 3. Security Validation Chain
|
||||
|
||||
```
|
||||
1. Path Input → Dangerous Path Detection → Rejection/Sanitization
|
||||
2. Validated Path → Absolute Path Conversion → Sandbox Boundary Check
|
||||
3. Bounded Path → Docker Translation → Container Path Generation
|
||||
4. Safe Path → File Operation → Error-Resistant Content Return
|
||||
```
|
||||
|
||||
## Performance Characteristics
|
||||
|
||||
### Scalability Factors
|
||||
|
||||
- **Concurrent Tool Execution**: AsyncIO enables parallel processing of multiple tool requests
|
||||
- **Memory Efficiency**: Token-aware file processing prevents memory exhaustion
|
||||
- **Context Optimization**: Conversation deduplication reduces redundant processing
|
||||
- **Error Resilience**: Graceful degradation maintains functionality during failures
|
||||
|
||||
### Resource Management
|
||||
|
||||
- **Token Budgeting**: 40% context reservation (30% Memory Bank + 10% Memory MCP)
|
||||
- **File Prioritization**: Direct code files prioritized over supporting documentation
|
||||
- **Redis Optimization**: Thread-based storage with automatic cleanup
|
||||
- **Gemini API Efficiency**: Thinking mode selection optimizes computational costs
|
||||
|
||||
## Extension Points
|
||||
|
||||
### Adding New Tools
|
||||
|
||||
1. **Inherit from BaseTool** (`tools/base.py:25`)
|
||||
2. **Implement required methods**: `execute()`, `get_schema()`
|
||||
3. **Register with MCP Engine**: Add to tool discovery system
|
||||
4. **Update CLAUDE.md**: Define collaboration patterns and usage guidelines
|
||||
|
||||
### Security Extensions
|
||||
|
||||
1. **Custom Validators**: Add to `utils/file_utils.py` validation chain
|
||||
2. **Path Translators**: Extend Docker path mapping for new mount points
|
||||
3. **Permission Gates**: Implement granular access controls for sensitive operations
|
||||
|
||||
### Performance Optimizations
|
||||
|
||||
1. **Caching Layers**: Add Redis caching for frequently accessed files
|
||||
2. **Context Compression**: Implement intelligent context summarization
|
||||
3. **Parallel Processing**: Extend AsyncIO patterns for I/O-bound operations
|
||||
|
||||
---
|
||||
|
||||
This architecture provides a robust, secure, and extensible foundation for AI-assisted development workflows while maintaining clear separation of concerns and comprehensive error handling.
|
||||
602
docs/contributing/code-style.md
Normal file
602
docs/contributing/code-style.md
Normal file
@@ -0,0 +1,602 @@
|
||||
# Code Style Guide
|
||||
|
||||
## Overview
|
||||
|
||||
This document establishes coding standards and style guidelines for the Gemini MCP Server project. Consistent code style improves readability, maintainability, and collaboration efficiency.
|
||||
|
||||
## Python Style Guidelines
|
||||
|
||||
### PEP 8 Compliance
|
||||
|
||||
**Base Standard**: Follow [PEP 8](https://peps.python.org/pep-0008/) as the foundation for all Python code.
|
||||
|
||||
**Automated Formatting**: Use Black formatter with default settings:
|
||||
```bash
|
||||
black tools/ utils/ tests/ --line-length 88
|
||||
```
|
||||
|
||||
**Line Length**: 88 characters (Black default)
|
||||
```python
|
||||
# Good
|
||||
result = some_function_with_long_name(
|
||||
parameter_one, parameter_two, parameter_three
|
||||
)
|
||||
|
||||
# Avoid
|
||||
result = some_function_with_long_name(parameter_one, parameter_two, parameter_three)
|
||||
```
|
||||
|
||||
### Import Organization
|
||||
|
||||
**Import Order** (enforced by isort):
|
||||
```python
|
||||
# 1. Standard library imports
|
||||
import asyncio
|
||||
import json
|
||||
import os
|
||||
from pathlib import Path
|
||||
from typing import Dict, List, Optional
|
||||
|
||||
# 2. Third-party imports
|
||||
import redis
|
||||
from pydantic import BaseModel
|
||||
|
||||
# 3. Local application imports
|
||||
from tools.base import BaseTool
|
||||
from utils.file_utils import validate_file_path
|
||||
```
|
||||
|
||||
**Import Formatting**:
|
||||
```python
|
||||
# Good - Explicit imports
|
||||
from typing import Dict, List, Optional
|
||||
from utils.conversation_memory import ThreadContext, ConversationMemory
|
||||
|
||||
# Avoid - Wildcard imports
|
||||
from utils.conversation_memory import *
|
||||
```
|
||||
|
||||
### Naming Conventions
|
||||
|
||||
**Functions and Variables**: snake_case
|
||||
```python
|
||||
def process_file_content(file_path: str) -> str:
|
||||
context_tokens = calculate_token_count(content)
|
||||
return formatted_content
|
||||
```
|
||||
|
||||
**Classes**: PascalCase
|
||||
```python
|
||||
class GeminiClient:
|
||||
pass
|
||||
|
||||
class ThreadContext:
|
||||
pass
|
||||
```
|
||||
|
||||
**Constants**: UPPER_SNAKE_CASE
|
||||
```python
|
||||
MAX_CONTEXT_TOKENS = 1000000
|
||||
THINKING_MODE_TOKENS = {
|
||||
'minimal': 128,
|
||||
'low': 2048,
|
||||
'medium': 8192
|
||||
}
|
||||
```
|
||||
|
||||
**Private Methods**: Leading underscore
|
||||
```python
|
||||
class ToolBase:
|
||||
def execute(self):
|
||||
return self._process_internal_logic()
|
||||
|
||||
def _process_internal_logic(self):
|
||||
# Private implementation
|
||||
pass
|
||||
```
|
||||
|
||||
## Type Hints
|
||||
|
||||
### Mandatory Type Hints
|
||||
|
||||
**Function Signatures**: Always include type hints
|
||||
```python
|
||||
# Good
|
||||
def validate_file_path(file_path: str) -> bool:
|
||||
return os.path.exists(file_path)
|
||||
|
||||
async def process_request(request: dict) -> ToolOutput:
|
||||
# Implementation
|
||||
pass
|
||||
|
||||
# Avoid
|
||||
def validate_file_path(file_path):
|
||||
return os.path.exists(file_path)
|
||||
```
|
||||
|
||||
**Complex Types**: Use typing module
|
||||
```python
|
||||
from typing import Dict, List, Optional, Union, Any
|
||||
|
||||
def process_files(files: List[str]) -> Dict[str, Any]:
|
||||
return {"processed": files}
|
||||
|
||||
def get_config(key: str) -> Optional[str]:
|
||||
return os.getenv(key)
|
||||
```
|
||||
|
||||
**Generic Types**: Use TypeVar for reusable generics
|
||||
```python
|
||||
from typing import TypeVar, Generic
|
||||
|
||||
T = TypeVar('T')
|
||||
|
||||
class Repository(Generic[T]):
|
||||
def get(self, id: str) -> Optional[T]:
|
||||
# Implementation
|
||||
pass
|
||||
```
|
||||
|
||||
## Documentation Standards
|
||||
|
||||
### Docstring Format
|
||||
|
||||
**Use Google Style** docstrings:
|
||||
```python
|
||||
def execute_tool(name: str, arguments: dict, context: Optional[str] = None) -> ToolOutput:
|
||||
"""Execute a tool with given arguments and context.
|
||||
|
||||
Args:
|
||||
name: The name of the tool to execute
|
||||
arguments: Tool-specific parameters and configuration
|
||||
context: Optional conversation context for threading
|
||||
|
||||
Returns:
|
||||
ToolOutput containing the execution result and metadata
|
||||
|
||||
Raises:
|
||||
ToolNotFoundError: If the specified tool doesn't exist
|
||||
ValidationError: If arguments don't match tool schema
|
||||
|
||||
Example:
|
||||
>>> output = execute_tool("chat", {"prompt": "Hello"})
|
||||
>>> print(output.content)
|
||||
"Hello! How can I help you today?"
|
||||
"""
|
||||
# Implementation
|
||||
pass
|
||||
```
|
||||
|
||||
**Class Documentation**:
|
||||
```python
|
||||
class ConversationMemory:
|
||||
"""Manages conversation threading and context persistence.
|
||||
|
||||
This class handles storing and retrieving conversation contexts
|
||||
using Redis as the backend storage. It supports thread-based
|
||||
organization and automatic cleanup of expired conversations.
|
||||
|
||||
Attributes:
|
||||
redis_client: Redis connection for storage operations
|
||||
default_ttl: Default time-to-live for conversation threads
|
||||
|
||||
Example:
|
||||
>>> memory = ConversationMemory("redis://localhost:6379")
|
||||
>>> context = ThreadContext("thread-123")
|
||||
>>> await memory.store_thread(context)
|
||||
"""
|
||||
|
||||
def __init__(self, redis_url: str, default_ttl: int = 86400):
|
||||
"""Initialize conversation memory with Redis connection.
|
||||
|
||||
Args:
|
||||
redis_url: Redis connection string
|
||||
default_ttl: Default TTL in seconds (default: 24 hours)
|
||||
"""
|
||||
pass
|
||||
```
|
||||
|
||||
### Inline Comments
|
||||
|
||||
**When to Comment**:
|
||||
```python
|
||||
# Good - Explain complex business logic
|
||||
def calculate_token_budget(files: List[str], total_budget: int) -> Dict[str, int]:
|
||||
# Priority 1 files (source code) get 60% of budget
|
||||
priority_1_budget = int(total_budget * 0.6)
|
||||
|
||||
# Group files by priority based on extension
|
||||
priority_groups = defaultdict(list)
|
||||
for file in files:
|
||||
ext = Path(file).suffix.lower()
|
||||
priority = FILE_PRIORITIES.get(ext, 4)
|
||||
priority_groups[priority].append(file)
|
||||
|
||||
return allocate_budget_by_priority(priority_groups, total_budget)
|
||||
|
||||
# Avoid - Stating the obvious
|
||||
def get_file_size(file_path: str) -> int:
|
||||
# Get the size of the file
|
||||
return os.path.getsize(file_path)
|
||||
```
|
||||
|
||||
**Security and Performance Notes**:
|
||||
```python
|
||||
def validate_file_path(file_path: str) -> bool:
|
||||
# Security: Prevent directory traversal attacks
|
||||
if '..' in file_path or file_path.startswith('/etc/'):
|
||||
return False
|
||||
|
||||
# Performance: Early return for non-existent files
|
||||
if not os.path.exists(file_path):
|
||||
return False
|
||||
|
||||
return True
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Exception Handling Patterns
|
||||
|
||||
**Specific Exceptions**:
|
||||
```python
|
||||
# Good - Specific exception handling
|
||||
try:
|
||||
with open(file_path, 'r') as f:
|
||||
content = f.read()
|
||||
except FileNotFoundError:
|
||||
logger.warning(f"File not found: {file_path}")
|
||||
return None
|
||||
except PermissionError:
|
||||
logger.error(f"Permission denied: {file_path}")
|
||||
raise SecurityError(f"Access denied to {file_path}")
|
||||
except UnicodeDecodeError:
|
||||
logger.warning(f"Encoding error in {file_path}")
|
||||
return f"Error: Cannot decode file {file_path}"
|
||||
|
||||
# Avoid - Bare except clauses
|
||||
try:
|
||||
content = f.read()
|
||||
except:
|
||||
return None
|
||||
```
|
||||
|
||||
**Custom Exceptions**:
|
||||
```python
|
||||
class GeminiMCPError(Exception):
|
||||
"""Base exception for Gemini MCP Server errors."""
|
||||
pass
|
||||
|
||||
class ToolNotFoundError(GeminiMCPError):
|
||||
"""Raised when a requested tool is not found."""
|
||||
pass
|
||||
|
||||
class ValidationError(GeminiMCPError):
|
||||
"""Raised when input validation fails."""
|
||||
pass
|
||||
```
|
||||
|
||||
### Logging Standards
|
||||
|
||||
**Logging Levels**:
|
||||
```python
|
||||
import logging
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
# DEBUG: Detailed diagnostic information
|
||||
logger.debug(f"Processing file: {file_path}, size: {file_size}")
|
||||
|
||||
# INFO: General operational information
|
||||
logger.info(f"Tool '{tool_name}' executed successfully")
|
||||
|
||||
# WARNING: Something unexpected but recoverable
|
||||
logger.warning(f"File {file_path} exceeds recommended size limit")
|
||||
|
||||
# ERROR: Error condition but application continues
|
||||
logger.error(f"Failed to process file {file_path}: {str(e)}")
|
||||
|
||||
# CRITICAL: Serious error, application may not continue
|
||||
logger.critical(f"Redis connection failed: {connection_error}")
|
||||
```
|
||||
|
||||
**Structured Logging**:
|
||||
```python
|
||||
# Good - Structured logging with context
|
||||
logger.info(
|
||||
"Tool execution completed",
|
||||
extra={
|
||||
"tool_name": tool_name,
|
||||
"execution_time": execution_time,
|
||||
"files_processed": len(files),
|
||||
"thinking_mode": thinking_mode
|
||||
}
|
||||
)
|
||||
|
||||
# Avoid - Unstructured string formatting
|
||||
logger.info(f"Tool {tool_name} took {execution_time}s to process {len(files)} files")
|
||||
```
|
||||
|
||||
## Async/Await Patterns
|
||||
|
||||
### Async Function Design
|
||||
|
||||
**Async When Needed**:
|
||||
```python
|
||||
# Good - I/O operations should be async
|
||||
async def fetch_gemini_response(prompt: str) -> str:
|
||||
async with aiohttp.ClientSession() as session:
|
||||
async with session.post(GEMINI_API_URL, json=payload) as response:
|
||||
return await response.text()
|
||||
|
||||
# Good - CPU-bound work remains sync
|
||||
def parse_stack_trace(trace_text: str) -> List[StackFrame]:
|
||||
# CPU-intensive parsing logic
|
||||
return parsed_frames
|
||||
```
|
||||
|
||||
**Async Context Managers**:
|
||||
```python
|
||||
class AsyncRedisClient:
|
||||
async def __aenter__(self):
|
||||
self.connection = await redis.connect(self.url)
|
||||
return self
|
||||
|
||||
async def __aexit__(self, exc_type, exc_val, exc_tb):
|
||||
await self.connection.close()
|
||||
|
||||
# Usage
|
||||
async with AsyncRedisClient(redis_url) as client:
|
||||
await client.store_data(key, value)
|
||||
```
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
### Input Validation
|
||||
|
||||
**Path Validation**:
|
||||
```python
|
||||
def validate_file_path(file_path: str) -> bool:
|
||||
"""Validate file path for security and accessibility."""
|
||||
# Convert to absolute path
|
||||
abs_path = os.path.abspath(file_path)
|
||||
|
||||
# Check for directory traversal
|
||||
if not abs_path.startswith(PROJECT_ROOT):
|
||||
raise SecurityError(f"Path outside project root: {abs_path}")
|
||||
|
||||
# Check for dangerous patterns
|
||||
dangerous_patterns = ['../', '~/', '/etc/', '/var/']
|
||||
if any(pattern in file_path for pattern in dangerous_patterns):
|
||||
raise SecurityError(f"Dangerous path pattern detected: {file_path}")
|
||||
|
||||
return True
|
||||
```
|
||||
|
||||
**Data Sanitization**:
|
||||
```python
|
||||
def sanitize_user_input(user_input: str) -> str:
|
||||
"""Sanitize user input to prevent injection attacks."""
|
||||
# Remove null bytes
|
||||
sanitized = user_input.replace('\x00', '')
|
||||
|
||||
# Limit length
|
||||
if len(sanitized) > MAX_INPUT_LENGTH:
|
||||
sanitized = sanitized[:MAX_INPUT_LENGTH]
|
||||
|
||||
# Remove control characters
|
||||
sanitized = ''.join(char for char in sanitized if ord(char) >= 32)
|
||||
|
||||
return sanitized
|
||||
```
|
||||
|
||||
### Secret Management
|
||||
|
||||
**Environment Variables**:
|
||||
```python
|
||||
# Good - Environment variable with validation
|
||||
GEMINI_API_KEY = os.getenv('GEMINI_API_KEY')
|
||||
if not GEMINI_API_KEY:
|
||||
raise ConfigurationError("GEMINI_API_KEY environment variable required")
|
||||
|
||||
# Avoid - Hardcoded secrets
|
||||
API_KEY = "sk-1234567890abcdef" # Never do this
|
||||
```
|
||||
|
||||
**Secret Logging Prevention**:
|
||||
```python
|
||||
def log_request_safely(request_data: dict) -> None:
|
||||
"""Log request data while excluding sensitive fields."""
|
||||
safe_data = request_data.copy()
|
||||
|
||||
# Remove sensitive fields
|
||||
sensitive_fields = ['api_key', 'token', 'password', 'secret']
|
||||
for field in sensitive_fields:
|
||||
if field in safe_data:
|
||||
safe_data[field] = '[REDACTED]'
|
||||
|
||||
logger.info(f"Processing request: {safe_data}")
|
||||
```
|
||||
|
||||
## Performance Guidelines
|
||||
|
||||
### Memory Management
|
||||
|
||||
**Generator Usage**:
|
||||
```python
|
||||
# Good - Memory efficient for large datasets
|
||||
def process_large_file(file_path: str) -> Generator[str, None, None]:
|
||||
with open(file_path, 'r') as f:
|
||||
for line in f:
|
||||
yield process_line(line)
|
||||
|
||||
# Avoid - Loading entire file into memory
|
||||
def process_large_file(file_path: str) -> List[str]:
|
||||
with open(file_path, 'r') as f:
|
||||
return [process_line(line) for line in f.readlines()]
|
||||
```
|
||||
|
||||
**Context Managers**:
|
||||
```python
|
||||
# Good - Automatic resource cleanup
|
||||
class FileProcessor:
|
||||
def __enter__(self):
|
||||
self.temp_files = []
|
||||
return self
|
||||
|
||||
def __exit__(self, exc_type, exc_val, exc_tb):
|
||||
# Cleanup temporary files
|
||||
for temp_file in self.temp_files:
|
||||
os.unlink(temp_file)
|
||||
```
|
||||
|
||||
### Caching Patterns
|
||||
|
||||
**LRU Cache for Expensive Operations**:
|
||||
```python
|
||||
from functools import lru_cache
|
||||
|
||||
@lru_cache(maxsize=128)
|
||||
def parse_file_content(file_path: str, file_hash: str) -> str:
|
||||
"""Parse file content with caching based on file hash."""
|
||||
with open(file_path, 'r') as f:
|
||||
return expensive_parsing_operation(f.read())
|
||||
```
|
||||
|
||||
## Testing Standards
|
||||
|
||||
### Test File Organization
|
||||
|
||||
**Test Structure**:
|
||||
```python
|
||||
# tests/test_tools.py
|
||||
import pytest
|
||||
from unittest.mock import Mock, patch
|
||||
|
||||
from tools.chat import ChatTool
|
||||
from tools.models import ToolOutput
|
||||
|
||||
class TestChatTool:
|
||||
"""Test suite for ChatTool functionality."""
|
||||
|
||||
def setup_method(self):
|
||||
"""Set up test fixtures before each test method."""
|
||||
self.chat_tool = ChatTool()
|
||||
self.mock_gemini_client = Mock()
|
||||
|
||||
def test_basic_chat_execution(self):
|
||||
"""Test basic chat tool execution with simple prompt."""
|
||||
# Arrange
|
||||
request = {"prompt": "Hello"}
|
||||
|
||||
# Act
|
||||
result = self.chat_tool.execute(request)
|
||||
|
||||
# Assert
|
||||
assert isinstance(result, ToolOutput)
|
||||
assert result.status == "success"
|
||||
|
||||
@patch('tools.chat.GeminiClient')
|
||||
def test_chat_with_mocked_api(self, mock_client):
|
||||
"""Test chat tool with mocked Gemini API responses."""
|
||||
# Test implementation
|
||||
pass
|
||||
```
|
||||
|
||||
### Test Naming Conventions
|
||||
|
||||
**Test Method Names**:
|
||||
```python
|
||||
def test_should_validate_file_path_when_path_is_safe():
|
||||
"""Test that safe file paths are correctly validated."""
|
||||
pass
|
||||
|
||||
def test_should_raise_security_error_when_path_contains_traversal():
|
||||
"""Test that directory traversal attempts raise SecurityError."""
|
||||
pass
|
||||
|
||||
def test_should_return_none_when_file_not_found():
|
||||
"""Test that missing files return None gracefully."""
|
||||
pass
|
||||
```
|
||||
|
||||
## Configuration Management
|
||||
|
||||
### Environment-Based Configuration
|
||||
|
||||
**Configuration Class**:
|
||||
```python
|
||||
class Config:
|
||||
"""Application configuration with validation."""
|
||||
|
||||
def __init__(self):
|
||||
self.gemini_api_key = self._require_env('GEMINI_API_KEY')
|
||||
self.redis_url = os.getenv('REDIS_URL', 'redis://localhost:6379')
|
||||
self.project_root = os.getenv('PROJECT_ROOT', '/workspace')
|
||||
self.max_context_tokens = int(os.getenv('MAX_CONTEXT_TOKENS', '1000000'))
|
||||
|
||||
# Validate configuration
|
||||
self._validate_configuration()
|
||||
|
||||
def _require_env(self, key: str) -> str:
|
||||
"""Require environment variable or raise error."""
|
||||
value = os.getenv(key)
|
||||
if not value:
|
||||
raise ConfigurationError(f"Required environment variable: {key}")
|
||||
return value
|
||||
|
||||
def _validate_configuration(self) -> None:
|
||||
"""Validate configuration values."""
|
||||
if not os.path.exists(self.project_root):
|
||||
raise ConfigurationError(f"PROJECT_ROOT not found: {self.project_root}")
|
||||
```
|
||||
|
||||
## Pre-commit Hooks
|
||||
|
||||
### Automated Quality Checks
|
||||
|
||||
**Required Tools**:
|
||||
```bash
|
||||
# Install development dependencies
|
||||
pip install black isort flake8 mypy pytest
|
||||
|
||||
# Format code
|
||||
black tools/ utils/ tests/
|
||||
isort tools/ utils/ tests/
|
||||
|
||||
# Check code quality
|
||||
flake8 tools/ utils/ tests/
|
||||
mypy tools/ utils/
|
||||
|
||||
# Run tests
|
||||
pytest tests/ -v --cov=tools --cov=utils
|
||||
```
|
||||
|
||||
**Pre-commit Configuration** (`.pre-commit-config.yaml`):
|
||||
```yaml
|
||||
repos:
|
||||
- repo: https://github.com/psf/black
|
||||
rev: 23.3.0
|
||||
hooks:
|
||||
- id: black
|
||||
language_version: python3.9
|
||||
|
||||
- repo: https://github.com/pycqa/isort
|
||||
rev: 5.12.0
|
||||
hooks:
|
||||
- id: isort
|
||||
|
||||
- repo: https://github.com/pycqa/flake8
|
||||
rev: 6.0.0
|
||||
hooks:
|
||||
- id: flake8
|
||||
|
||||
- repo: https://github.com/pre-commit/mirrors-mypy
|
||||
rev: v1.3.0
|
||||
hooks:
|
||||
- id: mypy
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
Following these code style guidelines ensures consistent, maintainable, and secure code across the Gemini MCP Server project. All team members should adhere to these standards and use the automated tools to enforce compliance.
|
||||
382
docs/contributing/file-overview.md
Normal file
382
docs/contributing/file-overview.md
Normal file
@@ -0,0 +1,382 @@
|
||||
# Repository File Overview
|
||||
|
||||
## Purpose
|
||||
|
||||
This document provides a comprehensive guide to the repository structure, explaining the purpose and role of each directory and key file within the Gemini MCP Server project.
|
||||
|
||||
## Repository Structure
|
||||
|
||||
```
|
||||
gemini-mcp-server/
|
||||
├── CLAUDE.md # Collaboration framework and development guidelines
|
||||
├── README.md # Project overview and quick start guide
|
||||
├── LICENSE # Project license (MIT)
|
||||
├── requirements.txt # Python dependencies
|
||||
├── pyproject.toml # Poetry configuration and project metadata
|
||||
├── pytest.ini # Test configuration
|
||||
├── Dockerfile # Container image definition
|
||||
├── docker-compose.yml # Multi-service Docker orchestration
|
||||
├── setup.py # Python package setup (legacy)
|
||||
├── config.py # Centralized configuration management
|
||||
├── server.py # Main MCP server entry point
|
||||
├── gemini_server.py # Gemini-specific server implementation
|
||||
├── log_monitor.py # Logging and monitoring utilities
|
||||
├── setup-docker.sh # Docker setup automation script
|
||||
├── claude_config_example.json # Example Claude Desktop configuration
|
||||
├── examples/ # Configuration examples for different platforms
|
||||
├── docs/ # Complete project documentation
|
||||
├── tools/ # MCP tool implementations
|
||||
├── utils/ # Shared utility modules
|
||||
├── prompts/ # System prompts for different tool types
|
||||
├── tests/ # Comprehensive test suite
|
||||
└── memory-bank/ # Memory Bank files for context preservation
|
||||
```
|
||||
|
||||
## Core Configuration Files
|
||||
|
||||
### CLAUDE.md
|
||||
**Purpose**: Defines the collaboration framework between Claude, Gemini, and human developers
|
||||
**Key Components**:
|
||||
- Tool selection matrix for appropriate AI collaboration
|
||||
- Memory Bank integration protocols
|
||||
- Mandatory collaboration patterns and workflows
|
||||
- Quality gates and documentation standards
|
||||
|
||||
**When to Update**: When changing collaboration patterns, adding new tools, or modifying development workflows
|
||||
|
||||
### config.py
|
||||
**Purpose**: Centralized configuration management for the MCP server
|
||||
**Key Components**:
|
||||
- Environment variable handling (`GEMINI_API_KEY`, `REDIS_URL`)
|
||||
- Model configuration (`GEMINI_MODEL`, `MAX_CONTEXT_TOKENS`)
|
||||
- Security settings (`PROJECT_ROOT`, path validation)
|
||||
- Redis connection settings for conversation memory
|
||||
|
||||
**Dependencies**: Environment variables, Docker configuration
|
||||
**Extension Points**: Add new configuration parameters for tools or features
|
||||
|
||||
### server.py
|
||||
**Purpose**: Main MCP server implementation providing the protocol interface
|
||||
**Key Components**:
|
||||
- MCP protocol compliance (`@server.list_tools()`, `@server.call_tool()`)
|
||||
- Tool registration and discovery system
|
||||
- Request routing and response formatting
|
||||
- Error handling and graceful degradation
|
||||
|
||||
**Dependencies**: `tools/` modules, `utils/` modules, MCP library
|
||||
**Data Flow**: Claude → MCP Protocol → Tool Selection → Gemini API → Response
|
||||
|
||||
## Tool Architecture
|
||||
|
||||
### tools/ Directory
|
||||
**Purpose**: Contains individual MCP tool implementations following plugin architecture
|
||||
|
||||
#### tools/base.py
|
||||
**Purpose**: Abstract base class defining the tool interface contract
|
||||
**Key Components**:
|
||||
- `BaseTool` abstract class with `execute()` and `get_schema()` methods
|
||||
- Standardized error handling patterns
|
||||
- Response formatting utilities (`ToolOutput` dataclass)
|
||||
|
||||
**Extension Points**: Inherit from `BaseTool` to create new tools
|
||||
|
||||
#### Individual Tool Files
|
||||
|
||||
**tools/chat.py**
|
||||
- **Purpose**: Quick questions, brainstorming, general collaboration
|
||||
- **Thinking Mode**: Default 'medium' (8192 tokens)
|
||||
- **Use Cases**: Immediate answers, idea exploration, simple code discussions
|
||||
|
||||
**tools/thinkdeep.py**
|
||||
- **Purpose**: Complex architecture, system design, strategic planning
|
||||
- **Thinking Mode**: Default 'high' (16384 tokens)
|
||||
- **Use Cases**: Major features, refactoring strategies, design decisions
|
||||
|
||||
**tools/analyze.py**
|
||||
- **Purpose**: Code exploration, understanding existing systems
|
||||
- **Thinking Mode**: Variable based on analysis scope
|
||||
- **Use Cases**: Dependency analysis, pattern detection, codebase comprehension
|
||||
|
||||
**tools/codereview.py**
|
||||
- **Purpose**: Code quality, security, bug detection
|
||||
- **Thinking Mode**: Default 'medium' (8192 tokens)
|
||||
- **Use Cases**: PR reviews, pre-commit validation, security audits
|
||||
|
||||
**tools/debug.py**
|
||||
- **Purpose**: Root cause analysis, error investigation
|
||||
- **Thinking Mode**: Default 'medium' (8192 tokens)
|
||||
- **Use Cases**: Stack trace analysis, performance issues, bug diagnosis
|
||||
|
||||
**tools/precommit.py**
|
||||
- **Purpose**: Automated quality gates before commits
|
||||
- **Thinking Mode**: Default 'medium' (8192 tokens)
|
||||
- **Use Cases**: Git repository validation, change analysis, quality assurance
|
||||
|
||||
#### tools/models.py
|
||||
**Purpose**: Shared data models and Gemini API integration
|
||||
**Key Components**:
|
||||
- `ToolOutput` dataclass for standardized responses
|
||||
- `GeminiClient` for API communication
|
||||
- Thinking mode token allocations (`THINKING_MODE_TOKENS`)
|
||||
- Pydantic models for request/response validation
|
||||
|
||||
**Dependencies**: `google-generativeai`, `pydantic`
|
||||
|
||||
## Utility Modules
|
||||
|
||||
### utils/ Directory
|
||||
**Purpose**: Shared utilities used across multiple tools and components
|
||||
|
||||
#### utils/file_utils.py
|
||||
**Purpose**: Secure file operations and content processing
|
||||
**Key Components**:
|
||||
- `validate_file_path()`: Multi-layer security validation
|
||||
- `read_file_with_token_limit()`: Token-aware file reading
|
||||
- `translate_docker_path()`: Host-to-container path mapping
|
||||
- Priority-based file processing (source code > docs > logs)
|
||||
|
||||
**Security Features**:
|
||||
- Directory traversal prevention
|
||||
- Sandbox boundary enforcement (PROJECT_ROOT)
|
||||
- Dangerous path pattern detection
|
||||
|
||||
**Data Flow**: File Request → Security Validation → Path Translation → Content Processing → Formatted Output
|
||||
|
||||
#### utils/git_utils.py
|
||||
**Purpose**: Git repository operations for code analysis
|
||||
**Key Components**:
|
||||
- Repository state detection (staged, unstaged, committed changes)
|
||||
- Branch comparison and diff analysis
|
||||
- Commit history processing
|
||||
- Change validation for precommit tool
|
||||
|
||||
**Dependencies**: `git` command-line tool
|
||||
**Integration**: Primary used by `precommit` tool for change analysis
|
||||
|
||||
#### utils/conversation_memory.py
|
||||
**Purpose**: Cross-session context preservation and threading
|
||||
**Key Components**:
|
||||
- `ThreadContext` dataclass for conversation state
|
||||
- `ConversationMemory` class for Redis-based persistence
|
||||
- Thread reconstruction and continuation support
|
||||
- Automatic cleanup of expired conversations
|
||||
|
||||
**Data Flow**: Tool Execution → Context Storage → Redis Persistence → Context Retrieval → Thread Reconstruction
|
||||
|
||||
**Dependencies**: Redis server, `redis-py` library
|
||||
|
||||
#### utils/token_utils.py
|
||||
**Purpose**: Token management and context optimization
|
||||
**Key Components**:
|
||||
- Token counting and estimation
|
||||
- Context budget allocation
|
||||
- Content truncation with structure preservation
|
||||
- Priority-based token distribution
|
||||
|
||||
**Integration**: Used by all tools for managing Gemini API token limits
|
||||
|
||||
## System Prompts
|
||||
|
||||
### prompts/ Directory
|
||||
**Purpose**: Standardized system prompts for different tool types
|
||||
|
||||
#### prompts/tool_prompts.py
|
||||
**Purpose**: Template prompts for consistent tool behavior
|
||||
**Key Components**:
|
||||
- Base prompt templates for each tool type
|
||||
- Context formatting patterns
|
||||
- Error message templates
|
||||
- Response structure guidelines
|
||||
|
||||
**Extension Points**: Add new prompt templates for new tools or specialized use cases
|
||||
|
||||
## Testing Infrastructure
|
||||
|
||||
### tests/ Directory
|
||||
**Purpose**: Comprehensive test suite ensuring code quality and reliability
|
||||
|
||||
#### Test Organization
|
||||
```
|
||||
tests/
|
||||
├── __init__.py # Test package initialization
|
||||
├── conftest.py # Shared test fixtures and configuration
|
||||
├── test_server.py # MCP server integration tests
|
||||
├── test_tools.py # Individual tool functionality tests
|
||||
├── test_utils.py # Utility module tests
|
||||
├── test_config.py # Configuration validation tests
|
||||
└── specialized test files... # Feature-specific test suites
|
||||
```
|
||||
|
||||
#### Key Test Files
|
||||
|
||||
**conftest.py**
|
||||
- **Purpose**: Shared pytest fixtures and test configuration
|
||||
- **Components**: Mock clients, temporary directories, sample data
|
||||
|
||||
**test_server.py**
|
||||
- **Purpose**: MCP protocol and server integration testing
|
||||
- **Coverage**: Tool registration, request routing, error handling
|
||||
|
||||
**test_tools.py**
|
||||
- **Purpose**: Individual tool functionality validation
|
||||
- **Coverage**: Tool execution, parameter validation, response formatting
|
||||
|
||||
**test_utils.py**
|
||||
- **Purpose**: Utility module testing
|
||||
- **Coverage**: File operations, security validation, token management
|
||||
|
||||
## Memory Bank System
|
||||
|
||||
### memory-bank/ Directory
|
||||
**Purpose**: Local file-based context preservation system
|
||||
|
||||
#### Memory Bank Files
|
||||
|
||||
**productContext.md**
|
||||
- **Purpose**: High-level project overview and goals
|
||||
- **Content**: Project description, key features, overall architecture
|
||||
- **Update Triggers**: Fundamental project changes, feature additions
|
||||
|
||||
**activeContext.md**
|
||||
- **Purpose**: Current development status and recent changes
|
||||
- **Content**: Current focus, recent changes, open questions/issues
|
||||
- **Update Triggers**: Session changes, progress updates
|
||||
|
||||
**progress.md**
|
||||
- **Purpose**: Task tracking using structured format
|
||||
- **Content**: Completed tasks, current tasks, next steps
|
||||
- **Update Triggers**: Task completion, milestone achievements
|
||||
|
||||
**decisionLog.md**
|
||||
- **Purpose**: Architectural decisions with rationale
|
||||
- **Content**: Technical decisions, rationale, implementation details
|
||||
- **Update Triggers**: Significant architectural choices, design decisions
|
||||
|
||||
**systemPatterns.md**
|
||||
- **Purpose**: Recurring patterns and standards documentation
|
||||
- **Content**: Coding patterns, architectural patterns, testing patterns
|
||||
- **Update Triggers**: Pattern introduction, standard modifications
|
||||
|
||||
**Data Flow**: Development Activity → Memory Bank Updates → Context Preservation → Cross-Session Continuity
|
||||
|
||||
## Documentation Structure
|
||||
|
||||
### docs/ Directory
|
||||
**Purpose**: Complete project documentation following CLAUDE.md standards
|
||||
|
||||
#### Documentation Categories
|
||||
|
||||
**docs/architecture/**
|
||||
- `overview.md`: High-level system architecture and component relationships
|
||||
- `components.md`: Detailed component descriptions and interactions
|
||||
- `data-flow.md`: Data flow patterns and processing pipelines
|
||||
- `decisions/`: Architecture Decision Records (ADRs)
|
||||
|
||||
**docs/api/**
|
||||
- `mcp-protocol.md`: MCP protocol implementation details
|
||||
- `tools/`: Individual tool API documentation
|
||||
|
||||
**docs/contributing/**
|
||||
- `setup.md`: Development environment setup
|
||||
- `workflows.md`: Development workflows and processes
|
||||
- `code-style.md`: Coding standards and style guide
|
||||
- `testing.md`: Testing strategies and requirements
|
||||
- `file-overview.md`: This file - repository structure guide
|
||||
|
||||
**docs/user-guides/**
|
||||
- `installation.md`: Installation and setup instructions
|
||||
- `configuration.md`: Configuration options and examples
|
||||
- `troubleshooting.md`: Common issues and solutions
|
||||
|
||||
## Configuration Examples
|
||||
|
||||
### examples/ Directory
|
||||
**Purpose**: Platform-specific configuration examples for different deployment scenarios
|
||||
|
||||
**claude_config_macos.json**
|
||||
- macOS-specific Claude Desktop configuration
|
||||
- Local development setup patterns
|
||||
- File path configurations for macOS
|
||||
|
||||
**claude_config_wsl.json**
|
||||
- Windows Subsystem for Linux configuration
|
||||
- Path translation patterns for WSL environment
|
||||
- Docker integration considerations
|
||||
|
||||
**claude_config_docker_home.json**
|
||||
- Docker-based deployment configuration
|
||||
- Container path mapping examples
|
||||
- Volume mount configurations
|
||||
|
||||
## Container Configuration
|
||||
|
||||
### Dockerfile
|
||||
**Purpose**: Container image definition for consistent deployment
|
||||
**Key Components**:
|
||||
- Python 3.9 base image
|
||||
- Dependency installation (requirements.txt)
|
||||
- Application code copying
|
||||
- Entry point configuration (`server.py`)
|
||||
|
||||
**Build Process**: Source Code → Dependency Installation → Application Setup → Runnable Container
|
||||
|
||||
### docker-compose.yml
|
||||
**Purpose**: Multi-service orchestration for complete system deployment
|
||||
**Services**:
|
||||
- `gemini-server`: Main MCP server application
|
||||
- `redis`: Conversation memory persistence
|
||||
- Volume mounts for configuration and data persistence
|
||||
|
||||
**Data Flow**: Docker Compose → Service Orchestration → Network Configuration → Volume Mounting → System Startup
|
||||
|
||||
## Extension Guidelines
|
||||
|
||||
### Adding New Tools
|
||||
|
||||
1. **Create Tool Class**: Inherit from `BaseTool` in `tools/new_tool.py`
|
||||
2. **Implement Interface**: Define `execute()` and `get_schema()` methods
|
||||
3. **Add Registration**: Update `server.py` tool discovery
|
||||
4. **Create Tests**: Add comprehensive tests in `tests/`
|
||||
5. **Update Documentation**: Add API documentation in `docs/api/tools/`
|
||||
|
||||
### Adding New Utilities
|
||||
|
||||
1. **Create Module**: Add new utility in `utils/new_utility.py`
|
||||
2. **Define Interface**: Clear function signatures with type hints
|
||||
3. **Add Security**: Validate inputs and handle errors gracefully
|
||||
4. **Write Tests**: Comprehensive unit tests with mocking
|
||||
5. **Update Dependencies**: Document component interactions
|
||||
|
||||
### Modifying Configuration
|
||||
|
||||
1. **Update config.py**: Add new configuration parameters
|
||||
2. **Environment Variables**: Define environment variable mappings
|
||||
3. **Validation**: Add configuration validation logic
|
||||
4. **Documentation**: Update configuration guide
|
||||
5. **Examples**: Provide example configurations
|
||||
|
||||
## Dependencies & Integration Points
|
||||
|
||||
### External Dependencies
|
||||
- **MCP Library**: Protocol implementation and compliance
|
||||
- **Google Generative AI**: Gemini API integration
|
||||
- **Redis**: Conversation memory persistence
|
||||
- **Docker**: Containerization and deployment
|
||||
- **pytest**: Testing framework
|
||||
|
||||
### Internal Integration Points
|
||||
- **Tool Registration**: `server.py` ↔ `tools/` modules
|
||||
- **Configuration**: `config.py` → All modules
|
||||
- **File Operations**: `utils/file_utils.py` → All file-accessing tools
|
||||
- **Memory Management**: `utils/conversation_memory.py` → All tools supporting continuation
|
||||
- **Security**: `utils/file_utils.py` validation → All file operations
|
||||
|
||||
### Data Flow Integration
|
||||
1. **Request Flow**: Claude → `server.py` → Tool Selection → `tools/` → `utils/` → Gemini API
|
||||
2. **Response Flow**: Gemini API → `tools/` → `utils/` → `server.py` → Claude
|
||||
3. **Memory Flow**: Tool Execution → `utils/conversation_memory.py` → Redis → Context Retrieval
|
||||
4. **Security Flow**: File Request → `utils/file_utils.py` → Validation → Safe Processing
|
||||
|
||||
---
|
||||
|
||||
This file overview provides the foundation for understanding the repository structure and serves as a guide for contributors to navigate the codebase effectively and make informed architectural decisions.
|
||||
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)
|
||||
470
docs/contributing/test-structure.md
Normal file
470
docs/contributing/test-structure.md
Normal file
@@ -0,0 +1,470 @@
|
||||
# Test Structure Documentation
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides a comprehensive analysis of the existing test structure in the Gemini MCP Server project. The test suite consists of **17 specialized test files** organized to validate all aspects of the system from unit-level functionality to complex AI collaboration workflows.
|
||||
|
||||
## Test Organization
|
||||
|
||||
### Test Directory Structure
|
||||
|
||||
```
|
||||
tests/
|
||||
├── __init__.py # Package initialization
|
||||
├── conftest.py # Global test configuration and fixtures
|
||||
├── test_claude_continuation.py # Claude continuation opportunities
|
||||
├── test_collaboration.py # AI-to-AI collaboration features
|
||||
├── test_config.py # Configuration validation
|
||||
├── test_conversation_history_bug.py # Bug fix regression tests
|
||||
├── test_conversation_memory.py # Redis-based conversation persistence
|
||||
├── test_cross_tool_continuation.py # Cross-tool conversation threading
|
||||
├── test_docker_path_integration.py # Docker environment path translation
|
||||
├── test_large_prompt_handling.py # Large prompt detection and handling
|
||||
├── test_live_integration.py # Live API testing (excluded from CI)
|
||||
├── test_precommit.py # Pre-commit validation and git integration
|
||||
├── test_prompt_regression.py # Normal prompt handling regression
|
||||
├── test_server.py # Main server functionality
|
||||
├── test_thinking_modes.py # Thinking mode functionality
|
||||
├── test_tools.py # Individual tool implementations
|
||||
└── test_utils.py # Utility function testing
|
||||
```
|
||||
|
||||
## Test Categories and Analysis
|
||||
|
||||
### 1. Core Functionality Tests
|
||||
|
||||
#### `test_server.py` - Main Server Functionality
|
||||
**Purpose**: Tests the core MCP server implementation and tool dispatch mechanism
|
||||
|
||||
**Key Test Classes**:
|
||||
- **Server startup and initialization**
|
||||
- **Tool registration and availability**
|
||||
- **Request routing and handling**
|
||||
- **Error propagation and handling**
|
||||
|
||||
**Example Coverage**:
|
||||
```python
|
||||
# Tests tool listing functionality
|
||||
def test_list_tools()
|
||||
|
||||
# Tests tool execution pipeline
|
||||
async def test_call_tool()
|
||||
|
||||
# Tests error handling for invalid tools
|
||||
async def test_call_invalid_tool()
|
||||
```
|
||||
|
||||
#### `test_config.py` - Configuration Management
|
||||
**Purpose**: Validates configuration loading, environment variable handling, and settings validation
|
||||
|
||||
**Key Areas**:
|
||||
- **Environment variable parsing**
|
||||
- **Default value handling**
|
||||
- **Configuration validation**
|
||||
- **Error handling for missing required config**
|
||||
|
||||
#### `test_tools.py` - Tool Implementation Testing
|
||||
**Purpose**: Tests individual tool implementations with comprehensive input validation
|
||||
|
||||
**Key Features**:
|
||||
- **Absolute path enforcement across all tools**
|
||||
- **Parameter validation for each tool**
|
||||
- **Error handling for malformed inputs**
|
||||
- **Tool-specific behavior validation**
|
||||
|
||||
**Critical Security Testing**:
|
||||
```python
|
||||
# Tests that all tools enforce absolute paths
|
||||
async def test_tool_absolute_path_requirement()
|
||||
|
||||
# Tests path traversal attack prevention
|
||||
async def test_tool_path_traversal_prevention()
|
||||
```
|
||||
|
||||
#### `test_utils.py` - Utility Function Testing
|
||||
**Purpose**: Tests file utilities, token counting, and directory handling functions
|
||||
|
||||
**Coverage Areas**:
|
||||
- **File reading and processing**
|
||||
- **Token counting and limits**
|
||||
- **Directory traversal and expansion**
|
||||
- **Path validation and security**
|
||||
|
||||
### 2. Advanced Feature Tests
|
||||
|
||||
#### `test_collaboration.py` - AI-to-AI Collaboration
|
||||
**Purpose**: Tests dynamic context requests and collaborative AI workflows
|
||||
|
||||
**Key Scenarios**:
|
||||
- **Clarification request parsing**
|
||||
- **Dynamic context expansion**
|
||||
- **AI-to-AI communication protocols**
|
||||
- **Collaboration workflow validation**
|
||||
|
||||
**Example Test**:
|
||||
```python
|
||||
async def test_clarification_request_parsing():
|
||||
"""Test parsing of AI clarification requests for additional context."""
|
||||
# Validates that Gemini can request additional files/context
|
||||
# and Claude can respond appropriately
|
||||
```
|
||||
|
||||
#### `test_cross_tool_continuation.py` - Cross-Tool Threading
|
||||
**Purpose**: Tests conversation continuity across different tools
|
||||
|
||||
**Critical Features**:
|
||||
- **Continuation ID persistence**
|
||||
- **Context preservation between tools**
|
||||
- **Thread management across tool switches**
|
||||
- **File context sharing between AI agents**
|
||||
|
||||
#### `test_conversation_memory.py` - Memory Persistence
|
||||
**Purpose**: Tests Redis-based conversation storage and retrieval
|
||||
|
||||
**Test Coverage**:
|
||||
- **Conversation storage and retrieval**
|
||||
- **Thread context management**
|
||||
- **TTL (time-to-live) handling**
|
||||
- **Memory cleanup and optimization**
|
||||
|
||||
#### `test_thinking_modes.py` - Cognitive Load Management
|
||||
**Purpose**: Tests thinking mode functionality across all tools
|
||||
|
||||
**Validation Areas**:
|
||||
- **Token budget enforcement**
|
||||
- **Mode selection and application**
|
||||
- **Performance characteristics**
|
||||
- **Quality vs. cost trade-offs**
|
||||
|
||||
### 3. Specialized Testing
|
||||
|
||||
#### `test_large_prompt_handling.py` - Scale Testing
|
||||
**Purpose**: Tests handling of prompts exceeding MCP token limits
|
||||
|
||||
**Key Scenarios**:
|
||||
- **Large prompt detection (>50,000 characters)**
|
||||
- **Automatic file-based prompt handling**
|
||||
- **MCP token limit workarounds**
|
||||
- **Response capacity preservation**
|
||||
|
||||
**Critical Flow Testing**:
|
||||
```python
|
||||
async def test_large_prompt_file_handling():
|
||||
"""Test that large prompts are automatically handled via file mechanism."""
|
||||
# Validates the workaround for MCP's 25K token limit
|
||||
```
|
||||
|
||||
#### `test_docker_path_integration.py` - Environment Testing
|
||||
**Purpose**: Tests Docker environment path translation and workspace mounting
|
||||
|
||||
**Coverage**:
|
||||
- **Host-to-container path mapping**
|
||||
- **Workspace directory access**
|
||||
- **Cross-platform path handling**
|
||||
- **Security boundary enforcement**
|
||||
|
||||
#### `test_precommit.py` - Quality Gate Testing
|
||||
**Purpose**: Tests pre-commit validation and git integration
|
||||
|
||||
**Validation Areas**:
|
||||
- **Git repository discovery**
|
||||
- **Change detection and analysis**
|
||||
- **Multi-repository support**
|
||||
- **Security scanning of changes**
|
||||
|
||||
### 4. Regression and Bug Fix Tests
|
||||
|
||||
#### `test_conversation_history_bug.py` - Bug Fix Validation
|
||||
**Purpose**: Regression test for conversation history duplication bug
|
||||
|
||||
**Specific Coverage**:
|
||||
- **Conversation deduplication**
|
||||
- **History consistency**
|
||||
- **Memory leak prevention**
|
||||
- **Thread integrity**
|
||||
|
||||
#### `test_prompt_regression.py` - Normal Operation Validation
|
||||
**Purpose**: Ensures normal prompt handling continues to work correctly
|
||||
|
||||
**Test Focus**:
|
||||
- **Standard prompt processing**
|
||||
- **Backward compatibility**
|
||||
- **Feature regression prevention**
|
||||
- **Performance baseline maintenance**
|
||||
|
||||
#### `test_claude_continuation.py` - Session Management
|
||||
**Purpose**: Tests Claude continuation opportunities and session management
|
||||
|
||||
**Key Areas**:
|
||||
- **Session state management**
|
||||
- **Continuation opportunity detection**
|
||||
- **Context preservation**
|
||||
- **Session cleanup and termination**
|
||||
|
||||
### 5. Live Integration Testing
|
||||
|
||||
#### `test_live_integration.py` - Real API Testing
|
||||
**Purpose**: Tests actual Gemini API integration (excluded from regular CI)
|
||||
|
||||
**Requirements**:
|
||||
- Valid `GEMINI_API_KEY` environment variable
|
||||
- Network connectivity to Google AI services
|
||||
- Redis server for conversation memory testing
|
||||
|
||||
**Test Categories**:
|
||||
- **Basic API request/response validation**
|
||||
- **Tool execution with real Gemini responses**
|
||||
- **Conversation threading with actual AI**
|
||||
- **Error handling with real API responses**
|
||||
|
||||
**Exclusion from CI**:
|
||||
```python
|
||||
@pytest.mark.skipif(not os.getenv("GEMINI_API_KEY"), reason="API key required")
|
||||
class TestLiveIntegration:
|
||||
"""Tests requiring actual Gemini API access."""
|
||||
```
|
||||
|
||||
## Test Configuration Analysis
|
||||
|
||||
### `conftest.py` - Global Test Setup
|
||||
|
||||
**Key Fixtures and Configuration**:
|
||||
|
||||
#### Environment Isolation
|
||||
```python
|
||||
# Ensures tests run in isolated sandbox environment
|
||||
os.environ["MCP_PROJECT_ROOT"] = str(temp_dir)
|
||||
```
|
||||
|
||||
#### Dummy API Keys
|
||||
```python
|
||||
# Provides safe dummy keys for testing without real credentials
|
||||
os.environ["GEMINI_API_KEY"] = "dummy-key-for-testing"
|
||||
```
|
||||
|
||||
#### Cross-Platform Compatibility
|
||||
```python
|
||||
# Handles Windows async event loop configuration
|
||||
if platform.system() == "Windows":
|
||||
asyncio.set_event_loop_policy(asyncio.WindowsProactorEventLoopPolicy())
|
||||
```
|
||||
|
||||
#### Project Path Fixtures
|
||||
```python
|
||||
@pytest.fixture
|
||||
def project_path():
|
||||
"""Provides safe project path for file operations in tests."""
|
||||
```
|
||||
|
||||
### `pytest.ini` - Test Runner Configuration
|
||||
|
||||
**Key Settings**:
|
||||
```ini
|
||||
[pytest]
|
||||
testpaths = tests
|
||||
python_files = test_*.py
|
||||
python_classes = Test*
|
||||
python_functions = test_*
|
||||
asyncio_mode = auto
|
||||
addopts =
|
||||
-v
|
||||
--strict-markers
|
||||
--tb=short
|
||||
```
|
||||
|
||||
## Mocking Strategies
|
||||
|
||||
### 1. Gemini API Mocking
|
||||
|
||||
**Pattern Used**:
|
||||
```python
|
||||
@patch("tools.base.BaseTool.create_model")
|
||||
async def test_tool_execution(self, mock_create_model):
|
||||
mock_model = Mock()
|
||||
mock_model.generate_content.return_value = Mock(
|
||||
candidates=[Mock(content=Mock(parts=[Mock(text="Mocked response")]))]
|
||||
)
|
||||
mock_create_model.return_value = mock_model
|
||||
```
|
||||
|
||||
**Benefits**:
|
||||
- **No API key required** for unit and integration tests
|
||||
- **Predictable responses** for consistent testing
|
||||
- **Fast execution** without network dependencies
|
||||
- **Cost-effective** testing without API charges
|
||||
|
||||
### 2. Redis Memory Mocking
|
||||
|
||||
**Pattern Used**:
|
||||
```python
|
||||
@patch("utils.conversation_memory.get_redis_client")
|
||||
def test_conversation_flow(self, mock_redis):
|
||||
mock_client = Mock()
|
||||
mock_redis.return_value = mock_client
|
||||
# Test conversation persistence logic
|
||||
```
|
||||
|
||||
**Advantages**:
|
||||
- **No Redis server required** for testing
|
||||
- **Controlled state** for predictable test scenarios
|
||||
- **Error simulation** for resilience testing
|
||||
|
||||
### 3. File System Mocking
|
||||
|
||||
**Pattern Used**:
|
||||
```python
|
||||
@patch("builtins.open", mock_open(read_data="test file content"))
|
||||
@patch("os.path.exists", return_value=True)
|
||||
def test_file_operations():
|
||||
# Test file reading without actual files
|
||||
```
|
||||
|
||||
**Security Benefits**:
|
||||
- **No file system access** during testing
|
||||
- **Path validation testing** without security risks
|
||||
- **Consistent test data** across environments
|
||||
|
||||
## Security Testing Focus
|
||||
|
||||
### Path Validation Testing
|
||||
|
||||
**Critical Security Tests**:
|
||||
1. **Absolute path enforcement** - All tools must reject relative paths
|
||||
2. **Directory traversal prevention** - Block `../` and similar patterns
|
||||
3. **Symlink attack prevention** - Detect and block symbolic link attacks
|
||||
4. **Sandbox boundary enforcement** - Restrict access to allowed directories
|
||||
|
||||
**Example Security Test**:
|
||||
```python
|
||||
async def test_path_traversal_attack_prevention():
|
||||
"""Test that directory traversal attacks are blocked."""
|
||||
dangerous_paths = [
|
||||
"../../../etc/passwd",
|
||||
"/etc/shadow",
|
||||
"~/../../root/.ssh/id_rsa"
|
||||
]
|
||||
|
||||
for path in dangerous_paths:
|
||||
with pytest.raises(SecurityError):
|
||||
await tool.execute({"files": [path]})
|
||||
```
|
||||
|
||||
### Docker Security Testing
|
||||
|
||||
**Container Security Validation**:
|
||||
- **Workspace mounting** - Verify read-only access enforcement
|
||||
- **Path translation** - Test host-to-container path mapping
|
||||
- **Privilege boundaries** - Ensure container cannot escape sandbox
|
||||
|
||||
## Test Execution Patterns
|
||||
|
||||
### Parallel Test Execution
|
||||
|
||||
**Strategy**: Tests are designed for parallel execution with proper isolation
|
||||
|
||||
**Benefits**:
|
||||
- **Faster test suite** execution
|
||||
- **Resource efficiency** for CI/CD
|
||||
- **Scalable testing** for large codebases
|
||||
|
||||
### Conditional Test Execution
|
||||
|
||||
**Live Test Skipping**:
|
||||
```python
|
||||
@pytest.mark.skipif(not os.getenv("GEMINI_API_KEY"), reason="API key required")
|
||||
```
|
||||
|
||||
**Platform-Specific Tests**:
|
||||
```python
|
||||
@pytest.mark.skipif(platform.system() == "Windows", reason="Unix-specific test")
|
||||
```
|
||||
|
||||
## Test Quality Metrics
|
||||
|
||||
### Coverage Analysis
|
||||
|
||||
**Current Test Coverage by Category**:
|
||||
- ✅ **Tool Functionality**: All 7 tools comprehensively tested
|
||||
- ✅ **Server Operations**: Complete request/response cycle coverage
|
||||
- ✅ **Security Validation**: Path safety and access control testing
|
||||
- ✅ **Collaboration Features**: AI-to-AI communication patterns
|
||||
- ✅ **Memory Management**: Conversation persistence and threading
|
||||
- ✅ **Error Handling**: Graceful degradation and error recovery
|
||||
|
||||
### Test Reliability
|
||||
|
||||
**Design Characteristics**:
|
||||
- **Deterministic**: Tests produce consistent results
|
||||
- **Isolated**: No test dependencies or shared state
|
||||
- **Fast**: Unit tests complete in milliseconds
|
||||
- **Comprehensive**: Edge cases and error conditions covered
|
||||
|
||||
## Integration with Development Workflow
|
||||
|
||||
### Test-Driven Development Support
|
||||
|
||||
**TDD Cycle Integration**:
|
||||
1. **Red**: Write failing test for new functionality
|
||||
2. **Green**: Implement minimal code to pass test
|
||||
3. **Refactor**: Improve code while maintaining test coverage
|
||||
|
||||
### Pre-Commit Testing
|
||||
|
||||
**Quality Gates**:
|
||||
- **Security validation** before commits
|
||||
- **Functionality regression** prevention
|
||||
- **Code quality** maintenance
|
||||
- **Performance baseline** protection
|
||||
|
||||
### CI/CD Integration
|
||||
|
||||
**GitHub Actions Workflow**:
|
||||
- **Multi-Python version** testing (3.10, 3.11, 3.12)
|
||||
- **Parallel test execution** for efficiency
|
||||
- **Selective live testing** when API keys available
|
||||
- **Coverage reporting** and quality gates
|
||||
|
||||
## Best Practices Demonstrated
|
||||
|
||||
### 1. Comprehensive Mocking
|
||||
Every external dependency is properly mocked for reliable testing
|
||||
|
||||
### 2. Security-First Approach
|
||||
Strong emphasis on security validation and vulnerability prevention
|
||||
|
||||
### 3. Collaboration Testing
|
||||
Extensive testing of AI-to-AI communication and workflow patterns
|
||||
|
||||
### 4. Real-World Scenarios
|
||||
Tests cover actual usage patterns and edge cases
|
||||
|
||||
### 5. Maintainable Structure
|
||||
Clear organization and focused test files for easy maintenance
|
||||
|
||||
## Recommendations for Contributors
|
||||
|
||||
### Adding New Tests
|
||||
|
||||
1. **Follow Naming Conventions**: Use descriptive test names that explain the scenario
|
||||
2. **Maintain Isolation**: Mock all external dependencies
|
||||
3. **Test Security**: Include path validation and security checks
|
||||
4. **Cover Edge Cases**: Test error conditions and boundary cases
|
||||
5. **Document Purpose**: Use docstrings to explain test objectives
|
||||
|
||||
### Test Quality Standards
|
||||
|
||||
1. **Fast Execution**: Unit tests should complete in milliseconds
|
||||
2. **Predictable Results**: Tests should be deterministic
|
||||
3. **Clear Assertions**: Use descriptive assertion messages
|
||||
4. **Proper Cleanup**: Ensure tests don't leave side effects
|
||||
|
||||
### Testing New Features
|
||||
|
||||
1. **Start with Unit Tests**: Test individual components first
|
||||
2. **Add Integration Tests**: Test component interactions
|
||||
3. **Include Security Tests**: Validate security measures
|
||||
4. **Test Collaboration**: If relevant, test AI-to-AI workflows
|
||||
|
||||
---
|
||||
|
||||
This test structure demonstrates a mature, production-ready testing approach that ensures code quality, security, and reliability while supporting the collaborative AI development patterns that make this project unique.
|
||||
690
docs/contributing/testing.md
Normal file
690
docs/contributing/testing.md
Normal file
@@ -0,0 +1,690 @@
|
||||
# Testing Strategy & Guidelines
|
||||
|
||||
## Overview
|
||||
|
||||
This document outlines the comprehensive testing strategy for the Gemini MCP Server project, including unit testing, integration testing, and quality assurance practices that align with CLAUDE.md collaboration patterns.
|
||||
|
||||
## Testing Philosophy
|
||||
|
||||
### Test-Driven Development (TDD)
|
||||
|
||||
**TDD Cycle**:
|
||||
1. **Red**: Write failing test for new functionality
|
||||
2. **Green**: Implement minimal code to pass the test
|
||||
3. **Refactor**: Improve code while maintaining test coverage
|
||||
4. **Repeat**: Continue cycle for all new features
|
||||
|
||||
**Example TDD Flow**:
|
||||
```python
|
||||
# 1. Write failing test
|
||||
def test_chat_tool_should_process_simple_prompt():
|
||||
tool = ChatTool()
|
||||
result = tool.execute({"prompt": "Hello"})
|
||||
assert result.status == "success"
|
||||
assert "hello" in result.content.lower()
|
||||
|
||||
# 2. Implement minimal functionality
|
||||
class ChatTool:
|
||||
def execute(self, request):
|
||||
return ToolOutput(content="Hello!", status="success")
|
||||
|
||||
# 3. Refactor and enhance
|
||||
```
|
||||
|
||||
### Testing Pyramid
|
||||
|
||||
```
|
||||
/\
|
||||
/ \ E2E Tests (Few, High-Value)
|
||||
/____\ Integration Tests (Some, Key Paths)
|
||||
/______\ Unit Tests (Many, Fast, Isolated)
|
||||
/________\
|
||||
```
|
||||
|
||||
**Distribution**:
|
||||
- **70% Unit Tests**: Fast, isolated, comprehensive coverage
|
||||
- **20% Integration Tests**: Component interaction validation
|
||||
- **10% End-to-End Tests**: Complete workflow validation
|
||||
|
||||
## Test Categories
|
||||
|
||||
### 1. Unit Tests
|
||||
|
||||
**Purpose**: Test individual functions and classes in isolation
|
||||
|
||||
**Location**: `tests/unit/`
|
||||
|
||||
**Example Structure**:
|
||||
```python
|
||||
# tests/unit/test_file_utils.py
|
||||
import pytest
|
||||
from unittest.mock import Mock, patch, mock_open
|
||||
|
||||
from utils.file_utils import validate_file_path, read_file_with_token_limit
|
||||
|
||||
class TestFileUtils:
|
||||
"""Unit tests for file utility functions."""
|
||||
|
||||
def test_validate_file_path_with_safe_path(self):
|
||||
"""Test that safe file paths pass validation."""
|
||||
safe_path = "/workspace/tools/chat.py"
|
||||
assert validate_file_path(safe_path) is True
|
||||
|
||||
def test_validate_file_path_with_traversal_attack(self):
|
||||
"""Test that directory traversal attempts are blocked."""
|
||||
dangerous_path = "/workspace/../../../etc/passwd"
|
||||
with pytest.raises(SecurityError):
|
||||
validate_file_path(dangerous_path)
|
||||
|
||||
@patch('builtins.open', new_callable=mock_open, read_data="test content")
|
||||
def test_read_file_with_token_limit(self, mock_file):
|
||||
"""Test file reading with token budget enforcement."""
|
||||
content = read_file_with_token_limit("/test/file.py", max_tokens=100)
|
||||
assert "test content" in content
|
||||
mock_file.assert_called_once_with("/test/file.py", 'r', encoding='utf-8')
|
||||
```
|
||||
|
||||
**Unit Test Guidelines**:
|
||||
- **Isolation**: Mock external dependencies (file system, network, database)
|
||||
- **Fast Execution**: Each test should complete in milliseconds
|
||||
- **Single Responsibility**: One test per behavior/scenario
|
||||
- **Descriptive Names**: Test names should describe the scenario and expected outcome
|
||||
|
||||
### 2. Integration Tests
|
||||
|
||||
**Purpose**: Test component interactions and system integration
|
||||
|
||||
**Location**: `tests/integration/`
|
||||
|
||||
**Example Structure**:
|
||||
```python
|
||||
# tests/integration/test_tool_execution.py
|
||||
import pytest
|
||||
import asyncio
|
||||
from unittest.mock import patch
|
||||
|
||||
from server import call_tool
|
||||
from tools.chat import ChatTool
|
||||
from utils.conversation_memory import ConversationMemory
|
||||
|
||||
class TestToolExecution:
|
||||
"""Integration tests for tool execution pipeline."""
|
||||
|
||||
@pytest.fixture
|
||||
def mock_redis(self):
|
||||
"""Mock Redis for conversation memory testing."""
|
||||
with patch('redis.Redis') as mock:
|
||||
yield mock
|
||||
|
||||
@pytest.fixture
|
||||
def conversation_memory(self, mock_redis):
|
||||
"""Create conversation memory with mocked Redis."""
|
||||
return ConversationMemory("redis://mock")
|
||||
|
||||
async def test_chat_tool_execution_with_memory(self, conversation_memory):
|
||||
"""Test chat tool execution with conversation memory integration."""
|
||||
# Arrange
|
||||
request = {
|
||||
"name": "chat",
|
||||
"arguments": {
|
||||
"prompt": "Hello",
|
||||
"continuation_id": "test-thread-123"
|
||||
}
|
||||
}
|
||||
|
||||
# Act
|
||||
result = await call_tool(request["name"], request["arguments"])
|
||||
|
||||
# Assert
|
||||
assert len(result) == 1
|
||||
assert result[0].type == "text"
|
||||
assert "hello" in result[0].text.lower()
|
||||
|
||||
async def test_tool_execution_error_handling(self):
|
||||
"""Test error handling in tool execution pipeline."""
|
||||
# Test with invalid tool name
|
||||
with pytest.raises(ToolNotFoundError):
|
||||
await call_tool("nonexistent_tool", {})
|
||||
```
|
||||
|
||||
**Integration Test Guidelines**:
|
||||
- **Real Component Interaction**: Test actual component communication
|
||||
- **Mock External Services**: Mock external APIs (Gemini, Redis) for reliability
|
||||
- **Error Scenarios**: Test error propagation and handling
|
||||
- **Async Testing**: Use pytest-asyncio for async code testing
|
||||
|
||||
### 3. Live Integration Tests
|
||||
|
||||
**Purpose**: Test real API integration with external services
|
||||
|
||||
**Location**: `tests/live/`
|
||||
|
||||
**Requirements**:
|
||||
- Valid `GEMINI_API_KEY` environment variable
|
||||
- Redis server running (for conversation memory tests)
|
||||
- Network connectivity
|
||||
|
||||
**Example Structure**:
|
||||
```python
|
||||
# tests/live/test_gemini_integration.py
|
||||
import pytest
|
||||
import os
|
||||
|
||||
from tools.chat import ChatTool
|
||||
from tools.models import GeminiClient
|
||||
|
||||
@pytest.mark.live
|
||||
@pytest.mark.skipif(not os.getenv("GEMINI_API_KEY"), reason="API key required")
|
||||
class TestGeminiIntegration:
|
||||
"""Live tests requiring actual Gemini API access."""
|
||||
|
||||
def setup_method(self):
|
||||
"""Set up for live testing."""
|
||||
self.api_key = os.getenv("GEMINI_API_KEY")
|
||||
self.client = GeminiClient(self.api_key)
|
||||
|
||||
async def test_basic_gemini_request(self):
|
||||
"""Test basic Gemini API request/response."""
|
||||
response = await self.client.generate_response(
|
||||
prompt="Say 'test successful'",
|
||||
thinking_mode="minimal"
|
||||
)
|
||||
assert "test successful" in response.lower()
|
||||
|
||||
async def test_chat_tool_with_real_api(self):
|
||||
"""Test ChatTool with real Gemini API integration."""
|
||||
tool = ChatTool()
|
||||
result = await tool.execute({
|
||||
"prompt": "What is 2+2?",
|
||||
"thinking_mode": "minimal"
|
||||
})
|
||||
|
||||
assert result.status == "success"
|
||||
assert "4" in result.content
|
||||
```
|
||||
|
||||
**Live Test Guidelines**:
|
||||
- **Skip When Unavailable**: Skip if API keys or services unavailable
|
||||
- **Rate Limiting**: Respect API rate limits with delays
|
||||
- **Minimal Mode**: Use minimal thinking mode for speed
|
||||
- **Cleanup**: Clean up any created resources
|
||||
|
||||
### 4. Security Tests
|
||||
|
||||
**Purpose**: Validate security measures and vulnerability prevention
|
||||
|
||||
**Location**: `tests/security/`
|
||||
|
||||
**Example Structure**:
|
||||
```python
|
||||
# tests/security/test_path_validation.py
|
||||
import pytest
|
||||
|
||||
from utils.file_utils import validate_file_path
|
||||
from exceptions import SecurityError
|
||||
|
||||
class TestSecurityValidation:
|
||||
"""Security-focused tests for input validation."""
|
||||
|
||||
@pytest.mark.parametrize("dangerous_path", [
|
||||
"../../../etc/passwd",
|
||||
"/etc/shadow",
|
||||
"~/../../root/.ssh/id_rsa",
|
||||
"/var/log/auth.log",
|
||||
"\\..\\..\\windows\\system32\\config\\sam"
|
||||
])
|
||||
def test_dangerous_path_rejection(self, dangerous_path):
|
||||
"""Test that dangerous file paths are rejected."""
|
||||
with pytest.raises(SecurityError):
|
||||
validate_file_path(dangerous_path)
|
||||
|
||||
def test_secret_sanitization_in_logs(self):
|
||||
"""Test that sensitive data is sanitized in log output."""
|
||||
request_data = {
|
||||
"prompt": "Hello",
|
||||
"api_key": "sk-secret123",
|
||||
"token": "bearer-token-456"
|
||||
}
|
||||
|
||||
sanitized = sanitize_for_logging(request_data)
|
||||
|
||||
assert sanitized["api_key"] == "[REDACTED]"
|
||||
assert sanitized["token"] == "[REDACTED]"
|
||||
assert sanitized["prompt"] == "Hello" # Non-sensitive data preserved
|
||||
```
|
||||
|
||||
## Test Configuration
|
||||
|
||||
### pytest Configuration
|
||||
|
||||
**pytest.ini**:
|
||||
```ini
|
||||
[tool:pytest]
|
||||
testpaths = tests
|
||||
python_files = test_*.py *_test.py
|
||||
python_classes = Test*
|
||||
python_functions = test_*
|
||||
addopts =
|
||||
-v
|
||||
--strict-markers
|
||||
--disable-warnings
|
||||
--cov=tools
|
||||
--cov=utils
|
||||
--cov-report=html
|
||||
--cov-report=term-missing
|
||||
--cov-fail-under=80
|
||||
|
||||
markers =
|
||||
unit: Unit tests (fast, isolated)
|
||||
integration: Integration tests (component interaction)
|
||||
live: Live tests requiring API keys and external services
|
||||
security: Security-focused tests
|
||||
slow: Tests that take more than 1 second
|
||||
```
|
||||
|
||||
**conftest.py**:
|
||||
```python
|
||||
# tests/conftest.py
|
||||
import pytest
|
||||
import asyncio
|
||||
from unittest.mock import Mock, patch
|
||||
|
||||
@pytest.fixture(scope="session")
|
||||
def event_loop():
|
||||
"""Create an instance of the default event loop for the test session."""
|
||||
loop = asyncio.get_event_loop_policy().new_event_loop()
|
||||
yield loop
|
||||
loop.close()
|
||||
|
||||
@pytest.fixture
|
||||
def mock_gemini_client():
|
||||
"""Mock Gemini client for testing without API calls."""
|
||||
with patch('tools.models.GeminiClient') as mock:
|
||||
mock_instance = Mock()
|
||||
mock_instance.generate_response.return_value = "Mocked response"
|
||||
mock.return_value = mock_instance
|
||||
yield mock_instance
|
||||
|
||||
@pytest.fixture
|
||||
def mock_redis():
|
||||
"""Mock Redis client for testing without Redis server."""
|
||||
with patch('redis.Redis') as mock:
|
||||
yield mock
|
||||
|
||||
@pytest.fixture
|
||||
def sample_file_content():
|
||||
"""Sample file content for testing file processing."""
|
||||
return """
|
||||
def example_function():
|
||||
# This is a sample function
|
||||
return "hello world"
|
||||
|
||||
class ExampleClass:
|
||||
def method(self):
|
||||
pass
|
||||
"""
|
||||
|
||||
@pytest.fixture
|
||||
def temp_project_directory(tmp_path):
|
||||
"""Create temporary project directory structure for testing."""
|
||||
project_dir = tmp_path / "test_project"
|
||||
project_dir.mkdir()
|
||||
|
||||
# Create subdirectories
|
||||
(project_dir / "tools").mkdir()
|
||||
(project_dir / "utils").mkdir()
|
||||
(project_dir / "tests").mkdir()
|
||||
|
||||
# Create sample files
|
||||
(project_dir / "tools" / "sample.py").write_text("# Sample tool")
|
||||
(project_dir / "utils" / "helper.py").write_text("# Helper utility")
|
||||
|
||||
return project_dir
|
||||
```
|
||||
|
||||
## Test Data Management
|
||||
|
||||
### Test Fixtures
|
||||
|
||||
**File-based Fixtures**:
|
||||
```python
|
||||
# tests/fixtures/sample_code.py
|
||||
PYTHON_CODE_SAMPLE = '''
|
||||
import asyncio
|
||||
from typing import Dict, List
|
||||
|
||||
async def process_data(items: List[str]) -> Dict[str, int]:
|
||||
"""Process a list of items and return counts."""
|
||||
result = {}
|
||||
for item in items:
|
||||
result[item] = len(item)
|
||||
return result
|
||||
'''
|
||||
|
||||
JAVASCRIPT_CODE_SAMPLE = '''
|
||||
async function processData(items) {
|
||||
const result = {};
|
||||
for (const item of items) {
|
||||
result[item] = item.length;
|
||||
}
|
||||
return result;
|
||||
}
|
||||
'''
|
||||
|
||||
ERROR_LOGS_SAMPLE = '''
|
||||
2025-01-11 23:45:12 ERROR [tool_execution] Tool 'analyze' failed: File not found
|
||||
Traceback (most recent call last):
|
||||
File "/app/tools/analyze.py", line 45, in execute
|
||||
content = read_file(file_path)
|
||||
File "/app/utils/file_utils.py", line 23, in read_file
|
||||
with open(file_path, 'r') as f:
|
||||
FileNotFoundError: [Errno 2] No such file or directory: '/nonexistent/file.py'
|
||||
'''
|
||||
```
|
||||
|
||||
### Mock Data Factories
|
||||
|
||||
**ToolOutput Factory**:
|
||||
```python
|
||||
# tests/factories.py
|
||||
from dataclasses import dataclass
|
||||
from typing import Dict, Any, List
|
||||
|
||||
def create_tool_output(
|
||||
content: str = "Default response",
|
||||
status: str = "success",
|
||||
metadata: Dict[str, Any] = None,
|
||||
files_processed: List[str] = None
|
||||
) -> ToolOutput:
|
||||
"""Factory for creating ToolOutput test instances."""
|
||||
return ToolOutput(
|
||||
content=content,
|
||||
metadata=metadata or {},
|
||||
files_processed=files_processed or [],
|
||||
status=status
|
||||
)
|
||||
|
||||
def create_thread_context(
|
||||
thread_id: str = "test-thread-123",
|
||||
files: List[str] = None
|
||||
) -> ThreadContext:
|
||||
"""Factory for creating ThreadContext test instances."""
|
||||
return ThreadContext(
|
||||
thread_id=thread_id,
|
||||
conversation_files=set(files or []),
|
||||
tool_history=[],
|
||||
context_tokens=0
|
||||
)
|
||||
```
|
||||
|
||||
## Mocking Strategies
|
||||
|
||||
### External Service Mocking
|
||||
|
||||
**Gemini API Mocking**:
|
||||
```python
|
||||
class MockGeminiClient:
|
||||
"""Mock Gemini client for testing."""
|
||||
|
||||
def __init__(self, responses: Dict[str, str] = None):
|
||||
self.responses = responses or {
|
||||
"default": "This is a mocked response from Gemini"
|
||||
}
|
||||
self.call_count = 0
|
||||
|
||||
async def generate_response(self, prompt: str, **kwargs) -> str:
|
||||
"""Mock response generation."""
|
||||
self.call_count += 1
|
||||
|
||||
# Return specific response for specific prompts
|
||||
for key, response in self.responses.items():
|
||||
if key in prompt.lower():
|
||||
return response
|
||||
|
||||
return self.responses.get("default", "Mock response")
|
||||
|
||||
# Usage in tests
|
||||
@patch('tools.models.GeminiClient', MockGeminiClient)
|
||||
def test_with_mocked_gemini():
|
||||
# Test implementation
|
||||
pass
|
||||
```
|
||||
|
||||
**File System Mocking**:
|
||||
```python
|
||||
@patch('builtins.open', mock_open(read_data="file content"))
|
||||
@patch('os.path.exists', return_value=True)
|
||||
@patch('os.path.getsize', return_value=1024)
|
||||
def test_file_operations():
|
||||
"""Test file operations with mocked file system."""
|
||||
content = read_file("/mocked/file.py")
|
||||
assert content == "file content"
|
||||
```
|
||||
|
||||
## Performance Testing
|
||||
|
||||
### Load Testing
|
||||
|
||||
**Concurrent Tool Execution**:
|
||||
```python
|
||||
# tests/performance/test_load.py
|
||||
import asyncio
|
||||
import pytest
|
||||
import time
|
||||
|
||||
@pytest.mark.slow
|
||||
class TestPerformance:
|
||||
"""Performance tests for system load handling."""
|
||||
|
||||
async def test_concurrent_tool_execution(self):
|
||||
"""Test system performance under concurrent load."""
|
||||
start_time = time.time()
|
||||
|
||||
# Create 10 concurrent tool execution tasks
|
||||
tasks = []
|
||||
for i in range(10):
|
||||
task = asyncio.create_task(
|
||||
call_tool("chat", {"prompt": f"Request {i}"})
|
||||
)
|
||||
tasks.append(task)
|
||||
|
||||
# Wait for all tasks to complete
|
||||
results = await asyncio.gather(*tasks)
|
||||
|
||||
end_time = time.time()
|
||||
execution_time = end_time - start_time
|
||||
|
||||
# Verify all requests succeeded
|
||||
assert len(results) == 10
|
||||
assert all(len(result) == 1 for result in results)
|
||||
|
||||
# Performance assertion (adjust based on requirements)
|
||||
assert execution_time < 30.0 # All requests should complete within 30s
|
||||
|
||||
async def test_memory_usage_stability(self):
|
||||
"""Test that memory usage remains stable under load."""
|
||||
import psutil
|
||||
import gc
|
||||
|
||||
process = psutil.Process()
|
||||
initial_memory = process.memory_info().rss
|
||||
|
||||
# Execute multiple operations
|
||||
for i in range(100):
|
||||
await call_tool("chat", {"prompt": f"Memory test {i}"})
|
||||
|
||||
# Force garbage collection periodically
|
||||
if i % 10 == 0:
|
||||
gc.collect()
|
||||
|
||||
final_memory = process.memory_info().rss
|
||||
memory_growth = final_memory - initial_memory
|
||||
|
||||
# Memory growth should be reasonable (adjust threshold as needed)
|
||||
assert memory_growth < 100 * 1024 * 1024 # Less than 100MB growth
|
||||
```
|
||||
|
||||
## Test Execution
|
||||
|
||||
### Running Tests
|
||||
|
||||
**Basic Test Execution**:
|
||||
```bash
|
||||
# Run all tests
|
||||
pytest
|
||||
|
||||
# Run specific test categories
|
||||
pytest -m unit # Unit tests only
|
||||
pytest -m integration # Integration tests only
|
||||
pytest -m "not live" # All tests except live tests
|
||||
pytest -m "live and not slow" # Live tests that are fast
|
||||
|
||||
# Run with coverage
|
||||
pytest --cov=tools --cov=utils --cov-report=html
|
||||
|
||||
# Run specific test file
|
||||
pytest tests/unit/test_file_utils.py -v
|
||||
|
||||
# Run specific test method
|
||||
pytest tests/unit/test_file_utils.py::TestFileUtils::test_validate_file_path -v
|
||||
```
|
||||
|
||||
**Continuous Integration**:
|
||||
```bash
|
||||
# CI test script
|
||||
#!/bin/bash
|
||||
set -e
|
||||
|
||||
echo "Running unit tests..."
|
||||
pytest -m unit --cov=tools --cov=utils --cov-fail-under=80
|
||||
|
||||
echo "Running integration tests..."
|
||||
pytest -m integration
|
||||
|
||||
echo "Running security tests..."
|
||||
pytest -m security
|
||||
|
||||
echo "Checking code quality..."
|
||||
flake8 tools/ utils/ tests/
|
||||
mypy tools/ utils/
|
||||
|
||||
echo "All tests passed!"
|
||||
```
|
||||
|
||||
### Test Reports
|
||||
|
||||
**Coverage Reports**:
|
||||
```bash
|
||||
# Generate HTML coverage report
|
||||
pytest --cov=tools --cov=utils --cov-report=html
|
||||
open htmlcov/index.html
|
||||
|
||||
# Generate terminal coverage report
|
||||
pytest --cov=tools --cov=utils --cov-report=term-missing
|
||||
```
|
||||
|
||||
**Test Results Export**:
|
||||
```bash
|
||||
# Export test results to JUnit XML (for CI integration)
|
||||
pytest --junitxml=test-results.xml
|
||||
|
||||
# Export test results with timing information
|
||||
pytest --durations=10 # Show 10 slowest tests
|
||||
```
|
||||
|
||||
## Quality Metrics
|
||||
|
||||
### Coverage Targets
|
||||
|
||||
**Minimum Coverage Requirements**:
|
||||
- **Overall Coverage**: 80%
|
||||
- **Critical Modules**: 90% (security, file_utils, conversation_memory)
|
||||
- **Tool Modules**: 85%
|
||||
- **Utility Modules**: 80%
|
||||
|
||||
**Coverage Enforcement**:
|
||||
```bash
|
||||
# Fail build if coverage drops below threshold
|
||||
pytest --cov-fail-under=80
|
||||
```
|
||||
|
||||
### Test Quality Metrics
|
||||
|
||||
**Test Suite Characteristics**:
|
||||
- **Fast Execution**: Unit test suite should complete in <30 seconds
|
||||
- **Reliable**: Tests should have <1% flaky failure rate
|
||||
- **Maintainable**: Test code should follow same quality standards as production code
|
||||
- **Comprehensive**: All critical paths and edge cases covered
|
||||
|
||||
## Integration with Development Workflow
|
||||
|
||||
### Pre-commit Testing
|
||||
|
||||
**Git Hook Integration**:
|
||||
```bash
|
||||
#!/bin/sh
|
||||
# .git/hooks/pre-commit
|
||||
|
||||
echo "Running pre-commit tests..."
|
||||
|
||||
# Run fast tests before commit
|
||||
pytest -m "unit and not slow" --cov-fail-under=80
|
||||
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "Tests failed. Commit blocked."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "Pre-commit tests passed."
|
||||
```
|
||||
|
||||
### CI/CD Integration
|
||||
|
||||
**GitHub Actions Workflow**:
|
||||
```yaml
|
||||
name: Test Suite
|
||||
on: [push, pull_request]
|
||||
|
||||
jobs:
|
||||
test:
|
||||
runs-on: ubuntu-latest
|
||||
strategy:
|
||||
matrix:
|
||||
python-version: [3.9, 3.10, 3.11]
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- name: Set up Python ${{ matrix.python-version }}
|
||||
uses: actions/setup-python@v4
|
||||
with:
|
||||
python-version: ${{ matrix.python-version }}
|
||||
|
||||
- name: Install dependencies
|
||||
run: |
|
||||
pip install -r requirements.txt
|
||||
pip install pytest pytest-cov pytest-asyncio
|
||||
|
||||
- name: Run unit tests
|
||||
run: pytest -m unit --cov=tools --cov=utils --cov-fail-under=80
|
||||
|
||||
- name: Run integration tests
|
||||
run: pytest -m integration
|
||||
|
||||
- name: Run security tests
|
||||
run: pytest -m security
|
||||
|
||||
- name: Upload coverage reports
|
||||
uses: codecov/codecov-action@v3
|
||||
with:
|
||||
file: ./coverage.xml
|
||||
```
|
||||
|
||||
## Detailed Test Structure Analysis
|
||||
|
||||
For a comprehensive analysis of the existing test suite, including detailed breakdowns of all 17 test files, security testing patterns, and collaboration feature validation, see:
|
||||
|
||||
**[Test Structure Documentation](test-structure.md)** - Complete analysis of existing test organization, mocking strategies, and quality assurance patterns
|
||||
|
||||
---
|
||||
|
||||
This comprehensive testing strategy ensures high-quality, reliable code while maintaining development velocity and supporting the collaborative patterns defined in CLAUDE.md.
|
||||
622
docs/contributing/workflows.md
Normal file
622
docs/contributing/workflows.md
Normal file
@@ -0,0 +1,622 @@
|
||||
# Development Workflows & Processes
|
||||
|
||||
## Overview
|
||||
|
||||
This document outlines the development workflows and processes for the Gemini MCP Server project, following the collaboration patterns defined in CLAUDE.md and integrating with the Memory Bank system for context preservation.
|
||||
|
||||
## Pull Request Automation & Versioning
|
||||
|
||||
### Automated Workflows
|
||||
|
||||
The project implements automated versioning and Docker builds based on PR title prefixes, enabling seamless releases and testing.
|
||||
|
||||
#### PR Title Prefix System
|
||||
|
||||
**Version Bumping Prefixes** (creates releases):
|
||||
- `feat:` → Minor version bump (1.X.0) + Docker build + GitHub release
|
||||
- `fix:` → Patch version bump (1.0.X) + Docker build + GitHub release
|
||||
- `breaking:` → Major version bump (X.0.0) + Docker build + GitHub release
|
||||
- `perf:` → Patch version bump + Docker build + GitHub release
|
||||
- `refactor:` → Patch version bump + Docker build + GitHub release
|
||||
|
||||
**Non-Version Prefixes** (no releases):
|
||||
- `docs:` → Documentation changes only
|
||||
- `chore:` → Maintenance tasks
|
||||
- `test:` → Test updates
|
||||
- `ci:` → CI/CD pipeline changes
|
||||
- `style:` → Code formatting/style
|
||||
|
||||
**Docker Build Combinations** (Docker without versioning):
|
||||
- `docker:` → Force Docker build only
|
||||
- `docs+docker:` → Documentation + Docker build
|
||||
- `chore+docker:` → Maintenance + Docker build
|
||||
- `test+docker:` → Test changes + Docker build
|
||||
- `ci+docker:` → CI changes + Docker build
|
||||
- `style+docker:` → Style changes + Docker build
|
||||
|
||||
#### Workflow Execution Flow
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[PR Created] --> B[docker-test.yml]
|
||||
B --> C[test.yml]
|
||||
A --> C
|
||||
|
||||
D[PR Merged] --> E[auto-version.yml]
|
||||
E --> F{PR Title Analysis}
|
||||
|
||||
F -->|feat:, fix:, etc.| G[Version Bump]
|
||||
F -->|docker:, docs+docker:, etc.| H[Docker Build Flag]
|
||||
F -->|docs:, chore:, etc.| I[No Action]
|
||||
|
||||
G --> J[Create Git Tag]
|
||||
J --> K[build_and_publish_docker.yml]
|
||||
|
||||
H --> L[Repository Dispatch]
|
||||
L --> K
|
||||
|
||||
K --> M[Build & Push to GHCR]
|
||||
|
||||
G --> N[Create GitHub Release]
|
||||
```
|
||||
|
||||
#### Docker Image Tagging Strategy
|
||||
|
||||
**For Version Releases:**
|
||||
- `v1.2.3` - Semantic version tag
|
||||
- `latest` - Latest stable release
|
||||
|
||||
**For Docker-only Builds:**
|
||||
- `pr-{number}` - PR-specific tag (e.g., `pr-42`)
|
||||
- `main-{commit-sha}` - Commit-specific tag (e.g., `main-abc1234`)
|
||||
|
||||
#### Implementation Details
|
||||
|
||||
**Auto-version Workflow** (`.github/workflows/auto-version.yml`):
|
||||
1. Analyzes PR title for semantic prefix
|
||||
2. Updates `config.py` with new version
|
||||
3. Creates git tag and GitHub release
|
||||
4. Triggers Docker build via tag creation or repository dispatch
|
||||
|
||||
**Docker Build Workflow** (`.github/workflows/build_and_publish_docker.yml`):
|
||||
1. Triggered by git tags or repository dispatch
|
||||
2. Builds multi-platform Docker images
|
||||
3. Pushes to GitHub Container Registry (GHCR)
|
||||
4. Handles different tagging strategies based on trigger
|
||||
|
||||
**Docker Test Workflow** (`.github/workflows/docker-test.yml`):
|
||||
1. Runs on all PRs
|
||||
2. Validates Docker build without publishing
|
||||
3. Provides early feedback on containerization issues
|
||||
|
||||
## Core Development Workflow
|
||||
|
||||
### 1. Feature Development Process
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[Issue/Feature Request] --> B[Planning Phase]
|
||||
B --> C[Analysis Phase]
|
||||
C --> D[Implementation Phase]
|
||||
D --> E[Review Phase]
|
||||
E --> F[Documentation Phase]
|
||||
F --> G[Testing Phase]
|
||||
G --> H[Validation Phase]
|
||||
H --> I[Deployment]
|
||||
|
||||
B --> B1[thinkdeep - Architecture Planning]
|
||||
C --> C1[analyze - Codebase Understanding]
|
||||
D --> D1[Code Implementation]
|
||||
E --> E1[codereview - Quality Validation]
|
||||
F --> F1[Documentation Updates]
|
||||
G --> G1[Test Implementation]
|
||||
H --> H1[precommit - Final Validation]
|
||||
```
|
||||
|
||||
### 2. Tool Selection Matrix Integration
|
||||
|
||||
**Planning Phase** - Use `thinkdeep`:
|
||||
```json
|
||||
{
|
||||
"name": "thinkdeep",
|
||||
"arguments": {
|
||||
"current_analysis": "Need to implement new tool for X functionality",
|
||||
"focus_areas": ["architecture", "integration", "security"],
|
||||
"thinking_mode": "high"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Analysis Phase** - Use `analyze`:
|
||||
```json
|
||||
{
|
||||
"name": "analyze",
|
||||
"arguments": {
|
||||
"files": ["/workspace/tools/", "/workspace/utils/"],
|
||||
"question": "Understand existing tool architecture for new implementation",
|
||||
"analysis_type": "architecture"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Review Phase** - Use `codereview`:
|
||||
```json
|
||||
{
|
||||
"name": "codereview",
|
||||
"arguments": {
|
||||
"files": ["/workspace/new-feature/"],
|
||||
"context": "New tool implementation following established patterns",
|
||||
"review_type": "full"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Validation Phase** - Use `precommit`:
|
||||
```json
|
||||
{
|
||||
"name": "precommit",
|
||||
"arguments": {
|
||||
"path": "/workspace/",
|
||||
"original_request": "Implement new X tool with Y capabilities"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Memory Bank Integration Workflow
|
||||
|
||||
### Session Initialization
|
||||
|
||||
**Every development session must start with Memory Bank check**:
|
||||
|
||||
```bash
|
||||
# 1. Check Memory Bank status
|
||||
ls memory-bank/
|
||||
|
||||
# 2. Read current context
|
||||
cat memory-bank/activeContext.md
|
||||
cat memory-bank/progress.md
|
||||
cat memory-bank/decisionLog.md
|
||||
|
||||
# 3. Update current focus if needed
|
||||
```
|
||||
|
||||
### Progress Tracking
|
||||
|
||||
**During development, update Memory Bank files**:
|
||||
|
||||
**activeContext.md** - Current work status:
|
||||
```markdown
|
||||
## Current Focus
|
||||
[2025-01-11 23:30:00] - Implementing new debug tool feature for better error analysis
|
||||
Working on: Enhanced stack trace parsing for multi-language support
|
||||
|
||||
## Recent Changes
|
||||
[2025-01-11 23:15:00] - Completed comprehensive documentation following CLAUDE.md structure
|
||||
- docs/architecture/ completed (3 files)
|
||||
- docs/api/ completed (MCP protocol + 6 tool APIs)
|
||||
- Starting docs/contributing/ development workflow documentation
|
||||
```
|
||||
|
||||
**progress.md** - Task completion tracking:
|
||||
```markdown
|
||||
## Current Tasks
|
||||
- 🔄 Creating docs/contributing/ workflow documentation
|
||||
- ✅ All tool API documentation completed
|
||||
- 🔄 Planning next enhancement: multi-language debug support
|
||||
|
||||
## Completed Tasks
|
||||
- ✅ Comprehensive architecture documentation (overview, components, data-flow)
|
||||
- ✅ Complete API documentation (MCP protocol + all 6 tools)
|
||||
- ✅ Memory Bank integration with CLAUDE.md collaboration rules
|
||||
```
|
||||
|
||||
**decisionLog.md** - Architectural decisions:
|
||||
```markdown
|
||||
[2025-01-11 23:30:00] - Tool Documentation Structure
|
||||
Decision: Create individual API reference files for each tool rather than single comprehensive document
|
||||
Rationale: Better maintainability, easier navigation, clearer separation of concerns
|
||||
Implementation: docs/api/tools/ directory with dedicated files for chat, thinkdeep, analyze, codereview, debug, precommit
|
||||
```
|
||||
|
||||
### UMB (Update Memory Bank) Protocol
|
||||
|
||||
**Manual synchronization command**: `Update Memory Bank` or `UMB`
|
||||
|
||||
**When to use UMB**:
|
||||
- End of development session
|
||||
- After major milestone completion
|
||||
- Before switching between different features
|
||||
- When context becomes fragmented
|
||||
|
||||
**UMB Process**:
|
||||
1. Stop current activity
|
||||
2. Review complete chat history
|
||||
3. Update all Memory Bank files comprehensively
|
||||
4. Ensure cross-session continuity
|
||||
5. Document continuation points
|
||||
|
||||
## Git Workflow
|
||||
|
||||
### Branch Strategy
|
||||
|
||||
**Branch Naming Convention**:
|
||||
```bash
|
||||
feature/tool-enhancement-debug-multilang
|
||||
feature/docs-api-reference
|
||||
bugfix/security-path-validation
|
||||
hotfix/memory-leak-conversation-storage
|
||||
```
|
||||
|
||||
**Branch Lifecycle**:
|
||||
```bash
|
||||
# 1. Create feature branch
|
||||
git checkout -b feature/new-functionality
|
||||
|
||||
# 2. Regular commits with descriptive messages
|
||||
git add .
|
||||
git commit -m "Implement core functionality for X feature
|
||||
|
||||
- Add new utility functions
|
||||
- Update configuration handling
|
||||
- Add comprehensive tests
|
||||
- Update documentation
|
||||
|
||||
🤖 Generated with Claude Code
|
||||
Co-Authored-By: Claude <noreply@anthropic.com>"
|
||||
|
||||
# 3. Pre-merge validation
|
||||
# Run precommit tool validation
|
||||
# Update documentation
|
||||
# Ensure Memory Bank is synchronized
|
||||
|
||||
# 4. Create pull request
|
||||
gh pr create --title "Feature: New functionality" --body "..."
|
||||
```
|
||||
|
||||
### Commit Message Standards
|
||||
|
||||
**Format Template**:
|
||||
```
|
||||
<type>: <description>
|
||||
|
||||
<body with detailed changes>
|
||||
|
||||
🤖 Generated with Claude Code
|
||||
Co-Authored-By: Claude <noreply@anthropic.com>
|
||||
```
|
||||
|
||||
**Commit Types**:
|
||||
- `feat`: New feature implementation
|
||||
- `fix`: Bug fixes and corrections
|
||||
- `docs`: Documentation updates
|
||||
- `refactor`: Code refactoring without functionality change
|
||||
- `test`: Test additions or modifications
|
||||
- `config`: Configuration and setup changes
|
||||
|
||||
### Pre-Commit Validation
|
||||
|
||||
**Mandatory validation before every commit**:
|
||||
|
||||
```bash
|
||||
# 1. Run precommit tool
|
||||
claude-code-cli --tool precommit --path $(pwd)
|
||||
|
||||
# 2. Address any critical/high issues
|
||||
# 3. Update documentation if code changes
|
||||
# 4. Ensure Memory Bank reflects changes
|
||||
# 5. Commit only after validation passes
|
||||
```
|
||||
|
||||
## Code Review Process
|
||||
|
||||
### Self-Review Checklist
|
||||
|
||||
**Before requesting review**:
|
||||
- [ ] Run `codereview` tool on changes
|
||||
- [ ] Address all critical and high-severity issues
|
||||
- [ ] Update relevant documentation
|
||||
- [ ] Add/update tests for new functionality
|
||||
- [ ] Run full test suite locally
|
||||
- [ ] Update Memory Bank with decisions made
|
||||
- [ ] Ensure CLAUDE.md collaboration patterns followed
|
||||
|
||||
### Peer Review Process
|
||||
|
||||
**Review Preparation**:
|
||||
```json
|
||||
{
|
||||
"name": "analyze",
|
||||
"arguments": {
|
||||
"files": ["/workspace/changed-files/"],
|
||||
"question": "Prepare comprehensive context for code review",
|
||||
"analysis_type": "general"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Review Execution**:
|
||||
```json
|
||||
{
|
||||
"name": "codereview",
|
||||
"arguments": {
|
||||
"files": ["/workspace/pull-request-files/"],
|
||||
"context": "Pull request review for [feature description]",
|
||||
"review_type": "full",
|
||||
"thinking_mode": "high"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Double Validation Protocol** (for critical changes):
|
||||
1. **Primary Analysis** (Gemini): Deep code review using `codereview`
|
||||
2. **Adversarial Review** (Claude): Challenge findings, look for edge cases
|
||||
3. **Synthesis**: Combine insights and resolve disagreements
|
||||
4. **Memory Update**: Record key decisions and validation results
|
||||
|
||||
## Documentation Workflow
|
||||
|
||||
### Documentation-Driven Development
|
||||
|
||||
**Every code change requires corresponding documentation updates**:
|
||||
|
||||
1. **Architecture Changes**: Update `docs/architecture/`
|
||||
2. **API Changes**: Update `docs/api/` and tool references
|
||||
3. **Process Changes**: Update `docs/contributing/`
|
||||
4. **User-Facing Changes**: Update `docs/user-guides/`
|
||||
|
||||
### Documentation Quality Standards
|
||||
|
||||
**For Technical Audiences**:
|
||||
- Include specific file and line number references (`file_path:line_number`)
|
||||
- Explain architectural decisions and trade-offs
|
||||
- Provide concrete examples and code snippets
|
||||
- Document error scenarios and recovery strategies
|
||||
|
||||
**For Non-Technical Audiences**:
|
||||
- Use plain language and explain technical terms
|
||||
- Start with problem statements and value propositions
|
||||
- Include practical usage scenarios
|
||||
- Provide troubleshooting guides
|
||||
|
||||
### Documentation Review Process
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "analyze",
|
||||
"arguments": {
|
||||
"files": ["/workspace/docs/"],
|
||||
"question": "Review documentation completeness and accuracy against code changes",
|
||||
"analysis_type": "quality"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Testing Workflow
|
||||
|
||||
### Test Strategy
|
||||
|
||||
**Test Categories**:
|
||||
1. **Unit Tests**: Individual tool functionality (`tests/test_tools.py`)
|
||||
2. **Integration Tests**: Tool interaction and MCP protocol (`tests/test_integration.py`)
|
||||
3. **Live Tests**: Real API integration (requires API keys)
|
||||
4. **Security Tests**: Input validation and security scenarios
|
||||
|
||||
### Test Implementation Process
|
||||
|
||||
**Test-Driven Development**:
|
||||
```bash
|
||||
# 1. Write failing tests for new functionality
|
||||
pytest tests/test_new_feature.py -v
|
||||
|
||||
# 2. Implement functionality to pass tests
|
||||
# 3. Refactor while maintaining test coverage
|
||||
# 4. Add additional edge case tests
|
||||
# 5. Validate with full test suite
|
||||
pytest tests/ -v --cov=tools --cov=utils
|
||||
```
|
||||
|
||||
### Continuous Integration
|
||||
|
||||
**GitHub Actions Workflow**:
|
||||
```yaml
|
||||
name: Quality Assurance
|
||||
on: [push, pull_request]
|
||||
|
||||
jobs:
|
||||
test:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- name: Setup Python
|
||||
uses: actions/setup-python@v4
|
||||
with:
|
||||
python-version: '3.9'
|
||||
- name: Install dependencies
|
||||
run: pip install -r requirements.txt
|
||||
- name: Run tests
|
||||
run: pytest tests/ -v --cov=tools --cov=utils
|
||||
- name: Run precommit validation
|
||||
run: claude-code-cli --tool precommit --path .
|
||||
```
|
||||
|
||||
## Collaboration Patterns
|
||||
|
||||
### Claude & Gemini Workflow Integration
|
||||
|
||||
**Task Distribution**:
|
||||
- **Claude**: Immediate tasks, coordination, file operations, git management
|
||||
- **Gemini**: Deep analysis, strategic planning, comprehensive code review
|
||||
- **Both**: Documentation creation, problem-solving, architecture decisions
|
||||
|
||||
**Communication Patterns**:
|
||||
```json
|
||||
// Claude initiates analysis
|
||||
{
|
||||
"name": "analyze",
|
||||
"arguments": {
|
||||
"files": ["/workspace/complex-system/"],
|
||||
"question": "Understand system for major refactoring",
|
||||
"continuation_id": "analysis-session-uuid"
|
||||
}
|
||||
}
|
||||
|
||||
// Gemini provides deep insights
|
||||
// Claude uses insights for implementation decisions
|
||||
// Both collaborate on documentation and validation
|
||||
```
|
||||
|
||||
### Cross-Tool Continuation
|
||||
|
||||
**Maintain context across tool usage**:
|
||||
```json
|
||||
// 1. Initial exploration
|
||||
{
|
||||
"name": "chat",
|
||||
"arguments": {
|
||||
"prompt": "How should we approach implementing caching?"
|
||||
}
|
||||
}
|
||||
|
||||
// 2. Deep strategic analysis
|
||||
{
|
||||
"name": "thinkdeep",
|
||||
"arguments": {
|
||||
"current_analysis": "Initial caching discussion insights...",
|
||||
"continuation_id": "chat-session-uuid"
|
||||
}
|
||||
}
|
||||
|
||||
// 3. Implementation analysis
|
||||
{
|
||||
"name": "analyze",
|
||||
"arguments": {
|
||||
"files": ["/workspace/"],
|
||||
"question": "Identify integration points for caching",
|
||||
"continuation_id": "strategy-session-uuid"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Release Workflow
|
||||
|
||||
### Automatic Versioning System
|
||||
|
||||
**Semantic versioning is automatically managed based on PR title prefixes**:
|
||||
|
||||
#### PR Title Conventions
|
||||
- `feat:` - New features → **MINOR** version bump (0.X.0)
|
||||
- `fix:` - Bug fixes → **PATCH** version bump (0.0.X)
|
||||
- `breaking:` or `BREAKING CHANGE:` - Breaking changes → **MAJOR** version bump (X.0.0)
|
||||
- `perf:` - Performance improvements → **PATCH** version bump
|
||||
- `refactor:` - Code refactoring → **PATCH** version bump
|
||||
- `docs:`, `chore:`, `test:`, `ci:`, `style:` - No version bump
|
||||
|
||||
#### Automatic Version Workflow
|
||||
1. **Create PR with appropriate prefix**: `feat: Add new debugging capability`
|
||||
2. **PR gets reviewed and merged to main**
|
||||
3. **GitHub Action automatically**:
|
||||
- Detects version bump type from PR title
|
||||
- Updates version in `config.py`
|
||||
- Updates `__updated__` timestamp
|
||||
- Commits version change
|
||||
- Creates git tag (e.g., `v3.3.0`)
|
||||
- Generates GitHub release with PR description
|
||||
- Triggers Docker build workflow
|
||||
|
||||
#### Manual Version Bumping (if needed)
|
||||
```bash
|
||||
# Run the version bump script manually
|
||||
python scripts/bump_version.py <major|minor|patch>
|
||||
|
||||
# Example: bump minor version
|
||||
python scripts/bump_version.py minor
|
||||
```
|
||||
|
||||
### Pre-Release Validation
|
||||
|
||||
**Comprehensive validation before release**:
|
||||
```bash
|
||||
# 1. Run full test suite
|
||||
pytest tests/ -v --cov=tools --cov=utils
|
||||
|
||||
# 2. Security audit
|
||||
claude-code-cli --tool codereview \
|
||||
--files /workspace/ \
|
||||
--context "Security audit for release" \
|
||||
--review-type security
|
||||
|
||||
# 3. Performance validation
|
||||
claude-code-cli --tool analyze \
|
||||
--files /workspace/ \
|
||||
--question "Identify performance issues for production" \
|
||||
--analysis-type performance
|
||||
|
||||
# 4. Documentation validation
|
||||
claude-code-cli --tool analyze \
|
||||
--files /workspace/docs/ \
|
||||
--question "Validate documentation completeness and accuracy"
|
||||
|
||||
# 5. Final precommit validation
|
||||
claude-code-cli --tool precommit --path /workspace/
|
||||
```
|
||||
|
||||
### Release Documentation
|
||||
|
||||
**Automatic release notes are generated from PR descriptions**:
|
||||
1. **GitHub Release**: Created automatically with PR details
|
||||
2. **CHANGELOG.md**: Update manually for major releases
|
||||
3. **README.md**: Update installation instructions if needed
|
||||
4. **docs/**: Ensure documentation reflects new features
|
||||
|
||||
### Deployment Process
|
||||
|
||||
**Docker Image Workflow**:
|
||||
```bash
|
||||
# 1. Build and test image locally
|
||||
docker build -t gemini-mcp-server:latest .
|
||||
docker run --rm gemini-mcp-server:latest --version
|
||||
|
||||
# 2. Push to registry (automated via GitHub Actions)
|
||||
# 3. Update deployment configurations
|
||||
# 4. Monitor deployment health
|
||||
```
|
||||
|
||||
## Troubleshooting Workflow
|
||||
|
||||
### Issue Investigation Process
|
||||
|
||||
**Systematic debugging approach**:
|
||||
```json
|
||||
{
|
||||
"name": "debug",
|
||||
"arguments": {
|
||||
"error_description": "Detailed problem description",
|
||||
"error_context": "Stack traces, logs, environment info",
|
||||
"files": ["/workspace/related-modules/"],
|
||||
"thinking_mode": "high"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Memory Bank for Issue Tracking
|
||||
|
||||
**Document issues and resolutions**:
|
||||
```markdown
|
||||
## decisionLog.md
|
||||
[2025-01-11 23:45:00] - Memory Leak Resolution
|
||||
Decision: Implement proper cleanup in conversation memory module
|
||||
Rationale: Redis connections not properly closed, causing memory growth
|
||||
Implementation: Added context managers and explicit cleanup in utils/conversation_memory.py:150
|
||||
```
|
||||
|
||||
### Knowledge Base Maintenance
|
||||
|
||||
**Update Memory Bank with solutions**:
|
||||
- Store successful debugging approaches
|
||||
- Document common issues and resolutions
|
||||
- Maintain troubleshooting patterns
|
||||
- Cross-reference with architectural decisions
|
||||
|
||||
---
|
||||
|
||||
This development workflow ensures high-quality, collaborative development while maintaining consistency with CLAUDE.md patterns and preserving knowledge through the Memory Bank system.
|
||||
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)
|
||||
44
scripts/README.md
Normal file
44
scripts/README.md
Normal file
@@ -0,0 +1,44 @@
|
||||
# Scripts Directory
|
||||
|
||||
This directory contains utility scripts for the Gemini MCP Server project.
|
||||
|
||||
## bump_version.py
|
||||
|
||||
A utility script for semantic version bumping that integrates with the automatic versioning workflow.
|
||||
|
||||
### Usage
|
||||
|
||||
```bash
|
||||
python scripts/bump_version.py <major|minor|patch>
|
||||
```
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# Bump patch version (e.g., 3.2.0 → 3.2.1)
|
||||
python scripts/bump_version.py patch
|
||||
|
||||
# Bump minor version (e.g., 3.2.0 → 3.3.0)
|
||||
python scripts/bump_version.py minor
|
||||
|
||||
# Bump major version (e.g., 3.2.0 → 4.0.0)
|
||||
python scripts/bump_version.py major
|
||||
```
|
||||
|
||||
### Features
|
||||
|
||||
- Reads current version from `config.py`
|
||||
- Applies semantic versioning rules
|
||||
- Updates both `__version__` and `__updated__` fields
|
||||
- Preserves file formatting and structure
|
||||
- Outputs new version for GitHub Actions integration
|
||||
|
||||
### Integration
|
||||
|
||||
This script is primarily used by the GitHub Actions workflow (`.github/workflows/auto-version.yml`) for automatic version bumping based on PR title prefixes. Manual usage is available for special cases.
|
||||
|
||||
### Version Bump Rules
|
||||
|
||||
- **Major**: Increments first digit, resets others (3.2.1 → 4.0.0)
|
||||
- **Minor**: Increments second digit, resets patch (3.2.1 → 3.3.0)
|
||||
- **Patch**: Increments third digit (3.2.1 → 3.2.2)
|
||||
115
scripts/bump_version.py
Executable file
115
scripts/bump_version.py
Executable file
@@ -0,0 +1,115 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Version bumping utility for Gemini MCP Server
|
||||
|
||||
This script handles semantic version bumping for the project by:
|
||||
- Reading current version from config.py
|
||||
- Applying the appropriate version bump (major, minor, patch)
|
||||
- Updating config.py with new version and timestamp
|
||||
- Preserving file structure and formatting
|
||||
"""
|
||||
|
||||
import re
|
||||
import sys
|
||||
from datetime import datetime
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
def parse_version(version_string: str) -> tuple[int, int, int]:
|
||||
"""Parse semantic version string into tuple of integers."""
|
||||
match = re.match(r"^(\d+)\.(\d+)\.(\d+)", version_string)
|
||||
if not match:
|
||||
raise ValueError(f"Invalid version format: {version_string}")
|
||||
return int(match.group(1)), int(match.group(2)), int(match.group(3))
|
||||
|
||||
|
||||
def bump_version(version: tuple[int, int, int], bump_type: str) -> tuple[int, int, int]:
|
||||
"""Apply version bump according to semantic versioning rules."""
|
||||
major, minor, patch = version
|
||||
|
||||
if bump_type == "major":
|
||||
return (major + 1, 0, 0)
|
||||
elif bump_type == "minor":
|
||||
return (major, minor + 1, 0)
|
||||
elif bump_type == "patch":
|
||||
return (major, minor, patch + 1)
|
||||
else:
|
||||
raise ValueError(f"Invalid bump type: {bump_type}")
|
||||
|
||||
|
||||
def update_config_file(new_version: str) -> None:
|
||||
"""Update version and timestamp in config.py while preserving structure."""
|
||||
config_path = Path(__file__).parent.parent / "config.py"
|
||||
|
||||
if not config_path.exists():
|
||||
raise FileNotFoundError(f"config.py not found at {config_path}")
|
||||
|
||||
# Read the current content
|
||||
content = config_path.read_text()
|
||||
|
||||
# Update version using regex to preserve formatting
|
||||
version_pattern = r'(__version__\s*=\s*["\'])[\d\.]+(["\'])'
|
||||
content = re.sub(version_pattern, rf"\g<1>{new_version}\g<2>", content)
|
||||
|
||||
# Update the __updated__ field with current date
|
||||
current_date = datetime.now().strftime("%Y-%m-%d")
|
||||
updated_pattern = r'(__updated__\s*=\s*["\'])[\d\-]+(["\'])'
|
||||
content = re.sub(updated_pattern, rf"\g<1>{current_date}\g<2>", content)
|
||||
|
||||
# Write back the updated content
|
||||
config_path.write_text(content)
|
||||
print(f"Updated config.py: version={new_version}, updated={current_date}")
|
||||
|
||||
|
||||
def get_current_version() -> str:
|
||||
"""Extract current version from config.py."""
|
||||
config_path = Path(__file__).parent.parent / "config.py"
|
||||
|
||||
if not config_path.exists():
|
||||
raise FileNotFoundError(f"config.py not found at {config_path}")
|
||||
|
||||
content = config_path.read_text()
|
||||
match = re.search(r'__version__\s*=\s*["\']([^"\']+)["\']', content)
|
||||
|
||||
if not match:
|
||||
raise ValueError("Could not find __version__ in config.py")
|
||||
|
||||
return match.group(1)
|
||||
|
||||
|
||||
def main():
|
||||
"""Main entry point for version bumping."""
|
||||
if len(sys.argv) != 2:
|
||||
print("Usage: python bump_version.py <major|minor|patch>")
|
||||
sys.exit(1)
|
||||
|
||||
bump_type = sys.argv[1].lower()
|
||||
if bump_type not in ["major", "minor", "patch"]:
|
||||
print(f"Invalid bump type: {bump_type}")
|
||||
print("Valid types: major, minor, patch")
|
||||
sys.exit(1)
|
||||
|
||||
try:
|
||||
# Get current version
|
||||
current = get_current_version()
|
||||
print(f"Current version: {current}")
|
||||
|
||||
# Parse and bump version
|
||||
version_tuple = parse_version(current)
|
||||
new_version_tuple = bump_version(version_tuple, bump_type)
|
||||
new_version = f"{new_version_tuple[0]}.{new_version_tuple[1]}.{new_version_tuple[2]}"
|
||||
|
||||
# Update config file
|
||||
update_config_file(new_version)
|
||||
|
||||
# Output new version for GitHub Actions
|
||||
print(f"New version: {new_version}")
|
||||
print(f"::set-output name=version::{new_version}")
|
||||
|
||||
except Exception as e:
|
||||
print(f"Error: {e}")
|
||||
sys.exit(1)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
Reference in New Issue
Block a user