内容
# @dangtdn/gitagent-mcp-server
🚀 **GitAgent 管理服务器** - 将您的 GitHub 仓库连接到 AI 编辑器，如 Cursor、VS Code、Claude Desktop、Antigravity 等。
[](https://www.npmjs.com/package/@dangtdn/gitagent-mcp-server)
[](https://opensource.org/licenses/MIT)
## 🎯 为什么选择 GitAgent MCP？
与官方 GitHub MCP 服务器相比，**GitAgent MCP** 是一个基于原生 Node.js 的、功能丰富的替代方案，专为高级开发工作流和自动化项目管理而设计。
### 🌟 主要亮点和优势
* 🚀 **丰富的工具集（45 个工具）**：涵盖从仓库管理、问题、拉取请求、提交、分支、发布、GitHub Actions 工作流到项目 v2 的所有内容。*（官方服务器仅有 26 个工具）*。
* 📦 **无需 Docker**：使用标准的 Node.js/NPM 在 Windows、macOS 或 Linux 上原生运行。适用于轻量级 IDE 环境，不需要或无法运行 Docker。
* 🗂️ **GitHub 项目 v2 集成**：唯一提供对 GitHub 项目 v2 自定义字段（状态、优先级、大小、估计、日期等）完全读写访问的 MCP 服务器。
* ⚙️ **CI/CD 和发布自动化**：直接列出工作流、触发 GitHub Actions 管道，并通过 AI 命令管理发布。
* ⏱️ **开发分析**：从拉取请求中检索提交，并链接开发信息以分析问题解决时间和开发者活动。
### 👥 适用人群
* **开发者**：希望 AI 编码助手（如 Cursor、VS Code、Claude Desktop、Antigravity）执行直接 Git 操作（分支、文件差异、创建拉取请求、读取内容），而无需离开编辑器。
* **技术负责人和项目经理**：希望通过提示 AI 助手直接自动化问题跟踪、状态更新或生成发布说明。
* **DevOps 工程师**：希望从聊天界面检查管道状态或触发部署。
### ❓ 何时使用？
* **使用 GitAgent MCP 如果**：
* 您需要与 **GitHub 项目 v2** 或 **GitHub Actions** 集成。
* 您想要一个 **轻量级、原生 Node.js** 设置，而无需安装 Docker Desktop。
* 您想要深入的开发进度分析（链接的拉取请求、提交统计）。
* **使用官方 GitHub MCP 如果**：
* 您需要执行大量文件提交（`push_files`）。
* 您需要全局搜索 GitHub 用户（`search_users`）。
## 🌟 功能
- ✅ **完整的 GitHub 集成** - 问题、拉取请求、分支、提交、文件
- ✅ **项目 v2 字段** - 访问 GitHub 项目字段（状态、优先级、大小等）
- ✅ **写入操作** - 创建问题、拉取请求、评论、合并拉取请求
- ✅ **私有仓库** - 使用您自己的令牌访问私有仓库
- ✅ **多种传输方式** - Stdio（用于编辑器）和 HTTP（用于 Web 应用程序）
## 📦 安装
### 选项 1：按需执行（推荐）
您可以使用 `npx` 直接运行服务器，而无需全局安装。这保证您始终运行最新版本：
```json
{
"mcpServers": {
"gitagent": {
"command": "npx",
"args": ["-y", "@dangtdn/gitagent-mcp-server"],
"env": {
"GITHUB_TOKEN": "ghp_your_github_token_here"
}
}
}
}
```
### 选项 2：全局安装
如果您更喜欢在系统上全局安装：
```bash
npm install -g @dangtdn/gitagent-mcp-server
```
#### 在编辑器中配置：
```json
{
"mcpServers": {
"gitagent": {
"command": "gitagent-mcp",
"args": [],
"env": {
"GITHUB_TOKEN": "ghp_your_github_token_here"
}
}
}
}
```
> 💡 **提示（更新）：** 要将全局安装更新到最新版本，请运行：
>
> ```bash
> npm install -g @dangtdn/gitagent-mcp-server@latest
> ```
### 选项 3：本地安装（克隆和构建）
如果您更喜欢从克隆目录运行：
1. **克隆仓库：**
```bash
git clone https://github.com/dangtdn/gitagent-mcp.git
cd gitagent-mcp
```
2. **安装依赖项：**
```bash
npm install
```
3. **构建项目：**
```bash
npm run build
```
4. **在编辑器中配置**（使用 `dist/index.js` 的绝对路径）：
```json
{
"mcpServers": {
"gitagent": {
"command": "node",
"args": ["C:/path/to/gitagent-mcp/dist/index.js"],
"env": {
"GITHUB_TOKEN": "ghp_your_github_token_here"
}
}
}
}
```
> **注意：** 将 `C:/path/to/gitagent-mcp` 替换为您的机器上克隆文件夹的实际路径。
## 🔧 配置
### 获取 GitHub 令牌
1. 前往 [GitHub 设置 → 开发者设置 → 个人访问令牌](https://github.com/settings/tokens)
2. 生成新的令牌（经典）
3. 选择作用域：`repo`、`read:user`、`read:org`
4. 复制令牌并在您的配置中使用
## 🛠️ 可用工具（44 个工具）
> 📖 **阅读详细使用指南：** [GUIDE.md](GUIDE.md)
### 读取操作（24 个工具）
| 工具 | 描述 |
| --------------------------------- | ------------------------------------------------------------------ |
| `list_repositories` | 列出所有可访问的仓库 |
| `get_repository` | 获取仓库的详细信息 |
| `list_issues` | 列出仓库中的问题，支持过滤（状态、指派人、标签） |
| `get_issue` | 获取特定问题的详细信息 |
| `list_issue_comments` | 列出问题或拉取请求上的所有评论 |
| `get_issue_comment` | 获取特定问题评论的详细信息 |
| `list_pull_requests` | 列出仓库中的拉取请求 |
| `get_pull_request` | 获取拉取请求的详细信息 |
| `get_pr_files` | 获取拉取请求中更改的文件列表 |
| `get_pr_reviews` | 获取拉取请求上的评论 |
| `get_pr_commits` | 获取拉取请求的所有提交，包含 SHA、消息、作者、日期 |
| `get_issue_linked_prs` | 获取问题开发部分链接的拉取请求 |
| `get_issue_development_info` | 获取链接的拉取请求及其提交，用于时间分析 |
| `list_branches` | 列出仓库中的分支 |
| `list_commits` | 列出仓库中的提交 |
| `get_file_content` | 获取仓库中文件的內容 |
| `search_code` | 在仓库中搜索代码 |
| `search_issues` | **新增** 跨仓库搜索问题和拉取请求 |
| `get_diff` | 比较两个提交/分支/标签并获取差异 |
| `list_releases` | 列出仓库中的发布 |
| `list_workflows` | 列出 GitHub Actions 工作流 |
| `list_issues_with_project_fields` | 列出带有 GitHub 项目 v2 字段（状态、优先级等）的问题 |
| `get_repository_projects` | **新增** 获取所有 GitHub 项目 v2 及字段和选项 |
| `get_issue_project_items` | **新增** 获取问题的项目条目及其字段值 |
### 写入操作（21 个工具）
| 工具 | 描述 |
| ----------------------------- | ------------------------------------------------------------------- |
| `create_issue` | 创建新问题 |
| `update_issue` | 更新问题（标题、正文、状态、标签、指派人） |
| `close_issue` | 关闭问题（已完成或未计划） |
| `add_issue_comment` | 添加问题评论 |
| `add_labels` | 为问题或拉取请求添加标签 |
| `remove_labels` | 从问题或拉取请求中删除标签 |
| `create_pull_request` | 创建新的拉取请求 |
| `update_pull_request` | 更新拉取请求（标题、正文、状态、基准分支） |
| `request_reviewers` | 为拉取请求请求审查者 |
| `merge_pull_request` | 合并拉取请求（合并、压缩、变基） |
| `create_branch` | 从现有分支/提交创建新分支 |
| `delete_branch` | 删除仓库中的分支 |
| `create_file` | 在仓库中创建新文件 |
| `update_file` | 更新仓库中的现有文件 |
| `delete_file` | 从仓库中删除文件 |
| `create_release` | 创建带有标签的新发布 |
| `trigger_workflow` | 触发 GitHub Actions 工作流运行 |
| `update_project_item_field` | **新增** 更新项目 v2 中的单选字段（状态、优先级） |
| `update_project_item_number` | **新增** 更新项目 v2 中的数字字段（估计） |
| `update_project_item_date` | **新增** 更新项目 v2 中的日期字段（开始日期、目标日期） |
| `update_issue_project_status` | **新增** ⭐ 便捷工具，更新问题在项目中的状态 |
## 💡 使用示例
连接 AI 编辑器后，您可以使用自然语言：
```
列出我的-org/my-repo 中的所有打开问题
创建标题为“修复登录错误”的问题，标签为“错误”
获取指派给 @username 且状态为“进行中”的问题
使用压缩方法合并拉取请求 #42
```
## 📚 API 参考
### list_issues_with_project_fields
获取带有 GitHub 项目 v2 字段值的问题：
```typescript
{
owner: string, // 仓库所有者
repo: string, // 仓库名称
assignee: string, // 按指派人用户名过滤
projectStatus?: string, // 按项目状态过滤（例如，“进行中”）
first?: number // 获取问题数量（默认：50）
}
```
**示例响应：**
```json
{
"total": 1,
"filter": { "assignee": "John", "projectStatus": "In Progress" },
"issues": [
{
"number": 949,
"title": "Universal Search - Handling No Results",
"assignees": ["John"],
"projectFields": {
"Project-1": {
"Status": "In Progress",
"Priority": "P1",
"Size": "L",
"Stack": "FE"
}
}
}
]
}
```
## 🔐 安全
- 您的 GitHub 令牌 **从未存储** 在我们的服务器上
- 令牌通过环境变量传递
- 所有请求直接发送到 GitHub API
- 支持私有仓库
## 📄 许可证
MIT 许可证 - 参见 [LICENSE](LICENSE) 了解详情。
## 🤝 贡献
欢迎贡献！请随时提交拉取请求。
