# tencentcode-mcp

**Repository Path**: ynnyh/tencentcode-mcp

## Basic Information

- **Project Name**: tencentcode-mcp
- **Description**: 腾讯工蜂mcp
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-12-31
- **Last Updated**: 2026-05-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 腾讯工蜂, MCP, git-mcp

## README

# tencentcode-mcp

腾讯工蜂（Tencent Gongfeng）+ 本地 git 的 MCP Server。给 AI 助手（Claude/Cursor/Trae 等）一组工具，让它能够：

1. **生成日报/周报** — 扫描你本地所有 git 仓库，列出你某段时间内的提交。
2. **协助代码审查** — 取某次 commit 的完整 diff 给 AI 分析。
3. **操作工蜂仓库** — 浏览项目/分支/文件、看/建/合并 MR、搜索代码。

---

## 为什么"我的提交"走本地而不走工蜂 API

工蜂界面认识"哪些 commit 是你的"靠的是 push 事件里的 user_id + 账号绑定的多个邮箱列表。但工蜂 REST API 的 `/projects/:id/repository/commits` 只返回 commit 对象里写死的 `author_email`/`author_name`，**和用户账号没有直接绑定关系**。如果你历史上用过多个昵称/邮箱（如 `月魂`、公司邮箱、`xxx@qq.com`），任何单一 author 字段去 API 匹配都漏。

本地 `git log` 直接读你本地仓库，覆盖全部历史 + 包含**未推送**的提交，是日报场景最可靠的口径。

---

## 工具一览

### 本地 git（日报 / 代码审查）

| 工具 | 作用 |
|---|---|
| `list_my_local_commits` | 扫指定根目录下所有 git 仓库，列出你某时间段的提交 |
| `get_local_commit_diff` | 取本地某个 commit 的完整 patch（含文件统计），给 LLM 做 review |
| `list_all_recent_commits` | 列出**所有作者**在某时间段的提交，按作者分组（团队动态 / 谁改的） |

### 工蜂项目浏览

| 工具 | 作用 |
|---|---|
| `list_projects` | 列出项目（建议传 `membership: true` 只列你有权限的） |
| `get_project` | 项目详情 |
| `create_project` | 新建项目 |
| `list_branches` / `get_branch` / `create_branch` | 分支操作 |
| `list_commits` | 列出项目分支的提交（项目级，不按用户过滤） |
| `get_commit` | 单个 commit 详情 |
| `list_directory` | 列项目目录内容（支持 recursive） |
| `get_file_content` | 读文件内容（自动 base64 解码） |
| `search_code` | 在指定工蜂项目里搜代码关键词 |

### 合并请求

| 工具 | 作用 |
|---|---|
| `list_merge_requests` / `get_merge_request` | 列/看 MR |
| `get_mr_diff` | 取 MR 的完整文件级 diff（用于 LLM 审查同事的 MR） |
| `create_merge_request` / `accept_merge_request` | 建/合 MR |

### 用户

| 工具 | 作用 |
|---|---|
| `get_current_user` | 获取当前登录的工蜂用户信息 |

---

## 配置与运行

### 环境要求

- Node.js 18+
- 本地安装 git 并加入 PATH（本地工具依赖）
- 腾讯工蜂 Access Token（工蜂 API 工具依赖）

### 安装与构建

```bash
git clone <repo-url>
cd tencentcode-mcp
npm install
npm run build
```

### 环境变量

| 变量名 | 说明 |
|---|---|
| `TENCENT_CODE_ACCESS_TOKEN` | 工蜂 Personal Access Token（**必填**，仅当使用工蜂 API 工具时） |
| `TENCENT_CODE_PRIVATE_TOKEN` | `TENCENT_CODE_ACCESS_TOKEN` 的别名（兼容旧版） |
| `TENCENT_CODE_API_URL` | 工蜂 API 基地址，默认 `https://git.code.tencent.com/api/v3` |
| `TENCENT_CODE_LOCAL_ROOTS` | 本地仓库根目录默认值，分隔符 `;` 或 `,`，如 `D:/coding;D:/work`。设了之后调本地工具不用每次传 `rootDir` |

### 在 MCP 客户端配置

```json
{
  "mcpServers": {
    "tencentcode": {
      "command": "node",
      "args": ["D:/coding/my-mcp-servers/tencentcode-mcp/dist/index.js"],
      "env": {
        "TENCENT_CODE_ACCESS_TOKEN": "your-access-token",
        "TENCENT_CODE_LOCAL_ROOTS": "D:/coding"
      }
    }
  }
}
```

> 配了 `TENCENT_CODE_LOCAL_ROOTS` 后，本地工具调用就不用每次传 `rootDir` 了。

### 内置 Prompts（如客户端支持，会以 / 命令出现）

| 名称 | 用途 |
|---|---|
| `daily_report` | 一键生成今天的日报 |
| `weekly_report` | 一键生成本周的周报 |
| `review_my_commits` | 让 AI 审查你今天显著的代码改动 |

各模板都支持可选的 `rootDir` 参数；未传时用环境变量。

### MCP Inspector 调试

```bash
export TENCENT_CODE_ACCESS_TOKEN="your-token"
npm run build
npx @modelcontextprotocol/inspector@latest node dist/index.js
# 访问 http://localhost:6274
```

---

## 场景一：日报 / 周报

直接让 AI 调 `list_my_local_commits`：

```jsonc
// 今天（默认）
list_my_local_commits({ rootDir: "D:/coding" })

// 昨天
list_my_local_commits({ rootDir: "D:/coding", range: "yesterday" })

// 本周（周一至今）
list_my_local_commits({ rootDir: "D:/coding", range: "thisWeek" })

// 近 7 天，带完整 commit message body
list_my_local_commits({
  rootDir: "D:/coding",
  range: "last7days",
  includeBody: true
})
```

支持的 `range` 预设：`today`、`yesterday`、`thisWeek`、`lastWeek`、`last7days`、`last30days`、`thisMonth`。

也可以传 `since` / `until`（git 接受的任意时间格式）覆盖预设：

```jsonc
list_my_local_commits({
  rootDir: "D:/coding",
  since: "2026-05-01",
  until: "2026-05-31"
})
```

### 身份识别（多昵称场景）

不传 `author` 时，会自动用 `git config user.email` + `user.name` 两个身份去匹配。

如果你历史上用过别的邮箱/名字，用逗号分隔加进去：

```jsonc
list_my_local_commits({
  rootDir: "D:/coding",
  author: "me@qq.com,月魂,公司邮箱@company.com"
})
```

含 `@` 当邮箱用，不含的当姓名 regex。

### 提示词建议

> 帮我看下 `D:/coding` 下我**今天**的提交，按项目分组生成日报。语气简洁，每条一行，重点突出业务价值。

> 用 `list_my_local_commits` 取 `D:/coding` **本周**的提交（带 body），帮我整理成周报，分"已完成功能"和"已修复 bug"两类。

---

## 场景二：代码审查

两步：先列今天的提交，再针对感兴趣的 commit 取 diff。

```jsonc
// 第一步：列出今天的提交（带改动文件统计）
list_my_local_commits({
  rootDir: "D:/coding",
  includeStat: true
})

// 第二步：对某个 commit 拿完整 diff
get_local_commit_diff({
  repoPath: "D:/coding/your-project",
  sha: "8b98214"
})
```

`get_local_commit_diff` 返回结构：
```jsonc
{
  "sha": "...",
  "authorName": "...",
  "authoredDate": "...",
  "title": "...",
  "body": "...",
  "stat": {
    "filesChanged": 3,
    "insertions": 42,
    "deletions": 15,
    "files": [{ "path": "...", "insertions": 10, "deletions": 5 }]
  },
  "patch": "diff --git a/... ..."   // 完整 patch
}
```

### 提示词建议

> 用 `list_my_local_commits` 看 `D:/coding/foo` 项目今天我的提交（includeStat: true），挑出改动量大的 commit 用 `get_local_commit_diff` 看 diff，给我做 review，指出潜在 bug 和可以改进的地方。

---

## 场景三：工蜂仓库操作

让 AI 用工蜂 API 浏览/操作：

```jsonc
// 看我有权限的项目
list_projects({ membership: true, perPage: 50 })

// 看某项目最近的 commit
list_commits({ projectId: "219628", branch: "main", perPage: 10 })

// 读某文件
get_file_content({ projectId: "219628", filePath: "src/index.ts" })

// 项目内搜代码
search_code({ projectId: "219628", keyword: "function login" })

// 看开放中的 MR
list_merge_requests({ projectId: "219628", state: "opened" })
```

---

## 常见问题

### 1. `list_my_local_commits` 报"未找到 git"

检查 git 是否在 PATH 中：

```bash
git --version
```

Windows 上 Git for Windows 安装后通常会自动加 PATH；如果没有，重启终端或重新登录。

### 2. 找不到我自己的提交

先看返回里 `authors` 字段是哪些。如果跟你实际 commit author 不符，手动传：

```jsonc
list_my_local_commits({
  rootDir: "D:/coding",
  author: "你历史用过的所有邮箱,所有昵称"
})
```

或退而求其次用最宽松的 `match: "any"`：

```jsonc
list_my_local_commits({
  rootDir: "D:/coding",
  match: "any",
  author: "你的关键词1,关键词2"
})
```

会同时按 author 和 committer 子串匹配。

### 3. 提交对象的 author 和 committer 啥区别

- **author**：写代码的人（commit 时根据本地 git config 写入，一辈子不变）
- **committer**：最后落盘的人（rebase / cherry-pick / amend 时会刷成你）
- 默认 `match: "author"` 适合"看我写了啥"
- `match: "committer"` 适合"看我做了哪些 rebase/合并动作"
- `match: "any"` 任一命中

### 4. 工蜂 API 401/403

检查 Token 是否过期，登录工蜂网页 → 用户设置 → Access Tokens 重新生成。

### 5. MCP 服务启动后立刻退出

99% 是没设 `TENCENT_CODE_ACCESS_TOKEN`。验证：

```bash
echo $TENCENT_CODE_ACCESS_TOKEN
```

---

## 项目结构

```
tencentcode-mcp/
├── src/
│   ├── index.ts              # MCP 服务入口 + 工具定义/分发
│   ├── local-git.ts          # 本地 git 扫描相关（findGitRepos / getLocalCommits / getCommitDiff / 时间预设）
│   ├── types.ts              # 公共类型
│   └── client/
│       └── tencent-code.ts   # 工蜂 REST API 客户端
├── dist/                     # tsc 编译输出
├── package.json
├── tsconfig.json
└── README.md
```

---

## 开发

```bash
npm run build       # 编译
npm test            # 跑单元测试（vitest，覆盖 local-git 模块）
npm run test:watch  # 测试 watch 模式
npm run dev         # ts-node 直接跑（不走 dist）
```

调试时建议用 MCP Inspector，可视化看每个工具的入参/出参。

---

## 许可证

MIT