readme.md•4.43 kB
# 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