# 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