addinte templates and user guide

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,80 @@
+name: 🐞 Bug Report
+description: Create a report to help us improve
+labels: ["bug", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for taking the time to file a bug report! Please provide as much detail as possible to help us reproduce and fix the issue.
+
+  - type: input
+    id: version
+    attributes:
+      label: Project Version
+      description: "Which version are you using? (e.g., Docker image tag like `latest` or `v1.2.3`, or a git commit SHA)"
+      placeholder: "e.g., ghcr.io/beehiveinnovations/gemini-mcp-server:latest"
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Bug Description
+      description: A clear and concise description of what the bug is.
+      placeholder: "When I run the `codereview` tool on a Python file with syntax errors, it hangs instead of reporting an error."
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction-steps
+    attributes:
+      label: Steps to Reproduce
+      description: "Provide the exact steps to reproduce the behavior. Include the full command you ran."
+      placeholder: |
+        1. Create a file `test.py` with the content `def my_func(a,b)`
+        2. Run the command: `docker exec -i gemini-mcp-server python server.py`
+        3. Use Claude Desktop with gemini codereview tool on test.py
+        4. Observe the behavior...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected-behavior
+    attributes:
+      label: Expected Behavior
+      description: A clear and concise description of what you expected to happen.
+      placeholder: "I expected the tool to exit with an error message about the invalid Python syntax."
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant Log Output
+      description: "Please copy and paste any relevant log output. This will be automatically formatted into a code block."
+      render: shell
+
+  - type: dropdown
+    id: environment
+    attributes:
+      label: Operating System
+      description: What operating system are you running the Docker client on?
+      options:
+        - Windows (via WSL2)
+        - Windows (via Docker Desktop)
+        - macOS (Intel)
+        - macOS (Apple Silicon)
+        - Linux
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: no-duplicate-issues
+    attributes:
+      label: Sanity Checks
+      description: "Before submitting, please confirm the following:"
+      options:
+        - label: I have searched the existing issues and this is not a duplicate.
+          required: true
+        - label: I have confirmed that my `GEMINI_API_KEY` is set correctly.
+          required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 💬 General Discussion
+    url: https://github.com/BeehiveInnovations/gemini-mcp-server/discussions
+    about: Ask questions, share ideas, or discuss usage patterns with the community
+  - name: 📚 Documentation
+    url: https://github.com/BeehiveInnovations/gemini-mcp-server/blob/main/README.md
+    about: Check the README for setup instructions and usage examples
+  - name: 🤝 Contributing Guide
+    url: https://github.com/BeehiveInnovations/gemini-mcp-server/blob/main/CONTRIBUTING.md
+    about: Learn how to contribute to the project

.github/ISSUE_TEMPLATE/documentation.yml

@@ -0,0 +1,67 @@
+name: 📖 Documentation Improvement
+description: Report an issue or suggest an improvement for the documentation
+labels: ["documentation", "good first issue"]
+body:
+  - type: input
+    id: location
+    attributes:
+      label: Documentation Location
+      description: "Which file or page has the issue? (e.g., README.md, CONTRIBUTING.md, CLAUDE.md)"
+      placeholder: "e.g., README.md"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: issue-type
+    attributes:
+      label: Type of Documentation Issue
+      description: What kind of documentation improvement is this?
+      options:
+        - Typo or grammar error
+        - Unclear or confusing explanation
+        - Outdated information
+        - Missing information
+        - Code example doesn't work
+        - Installation/setup instructions unclear
+        - Tool usage examples need improvement
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What is wrong with the documentation?
+      description: "Please describe the problem. Be specific about what is unclear, incorrect, or missing."
+      placeholder: "The Docker setup command in the README is missing the `--pull=always` flag, which means users might use an outdated image version."
+    validations:
+      required: true
+
+  - type: textarea
+    id: suggestion
+    attributes:
+      label: Suggested Improvement
+      description: "How can we make it better? If you can, please provide the exact text or changes you'd like to see."
+      placeholder: |
+        Change:
+        ```
+        docker run ghcr.io/beehiveinnovations/gemini-mcp-server:latest
+        ```
+        
+        To:
+        ```
+        docker run --pull=always ghcr.io/beehiveinnovations/gemini-mcp-server:latest
+        ```
+
+  - type: dropdown
+    id: audience
+    attributes:
+      label: Target Audience
+      description: Which audience would benefit most from this improvement?
+      options:
+        - New users (first-time setup)
+        - Developers (contributing to the project)
+        - Advanced users (complex workflows)
+        - All users
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,51 @@
+name: ✨ Feature Request
+description: Suggest an idea for this project
+labels: ["enhancement", "needs-triage"]
+body:
+  - type: textarea
+    id: problem-description
+    attributes:
+      label: What problem is this feature trying to solve?
+      description: "A clear and concise description of the problem or user need. Why is this change needed?"
+      placeholder: "Currently, I can only use one Gemini tool at a time. I want to be able to chain multiple tools together (e.g., analyze -> codereview -> thinkdeep) in a single workflow."
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposed-solution
+    attributes:
+      label: Describe the solution you'd like
+      description: A clear and concise description of what you want to happen. How would it work from a user's perspective?
+      placeholder: "I'd like to be able to specify a workflow like 'analyze src/ then codereview the findings then use thinkdeep to suggest improvements' in a single command or configuration."
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Describe alternatives you've considered
+      description: A clear and concise description of any alternative solutions or features you've considered.
+      placeholder: "I considered manually running each tool sequentially, but automatic workflow chaining would be more efficient and ensure context is preserved between steps."
+
+  - type: dropdown
+    id: feature-type
+    attributes:
+      label: Feature Category
+      description: What type of enhancement is this?
+      options:
+        - New Gemini tool (chat, codereview, debug, etc.)
+        - Workflow improvement
+        - Integration enhancement
+        - Performance optimization
+        - User experience improvement
+        - Documentation enhancement
+        - Other
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: contribution
+    attributes:
+      label: Contribution
+      options:
+        - label: I am willing to submit a Pull Request to implement this feature.

.github/ISSUE_TEMPLATE/tool_addition.yml

@@ -0,0 +1,74 @@
+name: 🛠️ New Gemini Tool Proposal
+description: Propose a new Gemini MCP tool (e.g., `summarize`, `testgen`, `refactor`)
+labels: ["enhancement", "new-tool"]
+body:
+  - type: input
+    id: tool-name
+    attributes:
+      label: Proposed Tool Name
+      description: "What would the tool be called? (e.g., `summarize`, `testgen`, `refactor`)"
+      placeholder: "e.g., `docgen`"
+    validations:
+      required: true
+
+  - type: textarea
+    id: purpose
+    attributes:
+      label: What is the primary purpose of this tool?
+      description: "Explain the tool's core function and the value it provides to developers using Claude + Gemini."
+      placeholder: "This tool will automatically generate comprehensive documentation from code, extracting class and function signatures, docstrings, and creating usage examples."
+    validations:
+      required: true
+
+  - type: textarea
+    id: example-usage
+    attributes:
+      label: Example Usage in Claude Desktop
+      description: "Show how a user would invoke this tool through Claude and what the expected output would look like."
+      placeholder: |
+        **User prompt to Claude:**
+        "Use gemini to generate documentation for my entire src/ directory"
+
+        **Expected Gemini tool behavior:**
+        - Analyze all Python files in src/
+        - Extract classes, functions, and their docstrings
+        - Generate structured markdown documentation
+        - Include usage examples where possible
+        - Return organized documentation with table of contents
+      render: markdown
+    validations:
+      required: true
+
+  - type: dropdown
+    id: tool-category
+    attributes:
+      label: Tool Category
+      description: What category does this tool fit into?
+      options:
+        - Code Analysis (like analyze)
+        - Code Quality (like codereview)
+        - Code Generation/Refactoring
+        - Documentation Generation
+        - Testing Support
+        - Debugging Support (like debug)
+        - Workflow Automation
+        - Architecture Planning (like thinkdeep)
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: system-prompt
+    attributes:
+      label: Proposed System Prompt (Optional)
+      description: "If you have ideas for how Gemini should be prompted for this tool, share them here."
+      placeholder: |
+        You are an expert technical documentation generator. Your task is to create comprehensive, user-friendly documentation from source code...
+
+  - type: checkboxes
+    id: contribution
+    attributes:
+      label: Contribution
+      options:
+        - label: I am willing to submit a Pull Request to implement this new tool.
+        - label: I have checked that this tool doesn't overlap significantly with existing tools (analyze, codereview, debug, thinkdeep, chat).

.github/pull_request_template.md

@@ -0,0 +1,116 @@
+<!--
+Thank you for your contribution to the Gemini MCP Server! 
+Please provide a clear description of your changes and ensure all requirements are met.
+-->
+
+## Related Issue
+
+<!-- Link to the issue that this PR addresses -->
+<!-- e.g., "Closes #123" or "Fixes #456" -->
+<!-- If no issue exists, please consider creating one first to discuss the change -->
+
+Closes #
+
+## Type of Change
+
+<!--
+Please check the relevant box with [x]
+-->
+
+- [ ] 🐞 Bug fix (non-breaking change which fixes an issue)
+- [ ] ✨ New feature (non-breaking change which adds functionality)
+- [ ] 🛠️ New Gemini tool (adds a new tool like `chat`, `codereview`, etc.)
+- [ ] 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] 📖 Documentation update
+- [ ] 🧹 Refactor or chore (no user-facing changes)
+- [ ] 🏗️ Infrastructure/CI changes
+
+## Description
+
+<!--
+A clear and concise description of the changes.
+- **What** is the change?
+- **Why** is this change necessary?
+- **How** does it address the issue?
+-->
+
+## Testing
+
+<!--
+The project has high testing standards. Please describe the tests you have added or updated.
+Both unit tests (no API key) and live integration tests (with API key) are important.
+-->
+
+### Unit Tests (Required)
+- [ ] I have added new unit tests to cover my changes
+- [ ] I have run `python -m pytest tests/ --ignore=tests/test_live_integration.py -v` and all tests pass
+- [ ] New tests use proper mocking and don't require API keys
+
+### Live Integration Tests (Recommended)
+- [ ] I have tested this with a real Gemini API key using `python tests/test_live_integration.py`
+- [ ] The changes work as expected with actual API calls
+- [ ] I have tested this on [macOS/Linux/Windows (WSL2)]
+
+### Docker Testing (If Applicable)
+- [ ] I have tested the Docker build: `docker build -t test-image .`
+- [ ] I have tested the Docker functionality: `./setup-docker.sh`
+- [ ] Docker integration works with the changes
+
+## Code Quality
+
+<!--
+Please confirm you've followed the project's quality standards
+-->
+
+- [ ] My code follows the project's style guidelines (`black .` and `ruff check .`)
+- [ ] I have run the linting tools and fixed any issues
+- [ ] I have commented my code, particularly in hard-to-understand areas
+- [ ] My changes generate no new warnings
+- [ ] I have updated type hints where applicable
+
+## Documentation
+
+<!--
+Documentation should be updated to reflect any user-facing changes
+-->
+
+- [ ] I have made corresponding changes to the documentation
+- [ ] I have updated the README.md if my changes affect usage
+- [ ] I have updated CONTRIBUTING.md if my changes affect the development workflow
+- [ ] For new tools: I have added usage examples and parameter documentation
+
+## Breaking Changes
+
+<!--
+If this is a breaking change, please describe what breaks and how users should adapt
+-->
+
+- [ ] This change is backwards compatible
+- [ ] OR: I have documented the breaking changes and migration path below
+
+<!--
+If breaking changes, describe them here:
+-->
+
+## Additional Context
+
+<!--
+Add any other context about the pull request here, such as:
+- Performance implications
+- Security considerations
+- Future improvements this enables
+- Screenshots (for UI changes)
+- Related PRs or issues
+-->
+
+## Checklist for Maintainers
+
+<!--
+This section is for maintainers to check during review
+-->
+
+- [ ] Code review completed
+- [ ] All CI checks passing
+- [ ] Breaking changes properly documented
+- [ ] Version bump needed (if applicable)
+- [ ] Documentation updated and accurate

.github/workflows/build_and_publish_docker.yml

@@ -0,0 +1,77 @@
+name: Build and Publish Docker Image to GHCR
+
+on:
+  push:
+    branches: [ main ]
+    tags: [ 'v*' ]
+  pull_request:
+    branches: [ main ]
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+      id-token: write
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    - name: Set up Docker Buildx
+      uses: docker/setup-buildx-action@v3
+
+    - name: Log in to GitHub Container Registry
+      if: github.event_name != 'pull_request'
+      uses: docker/login-action@v3
+      with:
+        registry: ${{ env.REGISTRY }}
+        username: ${{ github.actor }}
+        password: ${{ secrets.GITHUB_TOKEN }}
+
+    - name: Extract metadata (tags, labels) for Docker
+      id: meta
+      uses: docker/metadata-action@v5
+      with:
+        images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+        tags: |
+          type=ref,event=branch
+          type=ref,event=pr
+          type=ref,event=tag
+          type=sha,prefix={{branch}}-
+          type=raw,value=latest,enable={{is_default_branch}}
+
+    - name: Build Docker image for PR
+      if: github.event_name == 'pull_request'
+      uses: docker/build-push-action@v5
+      with:
+        context: .
+        push: false
+        tags: ${{ steps.meta.outputs.tags }}
+        labels: ${{ steps.meta.outputs.labels }}
+        cache-from: type=gha
+        cache-to: type=gha,mode=max
+
+    - name: Build and push Docker image
+      if: github.event_name != 'pull_request'
+      uses: docker/build-push-action@v5
+      with:
+        context: .
+        push: true
+        tags: ${{ steps.meta.outputs.tags }}
+        labels: ${{ steps.meta.outputs.labels }}
+        cache-from: type=gha
+        cache-to: type=gha,mode=max
+
+    - name: Generate artifact attestation
+      if: github.event_name != 'pull_request'
+      uses: actions/attest-build-provenance@v1
+      with:
+        subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME}}
+        subject-digest: ${{ steps.build.outputs.digest }}
+        push-to-registry: true