# GIT MCP Server

Node.js server implementing Model Context Protocol (MCP) for git operations.

## Features

- Git repository management through MCP protocol
- Support for common Git operations
- Type-safe command execution with Zod schema validation
- Robust error handling with detailed git error messages
- Comprehensive test suite covering all operations

## API

The server provides the following Git operations:

### git_clone
Clone a git repository to a local directory.

```typescript
{
    repository: string;    // Git repository URL to clone
    directory?: string;    // Target directory for the repository
    branch?: string;       // Branch to checkout
}
```

### git_status
Get the status of a git repository, showing changed files and branch information.

```typescript
{
    repository_path: string;  // Path to the git repository
}
```

### git_pull
Pull changes from a remote repository into your local repository.

```typescript
{
    repository_path: string;  // Path to the git repository
    remote?: string;         // Remote name
    branch?: string;         // Branch name
}
```

### git_push
Push local changes to a remote repository.

```typescript
{
    repository_path: string;  // Path to the git repository
    remote?: string;         // Remote name
    branch?: string;         // Branch name
}
```

### git_commit
Commit changes to the repository with a message.

```typescript
{
    repository_path: string;  // Path to the git repository
    message: string;         // Commit message
    add_all?: boolean;       // Add all files before committing
}
```

### git_checkout
Checkout a branch or specific commit.

```typescript
{
    repository_path: string;  // Path to the git repository
    branch: string;          // Branch or commit to checkout
    create?: boolean;        // Create new branch if it does not exist
}
```

### git_log
Show commit history.

```typescript
{
    repository_path: string;  // Path to the git repository
    count?: number;          // Number of commits to show
}
```

### git_branch
List all branches in the repository.

```typescript
{
    repository_path: string;  // Path to the git repository
    show_remote?: boolean;   // Show remote branches as well
}
```

### git_add
Add files to the staging area.

```typescript
{
    repository_path: string;  // Path to the git repository
    files: string[];         // Files to add to the staging area
}
```

### git_init
Initialize a new git repository.

```typescript
{
    repository_path: string;  // Path for the new git repository
    bare?: boolean;          // Create a bare repository
}
```

### git_remote
Manage remote repositories.

```typescript
{
    repository_path: string;  // Path to the git repository
    action: 'add' | 'remove' | 'set-url' | 'list';  // Action to perform on remote
    name?: string;           // Name of the remote
    url?: string;            // URL of the remote repository
}
```

## Error Handling

The server provides robust error handling for git operations:

- All git commands are executed with proper error capturing
- Error messages are cleaned and formatted for improved readability
- Specific git error patterns are detected and extracted from command output
- Each tool returns structured error responses with `isError: true` flag
- Errors include descriptive messages that match standard git error formats

## Installation

```bash
npm install
npm run build
```

## Usage

The server can be run using:

```bash
npm start
```

Or directly using the built executable:

```bash
./dist/index.js
```

## Testing

The project includes a comprehensive test suite that verifies all git operations work correctly. To run the tests:

```bash
npm test
```

The tests:
- Create a temporary git repository
- Test the full git workflow (clone, branch, add, commit, etc.)
- Verify proper error handling for invalid operations
- Clean up resources after test execution

For continuous test development, you can also use:

```bash
npm run test:watch
```

## Docker

A Docker image is available for easy deployment:

```bash
docker build -t mcp-git .
docker run mcp-git
```

## Development

```bash
npm run dev  # Start development mode with watch
npm run build  # Build the project
```

## Using with Cursor AI Chat

For detailed instructions on using this Git MCP server with Cursor's AI assistant, please see [using with cursor](./docs/using-with-cursor.md).

## License

MIT