torbjorn/my-pal-mcp-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
068873f1f30b4bacede0bd32d9c994b5650414be
my-pal-mcp-server/docs/README.md
PCITI c5313b170a 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>
2025-06-12 12:10:27 +02:00

161 lines
9.7 KiB
Markdown
Raw Blame History

# 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).
Reference in New Issue View Git Blame Copy Permalink