内容
# mcp-github-issues
MCP（模型上下文协议）服务器，允许 AI 助手跨多个项目管理 GitHub 问题 —— 无需离开聊天。
您用日常语言描述一个任务，AI 发布它为 GitHub 问题，在您确认后 —— 没有静默 API 调用，没有中间文件。
---
## 工作原理
```bash
AI 助手
│
├─ list_issues ─────────► 显示仓库中开放的问题
│
├─ fetch_issue ─────────► 读取完整的问题上下文（正文 + 评论）
│
├─ publish_issue ───────► github.com/your-org/your-repo/issues/42 （仅在您确认后）
│
├─ add_comment ─────────► 在现有问题上发布评论
│
└─ update_issue ────────► 更改状态、标题、指派人或标签
```
1. 您用日常语言向 AI 助手描述一个任务。
2. AI 提出问题内容（标题、上下文、文件、检查清单）。
3. 您确认 —— AI 调用 `publish_issue`，问题通过 GitHub API 创建。
---
## 需求
- **Node.js** 18+
- **Claude Code CLI** — `npm install -g @anthropic-ai/claude-code`
- GitHub [个人访问令牌](https://github.com/settings/tokens)，具有 `repo` 作用域
---
## 快速开始
```bash
git clone https://github.com/prog-time/mcp-github-issues.git
cd mcp-github-issues
cp .env.example .env
# 编辑 .env — 添加您的 GitHub 令牌
cp projects.yaml.example projects.yaml
# 编辑 projects.yaml — 添加您的项目
./mcp.sh setup
```
`mcp.sh setup` 一步安装依赖并使用 Claude Code 注册 MCP 服务器。
---
## 配置
### 1. GitHub 令牌 —— `.env`
在项目根目录创建 `.env`（gitignored）：
```env
GITHUB_TOKEN_MYPROJECT=ghp_xxxxxxxxxxxxxxxxxxxx
```
每个项目可以使用单独的令牌，允许在个人和组织仓库之间具有不同的权限范围。
要生成令牌：**GitHub → 设置 → 开发者设置 → 个人访问令牌 → 精细令牌** （或使用 `repo` 作用域的经典令牌）。
### 2. 项目 —— `projects.yaml`
```yaml
projects:
myproject:
owner: your-org # GitHub 组织或用户名
repo: your-repo # 仓库名称
tokenEnv: GITHUB_TOKEN_MYPROJECT # 必须与 .env 中的键匹配
```
多个项目：
```yaml
projects:
api:
owner: acme-corp
repo: backend-api
tokenEnv: GITHUB_TOKEN_API
web:
owner: acme-corp
repo: frontend
tokenEnv: GITHUB_TOKEN_WEB
oss:
owner: your-username
repo: open-source-lib
tokenEnv: GITHUB_TOKEN_OSS
```
启动时使用 Zod 验证配置 —— 缺少或空字段会立即报告并显示清晰的错误消息。
---
## 安装
### 自动（推荐）
```bash
./mcp.sh setup
```
以 `mcp-github-issues` 为名称注册服务器，具有用户级作用域（在所有项目中可见）：
```
=== mcp-github-issues MCP 安装 ===
服务器名称 : mcp-github-issues
作用域 : user
目录 : /path/to/mcp-github-issues
[1/3] 安装依赖... 完成。
[2/3] 使用 Claude CLI 注册 MCP 服务器... 已注册 'mcp-github-issues' （作用域：user）。
[3/3] 验证...
mcp-github-issues: /path/to/mcp.sh - ✓ 已连接
=== 安装完成！ ===
```
自定义服务器名称或作用域：
```bash
./mcp.sh setup my-server # 自定义名称，用户作用域
./mcp.sh setup my-server local # 本地作用域（仅当前项目）
./mcp.sh setup my-server project # 项目作用域（.mcp.json）
```
### 手动
```bash
npm install
claude mcp add -s user -- mcp-github-issues /absolute/path/to/mcp-github-issues/mcp.sh
```
---
## MCP 客户端配置
### Claude Code（CLI / IDE 插件）
运行 `./mcp.sh setup` 后，服务器会自动注册。验证：
```bash
claude mcp list
# mcp-github-issues: /path/to/mcp.sh - ✓ 已连接
```
### Claude Desktop（macOS / Windows）
添加到 `~/Library/Application Support/Claude/claude_desktop_config.json` （macOS）或 `%APPDATA%\Claude\claude_desktop_config.json` （Windows）：
```json
{
"mcpServers": {
"mcp-github-issues": {
"command": "/absolute/path/to/mcp-github-issues/mcp.sh",
"env": {}
}
}
}
```
令牌由 `mcp.sh` 从 `.env` 加载 —— 无需在桌面配置中重复。编辑配置后重启 Claude Desktop。
---
## 可用工具
### `list_projects`
列出 `projects.yaml` 中定义的所有项目。
**无需输入。**
---
### `list_issues`
列出项目的 GitHub 问题，可选过滤器。
| 参数 | 类型 | 必需 | 描述 |
|-----------|----------|----------|-------------------------------------------------|
| `project` | `string` | 是 | `projects.yaml` 中的项目名称 |
| `state` | `string` | 否 | `open` \| `closed` \| `all` （默认：`open`） |
| `label` | `string` | 否 | 按标签名称过滤 |
| `assignee` | `string` | 否 | 按指派人用户名过滤 |
| `limit` | `number` | 否 | 返回最大结果数，1–100（默认：`30`） |
---
### `fetch_issue`
按编号或 URL 获取 GitHub 问题并返回其完整上下文（描述、标签、指派人、评论）。
| 参数 | 类型 | 必需 | 描述 |
|----------------|-----------|----------|-------------------------------------------------|
| `project` | `string` | 是 | `projects.yaml` 中的项目名称 |
| `issue` | `string` | 是 | 问题编号（例如 `123`）或完整的 GitHub 问题 URL |
| `include_comments` | `boolean` | 否 | 是否获取评论（默认：`true`） |
| `comment_limit` | `number` | 否 | 获取的最大评论数，1–100（默认：`50`） |
---
### `publish_issue`
直接创建新的 GitHub 问题，具有结构化上下文。仅在用户审查并确认内容后调用此工具。
| 参数 | 类型 | 必需 | 描述 |
|------------|------------|----------|-------------------------------------------------|
| `project` | `string` | 是 | `projects.yaml` 中的项目名称 |
| `title` | `string` | 是 | 问题标题（无类型前缀） |
| `context` | `string` | 是 | 描述 / 背景 |
| `files` | `string[]` | 否 | 受影响的文件路径 |
| `checklist` | `string[]` | 否 | 检查清单项目 |
| `assignee` | `string` | 否 | GitHub 用户名指派 |
| `type` | `string` | 否 | `bug` \| `feature` \| `task` （默认：`task`） |
**发布时发生的情况：
- **标题** —— 以类型标签前缀： `[BUG] Fix ...`， `[FEATURE] Add ...`， `[TASK] Refactor ...`
- **标签** —— 根据类型自动应用：
- `bug` → `bug`
- `feature` → `enhancement`
- `task` → `task`
- **正文** —— 从 `context`、`files` 和 `checklist` 生成，并带有“MCP 生成”的徽章
示例正文：
```markdown
> [!NOTE]
> 该任务由 MCP 服务器 —— prog-time/mcp-github-issues 生成
**类型**: bug
**指派人**: @johndoe
## 上下文
OAuth 回调后，用户被重定向回 /login 而不是仪表盘。
## 受影响的文件
- `src/auth/callback.ts`
- `src/middleware/session.ts`
## 检查清单
- [ ] 在本地重现问题
- [ ] 检查会话令牌过期逻辑
- [ ] 添加 OAuth 流的集成测试
```
---
### `add_comment`
向现有的 GitHub 问题添加评论。
| 参数 | 类型 | 必需 | 描述 |
|----------|----------|----------|-------------------------------------------------|
| `project` | `string` | 是 | `projects.yaml` 中的项目名称 |
| `issue` | `string` | 是 | 问题编号（例如 `123`）或完整的 GitHub 问题 URL |
| `body` | `string` | 是 | 评论文本（支持 Markdown） |
---
### `update_issue`
更新现有的 GitHub 问题：更改状态、标题、指派人或标签。
| 参数 | 类型 | 必需 | 描述 |
|---------------|------------|----------|-------------------------------------------------|
| `project` | `string` | 是 | `projects.yaml` 中的项目名称 |
| `issue` | `string` | 是 | 问题编号或完整的 GitHub 问题 URL |
| `state` | `string` | 否 | `open` \| `closed` |
| `title` | `string` | 否 | 新标题 |
| `assignee` | `string\|null` | 否 | 设置指派人用户名，或 `null` 删除所有指派 |
| `add_labels` | `string[]` | 否 | 添加标签 |
| `remove_labels`| `string[]` | 否 | 删除标签 |
---
### `create_pull_request`
为配置的项目创建新的 GitHub 拉取请求。
| 参数 | 类型 | 必需 | 描述 |
|-------------------------|-----------|----------|-------------------------------------------------------------------------------------|
| `project` | `string` | 是 | `projects.yaml` 中的项目名称 |
| `title` | `string` | 是 | 拉取请求标题 |
| `head` | `string` | 是 | 具有更改的分支（例如 `feature/my-feature` 或 `fork-owner:branch`） |
| `base` | `string` | 否 | 合并到的目标分支（默认：`main`） |
| `body` | `string` | 否 | 拉取请求描述（原始 Markdown） |
| `draft` | `boolean` | 否 | 创建为草稿拉取请求（默认：`false`） |
| `maintainer_can_modify` | `boolean` | 否 | 允许维护者编辑拉取请求头分支（仅适用于跨仓库拉取请求） |
返回拉取请求编号和 `html_url`。
---
## 典型对话
```
您： 在项目“api”中，创建一个任务：登录页面在 OAuth 后有重定向循环。
受影响的文件：src/auth/callback.ts。添加一个修复的检查清单。
AI： 这是提出的 issue：
标题：修复 OAuth 后登录重定向循环
类型：bug
上下文：...
文件：src/auth/callback.ts
检查清单：重现，检查会话过期逻辑，添加测试
是否发布？
您： 是的，发布并指派给 johndoe。
AI： 问题 #42 已创建：https://github.com/acme-corp/backend-api/issues/42
您： 关闭问题 #38 —— 它已经在上次发布中修复了。
AI： 问题 #38 已更新。状态 → closed。
```
---
## 项目结构
```
mcp-github-issues/
├── src/
│ ├── server.ts # MCP 服务器入口点
│ ├── config.ts # 加载并验证 projects.yaml，Octokit 缓存
│ ├── router.ts # 注册所有工具
│ ├── logger.ts # 文件 + stderr 日志记录器
│ └── tools/
│ ├── listProjects.ts
│ ├── listIssues.ts
│ ├── fetchIssue.ts
│ ├── publish.ts
│ ├── addComment.ts
│ ├── updateIssue.ts
│ └── createPullRequest.ts
├── tests/
│ └── src/
│ ├── config.test.ts
│ ├── router.test.ts
│ └── tools/
│ ├── fetchIssue.test.ts
│ ├── listProjects.test.ts
│ ├── listIssues.test.ts
│ ├── addComment.test.ts
│ ├── updateIssue.test.ts
│ └── publish.test.ts
├── logs/
│ └── server.log # 服务器日志（自动创建）
├── projects.yaml # 项目定义
├── projects.yaml.example # 模板
├── .env # GitHub 令牌（gitignored）
├── .env.example # 模板
├── mcp.sh # 服务器启动器 + 安装脚本
├── vitest.config.ts
├── package.json
└── tsconfig.json
```
---
## 日志
服务器同时将日志写入两个位置：
| 目的地 | 目的 |
|-------------------|-------------------------------------------------|
| `logs/server.log` | 持久文件日志，可读 |
| `stderr` | 由 Claude Desktop 捕获到其 `mcp-*.log` |
```bash
tail -f logs/server.log
```
Claude Desktop 日志位置（macOS）：
```
~/Library/Logs/Claude/mcp-server-mcp-github-issues.log
```
---
## 更新
```bash
git pull
./mcp.sh setup # 重新安装依赖并注册服务器
```
---
## 贡献
1. 分叉仓库
2. 创建分支：`git checkout -b feature/my-feature`
3. 进行更改并添加测试
4. 打开拉取请求
```bash
npm run dev # 开发模式（tsx 监视）
npm test # 运行测试一次
npm run test:watch # 监视模式
npx tsc --noEmit # 类型检查
npx eslint . # 校验
npm run build # 编译到 dist/
```
CI 在每次推送和拉取请求到 `main` 时运行 ESLint、类型检查和完整测试套件。
---
## 许可证
MIT
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器