Arcia125/git-workflow-mcp-server

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:

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:

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:

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:

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

   git clone https://github.com/Arcia125/git-workflow-mcp-server.git
   cd git-workflow-mcp-server
   

2. Install Dependencies

   npm install
   

3. Build the Server

   npm run build
   

4. Add to MCP Configuration

   Add the server to your MCP client settings file:

   {
     "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:

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:

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

// 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

// 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

{
  "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.