README.md•7.63 kB
# Git Workflow Automation MCP Server
A Model Context Protocol (MCP) server that provides automated Git workflow tools for committing, creating pull requests, and merging with proper GitHub authentication handling.
## Features
- **Automated Git Operations**: Commit, push, create PRs, and merge in one command
- **GitHub Authentication Handling**: Automatically clears problematic environment tokens
- **Dry Run Support**: Test operations before executing them
- **Conventional Commits**: Supports proper commit message formatting
- **Branch Management**: Automatic branch creation and switching
- **Error Handling**: Comprehensive error reporting and rollback capabilities
## Available Tools
### 1. `git_commit_and_push`
Commits staged changes and pushes to remote repository.
**Parameters:**
- `files` (array, optional): File paths to commit (empty for all changes)
- `commitMessage` (string, required): Commit message (use conventional format)
- `branch` (string, optional): Branch name to create/switch to
- `workingDir` (string, optional): Working directory path
- `dryRun` (boolean, optional): Preview without executing
**Example:**
```javascript
use_mcp_tool("git-workflow", "git_commit_and_push", {
"files": ["src/app.ts", "README.md"],
"commitMessage": "feat: add new authentication system",
"branch": "feature/auth-system",
"dryRun": true
})
```
### 2. `create_pull_request`
Creates a GitHub pull request with proper authentication handling.
**Parameters:**
- `title` (string, required): Pull request title
- `body` (string, required): Pull request description
- `baseBranch` (string, optional): Base branch (default: "main")
- `headBranch` (string, optional): Head branch (defaults to current)
- `workingDir` (string, optional): Working directory path
- `dryRun` (boolean, optional): Preview without executing
**Example:**
```javascript
use_mcp_tool("git-workflow", "create_pull_request", {
"title": "Feature: User Authentication System",
"body": "Implements comprehensive user authentication with JWT tokens and OAuth2 support",
"baseBranch": "main",
"headBranch": "feature/auth-system"
})
```
### 3. `merge_pull_request`
Merges a GitHub pull request.
**Parameters:**
- `prNumber` (string, required): Pull request number
- `mergeMethod` (string, optional): "merge", "squash", or "rebase" (default: "merge")
- `deleteBranch` (boolean, optional): Delete branch after merge (default: true)
- `workingDir` (string, optional): Working directory path
- `dryRun` (boolean, optional): Preview without executing
**Example:**
```javascript
use_mcp_tool("git-workflow", "merge_pull_request", {
"prNumber": "42",
"mergeMethod": "squash",
"deleteBranch": true
})
```
### 4. `complete_git_workflow`
Executes the complete Git workflow: commit, push, create PR, and optionally merge.
**Parameters:**
- `files` (array, optional): Files to commit
- `commitMessage` (string, required): Commit message (conventional format)
- `prTitle` (string, required): Pull request title
- `prBody` (string, required): Pull request description
- `branch` (string, optional): Feature branch name
- `baseBranch` (string, optional): Base branch (default: "main")
- `autoMerge` (boolean, optional): Automatically merge PR (default: false)
- `workingDir` (string, optional): Working directory path
- `dryRun` (boolean, optional): Preview without executing
**Example:**
```javascript
use_mcp_tool("git-workflow", "complete_git_workflow", {
"files": ["src/**/*.ts", "docs/**/*.md"],
"commitMessage": "feat(auth): implement OAuth2 authentication",
"prTitle": "Feature: OAuth2 Authentication System",
"prBody": "Adds comprehensive OAuth2 authentication with Google and GitHub providers",
"branch": "feature/oauth2-auth",
"autoMerge": false,
"dryRun": true
})
```
## Installation
### Quick Setup
1. **Clone the Repository**
```bash
git clone https://github.com/Arcia125/git-workflow-mcp-server.git
cd git-workflow-mcp-server
```
2. **Install Dependencies**
```bash
npm install
```
3. **Build the Server**
```bash
npm run build
```
4. **Add to MCP Configuration**
Add the server to your MCP client settings file:
```json
{
"mcpServers": {
"git-workflow": {
"command": "node",
"args": ["/path/to/git-workflow-mcp-server/build/index.js"],
"disabled": false,
"alwaysAllow": [],
"disabledTools": []
}
}
}
```
### Alternative: NPM Global Install (Coming Soon)
Future versions will support global npm installation:
```bash
npm install -g git-workflow-mcp-server
```
### Configuration Paths
**Common MCP Settings Locations:**
- **Roo-Code**: `%APPDATA%/Code - Insiders/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json`
- **Claude Desktop**: `%APPDATA%/Claude/claude_desktop_config.json`
- **Other MCP Clients**: Check your client's documentation for settings location
### Verify Installation
Test the installation with a dry run:
```javascript
use_mcp_tool("git-workflow", "git_commit_and_push", {
"files": ["README.md"],
"commitMessage": "test: verify MCP server installation",
"dryRun": true
})
```
## Prerequisites
- Node.js installed
- Git configured with remote repository
- GitHub CLI (`gh`) installed and authenticated
- Proper GitHub repository permissions
## Authentication
The server automatically handles GitHub authentication issues by:
1. Clearing problematic environment tokens (`GITHUB_TOKEN`, `GH_TOKEN`)
2. Using PowerShell commands for reliable token management
3. Relying on GitHub CLI keyring authentication
4. Providing detailed error messages for authentication failures
## Best Practices
### 1. Always Use Dry Run First
```javascript
// Test the operation first
use_mcp_tool("git-workflow", "complete_git_workflow", {
"commitMessage": "feat: add new feature",
"prTitle": "New Feature",
"prBody": "Description",
"dryRun": true
})
// Then execute after confirmation
use_mcp_tool("git-workflow", "complete_git_workflow", {
"commitMessage": "feat: add new feature",
"prTitle": "New Feature",
"prBody": "Description",
"dryRun": false
})
```
### 2. Use Conventional Commits
```javascript
// Good commit messages:
"feat(auth): add OAuth2 integration"
"fix(ui): resolve button alignment issue"
"docs(api): update endpoint documentation"
"refactor(utils): simplify date formatting"
```
### 3. Meaningful PR Titles and Descriptions
```javascript
{
"prTitle": "Feature: OAuth2 Authentication System",
"prBody": "## Changes\n- Implements OAuth2 with Google/GitHub\n- Adds JWT token management\n- Updates user authentication flow\n\n## Testing\n- All auth tests pass\n- Manual testing completed"
}
```
## Error Handling
The server provides comprehensive error handling:
- **Git Repository Errors**: Validates repository state
- **Authentication Failures**: Handles GitHub CLI auth issues
- **Network Issues**: Provides clear error messages
- **Branch Conflicts**: Manages branch creation/switching
- **Merge Conflicts**: Reports merge issues clearly
## Dependencies
- `@modelcontextprotocol/sdk`: MCP server framework
- `simple-git`: Git operations
- `axios`: HTTP requests (if needed)
- `zod`: Schema validation
## Development
To modify the server:
1. Edit `src/index.ts`
2. Run `npm run build`
3. Restart your MCP client
## Support
For issues or questions:
- Check GitHub CLI authentication: `gh auth status`
- Verify repository permissions
- Review error messages for specific guidance
- Test with dry run mode first
## Version
Version 0.1.0 - Initial release with core Git workflow automation features.