MCP Git Tools

MCP Git Tools

用于 Model Context Protocol（MCP）的 Git 工具实现。

中文文档

功能

此库提供一组可通过 Model Context Protocol 调用的 Git 操作：

• git_status - 获取仓库状态
• git_branches - 列出分支信息
• git_log - 获取提交历史，支持灵活的筛选选项（按时间、作者、分支和数量）
• git_commit - 创建新提交
• git_pull - 从远程拉取更改
• git_push - 向远程推送更改
• git_diff - 查看文件差异
• git_add - 将文件内容添加到暂存区
• git_reset - 将暂存区或工作树重置为指定状态
• git_worktree_list - 列出所有工作树
• git_worktree_add - 创建新的工作树
• git_worktree_remove - 移除工作树
• git_worktree_prune - 清理过期的工作树文件

安装

# 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

使用方法

作为独立服务运行

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

这会启动一个 MCP 服务，通过标准输入/输出与客户端交互。

使用 MCP Inspector 测试

1. 构建服务：

cargo build --release

2. 启动服务：

./target/release/mcp-git-server

3. 使用 MCP Inspector 测试工具：
   • 下载 MCP Inspector：https://github.com/modelcontextprotocol/inspector
   • 点击“Add a server”
   • 输入：/path/to/mcp-git-server/target/release/mcp-git-server
   • 点击“Add”
   • 使用 Inspector 界面测试每个工具

架构

本项目使用现代 RMCP SDK（v0.14.0），采用清晰的架构：

核心组件

GitToolsHandler

• 处理所有 Git 操作的中央处理器结构体
• 实现 RMCP SDK 中的 ServerHandler trait
• 包含每项 Git 操作对应的方法

ServerHandler 实现

• get_info() - 提供服务元数据和功能
• list_tools() - 列出所有可用工具及其架构
• call_tool() - 将工具调用路由到相应的处理方法

工具实现模式

每个工具都作为 GitToolsHandler 上的方法实现：

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

参数处理

所有工具参数都使用派生宏自动生成架构：

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

这提供了：

• 自动生成 JSON 架构
• 类型安全的参数解析
• 无需手动编写序列化/反序列化代码

传输方式

使用 RMCP 的 stdio() 传输方式，通过标准输入/输出进行通信。

工具详情

git_status

获取仓库状态。

参数：

• repo_path - Git 仓库路径

返回：

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

git_branches

列出所有分支。

参数：

• repo_path - Git 仓库路径

返回：

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

git_log

获取提交历史，支持灵活的筛选选项。

参数：

• repo_path - Git 仓库路径
• max_count -（可选）要返回的最大提交数
• branch -（可选）分支名称
• since -（可选）开始日期（例如，“2023-01-01”、“1 week ago”、“yesterday”）
• until -（可选）结束日期（例如，“2023-01-31”、“today”）
• author -（可选）按特定作者筛选（匹配姓名或电子邮件）

返回：

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

示例：

• 获取最近 10 条提交：{"repo_path": ".", "max_count": 10}
• 获取上周的提交：{"repo_path": ".", "since": "1 week ago"}
• 获取指定作者的提交：{"repo_path": ".", "author": "John"}
• 获取指定时间范围内的提交：{"repo_path": ".", "since": "2023-01-01", "until": "2023-12-31"}

git_commit

创建新提交。

参数：

• repo_path - Git 仓库路径
• message - 提交消息
• all -（可选）是否自动暂存已修改的文件

返回：

{
  "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

从远程拉取更改。

参数：

• repo_path - Git 仓库路径
• remote -（可选）远程名称，默认为“origin”
• branch -（可选）分支名称

返回：

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

git_push

推送更改到远程仓库。

参数：

• repo_path - Git 仓库的路径
• remote - （可选）远程仓库名称，默认为 "origin"
• branch - （可选）分支名称
• force - （可选）是否强制推送

返回：

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

git_diff

查看文件差异。

参数：

• repo_path - Git 仓库的路径
• path - （可选）文件或目录的路径
• staged - （可选）是否显示已暂存的更改
• commit - （可选）用于比较的提交

返回：

{
  "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

将文件内容添加到暂存区。

参数：

• repo_path - Git 仓库的路径
• path - 要添加的路径，或用于匹配的模式。使用 '.' 可添加所有文件。
• update - （可选）是否更新而非添加
• all - （可选）是否添加所有更改，包括未跟踪的文件

返回：

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

git_reset

将暂存区或工作区重置为指定状态。

参数：

• repo_path - Git 仓库的路径
• path - 要重置的路径，或用于匹配的模式。使用 '.' 可重置所有文件。
• hard - （可选）是否执行硬重置（警告：会丢弃所有本地更改）
• target - （可选）要重置到的提交或分支（默认为 HEAD）

返回：

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

git_worktree_list

列出仓库中的所有工作树。

参数：

• repo_path - Git 仓库的路径

返回：

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

git_worktree_add

创建新的工作树。

参数：

• repo_path - Git 仓库的路径
• path - 新工作树的路径
• branch - （可选）要创建的分支名称
• commit_ref - （可选）要检出的提交引用
• checkout - （可选）是否检出文件，默认为 true

返回：

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

git_worktree_remove

移除工作树。

参数：

• repo_path - Git 仓库的路径
• path - 要移除的工作树的路径
• force - （可选）即使工作树存在未提交更改也强制移除

返回：

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

git_worktree_prune

清理 $GIT_DIR/worktrees 中的工作树文件。

参数：

• repo_path - Git 仓库的路径
• verbose - （可选）报告所有移除项
• dry_run - （可选）不执行移除，仅显示结果

返回：

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

开发

项目结构

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

构建

# Debug build
cargo build

# Release build
cargo build --release

# Run tests
cargo test

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

添加新工具

要添加新的 Git 工具：

1. 在 src/lib.rs 中添加参数结构体：

#[derive(serde::Deserialize, schemars::JsonSchema)]
struct GitMyToolParams {
    repo_path: String,
    // other parameters...
}

2. 在 GitToolsHandler impl 代码块中添加方法：

#[tool(description = "Description of your tool")]
pub async fn git_my_tool(
    &self,
    repo_path: String,
    // other parameters...
) -> Result<CallToolResult> {
    // Implementation
}

3. 更新 list_tools() 方法，将新工具添加到返回列表中

依赖项

• rmcp v0.14.0 - 官方 RMCP SDK
• tokio - 异步运行时
• serde - 序列化框架
• serde_json - JSON 实现
• anyhow - 错误处理
• tracing - 日志框架
• tempfile - 测试工具

许可证

MIT 许可证