使用说明

MCP Git服务器（Kotlin+Ktor）

一个用于Git操作的MCP（模型上下文协议）服务器，使用Kotlin和Ktor构建。

特性

此MCP服务器通过HTTP REST API或STDIO通过MCP协议提供执行Git操作的工具：

可用工具

git_status -显示存储库状态
使用 git_diff -显示所做的更改（带有特定文件和暂存选项）
git_提交 -创建带有消息的提交
git_log -视图提交历史记录
git_branch -列出/创建/删除分支
git_checkout -恢复文件或切换分支
git_add -将文件添加到暂存区
git_push -将提交推送到远程存储库

需求

Java 17或更高版本
系统上已安装Git

安装

克隆仓库
使脚本可执行：

chmod +x mcp-git-server.sh

用法

HTTP模式（默认）

在端口8080上启动HTTP服务器：

./gradlew run

或者使用脚本：

./mcp-git-server.sh http

服务器将在以下时间可用 http://localhost:8080

终点：

GET / -服务器信息
GET /health -健康检查
POST /mcp -MCP命令的JSON-RPC端点

STDIO模式（克劳德桌面）

要通过stdin/stdout与Claude Desktop一起使用：

./mcp-git-server.sh stdio

使用Claude Desktop进行配置

添加到您的Claude Desktop配置文件(claude_desktop_config.json):

{
  "mcpServers": {
    "git": {
      "command": "/full/path/to/mcp-git-server.sh",
      "args": ["stdio"],
      "env": {
        "GIT_WORKING_DIR": "/path/to/repository"
      }
    }
  }
}

环境变量

GIT_WORKING_DIR：Git存储库目录（默认：当前目录）
MCP_PORT：HTTP服务器端口（默认值：8080）
MCP_HOST：HTTP服务器主机（默认值：0.0.0.0）

使用示例

通过HTTP（curl）

# Health check
curl http://localhost:8080/health

# View repository status
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "git_status",
      "arguments": {}
    }
  }'

通过STDIO

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"git_status","arguments":{}}}' | ./mcp-git-server.sh stdio

JSON-RPC请求

查看存储库状态

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "git_status",
    "arguments": {}
  }
}

查看文件差异

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "git_diff",
    "arguments": {
      "file_path": "src/Main.kt",
      "staged": false
    }
  }
}

做出承诺

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "git_commit",
    "arguments": {
      "message": "feat: add new feature",
      "add_all": true
    }
  }
}

查看提交历史记录

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "git_log",
    "arguments": {
      "max_count": 5,
      "oneline": true
    }
  }
}

列出分支

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "git_branch",
    "arguments": {
      "action": "list"
    }
  }
}

创建新分支

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "git_branch",
    "arguments": {
      "action": "create",
      "branch_name": "feature/new-feature"
    }
  }
}

结账

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "git_checkout",
    "arguments": {
      "target": "main",
      "create_new": false
    }
  }
}

添加文件

{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "tools/call",
  "params": {
    "name": "git_add",
    "arguments": {
      "files": "."
    }
  }
}

推到远程

{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "tools/call",
  "params": {
    "name": "git_push",
    "arguments": {
      "remote": "origin",
      "branch": "main",
      "set_upstream": true,
      "force": false
    }
  }
}

发展

构建项目

./gradlew build

运行单元测试

./gradlew test

测试HTTP服务器

# Terminal 1: Start server
./gradlew run

# Terminal 2: Run HTTP tests
./test-http.sh

完全重建

./mcp-git-server.sh --rebuild

项目结构

mcp-git-server/
├── build.gradle.kts          # Gradle configuration
├── settings.gradle.kts        # Project settings
├── mcp-git-server.sh          # Execution script
├── test-http.sh               # HTTP tests
├── test-manual.sh             # STDIO tests
├── README.md                  # Documentation
├── TESTING.md                 # Testing guide
└── src/
    ├── main/
    │   └── kotlin/
    │       └── com/
    │           └── mcp/
    │               └── git/
    │                   ├── Main.kt           # Entry point
    │                   ├── KtorServer.kt     # Ktor HTTP server
    │                   ├── McpServer.kt      # MCP server (logic)
    │                   ├── McpProtocol.kt    # Protocol structures
    │                   └── GitOperations.kt  # Git operations
    └── test/
        └── kotlin/
            └── com/
                └── mcp/
                    └── git/
                        ├── GitOperationsTest.kt  # Git operations tests
                        ├── McpServerTest.kt      # MCP server tests
                        └── KtorServerTest.kt     # HTTP tests

协议

此服务器实现模型上下文协议版本2024-11-05。

文档

测试.md -带示例的综合测试指南
HTTP-MIGRATION.md -HTTP迁移和双模支持文档
http-usage-example.md -HTTP使用示例和API参考

许可证

麻省理工学院