git-mcp-server

Exposes 25+ Git operations as MCP tools through a standardized three-file architecture (logic, handler, schema) that implements the 'Logic Throws, Handler Catches' pattern. Each tool is registered with Zod-validated input schemas and structured output types, enabling AI agents to discover and invoke Git operations with type safety. The MCP SDK (@modelcontextprotocol/sdk ^1.17.0) handles protocol negotiation and tool marshaling across both STDIO and HTTP transports.

Implements both STDIO (process-level IPC) and HTTP (Hono-based web server) transports for MCP communication, selectable via MCP_TRANSPORT_TYPE environment variable. STDIO transport launches as a child process with direct stdin/stdout communication for tight client-server coupling; HTTP transport runs a Hono web server on port 3010 (with automatic retry) supporting CORS, JWT/OAuth authentication via JOSE, and session persistence. Both transports route to the same underlying MCP server logic, enabling flexible deployment patterns.

Implements git pull with configurable merge strategies (merge, rebase, fast-forward only) and automatic conflict detection. Uses git pull with strategy flags (--rebase, --ff-only, --no-ff) and captures merge/rebase output including conflict information. Detects merge conflicts and returns structured response indicating conflict status and affected files. Supports pulling from specific remotes and branches.

Implements git merge with support for merging branches into current branch, detecting conflicts, and optionally aborting on conflict. Uses git merge with configurable flags (--no-commit for dry-run, --abort for rollback) and parses merge output to identify conflicted files and merge status. Returns structured merge result including conflict information and affected files. Supports both fast-forward and non-fast-forward merges.

Implements git rebase with support for rebasing onto different branches or commits, interactive rebase for commit editing, and conflict detection. Uses git rebase with configurable flags (--interactive for interactive mode, --abort for rollback, --continue for resuming after conflict resolution). Detects rebase conflicts and returns structured response indicating conflict status and affected commits. Supports rebasing current branch or specific branches.

Implements git tag operations for creating lightweight and annotated tags, listing tags with filtering, and deleting tags. Supports creating tags at specific commits or HEAD, annotated tags with messages and tagger information, and listing tags with optional filtering by pattern. Uses git tag with configurable flags (-a for annotated, -d for deletion) and returns structured tag information including tag name, type, and target commit.

Implements git worktree operations for creating isolated working directories for different branches, listing active worktrees, and removing worktrees. Uses git worktree add/list/remove commands to manage multiple working directories pointing to different branches of the same repository. Each worktree has its own working directory but shares the .git directory, enabling parallel development on multiple branches without switching. Returns structured worktree information including path, branch, and lock status.

Implements git stash operations for saving uncommitted changes, listing stashed changes, applying stashes, and deleting stashes. Uses git stash with configurable flags (save/push for stashing, apply/pop for retrieving, drop for deletion) and supports stashing specific files. Returns structured stash information including stash ID, description, and affected files. Enables temporary storage of work-in-progress changes without committing.

Implements git remote operations for adding, listing, removing, and configuring remote repositories. Uses git remote add/remove/set-url commands to manage remote configuration. Supports setting remote URLs, fetch/push URLs separately, and listing remotes with detailed information. Returns structured remote information including URL, fetch/push configuration, and tracking branches.

Implements a centralized error handling system where Git tool logic throws domain-specific errors (e.g., RepositoryNotFoundError, MergeConflictError, AuthenticationError) that are caught by MCP handlers and translated into protocol-compliant error responses with error codes and recovery suggestions. Uses TypeScript error classes for type-safe error handling and provides structured error information including error type, message, affected files, and suggested recovery actions. Enables clients to programmatically handle specific error conditions.

Implements structured logging using Winston ^3.17.0 with configurable log levels, transports, and formatting. Logs all Git operations (tool invocations, parameters, results, errors) with structured metadata enabling operational monitoring and debugging. Supports multiple transports (console, file, external services) and structured JSON output for log aggregation. Enables tracing of MCP requests through session IDs and request IDs.

Maintains session-specific working directories through a centralized state manager, enabling multiple concurrent Git operations to operate in isolated contexts without interfering with each other. Each MCP session gets its own working directory context that persists across tool invocations within that session. The architecture supports switching between repositories and managing multiple worktrees per session, with state tracked via session IDs passed through MCP requests.

Implements git clone operations through a validated tool that accepts repository URL, target directory, and optional branch/depth parameters, with Zod schema validation before execution. The implementation uses child_process to invoke native Git CLI, captures both stdout/stderr, and translates Git errors (authentication failures, invalid URLs, network timeouts) into structured MCP error responses. Supports shallow clones (--depth) and branch-specific cloning for bandwidth optimization.

Implements git commit operations through a tool that validates staged changes exist before committing, accepts commit message with optional template variables (author, timestamp), and supports amend mode for modifying previous commits. Uses child_process to invoke git commit with configurable flags (--amend, --no-verify), captures commit metadata (hash, author, timestamp), and returns structured commit information. Validates that at least one file is staged before allowing commit to prevent empty commits.

Provides comprehensive branch operations through separate tools for creating branches (with optional start point), switching branches (with detached HEAD support), deleting branches (with force flag), and listing branches (local, remote, or all). Each operation uses child_process to invoke native git commands (branch, checkout, branch -d/-D) with appropriate flags. Validates branch names before creation and prevents deletion of currently-checked-out branch. Returns structured branch information including tracking status and commit references.

Generates diffs between commits, branches, or working directory using git diff with support for staged vs unstaged changes, specific file filtering, and output formatting (unified, stat, patch). Invokes git diff with configurable flags (--cached for staged, --stat for summary, --name-only for file list) and parses output into structured format showing changed files, additions/deletions counts, and optionally full patch content. Supports comparing arbitrary revisions (commit hashes, branch names, HEAD~N).

Retrieves commit history using git log with support for filtering by author, date range, commit message pattern, and file path. Configurable output includes commit hash, author, timestamp, message, and optionally full diff or stats. Uses git log with format strings and grep filters to extract structured commit data. Supports pagination through --skip and --max-count flags to handle large histories efficiently. Can generate statistics (commits per author, commits per day) for repository analysis.

Provides real-time repository status through git status parsing, identifying staged changes, unstaged modifications, untracked files, and merge/rebase state. Invokes git status --porcelain for machine-readable output and parses status codes (M, A, D, ??, etc.) into structured format showing file paths, change types, and staging status. Detects special states (merge in progress, rebase in progress, detached HEAD) and includes them in status response.

Implements git push with support for pushing to specific remotes and branches, setting upstream tracking on first push, and force push with safety checks. Uses git push with configurable flags (--set-upstream for tracking, --force-with-lease for safer force push). Validates remote exists before pushing and returns push result including remote tracking information. Supports pushing to multiple branches in sequence through separate tool calls.