git-mcp服务器

Name: git-mcp服务器
Author: cyanheads

作者：cyanheads147 星标更新：2025-10-28

项目介绍

<div align="center"> <h1>@cyanheads/git-mcp-server</h1> <p><b>一个安全且可扩展的Git MCP服务器，为本地和（即将支持的）无服务器环境中的AI代理提供强大的版本控制功能。STDIO & 可流式传输HTTP</b> <div>27 工具 • 1 资源 • 1 提示</div> </p> </div> <div align="center">

</div>

🛠️ 工具概述

此服务器提供了27个全面的Git操作，组织成六个功能性类别：

类别	工具	描述
仓库管理	`git_init`, `git_clone`, `git_status`, `git_clean`	初始化仓库，从远程克隆，检查状态，清理未跟踪文件
暂存与提交	`git_add`, `git_commit`, `git_diff`	暂存更改，创建提交，并比较更改
历史与审查	`git_log`, `git_show`, `git_blame`, `git_reflog`	查看提交历史，审查对象，逐行追踪作者身份，查看引用日志
分支与合并	`git_branch`, `git_checkout`, `git_merge`, `git_rebase`, `git_cherry_pick`	管理分支，切换上下文，集成更改，应用特定提交
远程操作	`git_remote`, `git_fetch`, `git_pull`, `git_push`	配置远程，下载更新，同步仓库，发布更改
高级工作流程	`git_tag`, `git_stash`, `git_reset`, `git_worktree`, `git_set_working_dir`, `git_clear_working_dir`, `git_wrapup_instructions`	标记发布，暂存更改，重置状态，管理工作树，设置/清除会话目录，访问工作流程指导

📦 资源概述

服务器提供的资源提供了关于Git环境的上下文信息：

资源	URI	描述
Git 工作目录	`git://working-directory`	提供当前会话的工作目录用于Git操作。这是通过`git_set_working_dir`设置并作为默认值使用的目录。

🎯 提示概述

服务器提供了结构化的提示模板，引导AI代理完成复杂的工作流程：

提示	描述	参数
Git 结束	一种系统化的工作流程协议，用于完成Git会话。引导代理进行审查、记录、提交和标记更改。	`changelogPath`, `skipDocumentation`, `createTag`, 和 `updateAgentFiles`。

🚀 快速开始

运行时兼容性

此服务器支持Bun和Node.js运行时：

运行时	命令	最低版本	备注
Bun	`bunx @cyanheads/git-mcp-server@latest`	≥ 1.2.0	原生Bun运行时（最佳性能）
Node.js	`npx @cyanheads/git-mcp-server@latest`	≥ 20.0.0	通过npx/bunx（通用兼容性）

服务器自动检测运行时，并使用适当的进程启动方法进行Git操作。

MCP客户端设置/配置

在您的MCP客户端配置文件中添加以下内容（例如，cline_mcp_settings.json）。客户端有不同的方式来配置服务器，请参考您客户端的具体文档。

确保根据需要更新环境变量（特别是您的Git信息！）

使用Bun（bunx）

{
  "mcpServers": {
    "git-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/git-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "GIT_BASE_DIR": "~/Developer/",
        "LOGS_DIR": "~/Developer/logs/git-mcp-server/",
        "GIT_USERNAME": "cyanheads",
        "GIT_EMAIL": "casey@caseyjhand.com",
        "GIT_SIGN_COMMITS": "false"
      }
    }
  }
}

使用Node.js（npx）

{
  "mcpServers": {
    "git-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["@cyanheads/git-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "GIT_BASE_DIR": "~/Developer/",
        "LOGS_DIR": "~/Developer/logs/git-mcp-server/",
        "GIT_USERNAME": "cyanheads",
        "GIT_EMAIL": "casey@caseyjhand.com",
        "GIT_SIGN_COMMITS": "false"
      }
    }
  }
}

可流式传输HTTP配置

MCP_TRANSPORT_TYPE=http
MCP_HTTP_PORT=3015

✨ 服务器特性

此服务器基于mcp-ts-template构建，并继承了其丰富的功能集：

声明式工具：在单个自包含文件中定义代理能力。框架处理注册、验证和执行。
健壮的错误处理：统一的McpError系统确保一致、结构化的错误响应。
可插拔的身份验证：通过零麻烦支持none、jwt或oauth模式来保护服务器。
抽象存储：交换存储后端（in-memory、filesystem、Supabase、Cloudflare KV/R2）而不改变业务逻辑。
全栈可观测性：通过结构化日志（Pino）和可选的自动仪器OpenTelemetry获得深入洞察。
依赖注入：使用tsyringe构建了一个干净、解耦和可测试的架构。
边缘就绪架构：基于一个边缘兼容框架构建，可以在本地机器或Cloudflare Workers上无缝运行。注意：当前的git操作使用CLI提供商，这需要本地安装git。计划通过集成isomorphic-git提供商来支持边缘部署。

此外，还有专门针对Git集成的功能：

跨运行时兼容性：与Bun和Node.js运行时无缝协作。自动检测运行时并使用最优的进程启动（Bun.spawn在Bun中，child_process.spawn在Node.js中）。
基于提供商的架构：可插拔的git提供商系统，当前实现为CLI，计划通过isomorphic-git提供商支持边缘部署。
优化的Git执行：直接与git CLI交互，具有跨运行时支持的高性能进程管理、流式I/O和超时处理（当前CLI提供商）。
全面覆盖：27个工具涵盖了从初始化到推送的所有基本Git操作。
工作目录管理：会话特定的目录上下文，适用于多仓库工作流程。
可配置的Git身份：通过环境变量覆盖作者/提交者信息，并自动回退到全局git配置。
安全功能：对破坏性操作如git clean和git reset --hard要求明确确认标志。
提交签名：所有创建提交的操作（提交、合并、变基、樱桃挑选和标签）都支持可选的GPG/SSH签名。

开发环境设置

先决条件

要么 Bun v1.2.0+ 或者 Node.js v20.0.0+
在系统PATH中安装并可访问的Git

注意：开发使用Bun可以获得最佳体验，但发布的包同时支持Bun（bunx）和Node.js（npx）。

安装

克隆仓库：

git clone https://github.com/cyanheads/git-mcp-server.git

cd git-mcp-server

安装依赖项：

使用Bun（推荐用于开发）：

bun install

使用Node.js：

npm install

⚙️ 配置

所有配置都在启动时集中解析和验证在src/config/index.ts中。.env文件中的关键环境变量包括：

变量	描述	默认值
`MCP_TRANSPORT_TYPE`	使用的传输类型：`stdio` 或 `http`。	`stdio`
`MCP_SESSION_MODE`	HTTP传输的会话模式：`stateless`，`stateful` 或 `auto`。	`auto`
`MCP_RESPONSE_FORMAT`	响应格式：`json`（LLM优化），`markdown`（人类可读），或 `auto`。	`json`
`MCP_RESPONSE_VERBOSITY`	响应详细级别：`minimal`，`standard` 或 `full`。	`standard`
`MCP_HTTP_PORT`	HTTP服务器的端口。	`3015`
`MCP_HTTP_HOST`	HTTP服务器的主机名。	`127.0.0.1`
`MCP_HTTP_ENDPOINT_PATH`	MCP请求的端点路径。	`/mcp`
`MCP_AUTH_MODE`	认证模式：`none`，`jwt` 或 `oauth`。	`none`
`STORAGE_PROVIDER_TYPE`	存储后端：`in-memory`，`filesystem`，`supabase`，`cloudflare-kv`，`r2`。	`in-memory`
`OTEL_ENABLED`	设置为 `true` 启用OpenTelemetry。	`false`
`MCP_LOG_LEVEL`	日志的最低级别（`debug`，`info`，`warn`，`error`）。	`info`
`GIT_SIGN_COMMITS`	设置为 `"true"` 启用所有提交、合并、变基、樱桃挑选和标签的GPG/SSH签名。需要GPG/SSH配置。	`false`
`GIT_AUTHOR_NAME`	Git作者名称。别名：`GIT_USERNAME`，`GIT_USER`。如果未设置，则回退到全局git配置。	`(none)`
`GIT_AUTHOR_EMAIL`	Git作者电子邮件。别名：`GIT_EMAIL`，`GIT_USER_EMAIL`。如果未设置，则回退到全局git配置。	`(none)`
`GIT_BASE_DIR`	可选的绝对路径，限制所有git操作到特定目录树。为多租户或多用户环境提供安全沙箱。	`(none)`
`GIT_WRAPUP_INSTRUCTIONS_PATH`	可选的自定义markdown文件路径，包含Git工作流程说明。	`(none)`
`MCP_AUTH_SECRET_KEY`	对于`jwt`认证是必需的。 32个字符以上的密钥。	`(none)`
`OAUTH_ISSUER_URL`	对于`oauth`认证是必需的。 OIDC提供商的URL。	`(none)`

▶️ 运行服务器

对于最终用户（通过包管理器）

最简单的方式是通过bunx或npx（无需安装）：

使用Bun：

bunx @cyanheads/git-mcp-server@latest

使用Node.js：

npx @cyanheads/git-mcp-server@latest

两个命令完全相同，可以通过环境变量或您的MCP客户端配置进行配置。

本地开发

构建并运行生产版本：

# 一次性构建
bun rebuild

# 运行已构建的服务器
bun start:http
# 或
bun start:stdio

开发模式带热重载：
```
bun dev:http
# 或
bun dev:stdio
```

运行检查和测试：

bun devcheck # 检查、格式化、类型检查等
bun test     # 运行测试套件

Cloudflare Workers

构建Worker捆绑包：

bun build:worker

使用Wrangler本地运行：

bun deploy:dev

部署到Cloudflare：

bun deploy:prod

📂 项目结构

目录	目的及内容
`src/mcp-server/tools`	您的工具定义（`*.tool.ts`）。这是定义Git能力的地方。
`src/mcp-server/resources`	您的资源定义（`*.resource.ts`）。提供Git上下文数据源。
`src/mcp-server/transports`	HTTP和STDIO传输的实现，包括认证中间件。
`src/storage`	`StorageService`抽象和所有存储提供商的实现。
`src/services`	与外部服务的集成（LLMs、语音等）。
`src/container`	依赖注入容器注册和令牌。
`src/utils`	核心实用程序，用于日志记录、错误处理、性能和安全性。
`src/config`	使用Zod解析和验证环境变量。
`tests/`	单元和集成测试，镜像`src/`目录结构。

📤 理解工具响应

此服务器遵循MCP的双输出架构用于所有工具（MCP工具规范）：

响应格式选项

通过环境变量配置响应格式和详细程度（参见配置）：

变量	值	描述
`MCP_RESPONSE_FORMAT`	`json`（默认）、`markdown`、`auto`	输出格式：JSON用于LLM解析，Markdown用于人类UIs
`MCP_RESPONSE_VERBOSITY`	`minimal`、`standard`（默认）、`full`	详细程度：最小（核心数据）、标准（平衡）、全部（一切）

用户看到的内容（人类可读）

当您通过MCP客户端调用工具时，您会看到一个格式化的摘要，旨在供人类消费。例如，git_status可能会显示：

Markdown格式：

# Git 状态：main

## 暂存（2）
- src/index.ts
- README.md

## 未暂存（1）
- package.json

JSON格式（LLM优化）：

{
  "success": true,
  "branch": "main",
  "staged": ["src/index.ts", "README.md"],
  "unstaged": ["package.json"],
  "untracked": []
}

LLM看到的内容（完整的结构化数据）

幕后，LLM接收完整的结构化数据作为内容块，通过responseFormatter函数传递。这包括：

所有元数据（提交哈希、时间戳、作者）
完整的文件列表和更改详情（从不截断——LLM需要完整上下文）
根据配置的结构化JSON或格式化的markdown
回答后续问题所需的一切

为什么这很重要：LLM可以回答详细的提问，如“谁进行了最后一次提交？”或“提交abc123中哪些文件发生了变化？”因为它拥有完整数据集，即使您只看到了摘要。

详细程度等级：控制返回的数据量：

最小：仅核心数据（成功状态、主要标识符）
标准：平衡输出，带有必要上下文