Git Simple Read MCP

Git简单读取MCP

用于Git读取操作和工作区管理的模型上下文协议（MCP）服务器。

特性

此MCP服务器为Git存储库读取操作提供了以下工具：

工作空间管理

• clone_repository：将Git存储库克隆到托管工作区中
• list_workspace_repositories：列出工作区中的所有存储库
• remove_repository：从工作区中删除存储库

安全：所有操作仅限于指定工作区目录中的存储库。

存储库信息

• get_pository_info：获取基本存储库信息，包括：

- 提交计数 - 最后更新日期 - 当前分行 - 许可证文件检测 - README内容（前50行） - 远程URL

存储库操作

• pull-repository：执行 git pull 在指定的存储库上

分行管理

• list_brances：列出存储库中的所有分支（支持分页）
• switch_branch：切换到指定的分支

文件操作

• 搜索文件：使用增强的筛选功能搜索包含指定关键字的文件

- AND/OR逻辑支持 - 文件模式过滤（包括/排除模式） - 比赛周围的背景线 - 文件名和内容搜索

• 列表文件：列出指定目录中具有增强信息的文件

- 递归扩展 - 文件模式过滤（包括/排除模式） - 每个文件的字符数和行数 - 文件大小信息

• 获取_文件_内容：获取文件内容

- 一个请求中包含单个文件或多个文件 - 从指定行开始读取(start_line) - 始终显示行号以实现AI友好的输出 - 包括文件元数据（路径、行范围、总行数） - 每个文件的单独错误处理 - 减少令牌使用的最小输出格式

• get_adme_files：在存储库中查找所有README文件

- 支持递归搜索 - 返回文件元数据（大小、修改时间、行数）

安装

1. 克隆此存储库：

git clone 
cd git-simple-read-mcp

1. 构建项目：

go build .

用法

独立服务器

使用stdio传输启动MCP服务器（默认）：

./git-simple-read-mcp mcp --workspace ./my-workspace

使用HTTP传输启动MCP服务器：

./git-simple-read-mcp mcp --transport http --port 8080 --workspace ./my-workspace

如果工作区目录不存在，将自动创建它。所有Git操作将仅限于此工作区内的存储库。

远程MCP使用

要将其用作远程MCP服务器，请执行以下操作：

1.构建并启动HTTP服务器

# Build the server
go build .

# Start HTTP server (default port 8080)
./git-simple-read-mcp mcp --transport http --port 8080 --workspace ./workspace

# Or use the provided script
./start-server.sh ./workspace 8080

2.配置MCP客户端

添加到您的MCP客户端配置中（例如，Claude Code）：

{
  "mcpServers": {
    "git-remote": {
      "url": "http://localhost:8080/mcp",
      "description": "Git Simple Read MCP Server for repository read operations"
    }
  }
}

3.远程访问

对于跨网络的远程访问：

# Start server on all interfaces
./git-simple-read-mcp mcp --transport http --port 8080 --workspace ./workspace --host 0.0.0.0

# Then connect from client with
# "url": "http://your-server-ip:8080/mcp"

安全说明：在网络上公开时，考虑添加身份验证、HTTPS和防火墙规则。

4.Docker部署

使用Docker运行：

# Build the image
docker build -t git-simple-read-mcp .

# Run the container
docker run -d \
  --name git-simple-read-mcp \
  -p 8080:8080 \
  -v $(pwd)/workspace:/workspace \
  git-simple-read-mcp

# Or use docker-compose
docker-compose up -d

5.生产部署

对于基于systemd的系统：

# Copy files to production location
sudo cp git-simple-read-mcp /opt/git-simple-read-mcp/
sudo cp git-simple-read-mcp.service /etc/systemd/system/

# Create user and directories
sudo useradd -r -s /bin/false git-mcp
sudo mkdir -p /var/lib/git-simple-read-mcp/workspace
sudo chown -R git-mcp:git-mcp /var/lib/git-simple-read-mcp

# Enable and start service
sudo systemctl daemon-reload
sudo systemctl enable git-simple-read-mcp
sudo systemctl start git-simple-read-mcp

刀具参数

每个工具都接受JSON参数：

clone_repository

{
  "url": "https://github.com/user/repository.git",
  "name": "my-repo"
}

list_repositories

{}

remove_repository

{
  "name": "repository-name"
}

get_pository_info

{
  "repository": "my-repo"
}

pull-repository

{
  "repository": "my-repo"
}

list_brances

{
  "repository": "my-repo",
  "limit": 10
}

switch_branch

{
  "repository": "my-repo",
  "branch": "branch-name"
}

list_commits

{
  "repository": "my-repo",
  "limit": 20
}

参数：

• limit：返回的最大提交数，默认值：20

get_commit_diff

{
  "repository": "my-repo",
  "commit_hash": "a1b2c3d4"
}

参数：

• commit_hash：获取差异的提交哈希值。

搜索文件

{
  "repository": "my-repo",
  "keywords": ["keyword1", "keyword2"],
  "search_mode": "and",
  "include_filename": false,
  "context_lines": 0,
  "include_patterns": ["*.go", "*.js"],
  "exclude_patterns": ["*_test.go", "vendor/*"],
  "limit": 20
}

参数：

• keywords：搜索词数组
• search_mode：“and”（所有关键字）或“or”（任何关键字），默认值：“and
• include_filename：也在文件名中搜索，默认值：false
• context_lines：匹配项周围的上下文行，默认值：0
• include_patterns：要包含的文件模式（glob格式）
• exclude_patterns：要排除的文件模式（glob格式）
• limit：最大结果，默认值：20

列表文件

{
  "repository": "my-repo",
  "directory": "src",
  "recursive": true,
  "include_patterns": ["*.go", "*.js"],
  "exclude_patterns": ["*_test.go", "node_modules/*"],
  "limit": 50
}

参数：

• directory：目标目录，默认：“。”
• recursive：包括子目录，默认值：false
• include_patterns：要包含的文件模式（glob格式）
• exclude_patterns：要排除的文件模式（glob格式）
• limit：要返回的最大文件数，默认值：50

输出包括：

• 文件路径和名称
• 目录标志
• 文件大小（字节/KB/MB）
• 字符数（用于文本文件）
• 行数（用于文本文件）
• 修改时间

获取_文件_内容

单个文件：

{
  "repository": "my-repo",
  "file_path": "src/main.go",
  "start_line": 1,
  "max_lines": 100
}

多个文件：

{
  "repository": "my-repo",
  "file_paths": ["src/main.go", "src/utils.go", "config.json"],
  "start_line": 50,
  "max_lines": 100
}

参数：

• file_path：单个文件路径（为了向后兼容）
• file_paths：文件路径数组（用于多个文件）
• start_line：开始读取的行号（从1开始），默认值：1
• max_lines：每个文件的最大行数，默认值：100

输出格式（AI优化）：

[src/main.go L1-50/200]
   1: package main
   2:
   3: func main() {
...

格式： [path L{start}-{end}/{total}] 后面是行编号的内容。

多文件输出：

[src/main.go L1-50/200]
   1: package main
...

[src/utils.go L1-30/30]
   1: package main
...

[config.json ERR:file not found]

get_adme_files

{
  "repository": "my-repo",
  "recursive": true
}

参数：

• recursive：搜索子目录，默认值：false

增强功能示例

文件模式筛选

仅列出Go文件：

{
  "repository": "my-repo",
  "include_patterns": ["*.go"]
}

列出除测试和供应商之外的所有文件：

{
  "repository": "my-repo",
  "exclude_patterns": ["*_test.go", "vendor/*", "node_modules/*"]
}

仅在源文件中搜索函数：

{
  "repository": "my-repo", 
  "keywords": ["func"],
  "include_patterns": ["src/*.go", "lib/*.go"],
  "exclude_patterns": ["*_test.go"]
}

字符计数和文件信息

这 list_files 工具现在返回详细的文件信息：

📄 main.go (2.1 KB, 156 chars, 8 lines)
📄 utils.go (1.5 KB, 98 chars, 5 lines)
📁 src/
📄 src/app.js (856 bytes, 45 chars, 3 lines)

多文件内容检索

{
  "repository": "my-repo",
  "file_paths": ["main.go", "config.json", "README.md"],
  "start_line": 1,
  "max_lines": 50
}

通过单独的错误处理（AI优化的最小格式）返回所有文件的内容：

[main.go L1-10/10]
   1: package main
   2:
   3: func main() {}

[config.json ERR:file not found]

[README.md L1-5/5]
   1: # My Project
   2: This is a sample project

从特定行阅读

{
  "repository": "my-repo",
  "file_path": "large_file.go",
  "start_line": 100,
  "max_lines": 50
}

输出：

[large_file.go L100-149/500]
 100: func processData() {
 101:     // Processing logic
...

错误处理

在以下情况下，所有工具都会返回相应的错误消息：

• 存储库路径无效或不是Git存储库
• Git命令失败
• 文件操作遇到错误
• 参数缺失或无效

分页

有几个工具支持分页，以防止输出过大：

• list_branches：限制返回的分支数量
• search_files：限制搜索结果（默认值：20）
• list_files：限制文件列表（默认值：50）
• get_file_content：限制读取的行数（默认值：100）

安全考虑

• 此服务器对Git存储库执行只读操作
• 这 switch_branch 操作修改工作目录，但不提交更改
• 这 pull_repository 操作从远程源更新存储库
• 始终确保服务器对目标存储库具有适当的权限

依赖项

• 转到1.23.0或更高版本
• MCP Go SDK
• Cobra CLI
• Git命令行工具

许可证

本项目按原样提供，用于教育和发展目的。