git-mcp-server

Git MCP Server

A Model Context Protocol server that provides Git operations to Large Language Models. This tool enables LLMs to interact with Git repositories through a robust and flexible API.

Table of Contents

• Overview
• Features
• Installation
• Configuration
• Tools
• Performance
• Error Handling
• Best Practices
• Development
• Contributing
• License

Overview

Git MCP Server implements the Model Context Protocol (MCP), enabling standardized communication between LLMs and Git repositories through:

• Clients (Claude Desktop, IDEs) that maintain server connections
• Servers that provide tools and resources (Like our Git MCP Server)
• LLMs that interact with servers through client applications

Core Components

• GitOperations: Core Git command execution with error handling
• RepositoryValidator: Comprehensive repository validation
• PathValidator: Path validation and security checks
• CommandExecutor: Secure command execution
• PerformanceMonitor: Performance tracking and optimization
• RepositoryCache: Caching system for Git operations
• ErrorHandler: Structured error handling with recovery

Features

Git Operations

• Repository initialization and cloning
• File staging and committing
• Branch management
• Tag operations
• Remote repository handling
• Stash management
• Bulk operations support

Performance Optimization

• Repository state caching
• Command result caching
• Performance monitoring:
  • Operation timing
  • Memory usage tracking
  • Resource utilization
  • Cache hit rates
• Automatic cache invalidation
• Memory pressure monitoring

Error Handling

Error severity levels:

• CRITICAL: System-level failures
• HIGH: Operation-blocking errors
• MEDIUM: Non-blocking issues
• LOW: Minor problems

Error categories:

• SYSTEM: System-level errors
• VALIDATION: Input validation errors
• OPERATION: Git operation errors
• REPOSITORY: Repository state errors
• NETWORK: Network-related errors
• CONFIGURATION: Configuration errors
• SECURITY: Security-related errors

Error context tracking:

• Operation details
• Timestamps
• Stack traces
• Recovery steps
• Technical context

Security

• Path validation and sanitization
• Command injection prevention
• Repository access control
• Secure credential handling
• Input validation
• Error message sanitization

Installation

• Install the package:

npm install git-mcp-server

• Add to your MCP client settings:

{
  "mcpServers": {
    "git": {
      "command": "node",
      "args": ["/path/to/git-mcp-server/build/index.js"],
      "env": {
        "GIT_DEFAULT_PATH": "/path/to/default/repo/directory",
        "GIT_MAX_MEMORY": "1024", // Optional, in MB
        "GIT_CACHE_TTL": "300", // Optional, in seconds
        "GIT_LOG_LEVEL": "info" // Optional: debug, info, warn, error
      }
    }
  }
}

Configuration

Environment Variables

• GIT_DEFAULT_PATH: Default repository directory
• GIT_MAX_MEMORY: Maximum memory usage (MB)
• GIT_CACHE_TTL: Cache time-to-live (seconds)
• GIT_LOG_LEVEL: Logging level
• GIT_PERFORMANCE_MONITOR: Enable performance monitoring
• GIT_ERROR_DETAILS: Include detailed error information

Performance Tuning

Cache configuration:

{
  "repository": {
    "ttl": 300,
    "maxSize": 100
  },
  "command": {
    "ttl": 60,
    "maxSize": 500
  }
}

Resource thresholds:

{
  "memory": {
    "warning": 1024,
    "critical": 2048
  },
  "operations": {
    "warning": 100,
    "critical": 200
  }
}

Tools

init

Initialize a new Git repository:

{
  "path": "/path/to/repo" // Optional if GIT_DEFAULT_PATH is set
}

clone

Clone a repository:

{
  "url": "https://github.com/user/repo.git",
  "path": "/path/to/destination" // Optional
}

status

Get repository status:

{
  "path": "/path/to/repo" // Optional
}

add

Stage files:

{
  "path": "/path/to/repo", // Optional
  "files": ["/path/to/file1", "/path/to/file2"]
}

commit

Create a commit:

{
  "path": "/path/to/repo", // Optional
  "message": "Commit message"
}

push

Push commits to remote:

{
  "path": "/path/to/repo", // Optional
  "remote": "origin", // Optional, defaults to "origin"
  "branch": "main"
}

bulk_action

Execute multiple operations atomically. This is the preferred method for executing multiple Git operations as it:

• Ensures operations are executed in the correct order
• Provides atomic execution (all succeed or all fail)
• Optimizes performance through reduced command overhead
• Maintains consistent repository state
• Automatically handles cache invalidation

Example usage:

{
  "path": "/path/to/repo", // Optional
  "actions": [
    {
      "type": "stage",
      "files": ["file1", "file2"] // Optional - if omitted, stages all changes
    },
    {
      "type": "commit",
      "message": "Commit message"
    },
    {
      "type": "push",
      "branch": "main",
      "remote": "origin" // Optional - defaults to "origin"
    }
  ]
}

The bulk_action tool supports three types of operations:

• stage: Stage files for commit
  • files: Optional array of files to stage. If omitted, stages all changes
• commit: Create a new commit
  • message: Required commit message
• push: Push changes to remote
  • branch: Required branch name
  • remote: Optional remote name (defaults to "origin")

Performance

Caching Strategy

The server implements a robust caching system built on top of simple-git, providing two-level caching:

• Repository State Cache:

  • Branch information
  • Status
  • Tags
  • Remotes
  • Stash entries

• Command Result Cache:

  • Common command outputs
  • Validation results
  • Repository metadata

Cache invalidation:

• Automatic on state-changing operations (commit, push, etc.)
• TTL-based expiration (configurable via GIT_CACHE_TTL)
• Memory pressure-based eviction (monitored via GIT_MAX_MEMORY)
• LRU eviction policy for optimal cache utilization
• Smart invalidation based on operation dependencies
• Partial cache updates for efficiency

Implementation details:

• Uses simple-git for reliable Git operations
• Implements optimistic locking for cache updates
• Maintains cache coherency across operations
• Provides cache warming for frequently accessed data
• Supports concurrent cache access with proper synchronization

Performance Monitoring

Metrics collected:

• Operation timing
• Memory usage
• Cache hit rates
• Resource utilization
• Command execution stats

Monitoring tools:

// Get performance statistics
const stats = await performanceMonitor.getStatistics();

// Get cache statistics
const cacheStats = await repositoryCache.getStats();

// Get operation metrics
const metrics = await performanceMonitor.getMetrics(
  MetricType.OPERATION_DURATION,
  startTime,
  endTime
);

Error Handling

Error Types

// System errors
throw new SystemError('Disk space exhausted', {
  operation: 'clone',
  path: '/path/to/repo'
});

// Validation errors
throw new ValidationError('Invalid branch name', {
  operation: 'branch_create',
  details: { name: 'invalid/name' }
});

// Operation errors
throw new OperationError('Push failed', {
  operation: 'push',
  command: 'git push origin main'
});

Error Recovery

Each error includes recovery steps:

try {
  await gitOps.push(options);
} catch (error) {
  if (error instanceof GitMcpError) {
    console.log('Recovery steps:', error.getRecoverySteps());
  }
}

Error Context

Errors include detailed context:

{
  "name": "OperationError",
  "message": "Push failed: remote connection error",
  "code": "INTERNAL_ERROR",
  "severity": "HIGH",
  "category": "NETWORK",
  "context": {
    "operation": "push",
    "path": "/path/to/repo",
    "command": "git push origin main",
    "timestamp": 1234567890,
    "recoverySteps": [
      "Check network connection",
      "Verify remote URL",
      "Check credentials"
    ]
  }
}

Best Practices

Repository Operations

• Use bulk operations for multiple changes:

await gitOps.executeBulkActions({
  actions: [
    { type: 'stage', files: ['file1', 'file2'] },
    { type: 'commit', message: 'Update files' },
    { type: 'push', branch: 'main' }
  ]
});

• Validate paths and inputs:

PathValidator.validatePath(path, {
  mustExist: true,
  allowDirectory: true
});

• Handle embedded repositories:

const { path, hasEmbeddedRepo } = PathValidator.validateGitRepo(path);
if (hasEmbeddedRepo) {
  // Handle embedded .git directories
}

Performance

• Use caching appropriately:

const result = await repositoryCache.getState(
  repoPath,
  RepoStateType.BRANCH,
  'branch -a',
  () => executeGitCommand('branch -a')
);

• Monitor resource usage:

performanceMonitor.recordMemoryUsage();
performanceMonitor.recordResourceUsage('cpu', cpuUsage);

• Handle cache invalidation:

repositoryCache.invalidateState(repoPath, RepoStateType.STATUS);
repositoryCache.invalidateCommand(repoPath, 'status');

Error Handling

• Use appropriate error types:

if (!isValidBranch(name)) {
  throw new ValidationError(`Invalid branch name: ${name}`, {
    operation: 'branch_create',
    details: { name }
  });
}

• Include recovery steps:

throw new NetworkError('Remote unreachable', {
  operation: 'push',
  recoverySteps: [
    'Check network connection',
    'Verify remote URL'
  ]
});

• Log errors appropriately:

logger.error(
  operation,
  'Operation failed',
  path,
  error,
  { command, context }
);

Development

• Clone the repository:

git clone https://github.com/your-org/git-mcp-server.git
cd git-mcp-server

• Install dependencies:

npm install

• Build the project:

npm run build

• Run tests:

npm test

Contributing

• Fork the repository
• Create a feature branch
• Commit your changes
• Push to the branch
• Create a Pull Request

For bugs and feature requests, please create an issue.

License

Apache License 2.0

Built with the Model Context Protocol