npm package: @neosamon/jira-mcp-server
Description: Jira MCP Server - Model Context Protocol server for Jira integration
Latest version: 0.3.0

# Jira MCP Server

一个基于 TypeScript/Node.js 的 Jira Model Context Protocol (MCP) Server，允许 AI 助手直接与 Jira 进行交互。

## 架构

本项目采用分层模块化架构，将业务逻辑拆分为职责清晰的多个模块：

- **Domain Layer**: 领域类型和错误定义
- **Infrastructure Layer**: 配置管理和 HTTP 客户端
- **Service Layer**: Jira API 客户端和数据格式化
- **Tool Layer**: MCP 工具实现
- **Application Layer**: 依赖注入和应用启动

详细的架构说明请参阅 [ARCHITECTURE.md](ARCHITECTURE.md)。

## 功能

- **查询 Issue**: 通过 Issue Key 获取 Issue 的详细信息，包括类型、状态、优先级、描述和评论
- **搜索 Issues**: 使用 JQL (Jira Query Language) 批量搜索 Issues
- **创建评论**: 为指定的 Issue 添加评论
- **上传附件**: 支持批量上传文件到 Issue（Base64 编码或本地文件路径）
- **下载附件**: 从 Jira Issue 下载附件到本地文件系统
- **字段发现**: 探测 Issue 的所有可用字段，用于配置自定义字段映射
- **自定义字段**: 支持通过环境变量配置，提取 Jira 自定义字段

## 环境变量配置

在使用之前，需要设置以下环境变量：

| 环境变量 | 必需 | 说明 | 示例 |
|----------|------|------|------|
| `JIRA_BASE_URL` | 是 | Jira 服务器地址（不要以斜杠结尾） | `https://your-jira.example.com` |
| `JIRA_USERNAME` | 是 | Jira 用户名或邮箱 | `user@example.com` |
| `JIRA_API_TOKEN` | 条件必需* | Jira API Token | `your-api-token-here` |
| `JIRA_PASSWORD` | 条件必需* | Jira 密码 | `your-password` |
| `JIRA_AUTH_TYPE` | 否 | 认证方式：`auto`（默认）、`token`、`password` | `auto` |
| `JIRA_MAX_ATTACHMENT_SIZE` | 否 | 附件大小限制（字节），默认 10MB | `10485760` |
| `JIRA_DOWNLOAD_PATH` | 否 | 附件下载目录路径，默认 `/tmp/` | `/downloads` |
| `LOG_LEVEL` | 否 | 日志级别：`trace`、`debug`、`info`（默认）、`warn`、`error` | `info` |
| `LOG_TO_STDERR` | 否 | 是否输出到 stderr，默认 `true` | `true` |
| `LOG_TO_FILE` | 否 | 是否输出到文件，默认 `false` | `false` |
| `LOG_FILE_PATH` | 否 | 日志文件路径，默认 `/tmp/jira-mcp.log` | `/var/log/jira-mcp.log` |
| `LOG_FILE_MAX_SIZE` | 否 | 单文件最大大小，默认 `10M` | `10M` |
| `LOG_FILE_MAX_FILES` | 否 | 保留文件数量，默认 `5` | `5` |

**至少需要设置 `JIRA_API_TOKEN` 或 `JIRA_PASSWORD` 之一**

### 认证方式说明

本 MCP Server 支持两种认证方式：

1. **API Token 认证（推荐）**: 更安全，可以随时撤销
2. **密码认证**: 适用于不支持 API Token 的旧版本 Jira

#### 认证方式选择逻辑

```
JIRA_AUTH_TYPE 环境变量
│
├─ "token" → 强制使用 API Token（忽略 JIRA_PASSWORD）
├─ "password" → 强制使用密码（忽略 JIRA_API_TOKEN）
└─ "auto" 或未设置
   │
   ├─ 如果设置了 JIRA_PASSWORD → 使用密码（优先）
   └─ 否则 → 使用 API Token
```

#### 获取 Jira API Token

1. 登录到您的 Jira 实例
2. 进入 **Account Settings** > **Security** > **API Tokens**
3. 点击 **Create API token**
4. 复制生成的 Token 并设置为 `JIRA_API_TOKEN` 环境变量

### 日志配置（可选）

本 MCP Server 支持结构化日志输出，便于调试和问题追踪。

#### 日志级别

支持的日志级别（从详细到简略）：
- `trace`: 最详细的日志，包含所有操作细节
- `debug`: 调试信息，包括请求/响应详情
- `info`: 一般信息（默认级别），包括 API 调用摘要
- `warn`: 警告信息，包括重试和错误
- `error`: 错误信息，仅记录失败的操作

#### 输出目标

日志可以同时输出到 stderr 和文件：

- **stderr**: 默认开启，适合开发调试，不会干扰 MCP 协议通信
- **文件**: 需要手动启用，适合生产环境日志持久化

#### 配置示例

**仅 stderr（默认，开发环境推荐）:**
```bash
export LOG_LEVEL="debug"  # 显示调试信息
```

**启用文件日志（生产环境）:**
```bash
export LOG_TO_FILE="true"
export LOG_FILE_PATH="/var/log/jira-mcp.log"
export LOG_FILE_MAX_SIZE="50M"
export LOG_FILE_MAX_FILES="10"
```

**同时输出到 stderr 和文件:**
```bash
export LOG_TO_STDERR="true"
export LOG_TO_FILE="true"
export LOG_FILE_PATH="/var/log/jira-mcp.log"
```

#### 日志格式

日志采用 JSON 格式输出，便于解析和分析：

```json
{
  "level": "info",
  "message": "Jira MCP Server 配置加载成功",
  "baseURL": "https://jira.example.com",
  "authType": "token",
  "timestamp": "2026-02-27T10:30:00.000Z"
}
```

#### 日志文件轮转

当启用文件日志时，日志会自动轮转：
- 单个文件达到最大大小时自动创建新文件
- 旧文件会按时间戳命名并添加后缀（如 `.1`, `.2`）
- 超过保留数量的旧文件会自动删除

例如，配置 `maxSize=10M` 和 `maxFiles=5` 时：
```
jira-mcp.log        # 当前日志文件
jira-mcp.log.1      # 第一个轮转文件
jira-mcp.log.2      # 第二个轮转文件
...
```

### 自定义字段配置（可选）

Jira 实例通常包含自定义字段（如测试步骤、预期结果、代码分支等）。要提取这些字段，需要配置字段映射。

#### 配置步骤

1. **使用字段发现工具**找出目标字段的 ID：

   ```
   "使用 get_issue_fields 工具查看 Issue PROJ-123 的所有字段"
   ```

2. **配置环境变量**将字段名映射到字段 ID：

   ```bash
   export JIRA_FIELD_TEST_STEP="customfield_10206"
   export JIRA_FIELD_EXPECTED_RESULT="customfield_10208"
   export JIRA_FIELD_ACTUAL_RESULT="customfield_10210"
   export JIRA_FIELD_CODE_BRANCH="customfield_10300"
   ```

3. **重启服务器**，`get_issue` 工具将自动包含配置的自定义字段

#### 字段映射规则

- 环境变量格式：`JIRA_FIELD_<NAME>=<field_id>`
- 字段名会自动转换为驼峰命名（如 `JIRA_FIELD_TEST_STEP` → `testStep`）
- 未配置的字段不会出现在输出中
- 字段不存在或为空时显示 `N/A`

## 安装

### 通过 npm 全局安装

```bash
npm install -g @neosamon/jira-mcp-server
```

### 使用 npx 运行（无需安装）

```bash
npx @neosamon/jira-mcp-server
```

## 使用方法

### 设置环境变量

#### 使用 API Token 认证（推荐）

```bash
export JIRA_BASE_URL="https://your-jira.example.com"
export JIRA_USERNAME="your-email@example.com"
export JIRA_API_TOKEN="your-api-token"

npx @neosamon/jira-mcp-server
```

#### 使用密码认证

```bash
export JIRA_BASE_URL="https://your-jira.example.com"
export JIRA_USERNAME="your-email@example.com"
export JIRA_PASSWORD="your-password"

npx @neosamon/jira-mcp-server
```

#### 显式指定认证方式

```bash
# 强制使用 Token 认证
export JIRA_AUTH_TYPE="token"
export JIRA_API_TOKEN="your-api-token"

# 强制使用密码认证
export JIRA_AUTH_TYPE="password"
export JIRA_PASSWORD="your-password"
```

## Claude Desktop 配置

在 Claude Desktop 的配置文件中添加以下内容：

### macOS

配置文件路径: `~/Library/Application Support/Claude/claude_desktop_config.json`

### Windows

配置文件路径: `%APPDATA%\Claude\claude_desktop_config.json`

### 配置内容

#### 使用 API Token 认证（推荐）

```json
{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["@neosamon/jira-mcp-server"],
      "env": {
        "JIRA_BASE_URL": "https://your-jira.example.com",
        "JIRA_USERNAME": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}
```

#### 使用密码认证

```json
{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["@neosamon/jira-mcp-server"],
      "env": {
        "JIRA_BASE_URL": "https://your-jira.example.com",
        "JIRA_USERNAME": "your-email@example.com",
        "JIRA_PASSWORD": "your-password"
      }
    }
  }
}
```

## Claude CLI 配置

### 基于项目添加
```bash
claude mcp add jira --transport stdio \
    --env JIRA_BASE_URL="https://your-jira.example.com" \
    --env JIRA_USERNAME="your-email@example.com" \
    --env JIRA_PASSWORD="your-password" \
    -- npx @neosamon/jira-mcp-server
```

### 全局添加
```bash
claude mcp add jira --scope user --transport stdio \
    --env JIRA_BASE_URL="https://your-jira.example.com" \
    --env JIRA_USERNAME="your-email@example.com" \
    --env JIRA_PASSWORD="your-password" \
    -- npx @neosamon/jira-mcp-server
```

## 使用示例

配置完成后，您可以在 Claude 中使用以下命令：

### 基本功能

- "查询 Jira Issue PROJ-123 的详情"
- "为 PROJ-123 添加评论：已完成代码审查"
- "上传文件 error.log 到 Issue PROJ-123"
- "批量上传多个文件到 PROJ-456：screenshot.png、log.txt 和 report.pdf"

### 字段发现

- "使用 get_issue_fields 工具查看 Issue PROJ-123 的所有可用字段"
- "列出 PROJ-123 的字段，帮我找出测试步骤对应的字段 ID"

### JQL 搜索

- "搜索分配给我的所有进行中任务"
- "查找项目 PROJ 中所有高优先级的 Bug"
- "列出本周创建的所有 Issues"
- "搜索状态为 Open 且优先级为 High 的 Issues"

### 附件上传

本 MCP Server 支持批量上传附件到 Jira Issue。

#### 支持的输入方式

1. **Base64 编码内容**（适合小文件）
   - AI 助手可以直接编码文件内容并上传
   - 适合文本文件、JSON、小图片等

2. **本地文件路径**（适合大文件）
   - 适用于 MCP Server 有文件系统访问权限的场景
   - 适合大文件（如日志、压缩包）

#### 附件大小限制

默认最大附件大小为 **10MB**。可通过环境变量 `JIRA_MAX_ATTACHMENT_SIZE` 配置：

```bash
export JIRA_MAX_ATTACHMENT_SIZE=20971520  # 20MB
```

#### 使用示例

**上传单个文件（Base64）:**
```
上传 error.log 文件到 Issue PROJ-123
```

**批量上传多个文件:**
```
批量上传以下文件到 PROJ-456：
- screenshot.png
- error.log
- report.pdf
```

**指定 MIME 类型:**
- 对于常见文件类型，AI 助手会自动识别 MIME 类型
- 支持的类型包括：`text/plain`、`application/json`、`image/png`、`image/jpeg`、`application/pdf` 等

#### 错误处理

附件上传具有完善的错误处理：

- **文件过大**：会明确提示超出限制的文件及其大小
- **部分失败**：会显示成功和失败的详细列表
- **格式错误**：会提示具体的问题文件

示例输出：
```
📎 附件上传完成 - PROJ-123

📊 汇总: 2/3 成功

✅ 成功上传:
  • screenshot.png (150.50 KB)
    ID: att-100
  • error.log (5.20 KB)
    ID: att-101

❌ 失败:
  • huge.zip: File 'huge.zip' (15.00 MB) exceeds maximum size (10.00 MB)
```

### 附件下载

本 MCP Server 支持从 Jira Issue 下载附件到本地文件系统。

#### 下载方式

使用 `get_issue` 工具获取 Issue 详情后，可以从返回的附件列表中获取附件 URL，然后使用 `download_attachment` 工具下载。

#### 保存路径优先级

附件保存目录按以下优先级确定：

1. **工具参数 `outputPath`**: 最高优先级，允许临时覆盖默认路径
2. **环境变量 `JIRA_DOWNLOAD_PATH`**: 项目级默认配置
3. **`/tmp/` 目录**: 通用回退选项

#### 文件命名规则

下载的文件使用 `{attachmentId}-{filename}` 格式命名，防止不同附件的相同文件名冲突：

- URL: `http://jira.example.com/secure/attachment/151194/README.md`
- 保存为: `151194-README.md`

#### 使用示例

**从 Issue 获取附件 URL 并下载:**
```
1. 查询 Issue PROJ-123 的详情，获取附件列表
2. 下载附件 /secure/attachment/151194/screenshot.png
```

**指定自定义下载路径:**
```
下载附件 /secure/attachment/151194/report.pdf 到 /my/downloads 目录
```

**使用环境变量配置默认下载目录:**
```bash
export JIRA_DOWNLOAD_PATH="/Users/username/Downloads"
```

#### 下载超时

下载操作的超时时间为 **5 分钟**（300 秒），适合大文件下载。

#### 错误处理

- **URL 格式无效**: 会提示 URL 格式错误
- **附件不存在或无权限**: 会返回相应的错误信息
- **目录不可写**: 会提示目录不可写并建议检查权限或使用 `outputPath` 参数

示例输出：
```
📥 附件下载成功

文件: screenshot.png
大小: 150.50 KB
保存到: /tmp/151194-screenshot.png
```

## 兼容性

- **Node.js 版本**: 18 或更高版本
- **Jira 版本**: 7.0.9+ (使用 REST API v2)

## 许可证

MIT License