mcpField
A
atlassian-mcp

atlassian-mcp

github.com/farmage生产力218270 次安装5 周前更新
代码仓库

关于 atlassian-mcp

面向 Atlassian 集成开发与运维的技能，指导配置 MCP 服务、认证方式及 Jira 和 Confluence 查询，并强调权限验证与安全操作。

主要功能

  1. 01选择官方、开源或自托管服务
  2. 02配置 OAuth、API Token 或 PAT
  3. 03编写 Jira JQL 与 Confluence CQL
  4. 04处理分页、限流和错误恢复
  5. 05执行写入前验证权限

适用场景

  1. 01按条件查询 Jira 问题
  2. 02搜索或创建 Confluence 页面
  3. 03同步会议记录到 Jira 工单
  4. 04排查 Atlassian API 集成问题

MCP 相关

指导选择、配置和认证 Atlassian MCP 服务，并说明其 Jira 与 Confluence 工作流。包括查询设计、工具调用、权限检查和部署注意事项。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/farmage/opencode-skills --skill atlassian-mcp

安装后在 Claude Code 中输入/atlassian-mcp确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
authentication-patterns.md
common-workflows.md
confluence-operations.md
jira-queries.md
mcp-server-setup.md

详细介绍

Atlassian MCP 专家

何时使用此技能

  • 使用 JQL 过滤器查询 Jira 问题
  • 搜索或创建 Confluence 页面
  • 自动化冲刺工作流和待办事项管理
  • 设置 MCP 服务身份验证（OAuth/API 令牌）
  • 将会议记录同步到 Jira 工单
  • 根据问题数据生成文档
  • 调试 Atlassian API 集成问题
  • 在官方与开源 MCP 服务之间做出选择

核心工作流

  1. 选择服务 - 选择官方云服务、开源或可自托管的 MCP 服务
  2. 身份验证 - 配置 OAuth 2.1、API 令牌或 PAT 凭据
  3. 设计查询 - 为 Jira 编写 JQL，为 Confluence 编写 CQL；先使用 maxResults=1 验证，再完整执行
  4. 实现工作流 - 构建工具调用，处理分页和错误恢复
  5. 验证权限 - 在任何写入或批量操作前，通过只读探测确认所需的权限范围
  6. 部署 - 配置 IDE 集成，测试权限并监控速率限制

参考指南

根据上下文加载详细指南：

主题参考资料加载时机
服务设置references/mcp-server-setup.md安装、选择服务、配置
Jira 操作references/jira-queries.mdJQL 语法、问题的增删改查、冲刺、看板、问题关联
Confluence 操作references/confluence-operations.mdCQL 搜索、页面创建、空间、评论
身份验证references/authentication-patterns.mdOAuth 2.0、API 令牌、权限范围
常见工作流references/common-workflows.md问题分类、文档同步、冲刺自动化

快速入门示例

JQL 查询示例
# Open issues assigned to current user in a sprint
project = PROJ AND status = "In Progress" AND assignee = currentUser() ORDER BY priority DESC

# Unresolved bugs created in the last 7 days
project = PROJ AND issuetype = Bug AND status != Done AND created >= -7d ORDER BY created DESC

# Validate before bulk: test with maxResults=1 first
project = PROJ AND sprint in openSprints() AND status = Open ORDER BY created DESC
CQL 查询示例
# Find pages updated in a specific space recently
space = "ENG" AND type = page AND lastModified >= "2024-01-01" ORDER BY lastModified DESC

# Search page text for a keyword
space = "ENG" AND type = page AND text ~ "deployment runbook"
最小 MCP 服务配置
{
  "mcpServers": {
    "atlassian": {
      "command": "npx",
      "args": ["-y", "@sooperset/mcp-atlassian"],
      "env": {
        "JIRA_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "${JIRA_API_TOKEN}",
        "CONFLUENCE_URL": "https://your-domain.atlassian.net/wiki",
        "CONFLUENCE_EMAIL": "[email protected]",
        "CONFLUENCE_API_TOKEN": "${CONFLUENCE_API_TOKEN}"
      }
    }
  }
}

注意： 始终从环境变量或密钥管理器加载 JIRA_API_TOKEN 和 CONFLUENCE_API_TOKEN，切勿将凭据硬编码。

限制

必须做到
  • 遵守用户权限和工作区访问控制
  • 执行前验证 JQL/CQL 查询（先使用 maxResults=1 进行探测）
  • 使用指数退避处理速率限制
  • 对大型结果集使用分页（每页 50-100 项）
  • 为网络故障实现错误恢复
  • 记录 API 调用，以便调试和审计追踪
  • 先使用只读操作进行测试
  • 记录所需的权限范围
  • 对生产数据执行任何写入或批量操作前，先确认
禁止事项
  • 在代码中硬编码 API 令牌或 OAuth 密钥
  • 忽略 Atlassian API 返回的速率限制响应头
  • 未验证必填字段就创建问题
  • 跳过对用户提供的查询字符串进行输入清理
  • 未测试权限边界就部署
  • 未经确认提示就更新生产数据
  • 在同一会话中混用不同的身份验证方式
  • 在日志或错误消息中暴露敏感的问题数据

输出模板

实现 Atlassian MCP 功能时，请提供：

  1. MCP 服务配置（JSON/环境变量）
  2. 查询示例（附说明的 JQL/CQL）
  3. 带错误处理的工具调用实现
  4. 身份验证设置说明
  5. 权限要求简要说明

文档

评论

支持 Markdown