git-mcp-server

一个基于 Model Context Protocol (MCP) 的 Git 助手服务器。通过标准输入/输出传输提供一组 Git 与项目文档相关的工具，便于智能体或自动化流程进行仓库操作、文档生成与代码分析。

项目说明

• 目标：以 MCP 工具集形式对 Git 常用操作、文档与度量进行封装，支持在 IDE/代理中无缝调用。
• 特性：
  • Git 仓库全流程操作：初始化、克隆、提交、推送、分支管理、合并/变基、冲突处理
  • 文档生成：架构文档、软著代码文档（DOCX/PDF）、提交日志、版本文件
  • 代码度量：统计代码行数，支持输出按文件明细
  • 目录结构扫描：按深度生成树状结构
  • MCP 标准：使用 @modelcontextprotocol/sdk 以 stdio 作为传输层集成到各类 MCP 客户端

快速开始

• 环境：Node.js 18+（建议）
• 安装依赖：

npm install

• 构建：

npm run build

• 运行（本地）：

node dist/index.js
# 或（构建脚本已赋予可执行权限）
./dist/index.js

• 作为 MCP 服务器集成（示例 mcp.config.json）：

{
  "mcpServers": {
    "git-mcp-server": {
      "transport": "stdio",
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": ".",
      "env": { "MCP_SERVER_NAME": "git-mcp-server" }
    }
  }
}

npm 安装与使用

• 全局安装（推荐，用作系统 CLI/MCP 服务器）：

npm i -g @maogo/git-mcp-server
# 启动 MCP 服务器
git-mcp-server

• 项目内安装（结合 npx 或直接 Node 调用）：

npm i @maogo/git-mcp-server --save
# 通过 npx 使用该包的可执行文件
npx -p @maogo/git-mcp-server git-mcp-server
# 或直接调用入口脚本
node node_modules/@maogo/git-mcp-server/dist/index.js

• 使用全局可执行文件配置 MCP 客户端（推荐）：

{
  "mcpServers": {
    "git-mcp-server": {
      "transport": "stdio",
      "command": "git-mcp-server",
      "args": [],
      "env": { "MCP_SERVER_NAME": "git-mcp-server" }
    }
  }
}

技术架构

• 服务器初始化与连接：
  • src/index.ts:27 创建 McpServer
  • src/index.ts:602-603 使用 StdioServerTransport 连接
• 工具注册入口：在 src/index.ts 中统一通过 server.registerTool(...) 注册 Git/文档/度量工具
• Git 封装与解析：
  • execGit、spawnGit、getCurrentBranch、parseStatus 位于 src/lib/git.ts:7、src/lib/git.ts:18、src/lib/git.ts:34、src/lib/git.ts:40
• 文档与度量：
  • 架构文档/代码文档/软著文档/代码行统计位于 src/lib/docs.ts:79、src/lib/docs.ts:128、src/lib/docs.ts:251、src/lib/docs.ts:150
• 目录树构建：
  • src/lib/tree.ts:6，支持最大深度和隐藏文件过滤
• TypeScript 配置：
  • tsconfig.json 使用 NodeNext 模块系统与严格类型校验

目录结构

src/
  index.ts
  lib/
    git.ts
    docs.ts
    tree.ts
dist/
docs/
mcp.config.json
package.json
tsconfig.json

API 使用说明

所有工具以名称+参数的形式调用，返回统一 JSON。常见返回字段：

• ok: 布尔值，表示操作是否成功
• stdout/stderr: 进程输出（针对原生命令类工具）
• status/conflicts/payload/path 等：结构化结果

仓库操作

• git_init（初始化仓库）参数：cwd，defaultBranch?（src/index.ts:45-61）
• git_clone（克隆远程仓库）参数：repoUrl，dest，branch?，depth?（src/index.ts:63-80）
• git_status（查看仓库状态）参数：cwd，返回：branch/ahead/behind/files[]（src/index.ts:82-97）
• git_pull（拉取远程更新）参数：cwd，remote?，branch?（src/index.ts:99-114）
• git_commit（提交更改）参数：cwd，message，addAll?，authorName?，authorEmail?（src/index.ts:116-135）
• git_push_branch（推送分支）参数：cwd，remote?，branch?，setUpstream?（src/index.ts:204-221）
• git_branch_create（创建分支）（src/index.ts:153-169）
• git_branch_checkout（切换分支）（src/index.ts:171-185）
• git_branch_delete（删除分支）（src/index.ts:187-201）
• git_merge（合并分支）（src/index.ts:259-277）
• git_reset（重置到指定提交）（src/index.ts:242-257）
• git_revert（回滚指定提交）（src/index.ts:223-241）
• git_commit_log（生成提交日志到文件）（src/index.ts:404-426）
• git_version_file（生成版本文件）（src/index.ts:428-471）
• git_remote_set_url（修改远程地址）（src/index.ts:473-497）
• git_auth_config（配置用户名/邮箱/凭据助手）（src/index.ts:499-518）
• git_auth_credential_approve（保存针对 URL 的凭据）（src/index.ts:520-543）

冲突处理

• git_conflicts_list（列出当前冲突文件）（src/index.ts:279-296）
• git_conflict_use_ours（采用 ours 版本）（src/index.ts:298-317）
• git_conflict_use_theirs（采用 theirs 版本）（src/index.ts:319-338）
• git_merge_continue / git_merge_abort（src/index.ts:340-370）
• git_rebase_continue / git_rebase_abort（src/index.ts:372-399）

文档与度量

• doc_arch_generate（生成项目架构文档），默认输出 docs/ARCHITECTURE.md（src/index.ts:545-560）
• doc_code_generate（生成软著代码文档），默认输出 docs/SOFT_CODE.docx 或 docs/SOFT_CODE.pdf（src/index.ts:562-578）
• code_lines_count（统计代码行数），可选输出 docs/CODE_LINES.json（src/index.ts:580-600）

调用示例

• 提交更改：

{
  "name": "git_commit",
  "arguments": {
    "cwd": "/path/to/repo",
    "message": "feat: update docs",
    "addAll": true
  }
}

• 查看状态：

{
  "name": "git_status",
  "arguments": { "cwd": "/path/to/repo" }
}

• 生成架构文档：

{
  "name": "doc_arch_generate",
  "arguments": {
    "cwd": ".",
    "output": "docs/ARCHITECTURE.md",
    "maxDepth": 3,
    "includeHidden": false
  }
}

依赖

• 运行时：@modelcontextprotocol/sdk、zod、pdfkit
• 开发：typescript、@types/node