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

# git-mcp-server

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

## 项目说明

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

## 快速开始

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

```bash
npm install
```

- 构建：

```bash
npm run build
```

- 运行（本地）：

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

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

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

## npm 安装与使用

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

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

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

```bash
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 客户端（推荐）：

```json
{
  "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`）

## 调用示例

- 提交更改：

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

- 查看状态：

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

- 生成架构文档：

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

## 依赖

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