JIRA MCP 服务器

这是一个实现了模型上下文协议（MCP）的服务器，提供了对JIRA数据的访问，包括关系跟踪、优化的数据负载以及为AI上下文窗口进行的数据清理。

ℹ️ 对于Confluence有一个单独的MCP服务器链接

特性

• 使用JQL搜索JIRA问题（每次请求最多50条结果）
• 检索包含评论历史和优化负载的史诗子项（每次请求最多100个问题）
• 获取详细的问题信息，包括评论和相关问题
• 创建、更新和管理JIRA问题
• 从Atlassian文档格式中提取问题提及
• 跟踪问题关系（提及、链接、父/子、史诗）
• 清理并转换丰富的JIRA内容以提高AI上下文效率
• 支持带有安全多部分上传处理的文件附件

前提条件

• Bun (v1.0.0或更高版本)
• 具有API访问权限的JIRA账户

环境变量

JIRA_API_TOKEN=your_api_token
JIRA_BASE_URL=your_jira_instance_url  # e.g., https://your-domain.atlassian.net
JIRA_USER_EMAIL=your_email

安装与设置

1. 克隆仓库：

git clone [repository-url]
cd jira-mcp

2. 安装依赖并构建：

bun install
bun run build

3. 配置MCP服务器：

编辑相应的配置文件：

macOS:

• Cline: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

• Cline: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
• Claude Desktop: %APPDATA%\Claude Desktop\claude_desktop_config.json

Linux:

• Cline: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
• Claude Desktop: 目前尚不存在

在mcpServers对象下添加以下配置：

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["/absolute/path/to/jira-mcp/build/index.js"],
      "env": {
        "JIRA_API_TOKEN": "your_api_token",
        "JIRA_BASE_URL": "your_jira_instance_url",
        "JIRA_USER_EMAIL": "your_email"
      }
    }
  }
}

4. 重启MCP服务器。

在Cline的MCP设置中重启MCP服务器。重启Claude Desktop以加载新的MCP服务器。

开发

运行测试：

bun test

开发中的监视模式：

bun run dev

更改后重新构建：

bun run build

可用的MCP工具

search_issues

使用JQL搜索JIRA问题。每次请求最多返回50条结果。

输入模式：

{
  searchString: string // JQL search string
}

get_epic_children

获取史诗中的所有子问题及其评论和关系数据。每次请求限制为100个问题。

输入模式：

{
  epicKey: string // The key of the epic issue
}

get_issue

获取特定JIRA问题的详细信息，包括评论和所有关系。

输入模式：

{
  issueId: string // The ID or key of the JIRA issue
}

create_issue

创建具有指定字段的新JIRA问题。

输入模式：

{
  projectKey: string, // The project key where the issue will be created
  issueType: string, // The type of issue (e.g., "Bug", "Story", "Task")
  summary: string, // The issue summary/title
  description?: string, // Optional issue description
  fields?: { // Optional additional fields
    [key: string]: any
  }
}

update_issue

更新现有JIRA问题的字段。

输入模式：

{
  issueKey: string, // The key of the issue to update
  fields: { // Fields to update
    [key: string]: any
  }
}

add_attachment

向JIRA问题添加文件附件。

输入模式：

{
  issueKey: string, // The key of the issue
  fileContent: string, // Base64 encoded file content
  filename: string // Name of the file to be attached
}

数据清理特性

• 从 Atlassian 文档格式中提取文本
• 跟踪描述和评论中的问题提及
• 维护具有关系类型的形式问题链接
• 保持父/子关系
• 跟踪史诗关联
• 包含带有作者信息的评论历史
• 从响应中移除不必要的元数据
• 递归处理内容节点以查找提及
• 去重问题提及

技术细节

• 使用严格模式下的 TypeScript 构建
• 使用 Bun 运行时以提高性能
• Vite 用于优化构建
• 使用 JIRA REST API v3
• 通过 API 令牌进行基本身份验证
• 批量处理相关数据的 API 请求
• 针对 AI 上下文窗口优化响应负载
• 高效转换复杂的 Atlassian 结构
• 强健的错误处理
• 考虑了速率限制
• 最大限制：
  • 搜索结果：每次请求 50 个问题
  • 史诗子项：每次请求 100 个问题
• 支持安全文件附件的多部分表单数据
• 自动检测和验证内容类型

错误处理

服务器实现了全面的错误处理策略：

• 网络错误检测及适当的消息提示
• HTTP 状态码处理（特别是针对问题的 404 错误）
• 附带状态码的详细错误消息
• 将错误详情记录到控制台
• 对所有参数进行输入验证
• 通过 MCP 协议安全地传播错误
• 对常见的 JIRA API 错误进行专门处理
• 附件的 Base64 验证
• 多部分请求失败处理
• 速率限制检测
• 附件参数验证

许可证

本项目根据 MIT 许可证发布 - 有关详细信息，请参阅 LICENCE 文件。