Git操作服务器

Git MCP服务器

为您的AI代理提供对Git存储库的全面、安全和程序化控制！

MCP（模型上下文协议）服务器，为标准提供健壮、LLM友好的接口 git 命令行工具。使LLM和AI代理能够通过MCP标准执行各种Git操作，如克隆、提交、推送、拉取、分支、差异、日志、状态等。

建立在 cyanheads/mcp-ts-template，此服务器遵循模块化架构，具有强大的错误处理、日志记录和安全功能。

🚀 核心功能：Git工具🛠️

此服务器为您的AI配备了一套全面的工具，用于与Git存储库进行交互：

目录

| 概述 | 特性 | 安装 | | 配置 | 项目结构 | | 工具 | 资源 | 发展 | 许可证 |

概述

Git MCP服务器充当桥梁，允许理解模型上下文协议（MCP）的应用程序（MCP客户端）（如高级AI编码助手（LLM）、IDE扩展或自定义研究工具）直接安全地与本地Git存储库交互。

您的工具可以利用此服务器来：

• 自动化Git工作流：克隆存储库、创建分支、暂存更改、提交工作、推送更新和以编程方式管理标签。
• 获得存储库见解：检查状态、查看日志、差异更改，并在不离开宿主应用程序的情况下检查Git对象。
• 将Git集成到AI驱动的开发中：使LLM能够将版本控制作为其编码或重构任务的一部分进行管理，确保代码的完整性和历史记录。
• 支持CI/CD和DevOps自动化：构建自定义脚本和工具，以编排复杂的Git操作，实现自动化构建、测试和部署。

建立在坚固的基础上 mcp-ts-template，此服务器提供了一种标准化、安全且高效的方式，通过MCP标准公开Git功能。它通过安全地执行标准来实现这一点 git 使用Node.js安装在系统上的命令行工具 child_process 模块，确保兼容性并充分利用Git的强大功能。

开发者说明：此存储库包括 .微规则 该文件作为LLM编码代理的开发人员备忘单，可快速参考代码库模式、文件位置和代码片段。

特性

核心公用设施

利用 mcp-ts-template:

• 日志记录：结构化、可配置的日志记录（文件轮换、stdout JSON、MCP通知），带有敏感数据编辑功能。
• 错误处理：集中错误处理，标准化错误类型(McpError)，以及自动记录。
• 配置：环境变量加载(dotenv)经过全面验证。
• 输入验证/消毒：用途 zod 用于模式验证和自定义净化逻辑（对路径至关重要）。
• 请求上下文：使用唯一的请求ID跟踪和关联操作 AsyncLocalStorage.
• 类型安全：TypeScript和Zod模式强制执行强类型。
• HTTP传输：使用高性能HTTP服务器 你好，具有会话管理、CORS和身份验证支持。
• 部署：多阶段 Dockerfile 用于创建具有本机依赖支持的小型安全生产映像。

Git集成

• 直接Git CLI执行：通过安全执行标准与Git交互 git 通过Node.js的命令行工具 child_process，确保完全兼容和访问Git的功能。
• 全面指挥覆盖：将各种Git命令作为MCP工具公开（请参见 工具 部分）。
• 存储库交互：支持状态检查、分支、暂存、提交、获取、拉取、推送、差异化、日志记录、重置、标记等。
• 工作目录管理：允许设置和清除特定于会话的工作目录，以实现跨多个Git操作的上下文持久性。
• 安全功能：包括检查，并要求明确确认潜在的破坏性操作，如 git clean 和 git reset --hard.
• 提交签名：支持GPG或SSH签名以验证提交，通过 GIT_SIGN_COMMITS 环境变量和服务器端Git配置。包括一个可选的工具参数，用于在签名失败时回退到未签名的提交。

安装

先决条件

• Node.js（>=20.0.0）
• npm （附带Node.js）
• Git 已安装并可在系统PATH中访问。

MCP客户端设置

将以下内容添加到MCP客户端的配置文件中（例如。， cline_mcp_settings.json).此配置使用 npx 运行服务器，如果软件包不存在，它将自动安装：

{
  "mcpServers": {
    "git-mcp-server": {
      "command": "npx",
      "args": ["@cyanheads/git-mcp-server"],
      "env": {
        "MCP_LOG_LEVEL": "info",
        "GIT_SIGN_COMMITS": "false"
      }
    }
  }
}

合并冲突解决

使用分支时，您可能会遇到合并冲突。以下是解决这些问题的方法：

1. 检查状态 使用您的存储库来识别冲突：

   复制

   git status
   

   这将显示哪些文件存在冲突。

2. 打开冲突的文件 并寻找冲突标记：

   复制

   <<<<<<< HEAD
   Your current branch changes
   =======
   Incoming changes from the branch being merged
   >>>>>>> branch-name
   

3. 解决冲突 通过：

   • 决定保留哪些更改（来自分支或组合）
   • 删除冲突标记-(<<<<<<<, =======, >>>>>>>)
   • 确保最终内容正确有效。
   • 测试更改以确保一切按预期运行

4. 将文件标记为已解决 通过将其添加到staging中：

   复制

   git add <filename>
   

5. 完成合并 带有描述性提交消息：

   复制

   git commit -m "Resolve merge conflict in <filename>"
   

   如果你使用Git的默认合并提交消息，你可以简单地使用：

   复制

   git commit
   

   这将打开默认编辑器，其中包含一条预填充的提交消息，您可以在需要时对其进行修改。

快速开始

1. 克隆存储库:

   复制

   const result = await mcpClient.execute('git-mcp-server', 'git_clone', {
     repositoryUrl: 'https://github.com/username/repo.git',
     targetPath: '/path/to/clone/into'
   });
   

2. 进行更改并提交:

   复制

   // Stage changes
   await mcpClient.execute('git-mcp-server', 'git_add', {
     files: ['.'],
     path: '/path/to/repo'
   });
   
   // Create a commit
   await mcpClient.execute('git-mcp-server', 'git_commit', {
     message: 'feat: add new feature',
     path: '/path/to/repo'
   });
   

3. 推送更改:

   复制

   await mcpClient.execute('git-mcp-server', 'git_push', {
     path: '/path/to/repo',
     remote: 'origin',
     branch: 'main'
   });
   

如果手动运行（不通过MCP客户端）进行开发或测试

通过npm安装

npm install @cyanheads/git-mcp-server

或者从源代码安装（建议用于开发）

1. 克隆存储库：

   复制

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

2. 安装依赖项：

   复制

   npm install
   

3. 构建项目：

   复制

   npm run build
   # or npm run rebuild
   

配置

环境变量

使用环境变量配置服务器。这些环境变量在MCP客户端配置/设置中设置（例如。 claude_desktop_config.json 克劳德桌面）

项目结构

代码库遵循模块化结构 src/ 目录：

src/
├── index.ts           # Entry point: Initializes and starts the server
├── config/            # Configuration loading (env vars, package info)
│   └── index.ts
├── mcp-server/        # Core MCP server logic and capability registration
│   ├── server.ts      # Server setup, capability registration
│   ├── transports/    # Transport handling (stdio, http)
│   ├── resources/     # MCP Resource implementations (currently none)
│   └── tools/         # MCP Tool implementations (subdirs per tool)
├── types-global/      # Shared TypeScript type definitions
└── utils/             # Common utility functions (logger, error handler, etc.)

要查看详细的文件树，请运行 npm run tree 或查看 docs/tree.md.

工具

Git MCP服务器提供了一套与Git存储库交互的工具，可通过模型上下文协议调用。

注： path 如果通过设置，大多数工具的参数默认为会话的工作目录 git_set_working_dir.

资源

此版本（v2.1.4）中未实现MCP资源。

此版本侧重于基于最新版本重构的Git工具实现 mcp-ts-template 以及MCP SDK v1.13.0。在此重大更新期间，以前可用的资源功能已被临时删除。

如果您需要MCP资源访问权限（例如，直接通过服务器读取文件内容），请使用稳定的 v1.2.4版本发布.

未来的开发可能会在后续版本中重新引入资源功能。

发展

构建和测试

# Build the project (compile TS to JS in dist/ and make executable)
npm run build

# Test the server locally using the MCP inspector tool (stdio transport)
npm run inspector

# Test the server locally using the MCP inspector tool (http transport)
npm run inspector:http

# Clean build artifacts
npm run clean

# Generate a file tree representation for documentation
npm run tree

# Clean build artifacts and then rebuild the project
npm run rebuild

# Format code with Prettier
npm run format

# Start the server using stdio (default)
npm start
# Or explicitly:
npm run start:stdio

# Start the server using HTTP transport
npm run start:http

许可证

此项目根据Apache许可证2.0获得许可-请参阅 许可证 文件以获取详细信息。