内容
# 工具列表
**开发工作流 MCP 中心** — 通过[模型上下文协议](https://modelcontextprotocol.io)连接 AI 编码代理与 Jira、GitHub 等。
一个 MCP 服务器，暴露开发工具链操作（Jira 问题管理、GitHub PR 搜索等）作为 MCP 工具、资源和提示，供 AI 编码代理使用。AI IDE 和编码助手通过 MCP 协议自动发现和使用这些工具 — 无需手动 CLI 命令或上下文切换。
## 架构
```
┌─────────────────────────────────────────────────────┐
│ MCP 传输层（stdio） │
│ ┌─────────────────────────────────────────────────┐ │
│ │ MCP 服务器 │ │
│ │ （中心调度） │ │
│ └──────┬─────────────────────────────┬────────────┘ │
│ │ │ │
│ ┌──────┴──────┐ ┌─────────┴──────────┐ ┌─────────┴──────────┐ │
│ │ Jira 模块 │ │ GitHub 模块 │ │ Figma 模块 │ │
│ │ 8 个工具 │ │ 8 个工具 │ │ 8 个工具 │ │
│ │ 3 个资源 │ │ 1 个资源 │ │ │ │
│ │ 2 个提示 │ │ │ │ │ │
│ └──────┬──────┘ └─────────┬──────────┘ └─────────┬──────────┘ │
│ │ │ │
│ ┌──────┴─────────────────────────────┴──────────┐ │
│ │ 服务层：src/services/ │ │
│ │ JiraClient │ GitHubClient │ slim │ config │ │
│ └─────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
```
服务器被组织为一个**基于模块的集成中心**。每个外部工具（Jira、GitHub 等）都是一个自包含的集成模块，只有在其所需的环境变量存在时才会注册其功能。**内置的 `mcp_get_health` 工具**始终已注册。
有关完整的架构分解，请参见 [`docs/plans/01-jira-cli-mcp-server.md`](docs/plans/01-jira-cli-mcp-server.md)。
## 快速入门
```bash
cd toolkit-mcp
cp .env.example .env
npm install
npm run mcp # 启动 MCP 服务器（stdio）
```
服务器启动时带有 stdio 传输，准备好接受 MCP 客户端连接。根据您的 `.env` 值，有条件地注册工具 — 请参阅[配置](#配置)。
## 配置
所有变量均为可选 — 仅当存在所需的环境变量时，工具才会注册。
| 变量 | 集成 | 必需 |
|---|---|---|
| `JIRA_BASE_URL` + `JIRA_EMAIL` + `JIRA_TOKEN` | Jira | 所有 Jira 工具、资源和提示 |
| `GH_TOKEN` | GitHub | 所有 7 个 GitHub 工具和 `github://prs/{issueKey}` 资源 |
| `GH_REPOS` | GitHub | GitHub 搜索的逗号分隔仓库列表（默认：`TransActComm/TravelTracker,TransActComm/Portage-backend,TransActComm/Portage-frontend`） |
| `FIGMA_TOKEN` | Figma | 所有 Figma 工具 |
| `MCP_TRANSPORT` | 服务器 | 传输模式：`stdio`（默认）或 `http` |
| `MCP_PORT` | 服务器 | HTTP 端口（默认 `3000`，仅在 `http` 传输中使用） |
| `MCP_LOG_LEVEL` | 服务器 | 日志详细程度：`silent`、`info`（默认）或 `debug` |
完整的 `.env.example` 在项目根目录中。如果没有设置集成环境变量，服务器将仅使用 `mcp_get_health` 工具启动 — 优雅降级。
## 工具
共 24 个工具（23 个有条件 + 1 个内置始终注册）。
### Jira 工具（在设置 `JIRA_BASE_URL` + `JIRA_EMAIL` + `JIRA_TOKEN` 时注册）
| 工具 | 描述 | 关键参数 |
|---|---|---|
| `jira_whoami` | 返回身份验证的 Jira 用户配置文件。 | *(无)* |
| `jira_get_issues` | 获取一个或多个 Jira 问题。传递 `key` 获取单个问题，或传递 `jql` 进行搜索。 | `key`, `jql`, `limit`, `cursor`, `fields` |
| `jira_create_issue` | 在项目中创建新的 Jira 问题。 | `projectKey`, `issueType`, `summary`, `description`, `fields` |
| `jira_update_issue` | 更新现有 Jira 问题上的字段。 | `key`, `fields` |
| `jira_transition_issue` | 将 Jira 问题转换为新状态。 | `key`, `transitionId` 或 `transitionName`, `comment` |
| `jira_assign_issue` | 将 Jira 问题分配给用户或取消分配。 | `key`, `assignee`（accountId, "me", 或 "none"） |
| `jira_add_comment` | 向 Jira 问题添加评论。 | `key`, `body` |
| `jira_link_issues` | 将两个 Jira 问题链接在一起。 | `inwardKey`, `outwardKey`, `type`, `comment` |
### GitHub 工具（在设置 `GH_TOKEN` 时注册）
| 工具 | 描述 | 关键参数 |
|---|---|---|
| `github_get_prs` | 查找一个或多个问题键的拉取请求。支持标题/正文搜索和可选的分支名称匹配。 | `issueKey`, `keys`, `state`, `limit`, `cursor`, `searchBranches` |
| `github_create_pr` | 在 GitHub 上创建拉取请求。 | `repo`, `title`, `head`, `base`, `body`, `draft` |
| `github_list_branches` | 列出仓库的分支。 | `repo`, `limit`, `cursor` |
| `github_get_pr_details` | 获取完整的 PR 详细信息（正文、更改的文件、增加/删除、合并状态、基准/头部分支）通过仓库 + PR 编号。 | `repo`, `prNumber` |
| `github_get_pr_reviews` | 获取 PR 审查评论和审查线程摘要。 | `repo`, `prNumber` |
| `github_get_pr_checks` | 获取 PR 状态检查 / CI 结果（PR 最新提交的检查运行）。 | `repo`, `prNumber` |
| `github_search_prs` | 按作者、仓库、状态或自由文本查询灵活搜索 PR。提供至少一个 `query`、`author` 或 `repo`。 | `query`, `author`, `repo`, `state`, `limit`, `cursor` |
### Figma 工具（在设置 `FIGMA_TOKEN` 时注册）
| 工具 | 描述 | 关键参数 |
|---|---|---|
| `figma_get_me` | 返回身份验证的 Figma 用户配置文件。 | *(无)* |
| `figma_get_file` | 获取 Figma 文件概述（名称、页面、最后修改）。 | `fileKey` |
| `figma_get_nodes` | 通过 ID 检查特定的节点/设计元素。 | `fileKey`, `ids` |
| `figma_get_images` | 导出帧为 PNG/SVG/PDF 图片 URL。 | `fileKey`, `ids`, `format`, `scale` |
| `figma_get_comments` | 读取文件上的设计评论。 | `fileKey` |
| `figma_get_styles` | 列出颜色、文本样式和效果。 | `fileKey` |
| `figma_get_variables` | 列出设计令牌和变量集合。 | `fileKey` |
| `figma_get_versions` | 列出文件的版本历史。 | `fileKey` |
### 内置（始终注册）
| 工具 | 描述 | 关键参数 |
|---|---|---|
| `mcp_get_health` | 报告哪些集成处于活动状态。 | *(无)* |
### 分页响应形状
所有列表样式工具返回一个统一的信封：
```json
{
"items": [],
"nextPageToken": "opaque-cursor-or-null",
"hasMore": true
}
```
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
| `cursor` | 字符串 | — | 来自先前响应的不透明分页令牌 |
| `limit` | 数字 | 20 | 每页项目数（最大 100） |
- `jira_get_issues` 始终使用 `key` 返回一个项目 `PaginatedResponse`，且 `hasMore: false` — 输入模式无关的统一形状。
- 没有工具自动获取所有页面；代理必须通过 `cursor` 显式分页。
## 资源
共 4 个资源（全部有条件）。
| URI | 模块 | 描述 | 返回 |
|---|---|---|---|
| `jira://issue/{key}` | Jira | 按键获取单个 Jira 问题 | JSON 中的 `SlimIssue` |
| `jira://search/{jql}` | Jira | JQL 查询的 Jira 搜索结果（URI 编码） | JSON 中的 `SlimIssue[]`（最大 20） |
| `jira://myself` | Jira | 当前身份验证的 Jira 用户配置文件 | JSON 中的 Jira 用户 |
| `github://prs/{issueKey}` | GitHub | 问题键的拉取请求 | JSON 中的 `PrInfo[]` |
`jira://search/{jql}` 中的 JQL 是 URI 编码的（例如，`jira://search/project%20%3D%20TRIPS`）。限制性关键词（DELETE、UPDATE、CREATE、INSERT、DROP、ALTER、EXEC、ADMIN）被拒绝以确保安全。
## 提示
共 2 个提示（均为 Jira 环境变量有条件）。
| 提示 | 参数 | 描述 |
|---|---|---|
| `create-issue` | `projectKey`, `issueType`, `summary`（必填）；`description`, `priority`, `labels`（可选） | 生成一个引导式问题创建消息，提示代理调用 `jira_create_issue`。 |
| `triage-issue` | `key` | 获取问题 + 可用的转换 + 评论，返回结构化分析：摘要、状态、分配人、优先级、描述、可用转换、评论历史。 |
## 有条件的注册行为
- **Jira 模块** — 仅在设置了 `JIRA_BASE_URL`、`JIRA_EMAIL` 和 `JIRA_TOKEN` 时注册。
- **GitHub 模块** — 仅在设置了 `GH_TOKEN` 时注册。
- **Figma 模块** — 仅在设置了 `FIGMA_TOKEN` 时注册。
- **回退** — 如果未设置环境变量，服务器将仅使用 `mcp_get_health` 启动。不会崩溃。
- 服务器在启动时记录活动的集成： `[mcp] Jira integration: active`。
## 测试
使用 **vitest** 在 12 个测试文件中进行 219 项测试：
```bash
npm run test # 运行所有测试
npx vitest path/to/file.test.ts # 单个测试文件
```
所有工具处理程序都可以通过**依赖注入**进行测试 — 模拟客户端会传递给处理程序工厂，无需实际凭证。
## 脚本
| 脚本 | 描述 |
|---|---|
| `npm run mcp` | 开发模式 — `tsx` TypeScript 执行，stdio 传输（默认） |
| `npm run mcp:prod` | 生产模式 — 编译的 JS（首先运行 `npm run build`） |
| `npm run mcp:inspect` | 启动 MCP 检查器进行调试 |
| `npm run build` | TypeScript 编译（`tsc`） |
| `npm run typecheck` | 仅 TypeScript 类型检查（`tsc --noEmit`） |
| `npm run test` | 运行所有测试（vitest） |
| `npm run test:watch` | Vitest 监视模式 |
## MCP 客户端配置（AI IDE）
### OpenCode / Claude 桌面版
```json
{
"mcpServers": {
"toolkit-mcp": {
"command": "node",
"args": ["--import", "tsx", "/path/to/toolkit-mcp/src/mcp-server.ts"],
"env": {
"JIRA_BASE_URL": "https://pathwise.atlassian.net",
"JIRA_EMAIL": "you@pathwisek12.com",
"JIRA_TOKEN": "<atlassian-api-token>",
"GH_TOKEN": "<github-token>"
}
}
}
}
```
### VS Code（Cline、Continue 等）
```json
{
"mcpServers": {
"toolkit-mcp": {
"command": "node",
"args": ["--import", "tsx", "/path/to/toolkit-mcp/src/mcp-server.ts"],
"env": {
"JIRA_BASE_URL": "https://pathwise.atlassian.net",
"JIRA_EMAIL": "you@pathwisek12.com",
"JIRA_TOKEN": "<atlassian-api-token>",
"GH_TOKEN": "<github-token>"
}
}
}
}
```
**注意：** 省略您不需要的集成环境变量（例如，如果您只使用 Jira，请跳过 `GH_TOKEN`）。仅当存在集成环境变量时，工具才会注册。
## 项目布局
```
src/
├── mcp-server.ts # 入口：引导、传输、中心调度
├── mcp-config.ts # MCP 特定配置（传输、端口、日志级别）
├── mcp-health.ts # mcp_get_health 工具处理程序
├── services/
│ ├── index.ts # Barrel — 重新导出所有服务类/类型
│ ├── config.ts # loadConfig() + dotenv（Jira/GitHub 共享）
│ ├── slim.ts # SlimIssue, toSlimIssue, adfToText
│ ├── jira/
│ │ └── jira-client.ts # JiraClient 类
│ └── github/
│ └── github-client.ts # GitHubClient 类
├── integrations/
│ ├── index.ts # 模块注册 + IntegrationModule 接口
│ ├── helpers.ts # PaginatedResponse 帮助程序，zodToJsonSchema
│ ├── jira/
│ │ ├── index.ts # JiraModule：needsEnv, createToolHandlers, resources, prompts
│ │ └── module.ts # Jira 工具处理程序、Zod 模式、描述符
│ └── github/
│ ├── index.ts # GitHubModule：needsEnv, createToolHandlers, resources
│ └── module.ts # GitHub 工具处理程序、Zod 模式、描述符
## 依赖
- **@modelcontextprotocol/sdk** — MCP 协议实现（服务器、传输、类型）。
- **zod** — 工具输入参数的模式验证。
- **axios** — Jira 和 GitHub API 调用的 HTTP 客户端。
- **dotenv** — 从 `.env` 加载环境变量。
> **注意：** `jira-cli` 库已被吸收到 `src/services/` 作为内部服务层。不需要外部依赖 — JiraClient、GitHubClient 及其实用程序直接位于 toolkit-mcp 代码库中。
## 参考
- **架构计划：** [`docs/plans/01-jira-cli-mcp-server.md`](docs/plans/01-jira-cli-mcp-server.md) — 涵盖所有阶段的完整实现计划。
- **架构审查：** [`docs/code-review/jira-cli-mcp-server-plan-review.md`](docs/code-review/jira-cli-mcp-server-plan-review.md) — 已解决的 18 个发现。
- **第一阶段审查：** [`docs/code-review/phase1-mcp-implementation-review.md`](docs/code-review/phase1-mcp-implementation-review.md)。
- **代理约定：** `/ezat/AGENTS.md` — monorepo 级工作流、构建/ lint / 测试命令。
