Git MCP

# GIT MCP Server Professional MCP (Model Context Protocol) server for Git operations with multi-provider support, enhanced security, and comprehensive safety features. ## Features - 🚀 **17 Specialized Git Tools** - Complete Git workflow coverage with safety warnings - 🔄 **Multi-Provider Support** - GitHub and Gitea simultaneously with credential validation - 🔒 **Security-First Design** - Read-only file operations, no content modification via API - 🚨 **Safety Warnings** - Comprehensive warnings for destructive operations - 🛡️ **Enhanced Error Handling** - Detailed diagnostics with actionable solutions - 📋 **Comprehensive Validation** - Pre-execution validation with helpful guidance - 🔧 **IDE/Client Compatibility** - Universal aliases for different MCP client expectations - 📦 **NPM Distribution** - Easy installation via npx - 🤖 **AI Agent Integration** - Designed for AI agent workflows with safety controls ## Quick Start ### Installation & Usage ```bash # Run directly with npx (recommended) npx @andrebuzeli/git-mcp@latest # Or install globally npm install -g @andrebuzeli/git-mcp git-mcp ``` ### Configuration Set up your provider credentials via environment variables: #### GitHub Configuration ```bash export GITHUB_TOKEN="your_github_token" export GITHUB_USERNAME="your_username" ``` #### Gitea Configuration ```bash export GITEA_URL="https://your-gitea-instance.com" export GITEA_TOKEN="your_gitea_token" export GITEA_USERNAME="your_username" ``` #### Multi-Provider Support Configure both GitHub and Gitea to use `provider="both"` in tool calls. ## Available Tools | Tool | Description | Operations | Safety Features | |------|-------------|------------|-----------------| | `git-workflow` | Core Git operations | init, status, commit, sync, backup, create, list, get, update, delete, fork, search | Repository deletion warnings | | `git-files` | **Read-only** file operations | read, list, search, backup | File modification blocked | | `git-branches` | Branch management | create, list, get, delete, merge, compare | Branch deletion warnings | | `git-issues` | Issue management | create, list, get, update, close, comment, search | - | | `git-pulls` | Pull request management | create, list, get, update, merge, close, review, search | - | | `git-tags` | Tag management | create, list, get, delete, search | - | | `git-release` | Release management | create, list, get, update, delete, publish, download | - | | `git-remote` | Remote repository management | add, remove, rename, show, set-url, prune | - | | `git-reset` | **⚠️ Repository reset** | soft, mixed, hard, reset-to-commit, reset-branch | **Hard reset warnings** | | `git-stash` | Stash management | stash, pop, apply, list, show, drop, clear | - | | `git-config` | Git configuration | get, set, unset, list, edit, show | - | | `git-monitor` | Repository monitoring | status, changes, health | - | | `git-backup` | Repository backup | create, restore, list, verify | - | | `git-archive` | Repository archiving | create, extract, list, verify | - | | `git-sync` | Repository synchronization | sync, status | - | | `git-packages` | Package management | list, get, create, update, delete, publish, download | - | | `git-analytics` | Repository analytics | stats, insights, reports | - | ## Security Features ### 🔒 File Operations Restriction The `git-files` tool is **read-only only** for security reasons: **✅ Allowed Operations:** - `read` - Read file content - `list` - List directory contents - `search` - Search file content - `backup` - Create local backups **❌ Blocked Operations:** - `create` - Create new files (blocked) - `update` - Modify existing files (blocked) - `delete` - Delete files (blocked) **Why?** File content modification should be done through your local development environment, not via remote API calls. ### 🚨 Safety Warnings Destructive operations include comprehensive safety warnings: #### Git Reset Warnings ```json { "tool": "git-reset", "params": { "action": "hard", "projectPath": "/path/to/project" } } ``` **Result:** Detailed warning about data loss with alternatives: - `git reset --soft` (keeps changes staged) - `git reset --mixed` (keeps changes unstaged) - `git stash` (saves changes temporarily) #### Branch Deletion Warnings ```json { "tool": "git-branches", "params": { "action": "delete", "branchName": "feature-branch" } } ``` **Result:** Warning about permanent branch deletion with suggestions: - Ensure branch is merged first - Create backup branch before deletion - Check for unmerged commits ### 🔍 Enhanced Error Handling All tools provide detailed error messages with actionable solutions: **Example Error Response:** ```json { "success": false, "error": { "code": "BRANCH_NOT_FOUND", "message": "Branch not found", "suggestions": [ "Check if the branch name is correct", "Use git branch -a to see all available branches", "Ensure the branch exists on the remote repository" ] } } ``` ## Usage Examples ### Local Git Operations ```json { "tool": "git-workflow", "params": { "action": "status", "projectPath": "/path/to/project" } } ``` ```json { "tool": "git-workflow", "params": { "action": "commit", "projectPath": "/path/to/project", "message": "Add new feature" } } ``` ### Remote Repository Operations ```json { "tool": "git-workflow", "params": { "action": "create", "projectPath": "/path/to/project", "provider": "github", "name": "my-new-repo", "description": "My new repository", "private": true } } ``` ### Safe File Operations (Read-Only) ```json { "tool": "git-files", "params": { "action": "read", "projectPath": "/path/to/project", "filePath": "README.md" } } ``` ### Destructive Operations (With Warnings) ```json { "tool": "git-reset", "params": { "action": "hard", "projectPath": "/path/to/project", "confirmDestructive": true } } ``` ## Error Codes Reference ### Common Error Codes | Code | Description | Solution | |------|-------------|----------| | `VALIDATION_ERROR` | Parameter validation failed | Check required parameters and format | | `NOT_A_GIT_REPOSITORY` | Directory is not a Git repository | Use `git init` first | | `NOTHING_TO_COMMIT` | No changes to commit | Make changes first | | `MERGE_CONFLICT` | Merge conflicts detected | Resolve conflicts before proceeding | | `PERMISSION_DENIED` | Permission denied | Check credentials and access rights | | `PROVIDER_NOT_CONFIGURED` | Provider not configured | Set up GitHub or Gitea credentials | | `NETWORK_ERROR` | Network connectivity issue | Check internet connection | | `OPERATION_RESTRICTED` | File modification blocked | Use read-only operations only | | `SAFETY_WARNING` | Destructive operation detected | Review warning and confirm if needed | ### Git-Specific Error Codes | Code | Description | Solution | |------|-------------|----------| | `BRANCH_EXISTS` | Branch already exists | Use different name or delete existing | | `BRANCH_NOT_FOUND` | Branch not found | Check branch name and remote config | | `DIRTY_WORKING_TREE` | Uncommitted changes | Commit or stash changes first | | `DETACHED_HEAD` | Repository in detached HEAD state | Create branch or checkout existing | | `REF_LOCK_ERROR` | Cannot lock Git reference | Wait for other operations to complete | ## Configuration Guide ### Environment Variables **Required for GitHub:** - `GITHUB_TOKEN` - Personal access token with repo permissions - `GITHUB_USERNAME` - Your GitHub username **Required for Gitea:** - `GITEA_URL` - Your Gitea instance URL (e.g., `https://git.example.com`) - `GITEA_TOKEN` - Personal access token - `GITEA_USERNAME` - Your Gitea username ### Credential Validation The server automatically validates credentials on startup: - ✅ **Valid credentials** - API connectivity confirmed - ❌ **Invalid token** - Authentication failed - 🌐 **Network error** - Cannot reach provider API - ⚠️ **Partial failure** - Some providers failed validation ### Setup Instructions 1. **Generate GitHub Token:** - Go to GitHub Settings → Developer settings → Personal access tokens - Create token with `repo` scope - Copy token to `GITHUB_TOKEN` environment variable 2. **Generate Gitea Token:** - Go to your Gitea instance → Settings → Applications - Generate new token with appropriate permissions - Copy token to `GITEA_TOKEN` environment variable 3. **Test Configuration:** ```bash # Start the server to see validation results npx @andrebuzeli/git-mcp@latest ``` ## Troubleshooting ### Common Issues **"Provider not configured" error:** - Check environment variables are set correctly - Verify token has required permissions - Test API connectivity manually **"Operation restricted" error:** - File modification operations are blocked for security - Use read-only operations: `read`, `list`, `search`, `backup` - Make file changes through your local development environment **"Safety warning" error:** - Review the detailed warning message - Consider safer alternatives suggested - Use `confirmDestructive: true` only if absolutely necessary **"Network error" errors:** - Check internet connectivity - Verify provider URLs are correct - Check firewall/proxy settings ### Getting Help 1. **Check error messages** - They include specific suggestions 2. **Review safety warnings** - They explain risks and alternatives 3. **Validate credentials** - Server validates on startup 4. **Use read-only operations** - Safe file operations are always available ## Development ### Building from Source ```bash git clone https://github.com/your-repo/git-mcp.git cd git-mcp npm install npm run build ``` ### Testing ```bash npm test ``` ## License MIT License - see LICENSE file for details. ## Contributing 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Add tests for new functionality 5. Submit a pull request --- **⚠️ Important Security Notes:** - File content modification is intentionally restricted for security - Always review safety warnings before destructive operations - Keep your API tokens secure and rotate them regularly - Use `confirmDestructive: true` only when absolutely necessary