Jira上下文MCP协议实现

Jira上下文MCP

Jira的模型上下文协议（MCP）实现，允许您：

• 输入Jira票证链接以获取问题详细信息，并指示Cursor进行修复
• 检索指定Jira项目中分配给您的所有票证
• 根据特定问题类型过滤Jira问题，并自动指示Cursor解决这些问题
• 管理史诗：创建新史诗，将问题链接到史诗，并查看史诗层次结构
• 更新问题工作流程：在不离开IDE的情况下转换问题并添加评论
• 通过过滤已完成的任务来关注待处理的工作
• 与Jira的API无缝集成，实现自动化和效率

设置

先决条件

• Node.js 20.17.0或更高版本
• 具有API访问权限的Jira帐户
• Jira API令牌（可以在 大西洋API代币)

安装

1. 克隆此存储库：

   复制

   git clone https://github.com/yourusername/Jira-Context-MCP.git
   cd Jira-Context-MCP
   

2. 安装依赖项：

   复制

   npm install
   # or if you use pnpm
   pnpm install
   

3. 创建一个 .env 基于示例的文件：

   复制

   cp .env.example .env
   

4. 编辑 .env 使用服务器身份验证令牌的文件：

   复制

   MCP_AUTH_TOKEN=change-me
   HTTP_PORT=3000
   

构建

使用以下内容构建项目：

npm run build
# or
pnpm build

用法

启动服务器

启动HTTP服务器：

npm start
# or
pnpm start

注意：在HTTP模式下，Jira凭据由每个客户端通过标头提供。服务器无法读取 JIRA_* 从 .env.

或者使用CLI模式：

npm run start:cli
# or
pnpm start:cli

CLI模式需要 JIRA_BASE_URL, JIRA_USERNAME，以及 JIRA_API_TOKEN 在调用时通过环境变量提供。

在Cloudflare Workers（持久对象）上运行

此存储库现在包含一个Worker运行时，该运行时具有持久对象支持的MCP会话处理功能，可提供强大的、有状态的流式HTTP支持。

1. 为Wrangler创建本地开发文件：

   复制

   cat > .dev.vars <<'EOF'
   MCP_AUTH_TOKEN=change-me
   EOF
   

2. 在本地运行：

   复制

   npm run dev:worker
   

3. 设置部署时机密：

   复制

   npx wrangler secret put MCP_AUTH_TOKEN
   

4. 部署：

   复制

   npm run deploy:worker
   

工人入口点： src/runtimes/worker/entry.ts

持久对象会话管理器： src/runtimes/worker/session-do.ts

可选的端到端烟雾测试：

set -a && source .env.dev && set +a
npm run smoke:worker

用户身份验证（注册/登录/令牌）

Worker运行时现在支持使用D1的基于用户的API令牌。

1. 创建D1数据库：

   复制

   bunx wrangler d1 create jira_mcp_auth
   

2. 将D1绑定添加到 wrangler.toml:

   复制

   [[d1_databases]]
   binding = "AUTH_DB"
   database_name = "jira_mcp_auth"
   database_id = "<DATABASE_ID_FROM_CREATE_OUTPUT>"
   

3. 应用架构：

   复制

   bunx wrangler d1 execute jira_mcp_auth --file migrations/auth/0001_init_auth.sql
   

4. 使用身份验证端点：

   • POST /auth/register 随着 { "email": "...", "password": "..." }
   • POST /auth/login 随着 { "email": "...", "password": "..." }
   • GET /auth/me 随着 Authorization: Bearer mcp_...
   • GET /auth/tokens 随着 Authorization: Bearer mcp_...
   • POST /auth/tokens 随着 Authorization: Bearer mcp_...
   • POST /auth/tokens/revoke 随着 Authorization: Bearer mcp_... 和 { "tokenId": "..." }

/auth/login 返回每个用户的承载令牌(mcp_...)其可用于MCP请求。

令牌持久性行为：

• 令牌存储在D1中，并在Worker重启和部署期间保持有效。
• 集 neverExpires: true （或 expiresInDays: 0)发行不过期的代币。
• 使用以下方式撤销代币 /auth/tokens/revoke 立即失效。

如果您更喜欢浏览器流而不是curl，请打开身份验证控制台UI：

• 运行React应用程序：

  复制

  bun --cwd auth-ui install
  bun run dev:auth-ui
  

• 打开： http://localhost:5173/auth

Vite应用程序使用React Router和代理 /auth/register, /auth/login, /mcp，以及 /health 到Worker运行时。

代理目标默认为 http://localhost:8787 并且可以通过以下方式进行更改：

VITE_PROXY_TARGET=https://jira-context-mcp-preview.contacto-80f.workers.dev bun run dev:auth-ui

auth控制台允许您注册、登录、复制用户令牌，并运行快速的MCP初始化/工具测试。

要在Worker中发布UI，请使用资产构建和部署：

bun run deploy:worker:with-ui

使用UI资产预览部署：

bun run deploy:worker:preview:with-ui

已发布的UI路径：

• 预览： https://jira-context-mcp-preview.contacto-80f.workers.dev/auth
• 生产： https://jira-mcp-server.creax-ai.com/auth

与游标连接

1. 在光标中，打开命令面板（Ctrl+Shift+P或Cmd+Shift+P）
2. 类型 “连接到MCP服务器”
3. 选择 “连接到MCP服务器”
4. 输入服务器URL（建议： http://localhost:3000/mcp 对于节点或 http://localhost:8787/mcp 工人开发）
5. 在MCP客户端中配置这些标头（HTTP模式需要）：
   复制

   Authorization: Bearer <MCP_AUTH_TOKEN>
   X-Jira-Base-Url: https://your-domain.atlassian.net
   X-Jira-Username: your-email@example.com
   X-Jira-Api-Token: your-api-token-here
   

如果您的MCP客户端无法发送Jira标头，您可以将Jira参数作为查询参数传递给 /mcp （不太安全）： http://localhost:3000/mcp?jiraBaseUrl=...&jiraUsername=...&jiraApiToken=...

用于手册 curl 使用流式HTTP进行测试，包括中的两种内容类型 Accept: Accept: application/json, text/event-stream

可用工具

连接后，您可以在Cursor中使用以下工具：

1.获取Jira问题详细信息

获取有关特定Jira问题的详细信息：

/get_issue issueKey:PROJECT-123

2.获取分配的问题

检索特定项目中分配给您的问题：

/get_assigned_issues projectKey:PROJECT maxResults:10

3.按类型获取问题

按类型筛选问题（Bug、Story、Epic等）：

/get_issues_by_type issueType:Bug projectKey:PROJECT maxResults:10

4.获取项目

列出所有可用项目：

/get_projects

5.获取问题类型

列出所有可用的问题类型：

/get_issue_types

6.获取待处理的分配问题

仅检索分配给您的不完整问题（不包括“完成”状态）：

/get_pending_assigned_issues projectKey:PROJECT maxResults:10

7.获取Epics

从项目中检索所有重大问题：

/get_epics projectKey:PROJECT maxResults:10

8.获得Epic儿童

获取属于特定史诗的所有儿童问题：

/get_epic_children epicKey:PROJECT-123 maxResults:50

9.添加评论

为现有的Jira问题添加评论：

/add_comment issueKey:PROJECT-123 comment:"Updated the implementation as discussed"

10.获取问题转换

列出问题的所有可用工作流转换：

/get_issue_transitions issueKey:PROJECT-123

11.过渡问题

使用转换ID将问题移动到其他状态：

/transition_issue issueKey:PROJECT-123 transitionId:31

12.创建Epic

在项目中创建新史诗：

/create_epic projectKey:PROJECT summary:"Q1 2024 Features" description:"Epic for all Q1 feature development"

13.与家长产生问题

创建一个链接到父史诗的新问题：

/create_issue_with_parent projectKey:PROJECT issueType:Story summary:"Implement user authentication" parentKey:PROJECT-100 description:"Add OAuth2 login flow"

14.设置父问题

将问题链接到家长（适用于史诗→问题与议题→子任务关系）：

/set_parent_issue issueKey:PROJECT-456 parentKey:PROJECT-100

15.更新问题描述

替换现有Jira问题的描述：

/update_issue_description issueKey:PROJECT-123 description:"New detailed description with acceptance criteria"

16.获取链接类型

获取所有可用的问题链接类型，以了解关系选项：

/get_link_types

这将返回以下链接类型：

• 积木：“阻止”/“被阻止”
• 重复：“副本”/“复制人”
• 相关：“相关”/“相关”

17.链接问题

在两个问题（块、关联、重复等）之间建立关系：

/link_issues inwardIssue:PROJECT-105 outwardIssue:PROJECT-54 linkType:"Blocks" comment:"Bug fix must be completed before feature"

备注：对于“阻止”链接，内部问题是进行阻止的问题，外部问题是被阻止的问题。

命令示例

🚀 Jira MCP服务器+Cursor IDE=您的AI助手！ 以下是它如何让开发人员更聪明地工作：

📂 “列出我有权访问的所有Jira项目”
→ AI立即获取所有可用项目
不再手动搜索！

📋 “列出项目中的所有问题”
→ AI检索所有未结门票
不费吹灰之力，保持条理！

🐛 “仅筛选Bug或更改请求并修复它们”
→ AI识别并指示Cursor解决这些问题
通过自动化更快地解决问题！

✅ “找到分配给我的所有门票并修复它们”
→ AI提取您的任务并让Cursor处理它们
零烦恼地专注于你的工作！

🔍 “获取Jira问题PROJECT-123的详细信息”
→ AI在几秒钟内获取完整的问题信息
不再切换标签！

📊 “PROJECT过去7天的门票有什么变化？”
→ AI跟踪最近的更新并突出关键变化
不再手动检查机票历史记录！

💬 “在PROJECT-123中添加一条评论，说‘已在最新提交中修复’”
→ AI将评论直接发布到Jira
无需离开IDE即可更新门票！

🎯 “向我展示PROJECT中的所有史诗及其儿童问题”
→ AI立即获取史诗般的层次结构
一目了然地了解项目结构！

📝 “在PROJECT中创建一个名为“移动应用程序重新设计”的史诗”
→ AI为你创造史诗
通过自动化更快地规划项目！

🔗 “将问题PROJECT-456链接到父项目-100”
→ AI设置父关系（适用于史诗或子任务）
使用灵活的层次结构组织您的待办事项列表！

⚡ “将项目123移至进行中”
→ AI通过您的工作流程转换问题
在不切换上下文的情况下更新状态！

🖊️ “用新的验收标准重写项目123的描述”
→ AI取代Jira中的问题描述
保持产品文档和开发上下文同步！

🔗 “显示可用的链接类型”
→ AI获取所有问题链接类型（块、关联、重复等）
了解你的关系选择！

🚫 “PROJECT-105阻止PROJECT-54，因为需要先修复错误”
→ AI通过评论在问题之间创建“块”链接
自动跟踪依赖关系和阻止程序！

🔥 太长，读不下去了 你的AI现在会说Jira+Cursor！获取项目、过滤问题、跟踪更改、管理史诗、链接相关问题、添加评论、编辑描述和修复错误——所有这些都在IDE中。
从积压到bug修复，MCP Server让Jira为您工作！

示例工作流

修复特定Bug

1. 在Cursor中连接到Jira MCP服务器。
2. 获取问题详细信息：
   复制

   /get_issue issueKey:PROJECT-123
   

3. 查看问题详细信息并指示Cursor进行修复：
   复制

   Fix the bug described in PROJECT-123
   

处理分配的问题

1. 在Cursor中连接到Jira MCP服务器。
2. 检索您分配的问题：
   复制

   /get_assigned_issues projectKey:PROJECT
   

3. 请Cursor帮助解决以下问题之一：
   复制

   Help me solve the first issue in my assigned list
   

修复项目中的所有Bug

1. 在Cursor中连接到Jira MCP服务器。
2. 检索所有错误问题：
   复制

   /get_issues_by_type issueType:Bug projectKey:PROJECT
   

3. 指示光标：
   复制

   Help me fix these bugs one by one
   

查看最近的更改

1. 在Cursor中连接到Jira MCP服务器。
2. 检索最近的工单更新：
   复制

   /get_recent_changes projectKey:PROJECT maxDays:7
   

3. 查看更改以了解修改的最新情况。

计划和追踪史诗

1. 在Cursor中连接到Jira MCP服务器。
2. 创建一个新的史诗：
   复制

   /create_epic projectKey:PROJECT summary:"Q1 2024 Mobile Features" description:"All mobile app features for Q1"
   

3. 在史诗下创建儿童问题：
   复制

   /create_issue_with_parent projectKey:PROJECT issueType:Story summary:"Add push notifications" parentKey:PROJECT-100
   

4. 将现有问题与史诗联系起来：
   复制

   /set_parent_issue issueKey:PROJECT-456 parentKey:PROJECT-100
   

5. 查看所有史诗儿童以跟踪进度：
   复制

   /get_epic_children epicKey:PROJECT-100
   

更新问题状态并添加评论

1. 在Cursor中连接到Jira MCP服务器。
2. 获取问题的可用转换：
   复制

   /get_issue_transitions issueKey:PROJECT-123
   

3. 将问题移动到新状态：
   复制

   /transition_issue issueKey:PROJECT-123 transitionId:31
   

4. 添加注释解释更改：
   复制

   /add_comment issueKey:PROJECT-123 comment:"Moved to In Progress. Starting implementation today."
   

5. 使用最新详细信息更新描述：
   复制

   /update_issue_description issueKey:PROJECT-123 description:"Implementation plan: 1) Add API validation 2) Update UI components 3) Add tests"
   

专注于待完成的工作

1. 在Cursor中连接到Jira MCP服务器。
2. 只获取未完成的任务：
   复制

   /get_pending_assigned_issues projectKey:PROJECT
   

3. 请Cursor帮助确定优先级：
   复制

   Show me the highest priority pending issues and help me plan my day
   

链接相关问题和跟踪依赖关系

1. 在Cursor中连接到Jira MCP服务器。
2. 发现可用的链接类型：
   复制

   /get_link_types
   

3. 创建“块”关系（例如，在功能之前必须完成错误修复）：
   复制

   /link_issues inwardIssue:PROJECT-105 outwardIssue:PROJECT-54 linkType:"Blocks" comment:"Bug in PPG calculation must be fixed before Matchweek Bonus feature"
   

4. 链接重复问题：
   复制

   /link_issues inwardIssue:PROJECT-200 outwardIssue:PROJECT-198 linkType:"Duplicate"
   

5. 将应共同解决的问题联系起来：
   复制

   /link_issues inwardIssue:PROJECT-50 outwardIssue:PROJECT-51 linkType:"Relates"
   

备注：对于“阻止”链接，内向问题会阻止外向问题。因此，如果项目105阻止了项目54，在项目105完成之前，您无法完成项目54。

发展

项目结构

• src/ -源代码
  • services/ -Jira API服务
  • types/ -TypeScript类型定义
  • utils/ -实用功能
  • server.ts -MCP服务器实现
  • index.ts -应用程序入口点
  • cli.ts -CLI入口点

添加新工具

要添加新工具，请编辑 src/server.ts 在文件中添加新的工具定义 registerTools 方法。

许可证

麻省理工学院

作者

拉胡尔·戴- @拉胡尔代维奇