SKILL.md
readonly只读
name
atlassian-mcp
description
与Atlassian产品集成，通过MCP协议管理项目跟踪和文档。适用于使用JQL过滤器查询Jira问题、创建和更新自定义字段的工单、使用CQL搜索或编辑Confluence页面、管理冲刺和待办事项、设置MCP服务器认证、同步文档或调试Atlassian API集成。
Atlassian MCP 专家
何时使用此技能
- 使用JQL过滤器查询Jira问题
- 搜索或创建Confluence页面
- 自动化冲刺工作流和待办事项管理
- 设置MCP服务器认证（OAuth/API令牌）
- 将会议记录同步到Jira工单
- 从问题数据生成文档
- 调试Atlassian API集成问题
- 在官方与开源MCP服务器之间选择
核心工作流
- 选择服务器 - 选择官方云、开源或自托管MCP服务器
- 认证 - 配置OAuth 2.1、API令牌或PAT凭据
- 设计查询 - 为Jira编写JQL，为Confluence编写CQL；在完整执行前使用
maxResults=1验证 - 实现工作流 - 构建工具调用，处理分页，错误恢复
- 验证权限 - 在任何写入或批量操作前，通过只读探测确认所需范围
- 部署 - 配置IDE集成，测试权限，监控速率限制
参考指南
根据上下文加载详细指导：
| 主题 | 参考 | 加载时机 |
|---|---|---|
| 服务器设置 | references/mcp-server-setup.md |
安装、选择服务器、配置 |
| Jira操作 | references/jira-queries.md |
JQL语法、问题CRUD、冲刺、看板、问题链接 |
| Confluence操作 | references/confluence-operations.md |
CQL搜索、页面创建、空间、评论 |
| 认证 | references/authentication-patterns.md |
OAuth 2.0、API令牌、权限范围 |
| 常见工作流 | references/common-workflows.md |
问题分类、文档同步、冲刺自动化 |
快速入门示例
JQL查询示例
# 当前用户在一个冲刺中分配到的未关闭问题
project = PROJ AND status = "In Progress" AND assignee = currentUser() ORDER BY priority DESC
# 过去7天内创建的未解决缺陷
project = PROJ AND issuetype = Bug AND status != Done AND created >= -7d ORDER BY created DESC
# 批量操作前验证：先用maxResults=1测试
project = PROJ AND sprint in openSprints() AND status = Open ORDER BY created DESC
CQL查询示例
# 查找特定空间中最近更新的页面
space = "ENG" AND type = page AND lastModified >= "2024-01-01" ORDER BY lastModified DESC
# 搜索页面文本中的关键词
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": "user@example.com",
"JIRA_API_TOKEN": "${JIRA_API_TOKEN}",
"CONFLUENCE_URL": "https://your-domain.atlassian.net/wiki",
"CONFLUENCE_EMAIL": "user@example.com",
"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功能时，提供：
- MCP服务器配置（JSON/环境变量）
- 查询示例（JQL/CQL及说明）
- 带错误处理的工具调用实现
- 认证设置说明
- 权限要求的简要说明
