杰拉-MCP

Name: 杰拉-MCP
Author: MankowskiNick

作者：MankowskiNick5 星标更新：2025-09-20

安装使用来源：spider==github.com

项目介绍

JIRA MCP 集成

一个用于集成JIRA与Claude的Model Context Protocol（MCP）服务器。此工具允许Claude在对话中直接创建JIRA工单。

概述

JIRA MCP项目是一个Node.js/TypeScript应用程序，提供了一个Model Context Protocol（MCP）服务器，用于与JIRA和Zephyr集成。它允许AI助手通过标准化协议与JIRA进行项目管理和与Zephyr进行测试管理的交互。

特性

使用总结、描述、验收标准和问题类型创建JIRA工单
为故事工单分配故事点
自动为有故事点的故事创建链接的测试工单
根据问题类型和其他标准搜索JIRA工单
更新现有JIRA工单的新字段值
使用指定的关系类型链接JIRA工单
获取和添加Zephyr测试工单的测试步骤
无缝集成到Claude桌面应用
使用Claude桌面配置文件进行简单配置

安装

克隆仓库：

git clone https://github.com/MankowskiNick/jira-mcp.git
cd jira-mcp

安装依赖：
```
npm install
```

构建项目：

 npm run build -- 在Unix系统上
 -- 或 --
 npm run build-win -- 在Windows系统上

配置

配置位置

将JIRA MCP服务器配置添加到您的Claude配置文件中：

Claude桌面应用：
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Roaming\Claude\claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json
VSCode扩展：
- ~/.vscode-server/data/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

配置模板

已提供一个模板配置文件jira-mcp-config-template.json。该模板展示了JIRA MCP服务器的所有可能配置选项。

基本配置

向您的Claude配置文件添加以下配置：

{
  "mcpServers": {
    "jira-mcp": {
      "command": "node",
      "args": ["/path/to/project/build/index.js"],
      "env": {
        "JIRA_HOST": "your-site.atlassian.net",
        "JIRA_USERNAME": "your-email@example.com",
        "JIRA_API_TOKEN": "your_api_token",
        "JIRA_PROJECT_KEY": "your_project_key",
        "AUTO_CREATE_TEST_TICKETS": "true",

        "JIRA_ACCEPTANCE_CRITERIA_FIELD": "customfield_10429",
        "JIRA_STORY_POINTS_FIELD": "customfield_10040",
        "JIRA_EPIC_LINK_FIELD": "customfield_10014",

        "JIRA_PRODUCT_FIELD": "customfield_10757",
        "JIRA_PRODUCT_VALUE": "Your Product Name",
        "JIRA_PRODUCT_ID": "12345",

        "JIRA_CATEGORY_FIELD": "customfield_10636",
        "USE_ALTERNATE_CATEGORY": "false",
        "JIRA_DEFAULT_CATEGORY_VALUE": "Default Category",
        "JIRA_DEFAULT_CATEGORY_ID": "12345",
        "JIRA_ALTERNATE_CATEGORY_VALUE": "Alternate Category",
        "JIRA_ALTERNATE_CATEGORY_ID": "67890"
      }
    }
  }
}

必需配置

以下环境变量是必需的，以使JIRA MCP服务器正常工作：

JIRA_HOST: 您的JIRA实例域名（例如：company.atlassian.net）
JIRA_USERNAME: 您的JIRA用户名（通常是您的电子邮件地址）
JIRA_API_TOKEN: 您的JIRA API令牌（见下文如何获取）
JIRA_PROJECT_KEY: 您的JIRA项目的键（例如：SCRUM，DEV等）

可选配置

测试工单创建

AUTO_CREATE_TEST_TICKETS: 设置为“true”（默认）以自动为有故事点的故事创建链接的测试工单，或设置为“false”以禁用此功能

Zephyr集成

这些环境变量是Zephyr集成所必需的，用于向测试工单添加测试步骤：

ZAPI_BASE_URL: Zephyr API的基础URL（默认：“https://prod-api.zephyr4jiracloud.com/connect”）
ZAPI_ACCESS_KEY: 您的Zephyr访问密钥（在Zephyr Cloud设置中的API密钥下找到）
ZAPI_SECRET_KEY: 您的Zephyr秘密密钥（在Zephyr Cloud设置中的API密钥下找到）
ZAPI_JWT_EXPIRE_SEC: JWT令牌过期时间（秒，默认：3600）

自定义字段配置

以下环境变量允许您配置自定义字段而不必在源代码中硬编码它们：

JIRA_ACCEPTANCE_CRITERIA_FIELD: 接受标准字段ID（默认：“customfield_10429”）
JIRA_STORY_POINTS_FIELD: 故事点字段ID（默认：“customfield_10040”）
JIRA_EPIC_LINK_FIELD: 主题链接字段ID（默认：“customfield_10014”）

产品字段配置（可选）

这是完全可选的。为了使此功能工作，必须一起提供所有三个变量：

JIRA_PRODUCT_FIELD: 产品字段ID
JIRA_PRODUCT_VALUE: 产品的显示值
JIRA_PRODUCT_ID: 产品选项的ID

类别字段配置（可选）

这是完全可选的。只有在指定了JIRA_CATEGORY_FIELD时才会使用类别字段：

JIRA_CATEGORY_FIELD: 类别字段ID
USE_ALTERNATE_CATEGORY: 设置为“true”以使用替代类别，“false”为默认
JIRA_DEFAULT_CATEGORY_VALUE: 默认类别的显示值
JIRA_DEFAULT_CATEGORY_ID: 默认类别的ID
JIRA_ALTERNATE_CATEGORY_VALUE: 替代类别的显示值
JIRA_ALTERNATE_CATEGORY_ID: 替代类别的ID

最小配置示例

如果您想要绝对最小的配置，可以使用：

{
  "mcpServers": {
    "jira-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/jira-mcp/build/index.js"],
      "env": {
        "JIRA_HOST": "your-site.atlassian.net",
        "JIRA_USERNAME": "your-email@example.com",
        "JIRA_API_TOKEN": "your_api_token",
        "JIRA_PROJECT_KEY": "your_project_key"
      }
    }
  }
}

查找自定义字段ID

如果您需要找到JIRA实例的自定义字段ID：

打开JIRA实例中的一个工单
按F12打开开发者工具
转到网络标签
刷新页面
寻找请求issue/[ISSUE-KEY]
检查响应以找到自定义字段ID

或者，您可以使用JIRA API获取所有字段列表：

GET https://your-site.atlassian.net/rest/api/3/field

可用工具

create-ticket

创建一个新的JIRA工单。

参数：

summary: 工单的标题/总结（必需）
issue_type: 问题类型（Bug，Task，Story或Test，默认为Task）
description: 工单的详细描述（可选）
acceptance_criteria: 工单的验收标准（可选，存储在customfield_10429中）
story_points: 工单的故事点数（可选，斐波那契序列：1, 2, 3, 5, 8, 13等）
create_test_ticket: 覆盖默认设置以自动创建链接的测试工单（可选，布尔值）
parent_epic: 父主题的键，用于链接此工单（可选，例如："PROJ-123"）
sprint: 分配给工单的冲刺名称（可选，例如："2025_C1_S07"）
story_readiness: 故事是否准备好开发（可选，"Yes"或"No"）

当创建带有故事点的故事工单时：

自动为故事添加"QA-Testable"标签
如果启用了AUTO_CREATE_TEST_TICKETS，则会自动创建链接的测试工单
测试工单使用故事的标题作为其描述
测试工单与故事之间通过"Test Case Linking"关系链接

示例：

{
  "summary": "实现用户身份验证功能",
  "issue_type": "Story",
  "description": "作为一个用户，我希望能够登录到应用程序",
  "acceptance_criteria": "- 用户可以使用电子邮件和密码登录\n- 通过电子邮件重置密码的功能有效",
  "story_points": 5,
  "parent_epic": "PROJ-100",
  "sprint": "2025_C1_S07",
  "story_readiness": "Yes"
}

get-ticket

检索现有的JIRA工单的详细信息。

参数：

ticket_id: 您要读取的JIRA工单的ID/键（必需，例如："PROJ-123"）

示例：

{
  "ticket_id": "PROJ-123"
}

响应包括工单的所有字段，包括自定义字段。

search-tickets

根据问题类型和其他标准搜索JIRA工单。

参数：

issue_type: 要搜索的问题类型（Bug，Task，Story或Test）（必需）
max_results: 返回的最大结果数（可选，默认：10，最大：50）
additional_criteria: 包含在搜索中的其他JQL标准（可选）

示例：

{
  "issue_type": "Bug",
  "max_results": 20,
  "additional_criteria": "status = 'Open' AND priority = 'High'"
}

此工具允许您找到JIRA项目中特定类型的所有工单。您可以通过提供额外的JQL标准进一步细化搜索。

update-ticket

更新现有JIRA工单的新字段值。

参数：

ticket_key: 要更新的JIRA工单的键（必需，例如："PROJ-123"）
sprint: 要分配给工单的冲刺名称（可选，例如："2025_C1_S07"）
story_readiness: 故事是否准备好开发（可选，"Yes"或"No"）

示例：

{
  "ticket_key": "PROJ-123",
  "sprint": "2025_C1_S07",
  "story_readiness": "Yes"
}

此工具允许您更新现有工单的冲刺信息和故事准备状态。至少必须提供一个字段以进行更新。

link-tickets

使用指定的关系类型将两个JIRA工单链接在一起。

参数：

outward_issue: 外部问题的键（必需，例如："PROJ-123"）
inward_issue: 内部问题的键（必需，例如："PROJ-456"）
link_type: 要创建的链接类型（可选，默认为"Test Case Linking"）

示例：

{
  "outward_issue": "PROJ-123",
  "inward_issue": "PROJ-456",
  "link_type": "Blocks"
}

这会在两个工单之间创建具有指定关系类型的链接。例如，"PROJ-123 blocks PROJ-456"。

get-test-steps

从Zephyr测试工单中检索测试步骤。

参数：

ticket_key: 要从中检索步骤的测试工单的键（必需，例如："PROJ-123"）

示例：

{
  "ticket_key": "PROJ-123"
}

此工具检索与Zephyr测试工单关联的所有测试步骤。响应包括每个步骤的步骤描述、测试数据和预期结果。

add-test-steps

通过Zephyr集成向测试工单添加测试步骤。

参数：

ticket_key: 要添加步骤的测试工单的键（必需，例如："PROJ-123"）
steps: 测试步骤对象数组（必需），其中每个步骤对象包含：
- step: 测试步骤的描述（必需）
- data: 步骤的测试数据（可选）
- result: 步骤的预期结果（可选）

示例：

{
  "ticket_key": "PROJ-123",
  "steps": [
    {
      "step": "导航到登录页面",
      "data": "https://example.com/login",
      "result": "显示登录表单"
    },
    {
      "step": "输入有效的凭据",
      "data": "username=test, password=password123",
      "result": "用户成功登录"
    }
  ]
}

此工具要求安装并配置了Zephyr for Jira Cloud。您需要在配置文件中设置Zephyr API环境变量。

项目架构

该项目遵循模块化架构，明确划分关注点：

jira-mcp/
├── src/                      # 源代码
│   ├── index.ts              # 主入口点
│   ├── utils.ts              # 共享实用函数
│   ├── jira/                 # JIRA集成模块
│   │   ├── api.ts            # JIRA API交互函数
│   │   ├── formatting.ts     # JIRA内容格式化实用工具
│   │   ├── index.ts          # JIRA模块导出
│   │   ├── tools.ts          # JIRA MCP工具注册
│   │   └── types.ts          # JIRA类型定义
│   └── zephyr/               # Zephyr集成模块
│       ├── auth.ts           # Zephyr认证实用工具
│       ├── index.ts          # Zephyr模块导出
│       ├── test-steps.ts     # Zephyr测试步骤API函数
│       ├── tools.ts          # Zephyr MCP工具注册
│       └── types.ts          # Zephyr类型定义
├── util/                     # 实用脚本
│   └── update-mcp-settings.js # 更新MCP设置的脚本
├── package.json              # 项目元数据和依赖项
└── tsconfig.json             # TypeScript配置

核心组件

MCP服务器

应用程序使用@modelcontextprotocol/sdk包创建一个MCP服务器。此服务器公开可用于AI助手与JIRA和Zephyr交互的工具。

// src/index.ts
const server = new McpServer({
  name: "jira-mcp",
  version: "1.0.0",
});

// 注册工具
registerJiraTools(server);
registerZephyrTools(server);

// 使用stdio传输连接
const transport = new Stdio

杰拉-MCP

项目介绍

JIRA MCP 集成

概述

目录

特性

安装

配置

配置位置

配置模板

基本配置

必需配置

可选配置

测试工单创建

Zephyr集成

自定义字段配置

产品字段配置（可选）

类别字段配置（可选）

最小配置示例

查找自定义字段ID

可用工具

create-ticket

get-ticket

search-tickets

update-ticket

link-tickets

get-test-steps

add-test-steps

项目架构

核心组件

MCP服务器