Merge pull request #17 from yumeminami/feature/add-version-support-issue-15

Add version checking support for CLI tools

Author: yumeminami

CLAUDE.md

@@ -19,9 +19,11 @@ uv tool install --from . git_mcp_server --force
 
 # Run linting and security checks
 uv run ruff check git_mcp/
+uv run ruff format git_mcp/
 uv run bandit -r git_mcp/
+uv run mypy git_mcp/ --ignore-missing-imports --no-strict-optional
 
-# Run pre-commit hooks manually
+# Run pre-commit hooks manually (includes ruff, bandit, mypy, yaml/json checks)
 uv run pre-commit run --all-files
 
 # Run tests (when implemented - uses placeholder test currently)
@@ -30,6 +32,9 @@ uv run pytest
 # Test CLI entry points
 uv run git-mcp --help
 uv run git-mcp-server --help
+
+# Test MCP server directly
+echo '{"jsonrpc": "2.0", "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0.0"}}, "id": 1}' | git-mcp-server
 ```
 
 ### Installation & Setup
@@ -136,6 +141,8 @@ When working on this codebase:
 
 ## Dependencies
 
+**Python Version**: Requires Python >=3.13
+
 Core dependencies (from pyproject.toml):
 - `python-gitlab>=4.4.0` - GitLab API client
 - `PyGithub>=2.1.0` - GitHub API client
@@ -148,15 +155,47 @@ Core dependencies (from pyproject.toml):
 - `gitpython>=3.1.0` - Git repository interaction
 - `pyyaml>=6.0.0` - YAML configuration parsing
 - `tool>=0.8.0` - Tool utilities
+- `pre-commit>=4.2.0` - Git hooks for code quality
 
 Development tools:
 - `ruff>=0.1.0` - Linting and code formatting
 - `bandit[toml]>=1.7.0` - Security vulnerability scanning
 - `pytest>=8.0.0` - Testing framework (configured, tests not yet implemented)
 - `pytest-asyncio>=0.23.0` - Async testing support
-- `pre-commit>=4.2.0` - Git hooks for code quality (also core dependency)
 - `pip-audit>=2.0.0` - Security vulnerability scanning
 
+## API Documentation
+
+**Platform API References:**
+
+### GitHub API (PyGithub)
+- **Examples & Usage Patterns**: https://pygithub.readthedocs.io/en/stable/examples.html
+  - Comprehensive examples for common GitHub operations
+  - Authentication methods and best practices
+  - Rate limiting and pagination handling
+- **API Reference**: https://pygithub.readthedocs.io/en/stable/github_objects.html
+  - Complete class and method documentation
+  - Object relationships and property details
+
+### GitLab API (python-gitlab)
+- **API Objects Reference**: https://python-gitlab.readthedocs.io/en/stable/api-objects.html
+  - Complete list of available API objects and methods
+  - CRUD operations for issues, merge requests, projects
+  - Advanced features like pipelines, deployments, and wiki management
+- **Usage Guide**: https://python-gitlab.readthedocs.io/en/stable/gl_objects/
+  - Object-specific documentation with examples
+  - Authentication and connection management
+
+**When to Use These Resources:**
+- **Customizing platform adapters** (`git_mcp/platforms/`) - Reference API objects and methods
+- **Debugging API interactions** - Understand response structures and error handling
+- **Extending MCP tools** (`git_mcp/mcp_server.py`) - Add new platform operations
+- **Developing slash commands** - Integrate additional API functionality
+
+**Additional Resources:**
+- **GitHub REST API Docs**: https://docs.github.com/en/rest
+- **GitLab REST API Docs**: https://docs.gitlab.com/ee/api/
+
 ## Security Notes
 
 - All access tokens are stored securely in system keyring, never in config files

git_mcp/__init__.py

@@ -3,5 +3,17 @@
 A unified command-line tool for managing Git repositories across GitHub and GitLab platforms.
 """
 
-__version__ = "0.1.0"
+import importlib.metadata
+
+try:
+    __version__ = importlib.metadata.version("git_mcp_server")
+except importlib.metadata.PackageNotFoundError:
+    # Fallback for development/source installations
+    __version__ = "0.1.8"
+
 __author__ = "Git MCP Team"
+
+
+def get_version() -> str:
+    """Get the package version dynamically."""
+    return __version__

git_mcp/claude_commands/implement.md

@@ -43,6 +43,24 @@ Please implement the planned functionality thoroughly and in great detail, consi
 
 Use `get_project_details()` to understand codebase structure and `list_merge_requests()` to review implementation patterns in recent changes.
 
+## Platform API Resources
+
+**When implementing platform-specific features**, refer to the API documentation in CLAUDE.md:
+
+**For GitLab integrations** (`git_mcp/platforms/gitlab.py`):
+- **API Objects Reference**: https://python-gitlab.readthedocs.io/en/stable/api-objects.html
+- **Usage Examples**: https://python-gitlab.readthedocs.io/en/stable/gl_objects/
+
+**For GitHub integrations** (`git_mcp/platforms/github.py`):
+- **Examples & Patterns**: https://pygithub.readthedocs.io/en/stable/examples.html
+- **API Reference**: https://pygithub.readthedocs.io/en/stable/github_objects.html
+
+**Common use cases requiring API docs:**
+- Extending platform adapter methods
+- Adding new MCP tools for platform operations
+- Implementing custom issue/PR workflows
+- Debugging API response handling
+
 **After implementation, update the issue documentation with progress and file changes.**
 
 Use `/test` after implementation to generate comprehensive tests.

git_mcp/claude_commands/plan.md

@@ -35,6 +35,24 @@ Create a comprehensive development plan including:
 
 Use `get_project_details()` to understand project structure and `list_merge_requests()` to review existing workflow patterns.
 
+## Platform API Planning
+
+**When planning platform integrations**, consult the API documentation in CLAUDE.md:
+
+**GitLab API Resources:**
+- API Objects: https://python-gitlab.readthedocs.io/en/stable/api-objects.html
+- Usage Patterns: https://python-gitlab.readthedocs.io/en/stable/gl_objects/
+
+**GitHub API Resources:**
+- Examples: https://pygithub.readthedocs.io/en/stable/examples.html
+- API Reference: https://pygithub.readthedocs.io/en/stable/github_objects.html
+
+**Consider API limitations and capabilities when planning:**
+- Rate limiting requirements
+- Authentication scopes needed
+- Available operations and data structures
+- Error handling patterns
+
 ## Repository Context
 
 Analyze current repository structure:

git_mcp/claude_commands/pr.md

@@ -32,18 +32,65 @@ Analyze the changes made thoroughly and consider multiple ways to present them c
    !git status
    !git commit -m "Implement feature for issue #$ARGUMENTS"
 
-2. **Push to Remote**
+2. **Fork Detection and Repository Analysis**
+   - Use `get_fork_info()` to check if current repository is a fork
+   - If it's a fork, identify the upstream repository for PR creation
+   - Determine the correct target repository (fork vs upstream)
+
+3. **Push to Remote**
    !git push -u origin HEAD
 
-3. **Create Pull/Merge Request**
-   Use `create_merge_request()` to create the PR/MR with:
+4. **Create Pull/Merge Request with Fork Support**
+   Use `create_merge_request()` to create the PR/MR with enhanced fork support:
+
+   **For Fork-to-Upstream PRs:**
+   - Source branch: `username:branch-name` format (automatically detected)
+   - Target repository: Upstream repository (parent)
+   - Target branch: Usually `main` or `master`
+
+   **For Same-Repository PRs:**
+   - Source branch: `branch-name` format (current behavior)
+   - Target repository: Current repository
+   - Target branch: As specified or default
+
+   **PR Parameters:**
    - Craft a descriptive title linking to issue
    - Create comprehensive description that clearly explains the solution
    - **IMPORTANT**: In the description, use the full issue URL from `.claude/issue-$ARGUMENTS-*.md` instead of just `#$ARGUMENTS`
    - Extract the URL using: `grep "URL:" .claude/issue-$ARGUMENTS-*.md | head -1 | cut -d' ' -f2`
    - Consider appropriate labels and reviewers
 
-4. **PR Description Template**
+5. **Fork Workflow Examples**
+
+   **Example 1: Fork-to-Upstream PR**
+   ```
+   # Check if current repo is a fork
+   get_fork_info("github", "myuser/upstream-project")
+
+   # If it's a fork, create PR to upstream
+   create_merge_request(
+       platform="github",
+       project_id="upstream-owner/upstream-project",  # Target upstream repo
+       source_branch="myuser:feature-branch",         # Fork branch reference
+       target_branch="main",                          # Upstream main branch
+       title="Fix issue #123: Add new feature",
+       description="Implements feature as requested in issue..."
+   )
+   ```
+
+   **Example 2: Same-Repository PR (existing behavior)**
+   ```
+   create_merge_request(
+       platform="github",
+       project_id="myuser/my-project",
+       source_branch="feature-branch",                # Simple branch name
+       target_branch="main",
+       title="Fix issue #123: Add new feature",
+       description="Implements feature as requested in issue..."
+   )
+   ```
+
+6. **PR Description Template**
    ```
    ## Summary
    Implements [feature description] as requested in issue #$ARGUMENTS
@@ -60,13 +107,24 @@ Analyze the changes made thoroughly and consider multiple ways to present them c
    Closes #$ARGUMENTS
    ```
 
-5. **Final Steps**
+7. **Available Fork MCP Tools**
+
+   **New Tools for Fork Management:**
+   - `create_fork(platform, project_id, **kwargs)` - Create a fork of a repository
+   - `get_fork_info(platform, project_id)` - Check fork status and get parent info
+   - `list_forks(platform, project_id)` - List forks of a repository (basic implementation)
+
+   **Enhanced Existing Tools:**
+   - `create_merge_request()` - Now supports cross-repository PRs with `owner:branch` format
+   - All existing MCP tools work seamlessly with fork workflows
+
+8. **Final Steps**
    - Link PR to original issue (use `update_issue()` to close issue if needed)
    - Request code review via `get_merge_request_details()` for tracking
    - Monitor CI/CD pipeline
    - Address review feedback
 
-6. **Complete Issue Documentation**
+9. **Complete Issue Documentation**
    - Save final PR details to `.claude/issue-$ARGUMENTS-*.md`
    - Mark workflow as completed in the documentation
    - Issue document now serves as complete project history for this feature

git_mcp/cli.py

@@ -9,6 +9,7 @@
 from .core.config import get_config
 from .core.exceptions import GitMCPError
 from .utils.output import OutputFormatter
+from . import get_version
 
 
 # Global context for CLI
@@ -25,7 +26,7 @@ def get_formatter(self) -> OutputFormatter:
         return self.formatter
 
 
-@click.group()
+@click.group(invoke_without_command=True)
 @click.option(
     "--format",
     "output_format",
@@ -35,9 +36,23 @@ def get_formatter(self) -> OutputFormatter:
 )
 @click.option("--platform", help="Default platform to use")
 @click.option("--config-dir", type=click.Path(), help="Configuration directory path")
+@click.option(
+    "--version",
+    is_flag=True,
+    help="Show version and exit",
+)
 @click.pass_context
-def cli(ctx, output_format, platform, config_dir):
+def cli(ctx, output_format, platform, config_dir, version):
     """Git MCP Server - Unified management for GitHub and GitLab."""
+    if version:
+        click.echo(f"git-mcp {get_version()}")
+        ctx.exit()
+
+    # If no subcommand is provided, show help
+    if ctx.invoked_subcommand is None:
+        click.echo(ctx.get_help())
+        ctx.exit()
+
     ctx.ensure_object(CLIContext)
 
     if config_dir:

git_mcp/gemini_commands/implement.toml

@@ -24,5 +24,23 @@ Please implement the planned functionality thoroughly and in great detail, consi
 
 Use `get_project_details()` to understand codebase structure and `list_merge_requests()` to review implementation patterns in recent changes.
 
+## Platform API Resources
+
+**When implementing platform-specific features**, refer to the API documentation in CLAUDE.md:
+
+**For GitLab integrations** (`git_mcp/platforms/gitlab.py`):
+- API Objects Reference: https://python-gitlab.readthedocs.io/en/stable/api-objects.html
+- Usage Examples: https://python-gitlab.readthedocs.io/en/stable/gl_objects/
+
+**For GitHub integrations** (`git_mcp/platforms/github.py`):
+- Examples & Patterns: https://pygithub.readthedocs.io/en/stable/examples.html
+- API Reference: https://pygithub.readthedocs.io/en/stable/github_objects.html
+
+**Common use cases requiring API docs:**
+- Extending platform adapter methods
+- Adding new MCP tools for platform operations
+- Implementing custom issue/PR workflows
+- Debugging API response handling
+
 Use `/test` after implementation to generate comprehensive tests.
 '''

git_mcp/gemini_commands/plan.toml

@@ -18,6 +18,24 @@ Create a comprehensive development plan including:
 
 Use `get_project_details()` to understand project structure and `list_merge_requests()` to review existing workflow patterns.
 
+## Platform API Planning
+
+**When planning platform integrations**, consult the API documentation in CLAUDE.md:
+
+**GitLab API Resources:**
+- API Objects: https://python-gitlab.readthedocs.io/en/stable/api-objects.html
+- Usage Patterns: https://python-gitlab.readthedocs.io/en/stable/gl_objects/
+
+**GitHub API Resources:**
+- Examples: https://pygithub.readthedocs.io/en/stable/examples.html
+- API Reference: https://pygithub.readthedocs.io/en/stable/github_objects.html
+
+**Consider API limitations and capabilities when planning:**
+- Rate limiting requirements
+- Authentication scopes needed
+- Available operations and data structures
+- Error handling patterns
+
 ## Repository Context
 
 Analyze current repository structure by running:

git_mcp/gemini_commands/pr.toml

@@ -11,17 +11,40 @@ Analyze the changes made thoroughly and consider multiple ways to present them c
 1. **Prepare Branch**
    Run git commands to add, check status, and commit changes
 
-2. **Push to Remote**
+2. **Fork Detection and Repository Analysis**
+   - Use `get_fork_info()` to check if current repository is a fork
+   - If it's a fork, identify the upstream repository for PR creation
+   - Determine the correct target repository (fork vs upstream)
+
+3. **Push to Remote**
    Push the current branch to remote repository
 
-3. **Create Pull/Merge Request**
-   Use `create_merge_request()` to create the PR/MR with:
+4. **Create Pull/Merge Request with Fork Support**
+   Use `create_merge_request()` with enhanced fork support:
+
+   **For Fork-to-Upstream PRs:**
+   - Source branch: `username:branch-name` format (automatically detected)
+   - Target repository: Upstream repository (parent)
+   - Target branch: Usually `main` or `master`
+
+   **For Same-Repository PRs:**
+   - Source branch: `branch-name` format (current behavior)
+   - Target repository: Current repository
+   - Target branch: As specified or default
+
+   **PR Parameters:**
    - Craft a descriptive title linking to issue
    - Create comprehensive description that clearly explains the solution
    - Closes #[issue-id] in description
    - Consider appropriate labels and reviewers
 
-4. **PR Description Template**
+5. **Available Fork MCP Tools**
+   - `create_fork(platform, project_id, **kwargs)` - Create a fork
+   - `get_fork_info(platform, project_id)` - Check fork status
+   - `list_forks(platform, project_id)` - List repository forks
+   - `create_merge_request()` - Enhanced with cross-repo support
+
+6. **PR Description Template**
    ```
    ## Summary
    Implements [feature description] as requested in issue #[issue-id]
@@ -38,7 +61,7 @@ Analyze the changes made thoroughly and consider multiple ways to present them c
    Closes #[issue-id]
    ```
 
-5. **Final Steps**
+7. **Final Steps**
    - Link PR to original issue (use `update_issue()` to close issue if needed)
    - Request code review via `get_merge_request_details()` for tracking
    - Monitor CI/CD pipeline