# MCP Git Tools

Git tools implementation for the Model Context Protocol (MCP).

[中文文档](README_CN.md)

## Features

This library provides a set of Git operations that can be called through the Model Context Protocol:

- `git_status` - Get the status of a repository
- `git_branches` - List branch information
- `git_log` - Get commit history with flexible filtering options (by time, author, branch, count)
- `git_commit` - Create a new commit
- `git_pull` - Pull changes from remote
- `git_push` - Push changes to remote
- `git_diff` - View file differences
- `git_add` - Add file contents to the staging area
- `git_reset` - Reset the staging area or working tree to a specified state
- `git_worktree_list` - List all worktrees
- `git_worktree_add` - Create a new worktree
- `git_worktree_remove` - Remove a worktree
- `git_worktree_prune` - Prune expired worktree files

## Installation

```bash
# Clone the repository
git clone https://gitcode.com/lileeei/mcp-git-tools.git

# Navigate to the directory
cd mcp-git-tools

# Build
cargo build --release
```

## Usage

### Run as a standalone server

```bash
cargo run --release --bin mcp-git-server
```

This starts an MCP server that interacts with clients through standard input/output.

### Test with MCP Inspector

1. Build the server:
```bash
cargo build --release
```

2. Start the server:
```bash
./target/release/mcp-git-server
```

3. Use MCP Inspector to test the tools:
   - Download MCP Inspector: https://github.com/modelcontextprotocol/inspector
   - Click "Add a server"
   - Enter: `/path/to/mcp-git-server/target/release/mcp-git-server`
   - Click "Add"
   - Test each tool using the Inspector interface

## Architecture

This project uses the modern RMCP SDK (v0.14.0) with a clean architecture:

### Core Components

**GitToolsHandler**
- Central handler struct for all Git operations
- Implements `ServerHandler` trait from RMCP SDK
- Contains methods for each Git operation

**ServerHandler Implementation**
- `get_info()` - Provides server metadata and capabilities
- `list_tools()` - Lists all available tools with their schemas
- `call_tool()` - Routes tool calls to appropriate handler methods

### Tool Implementation Pattern

Each tool is implemented as a method on `GitToolsHandler`:

```rust
impl GitToolsHandler {
    #[tool(description = "Get the status of a git repository")]
    pub async fn git_status(
        &self,
        repo_path: String,
    ) -> Result<CallToolResult> {
        // Implementation
    }
}
```

### Parameter Handling

All tool parameters use derive macros for automatic schema generation:

```rust
#[derive(serde::Deserialize, schemars::JsonSchema)]
struct GitStatusParams {
    repo_path: String,
}
```

This provides:
- Automatic JSON schema generation
- Type-safe parameter parsing
- No manual serialization/deserialization code

### Transport

Uses RMCP's `stdio()` transport for standard input/output communication.

## Tool Details

### git_status

Get the status of a repository.

**Parameters:**
- `repo_path` - Path to the Git repository

**Returns:**
```json
{
  "status": ["M file1.txt", "?? file2.txt"],
  "is_clean": false
}
```

### git_branches

List all branches.

**Parameters:**
- `repo_path` - Path to the Git repository

**Returns:**
```json
{
  "branches": ["* main", "develop", "feature/new-feature"],
  "current": "main"
}
```

### git_log

Get commit history with flexible filtering options.

**Parameters:**
- `repo_path` - Path to Git repository
- `max_count` - (optional) Maximum number of commits to return
- `branch` - (optional) Branch name
- `since` - (optional) Start date (e.g., "2023-01-01", "1 week ago", "yesterday")
- `until` - (optional) End date (e.g., "2023-01-31", "today")
- `author` - (optional) Filter by specific author (matches name or email)

**Returns:**
```json
{
  "commits": [
    {
      "hash": "abcd1234",
      "author": "User Name",
      "author_date": "Mon Aug 1 10:00:00 2023 +0800",
      "message_title": "Initial commit"
    }
  ]
}
```

**Examples:**
- Get recent 10 commits: `{"repo_path": ".", "max_count": 10}`
- Get commits from last week: `{"repo_path": ".", "since": "1 week ago"}`
- Get commits by author: `{"repo_path": ".", "author": "John"}`
- Get commits from a time range: `{"repo_path": ".", "since": "2023-01-01", "until": "2023-12-31"}`

### git_commit

Create a new commit.

**Parameters:**
- `repo_path` - Path to the Git repository
- `message` - Commit message
- `all` - (optional) Whether to automatically stage modified files

**Returns:**
```json
{
  "success": true,
  "hash": "abcd1234",
  "message": "feat: Add new feature",
  "output": "[main abcd1234] feat: Add new feature\n 1 file changed, 10 insertions(+), 2 deletions(-)"
}
```

### git_pull

Pull changes from remote.

**Parameters:**
- `repo_path` - Path to the Git repository
- `remote` - (optional) Remote name, defaults to "origin"
- `branch` - (optional) Branch name

**Returns:**
```json
{
  "success": true,
  "remote": "origin",
  "output": "Updating abcd1234..efgh5678\nFast-forward\n file1.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)"
}
```

### git_push

Push changes to remote.

**Parameters:**
- `repo_path` - Path to the Git repository
- `remote` - (optional) Remote name, defaults to "origin"
- `branch` - (optional) Branch name
- `force` - (optional) Whether to force push

**Returns:**
```json
{
  "success": true,
  "remote": "origin",
  "output": "To github.com:user/repo.git\n   abcd1234..efgh5678  main -> main"
}
```

### git_diff

View file differences.

**Parameters:**
- `repo_path` - Path to the Git repository
- `path` - (optional) Path to file or directory
- `staged` - (optional) Whether to show staged changes
- `commit` - (optional) Commit to compare against

**Returns:**
```json
{
  "changes": "diff --git a/file.txt b/file.txt\nindex 1234567..abcdefg 100644\n--- a/file.txt\n+++ b/file.txt\n@@ -1,3 +1,4 @@\n Line 1\nLine 2\nLine 3\n+New line\nLine 4"
}
```

### git_add

Add file contents to the staging area.

**Parameters:**
- `repo_path` - Path to the Git repository
- `path` - Path(s) to add, or patterns to match. Use '.' for all files.
- `update` - (optional) Whether to update, rather than add
- `all` - (optional) Whether to add all changes, including untracked files

**Returns:**
```json
{
  "success": true,
  "message": "Files staged successfully",
  "status": ["M file1.txt", "A file2.txt"]
}
```

### git_reset

Reset the staging area or working tree to a specified state.

**Parameters:**
- `repo_path` - Path to the Git repository
- `path` - Path(s) to reset, or patterns to match. Use '.' for all files.
- `hard` - (optional) Whether to perform a hard reset (WARNING: discards all local changes)
- `target` - (optional) The commit or branch to reset to (defaults to HEAD)

**Returns:**
```json
{
  "success": true,
  "message": "Files unstaged successfully",
  "status": ["?? file1.txt", "?? file2.txt"]
}
```

### git_worktree_list

List all worktrees in a repository.

**Parameters:**
- `repo_path` - Path to the Git repository

**Returns:**
```json
{
  "worktrees": [
    {
      "id": "worktree-name",
      "path": "/path/to/worktree",
      "locked": false,
      "lock_reason": null
    }
  ]
}
```

### git_worktree_add

Create a new worktree.

**Parameters:**
- `repo_path` - Path to the Git repository
- `path` - Path for the new worktree
- `branch` - (optional) Branch name to create
- `commit_ref` - (optional) Commit reference to check out
- `checkout` - (optional) Whether to check out files, defaults to true

**Returns:**
```json
{
  "success": true,
  "path": "/path/to/new/worktree",
  "branch": "feature-branch",
  "output": "Preparing worktree (checking out 'feature-branch')"
}
```

### git_worktree_remove

Remove a worktree.

**Parameters:**
- `repo_path` - Path to the Git repository
- `path` - Path to the worktree to remove
- `force` - (optional) Force removal even if worktree is dirty

**Returns:**
```json
{
  "success": true,
  "path": "/path/to/worktree",
  "force": false,
  "output": "Removing worktrees/feature-branch"
}
```

### git_worktree_prune

Prune working tree files in $GIT_DIR/worktrees.

**Parameters:**
- `repo_path` - Path to the Git repository
- `verbose` - (optional) Report all removals
- `dry_run` - (optional) Do not remove, show only

**Returns:**
```json
{
  "success": true,
  "verbose": false,
  "dry_run": false,
  "output": "Pruning worktrees/feature-branch"
}
```

## Development

### Project Structure

```
mcp-git-tools/
├── Cargo.toml          # Dependencies and project configuration
├── src/
│   ├── lib.rs          # Core library with GitToolsHandler
│   └── bin/
│       └── server.rs   # Server entry point
├── tests/
│   └── lib_tests.rs   # Unit tests
```

### Building

```bash
# Debug build
cargo build

# Release build
cargo build --release

# Run tests
cargo test

# Run server
cargo run --release --bin mcp-git-server
```

### Adding New Tools

To add a new Git tool:

1. Add the parameter struct in `src/lib.rs`:
```rust
#[derive(serde::Deserialize, schemars::JsonSchema)]
struct GitMyToolParams {
    repo_path: String,
    // other parameters...
}
```

2. Add the method in the `GitToolsHandler` impl block:
```rust
#[tool(description = "Description of your tool")]
pub async fn git_my_tool(
    &self,
    repo_path: String,
    // other parameters...
) -> Result<CallToolResult> {
    // Implementation
}
```

3. Update the `list_tools()` method to include your new tool in the returned list

## Dependencies

- `rmcp` v0.14.0 - The official RMCP SDK
- `tokio` - Async runtime
- `serde` - Serialization framework
- `serde_json` - JSON implementation
- `anyhow` - Error handling
- `tracing` - Logging framework
- `tempfile` - Testing utilities

## License

MIT License