内容
# Jira MCP
用于 Jira Cloud 的小型 Python MCP 服务器。
## 前提条件
- Python 3.10+（`mcp` 包无法在 Python 3.9 上安装）
## 工具
- `get_jira_user`：通过 `/rest/api/3/myself` 获取已认证的 Jira 用户
- `get_current_active_sprint_info`：从配置的项目看板中获取当前活跃冲刺的元数据（通过 `JIRA_PROJECT_KEY` 和 `JIRA_BOARD_ID` 设置）
- `get_active_sprint_stories`：从配置的看板中获取当前活跃冲刺中分配给当前用户的故事问题，排除 `Ready for Production`（默认包括子任务）
- `get_my_assigned_board_stories`：`get_active_sprint_stories` 的向后兼容别名
- `get_all_current_sprint_stories`：从配置的看板中获取当前活跃冲刺中的所有故事问题，排除 `Ready for Production`（默认包括子任务）
- `move_story_to_in_progress`：将故事问题从 `Ready for Work` 转换到 `In Progress`，并进行验证检查
- `create_subtask_for_parent_assignee`：在父问题下创建一个子任务，并将其分配给与父问题相同的处理人
- `get_issue_attachments`：获取 Jira 问题的附件元数据（文件名、MIME 类型、大小、下载 URL、缩略图）；设置 `images_only=true` 以仅返回截图/图像
- `download_issue_attachments`：将问题的附件下载到本地目录（默认为当前工作目录下的 `tmp/{issue_key}/StoryAttachments/`）；设置 `images_only=true` 以仅下载图像
## 环境
在启动服务器之前，请设置以下变量：
- `ATLASSIAN_SITE_URL` 或 `JIRA_SITE_URL` - 您的 Jira Cloud 实例 URL
- `ATLASSIAN_EMAIL` 或 `JIRA_EMAIL_ID` - 您的 Atlassian 账户电子邮件
- `ATLASSIAN_API_TOKEN` 或 `JIRA_API_KEY` - API 令牌（在 https://id.atlassian.com/manage-profile/security/api-tokens 处生成）
- `JIRA_PROJECT_KEY` - 您的 Jira 项目密钥（例如，问题 `ABC-123` 中的 `ABC`）
- `JIRA_BOARD_ID` - 您的看板 ID（数字，在看板 URL 中可见）
### 如何创建 Atlassian API 令牌
1. 打开：https://id.atlassian.com/manage-profile/security/api-tokens
2. 使用与 Jira 相同的 Atlassian 账户登录。
3. 点击 **创建 API 令牌**。
4. 输入标签（例如：`jira-mcp-local`）并创建令牌。
5. 立即复制令牌值（您可能无法再次查看它）。
6. 在您的 `.env` 文件中设置：
```dotenv
JIRA_API_KEY="粘贴您的令牌值"
```
安全注意：请勿将 `.env` 或令牌值提交到 Git。
### 查找您的项目密钥和看板 ID
**项目密钥：**
- 打开您的项目中的任意问题，查看问题密钥：`PROJECT-123`
- `PROJECT` 部分是您的项目密钥
- 或访问项目设置并检查项目详情
**看板 ID：**
- 在 Jira 中打开您的敏捷看板
- URL 将包含 `/board/{BOARD_ID}/`
- 示例：`https://your-company.atlassian.net/software/c/projects/PROJECT/board/12345` → 看板 ID 为 `12345`
- 或使用 Jira API：`curl -u email:token https://your-company.atlassian.net/rest/agile/1.0/board`
### 配置（默认：`.env` 文件）
使用本地 `.env` 文件作为主要的设置方法。
1. 复制模板：
```bash
cp .env.example .env
```
2. 使用您的 Jira 值编辑 `.env`：
```dotenv
JIRA_SITE_URL="https://your-company.atlassian.net"
JIRA_EMAIL_ID="your-email@company.com"
JIRA_API_KEY="your-api-token"
JIRA_PROJECT_KEY="YOUR_PROJECT_KEY"
JIRA_BOARD_ID="12345"
```
3. 启动服务器：
```bash
bash ./run.sh
```
`run.sh` 在存在时会自动加载 `.env`。
### 备用选项（仅在需要时）
您也可以使用导出的 shell 变量（`~/.zshrc` / `~/.bashrc`）或内联导出，但 `.env` 是默认且推荐的可靠性路径。
## 运行
从项目目录：
```bash
./run.sh
```
如果您的 Mac 只有 Python 3.9，请先安装更新版本：
```bash
brew install python@3.11
```
或：
```bash
python3 -m jira_mcp.server
```
## MCP 客户端配置（`mcp.json`）
从 MCP 客户端（例如在 VS Code 中）使用此服务器时，请指向 `run.sh`。
`run.sh` 会自动加载 `.env`，因此请将您的 Jira 凭证和项目设置保存在那里。
1. 从模板创建 `.env`：
```bash
cp .env.example .env
```
2. 使用实际值编辑 `.env`。
3. 使用以下通用服务器条目更新您的 `mcp.json`（将 `/absolute/path/to/jira-mcp` 替换为您的本地路径）：
```json
{
"servers": {
"JIRA_MCP_LOCAL": {
"type": "stdio",
"command": "bash",
"args": [
"/absolute/path/to/jira-mcp/run.sh"
]
}
},
"inputs": []
}
```
