内容
# jira2ai
Jira AI 工作空间，用于 Jira Cloud 集成。
本仓库目前包含两个软件包：
- `jira2mcp` — 发布为 `jira2mcp` 的 MCP 适配器。
- `jira2cli` — 用于本地和开发工作流的 CLI 适配器。
这两个软件包都是已发布的 [jira2py](https://pypi.org/project/jira2py/) 帮助程序的薄封装。
使用 [FastMCP](https://github.com/jlowin/fastmcp) 和 [jira2py](https://pypi.org/project/jira2py/) 构建。
## 设置
### 1. 获取您的 Jira 凭证
您需要从 Jira Cloud 实例获取三个值：
| 变量 | 描述 |
|---|---|
| `JIRA_URL` | 您的 Jira 实例 URL（例如 `https://yourcompany.atlassian.net`） |
| `JIRA_USER` | 您的 Jira 账户电子邮件 |
| `JIRA_API_TOKEN` | 来自 [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens) 的 API令牌 |
### 2. 安装 uv（如果尚未安装）
`uvx` 是 [uv](https://docs.astral.sh/uv/) 的一部分，一个快速的 Python 包管理器：
```bash
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
### 3. 添加到 Claude 代码
```bash
claude mcp add jira -- uvx jira2mcp
```
### 4. 配置凭证
**选项 A：Shell 环境变量**
在您的 shell 配置文件（`~/.bashrc`、`~/.zshrc` 等）中导出它们：
```bash
export JIRA_URL="https://yourcompany.atlassian.net"
export JIRA_USER="you@company.com"
export JIRA_API_TOKEN="your-api-token"
```
MCP 配置保持最小：
```json
{
"mcpServers": {
"jira": {
"command": "uvx",
"args": ["jira2mcp"]
}
}
}
```
**选项 B：内联在 MCP 配置中**
如果您不想设置全局环境变量，请直接在 `env` 部分提供它们：
```json
{
"mcpServers": {
"jira": {
"command": "uvx",
"args": ["jira2mcp"],
"env": {
"JIRA_URL": "https://yourcompany.atlassian.net",
"JIRA_USER": "you@company.com",
"JIRA_API_TOKEN": "your-api-token"
}
}
}
}
```
## 工具
| 工具 | 描述 |
|---|---|
| `jira_read` | 按键读取 Jira 问题，附带完整详细信息 |
| `jira_search` | 使用 JQL 搜索问题 |
| `jira_create` | 创建新问题 |
| `jira_edit` | 更新现有问题 |
| `jira_comment` | 向问题添加评论 |
| `jira_comments` | 列出评论，附带分页 |
| `jira_fields` | 获取创建/编辑屏幕的字段元数据 |
| `jira_projects` | 列出可访问的项目 |
| `jira_users` | 按姓名或电子邮件搜索用户 |
| `jira_attachment` | 下载附件 |
| `jira_add_link` | 在两个问题之间创建链接 |
| `jira_delete_link` | 删除问题链接 |
| `jira_worklog_report` | 为 JQL 选择的问题在 UTC 日期范围内构建工作日志报告 |
## 资源
| 资源 | 描述 |
|---|---|
| `data://jira/link-types` | 您的 Jira 实例中可用的问题链接类型 |
## 提示
| 提示 | 描述 |
|---|---|
| `jql_syntax` | 用于构建搜索查询的 JQL 语法参考 |
## 本地开发的 CLI 用法
`jira2cli` 使用与上述相同的 `JIRA_URL`、`JIRA_USER` 和 `JIRA_API_TOKEN` 变量。
同步工作区一次：
```bash
uv sync --all-packages --group dev
```
然后从工作区运行 CLI：
```bash
uv run --package jira2cli jira2cli --help
uv run --package jira2cli jira2cli read PROJ-123
uv run --package jira2cli jira2cli search 'project = PROJ ORDER BY updated DESC'
uv run --package jira2cli jira2cli worklog-report --start-date 2026-06-12 --end-date 2026-06-13 --jql 'issue = PROJ-123'
```
`jira2cli` 可在此工作区中用于本地/开发用途。继续使用 `uvx jira2mcp` 进行 MCP 安装。
## 主要功能
- **Markdown 输入，Markdown 输出** — 在 Markdown 中编写描述和评论；它们会自动转换为 Atlassian 文档格式（ADF）。来自 Jira 的 ADF 字段会转换回 Markdown。
- **字段发现** — 使用 `jira_fields` 在创建或编辑问题之前发现所需和可用的字段。
- **用户查找** — 使用 `jira_users` 将显示名称解析为账户 ID 以进行分配。
- **额外字段** — 在 `jira_read` 上请求标准集合之外的附加字段；富文本字段会自动转换。
- **链接管理** — 读取 `data://jira/link-types` 资源以发现可用的链接类型，然后在问题之间创建或删除链接。
- **工作日志报告** — 使用 `jira_worklog_report` 或 `jira2cli worklog-report`，附带所需的 UTC `start_date`/`end_date` 和 JQL 问题选择。`end_date` 是包含的，可选的 `account_id` 过滤在客户端应用，`max_issues` 默认值为 `100`，并限制扫描多少个匹配问题（当更多匹配时，会有截断注释），行使用 `displayName` 作为友好用户名，结果反映配置的 Jira 账户的问题/工作日志可见性。
## 仓库布局
此仓库是一个 `uv` 工作区，包含两个软件包：
- `packages/jira2mcp` — 发布为 `jira2mcp` 的 FastMCP 服务器/适配器软件包。
- `packages/jira2cli` — 用于本地/开发用途的 CLI 适配器软件包。
最终用户 MCP 设置保持不变：直接使用 `uvx jira2mcp` 或 `claude mcp add jira -- uvx jira2mcp`。
## 贡献
有关工作区设置、开发检查、拉取请求指导和维护人员发布链接，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 维护人员
软件包特定的发布步骤、标签格式和当前停止门控位于 [docs/releasing.md](docs/releasing.md)。
最终用户 MCP 设置保持不变：`uvx jira2mcp` 或 `claude mcp add jira -- uvx jira2mcp`.
## 许可证
MIT
