1. 项目概述与核心价值如果你和我一样每天的工作都离不开 Jira 和 Confluence那你肯定也经历过这样的场景想给一个 Jira 任务上传个截图得手动打开网页点开附件再拖拽上传想看看团队下周谁休假得去 Confluence 日历里一个个翻或者想批量把几个任务移进下一个冲刺只能一个个手动拖拽。这些操作虽然不复杂但重复多了效率就被一点点磨掉了。尤其是在和 AI 助手协作时你希望它能直接帮你操作这些系统而不是仅仅给你一个“你可以去 Jira 上做这个”的建议。这就是mcp-atlassian-extended这个项目诞生的背景。它是一个基于Model Context Protocol (MCP)的服务器你可以把它理解为一个“翻译官”或“桥梁”。它的核心作用是让 Claude Desktop、Cursor、VS Code Copilot 这类支持 MCP 的 AI 助手能够直接、安全地调用你公司 Jira 和 Confluence 的 API执行一系列原本需要手动操作的任务。这个项目并非凭空创造而是对现有优秀项目mcp-atlassian的一个强力补充。mcp-atlassian已经很好地覆盖了问题创建、搜索、评论等基础功能而mcp-atlassian-extended则专注于填补那些空白地带比如附件管理、敏捷看板操作、用户搜索、项目版本管理使用更现代的 v2 API以及 Confluence 的团队日历和休假管理。它新增了26 个工具、15 个资源文档和 5 个预设工作流让 AI 助手在项目管理场景下的能力得到了质的提升。简单来说它的价值在于“将 AI 的智能与现有工具的 API 能力无缝结合”。无论是开发人员想通过 AI 快速创建带附件的工单还是项目经理想让 AI 帮忙规划冲刺容量并考虑成员休假这个工具都能让这些流程变得自动化、可对话。接下来我会带你深入拆解它的设计思路、具体怎么用以及我在部署和实践中总结出的一些关键技巧和避坑指南。1.1 核心需求与场景解析在深入技术细节之前我们先明确一下到底谁需要这个工具以及它解决了哪些具体痛点。目标用户画像软件开发团队尤其是使用 Scrum 或 Kanban 的敏捷团队。开发人员、测试人员、Scrum Master 和产品负责人都会从中受益。DevOps 或 SRE 工程师需要快速创建、跟踪和关闭事件工单并关联文档或日志附件。技术项目经理负责跨团队协调、版本发布规划和资源调度。任何频繁使用 Jira/Confluence 并与 AI 助手协同工作的知识工作者。核心解决的痛点上下文切换成本高在 IDE、终端、AI 聊天窗口和浏览器中的 Jira/Confluence 之间来回切换打断心流。重复性手动操作批量处理任务如移动冲刺、更新状态、管理附件上传/下载、查询团队可用性等。信息查询效率低快速回答“这个任务的附件有哪些”、“张三下周哪天休假”、“PROJ 项目下有哪些未发布的版本”这类问题无需离开当前工作环境。工作流自动化将“创建工单-设置自定义字段-关联文档-分配”等一系列操作封装成一个 AI 可执行的连贯流程。mcp-atlassian-extended的设计哲学很明确互补而非替代。它与mcp-atlassian服务器协同工作各自负责一部分 API 能力共同为 AI 助手提供一套完整的 Atlassian 生态操作界面。这种设计避免了功能重叠也使得每个服务器的职责更加清晰维护起来也更方便。2. 架构设计与核心组件解析要理解这个工具如何工作我们需要先拆解它的几个核心部分MCP 协议本身、FastMCP 框架以及本项目扩展的具体工具集。2.1 Model Context Protocol (MCP) 简介MCP 是一个新兴的开放协议由 Anthropic 提出旨在标准化 AI 应用程序与外部工具、数据源之间的通信方式。你可以把它想象成 AI 世界的“USB 协议”或“驱动程序模型”。在 MCP 模型下AI 客户端如 Claude Desktop, Cursor是发出指令的“大脑”。MCP 服务器如mcp-atlassian-extended是提供特定能力如操作 Jira的“手”或“工具库”。协议定义了他们之间对话的语言和规则通过 stdio 或 HTTP 传输 JSON-RPC 消息。一个 MCP 服务器会向客户端宣告三样东西工具 (Tools)客户端可以调用的函数例如jira_create_issue。资源 (Resources)客户端可以读取的静态或动态内容例如resource://guides/jql-library这个 URI 指向的 JQL 查询指南文档。提示词 (Prompts)预定义的多步骤工作流模板客户端可以将其呈现为“斜杠命令”例如/create_ticket。mcp-atlassian-extended就是一个实现了大量 Atlassian 相关 Tools, Resources 和 Prompts 的 MCP 服务器。2.2 技术栈与依赖分析项目基于 Python 构建选型非常务实和现代FastMCP这是底层框架由jlowin开发。它极大地简化了 MCP 服务器的创建过程开发者只需要用装饰器如mcp.tool()定义函数FastMCP 就会自动处理与 MCP 协议的对接、参数验证和结果返回。这避免了从头实现协议解析的复杂性。HTTPX一个现代化、功能齐全的 HTTP 客户端库支持同步和异步比传统的requests库性能更好并且原生支持 HTTP/2。项目用它来调用 Jira 和 Confluence 的 REST API。Pydantic用于数据验证和设置管理。所有工具函数的参数、环境变量的配置都通过 Pydantic 模型进行强类型校验这保证了输入数据的正确性减少了运行时错误。UV一个用 Rust 编写的极速 Python 包安装器和解析器。项目推荐使用uvx来运行这能保证依赖环境的隔离和一致性避免了全局 Python 环境可能带来的冲突。这个技术栈的选择体现了“稳定、高效、开发者友好”的原则。FastMCP 处理了 MCP 的复杂性让开发者聚焦业务逻辑即调用 Atlassian APIHTTPX 和 Pydantic 确保了网络交互和数据处理的可靠性UV 则优化了部署和运行体验。2.3 工具、资源与提示词的设计逻辑这是项目的核心扩展内容其设计并非随意堆砌 API而是经过了场景化思考。工具 (Tools) 的分类与场景工具被分成了 8 个逻辑类别覆盖了从问题管理到团队协作的完整链条。Jira 问题与附件create_issue和update_issue特别支持了自定义字段这是处理现实项目中复杂元数据的关键。附件工具链获取、上传、下载、删除实现了完整的文件生命周期管理。Jira 敏捷与冲刺get_board,get_sprint,move_to_sprint这几个工具直接支持了 Scrum Master 或开发者在冲刺规划会上的操作。backlog工具能快速拉取看板待办列表方便 AI 分析。Jira 版本管理get_project_versions,create_version,update_version使用了 Jira REST APIv2。这一点很重要因为 v2 API 在 Jira Cloud 和 Data Center 上行为更一致而旧的 v1 API 在某些操作上可能存在差异。这体现了项目对兼容性的细致考量。Confluence 日历与休假这是非常实用的扩展。who_is_out,get_time_off,sprint_capacity等工具将团队日历数据变成了可编程、可查询的资源直接赋能于冲刺容量规划和团队协调。注意工具的设计遵循了“单一职责”和“幂等性”原则。例如jira_update_issue既可以更新标准字段也可以更新自定义字段一次调用完成避免了多次 API 请求。同时大部分查询工具都是幂等的多次调用结果相同而写操作工具也通过参数校验和状态检查来尽量避免副作用。资源 (Resources) 的价值15 个资源文档是项目的“知识库”部分。它们不是动态数据而是静态的最佳实践指南例如《Jira 问题层级关系》、《故事点估算指南》、《JQL 查询库》等。当 AI 客户端加载这些资源后它在回答相关问题时如“如何写好验收标准”就能直接引用这些结构化的、高质量的内容而不是生成可能不准确或过于通用的建议。这极大地提升了 AI 在专业领域建议的准确性和实用性。提示词 (Prompts) 的工作流封装5 个预设提示词是更高层次的抽象。它们把多个工具调用组合成一个连贯的工作流。例如/plan_sprint提示词内部可能会依次调用jira_get_sprint获取冲刺信息-jira_backlog查看待办事项-confluence_sprint_capacity计算团队容量-jira_move_to_sprint移动问题。用户或 AI 只需要触发这个提示词并提供必要参数如看板 ID剩下的步骤由服务器引导完成。这降低了使用复杂度提供了开箱即用的自动化体验。3. 环境配置与安装部署详解理论讲完了我们进入实战环节。安装和配置是第一步这里有很多细节需要注意。3.1 前置条件与认证准备在安装服务器之前你必须先在 Atlassian 那边准备好 API 访问凭证。这是最关键的一步错误配置会导致服务器无法启动。对于 Jira/Confluence Cloud登录到https://id.atlassian.com/manage-profile/security/api-tokens。点击“创建 API 令牌”。为令牌起一个名字例如MCP-Server-Prod。重要记录下生成的令牌字符串。它只会显示一次丢失后需要重新创建。这个令牌需要和你用于登录 Jira/Confluence 的邮箱地址JIRA_USERNAME/CONFLUENCE_USERNAME配合使用进行 HTTP Basic Auth。对于 Jira/Confluence Data Center (自托管)在 Jira/Confluence 管理界面中为用户生成一个个人访问令牌。确保该令牌具有足够的权限项目浏览、问题创建、附件管理等详见后文权限章节。服务器支持通过JIRA_PAT、JIRA_PERSONAL_TOKEN或JIRA_TOKEN环境变量读取该令牌按此顺序查找。建议使用JIRA_PAT以保持清晰。权限梳理清单在创建令牌或配置用户权限时请对照下表检查。权限不足会导致工具调用返回403 Forbidden错误。操作场景所需 Jira 项目权限所需 Confluence 空间权限浏览项目、字段、看板浏览项目不涉及搜索用户浏览用户(全局权限)不涉及创建/编辑问题/史诗创建问题编辑问题不涉及创建/删除问题链接链接问题不涉及上传附件创建附件不涉及删除附件删除自己的附件(或删除所有附件)不涉及移动问题至冲刺管理冲刺(敏捷看板权限)不涉及创建/更新项目版本管理项目(项目管理员权限)不涉及访问 Confluence 日历/休假不涉及查看空间内容(对包含团队日历的空间)3.2 多种安装方式实操项目提供了从“一键点击”到“手动配置”的多种安装方式适配不同的 AI 客户端。1. 一键安装推荐给 Cursor 和 VS Code 用户这是最快捷的方式。项目作者提供了一个部署在 GitHub Pages 上的安装网关页面。对于Cursor直接点击项目 README 中的[![Install in Cursor]徽章按钮。这会触发 Cursor 的 deep link 协议自动打开客户端并引导你完成配置。对于VS Code / VS Code Insiders点击对应的徽章按钮页面会给出详细的配置步骤通常需要你将一段 JSON 配置复制到你的settings.json或.vscode/mcp.json文件中。2. 使用 UVX 命令行安装通用方法如果你的 AI 客户端支持通过命令行添加 MCP 服务器如 Claude Code, Gemini CLI这是最灵活的方式。# 首先确保系统已安装 uv # 安装 uv 的通用命令使用 curl curl -LsSf https://astral.sh/uv/install.sh | sh # 对于 Claude Code claude mcp add atlassian-extended -- uvx mcp-atlassian-extended执行命令后Claude Code 会引导你交互式地输入JIRA_URL,JIRA_USERNAME等环境变量。这种方式配置会被保存在 Claude Code 的本地配置中。3. 手动配置文件编辑对于 Windsurf、IntelliJ 或希望精细控制的 VS Code 用户需要手动编辑 MCP 配置文件。Windsurf配置文件位于~/.codeium/windsurf/mcp_config.json。IntelliJ在Settings | Tools | MCP Servers中添加。VS Code在项目根目录创建.vscode/mcp.json或在用户全局设置中配置。配置文件的核心结构如下{ mcpServers: { atlassian-extended: { command: uvx, args: [mcp-atlassian-extended], env: { JIRA_URL: https://your-company.atlassian.net, JIRA_USERNAME: your.emailcompany.com, JIRA_API_TOKEN: your_api_token_here, CONFLUENCE_URL: https://your-company.atlassian.net/wiki, CONFLUENCE_USERNAME: your.emailcompany.com, CONFLUENCE_API_TOKEN: your_api_token_here, // 可选配置 ATLASSIAN_READ_ONLY: false, JIRA_TIMEOUT: 30 } } } }重要提示args中的uvx和mcp-atlassian-extended是固定的。env对象里的键值对才是你需要根据自己环境修改的。如果只配置 Jira 或只配置 Confluence服务器会自动只启用对应的那部分工具。3.3 环境变量配置详解与最佳实践环境变量是服务器的主要配置方式。除了必填的 URL 和认证信息一些可选配置能帮你更好地适应生产环境。安全与网络调优配置ATLASSIAN_READ_ONLYtrue这是我最推荐的初始调试配置。将其设为true后所有会修改数据的工具创建、更新、删除、上传都会被服务器端直接拒绝返回只读错误。这让你可以安全地测试查询类工具而不用担心误操作产生脏数据。JIRA_TIMEOUT/CONFLUENCE_TIMEOUT默认 30 秒。如果你的网络到 Atlassian 实例较慢或者处理大量数据如导出所有项目版本可以适当调高例如60。JIRA_SSL_VERIFY/CONFLUENCE_SSL_VERIFY生产环境务必保持true。仅当你的自托管实例使用了自签名证书且你完全信任内部网络时才可将其设为false。设为false会带来中间人攻击风险。.env文件的使用服务器会自动从工作目录的.env文件中加载环境变量。这对于本地开发或不想在配置文件中明文存储令牌的情况非常有用。在项目根目录或你启动服务器的目录创建.env文件。内容格式如下JIRA_URLhttps://mycompany.atlassian.net JIRA_USERNAMEmecompany.com JIRA_API_TOKENyour_token_here CONFLUENCE_URLhttps://mycompany.atlassian.net/wiki CONFLUENCE_USERNAMEmecompany.com CONFLUENCE_API_TOKENyour_token_here ATLASSIAN_READ_ONLYfalse确保.env文件被添加到.gitignore中避免敏感信息泄露。部分配置的灵活性服务器设计得很灵活。如果你只设置了JIRA_*变量那么启动后只有 Jira 相关的工具可用Confluence 工具不会注册。反之亦然。这允许你根据实际需要只集成部分服务。4. 核心工具使用场景与实战示例配置好之后我们来看看这些工具在实际对话中如何发挥作用。以下是一些结合了 AI 助手如 Claude对话语境的典型用例。4.1 问题与附件管理实战场景一通过对话创建包含复杂字段的工单。用户对 AI 说“在 PROJECT 项目里创建一个类型为‘缺陷’的新问题摘要写‘登录页面在 Safari 浏览器上 CSS 错位’描述里附上重现步骤优先级设为‘高’把‘客户影响’自定义字段设为‘中等’故事点设为 3。”AI 的理解与执行AI 识别出这是一个创建问题的请求。它会调用jira_create_issue工具。project_keyPROJECTsummary登录页面在 Safari 浏览器上 CSS 错位issue_typeBugfields{priority: {name: High}}custom_fields{customfield_12345: Medium, customfield_10004: 3}(假设customfield_12345是‘客户影响’字段的 ID)实操心得这里的关键是获取自定义字段的 ID。你可以通过jira_list_fields工具查询所有字段及其 ID。通常故事点字段的 ID 是customfield_10004但其他自定义字段的 ID 每个 Jira 实例都可能不同。建议让 AI 先帮你查询一次或者自己通过 Jira 管理员后台获取。场景二为现有工单上传日志文件并关联另一个问题。用户“把刚才生成的错误日志app_error_20250415.log上传到问题 PROJECT-567 上并且把它和 PROJECT-568 关联起来关系是‘被…阻塞’。”AI 的执行序列调用jira_upload_attachment(issue_keyPROJECT-567, file_path./app_error_20250415.log)。这里file_path是 AI 所在环境的本地路径需要确保文件存在且可读。调用jira_create_link(link_typeBlocks, inward_issuePROJECT-568, outward_issuePROJECT-567)。这里inward和outward的关系是inward_issue(PROJECT-568)被outward_issue(PROJECT-567)阻塞。理解这个方向对建立正确的依赖关系很重要。4.2 敏捷冲刺与版本规划实战场景三规划下一个冲刺并考虑团队休假。用户“帮我规划看板 ID 为 5 的下一个冲刺。先看看团队成员是 Alice, Bob, Charlie在冲刺期间3月10日到21日的休假情况然后评估一下容量再从待办列表里选一些高优先级的故事加进去。”AI 的工作流容量计算调用confluence_sprint_capacity(team_members[Alice, Bob, Charlie], sprint_start2025-03-10, sprint_end2025-03-21)。这个工具会查询 Confluence 日历扣除成员的休假时间返回一个考虑了有效工作日的团队总容量通常以人天计。查看待办列表调用jira_backlog(board_id5, max_results100)获取看板待办事项列表并可能结合 JQL 过滤出高优先级的故事。分析并建议AI 结合容量和待办事项的复杂度故事点给出一个建议的冲刺范围列表例如[PROJECT-101, PROJECT-102, PROJECT-105]。执行移动用户确认后AI 调用jira_move_to_sprint(sprint_idnext_sprint_id, issue_keys[PROJECT-101, PROJECT-102, PROJECT-105])。场景四管理项目版本。用户“PROJECT 项目的下一个版本 ‘v2.1.0’ 计划在 4月1日发布帮我创建这个版本并把状态标记为‘未发布’。”AI 执行调用jira_create_version(project_keyPROJECT, namev2.1.0, release_date2025-04-01, releasedFalse)。releasedFalse对应“未发布”状态。当版本实际发布后你可以用jira_update_version(version_idversion_id, releasedTrue)来更新状态。4.3 资源与提示词的巧妙运用场景五利用资源文档指导工作。用户“我不太确定这个用户故事的定义是否完整有什么标准可以参考吗”AI 的响应AI 可以加载resource://rules/jira-ticket-writing和resource://rules/acceptance-criteria这两个资源。然后它会根据这些结构化指南来评估你的故事描述并给出具体的改进建议比如“根据最佳实践一个完整的用户故事描述应该包含角色、目标和价值。你的描述中缺少了‘作为一个…’的角色定义部分。”场景六使用预设提示词快速关闭工单。用户“使用/close_ticket流程来关闭问题 PROJECT-789。”AI 触发提示词AI 会执行close_ticket提示词定义的工作流。这个流程可能包括检查问题的“完成定义”清单是否全部满足可能需要调用jira_get_issue工具该工具可能来自基础的mcp-atlassian服务器。检查是否有关联的合并请求MR或代码提交可能需要集成 GitLab/GitHub 的 MCP 服务器。将问题状态过渡到“已完成”。添加一条格式规范的关闭评论。 这个过程将多个手动检查步骤自动化确保了工单关闭的规范性和完整性。5. 常见问题排查与安全实践在实际使用中你可能会遇到一些问题。下面是我总结的一些常见错误及其解决方法以及必须注意的安全事项。5.1 连接与认证问题排查问题现象可能原因排查步骤与解决方案服务器启动失败提示认证错误1. 环境变量未正确设置或加载。2. API 令牌无效或已撤销。3. 用户名/邮箱地址错误。4. (Data Center) PAT 权限不足。1.检查变量名确保是JIRA_API_TOKEN而不是JIRA_TOKEN(Cloud)。对于 DC检查JIRA_PAT。2.验证令牌用curl测试curl -u email:api_token $JIRA_URL/rest/api/2/myself(Cloud) 或curl -H Authorization: Bearer $JIRA_PAT $JIRA_URL/rest/api/2/myself(DC)。3.检查.env文件确保文件在正确的工作目录且格式正确无多余空格每行KEYVALUE。4.查看日志启动服务器时添加--verbose标志如果支持或查看客户端错误日志。工具调用返回403 Forbidden认证成功但令牌或用户缺少执行该操作的项目或全局权限。1. 对照前面的权限梳理清单检查执行该操作所需的具体权限。2. 联系 Jira/Confluence 管理员确认你的账户在相关项目/空间中的角色。3. 对于 Data Center检查 PAT 的权限范围是否包含了目标项目。工具调用返回404 Not Found请求的资源不存在。例如项目键错误、看板 ID 错误、问题键不存在。1.仔细核对参数确保project_key、board_id、issue_key等参数完全正确大小写敏感。2.使用查询工具验证先调用jira_list_projects确认项目键或jira_get_board确认看板 ID。3. 确认你使用的 Jira/Confluence 实例Cloud/DC是否支持该 API。附件上传/下载失败1. 文件路径错误或无权访问。2. 文件大小超过 Jira 限制通常 100MB。3. (下载) URL 验证失败。1.检查路径确保file_path是 AI 客户端可访问的绝对路径或相对路径。2.检查文件大小。3.下载安全服务器会验证下载 URL 是否属于配置的JIRA_URL域名这是防止服务器端请求伪造的安全措施。确保你的JIRA_URL配置正确。5.2 性能与限流处理速率限制 (Rate Limiting)Jira Cloud 对 API 调用有严格的速率限制。如果你短时间内通过 AI 密集调用工具可能会收到429 Too Many Requests错误。服务器会返回这个错误但处理策略取决于 AI 客户端。一些客户端可能会自动重试而另一些可能需要你手动等待。建议在自动化工作流中在连续的写操作之间添加短暂的延迟例如 1-2 秒。超时设置对于返回大量数据的操作如jira_backlog查询一个包含数百个条目的看板默认的 30 秒超时可能不够。如果遇到超时错误可以适当增加JIRA_TIMEOUT环境变量的值。Confluence 日历 API 性能Confluence 的团队日历功能有时通过插件实现其 API 响应可能比核心 Jira API 慢。查询大范围日期或大量成员的休假信息时请保持耐心。5.3 安全最佳实践安全是重中之重尤其是在处理企业敏感数据和操作权限时。最小权限原则为 MCP 服务器使用的 API 令牌申请最小必要权限。如果只是用于查询只给“浏览项目”权限。如果需要创建问题再加上“创建问题”。绝对不要直接使用具有管理员全局权限的账户令牌。善用只读模式在初次配置、测试或让不熟悉的团队成员试用时务必设置ATLASSIAN_READ_ONLYtrue。这是一个服务器端的硬性开关能有效防止任何意外的数据修改或删除。令牌隔离为 MCP 服务器单独创建一个 API 令牌不要与其他自动化脚本共享。这样如果出现问题你可以单独撤销这个令牌而不影响其他服务。环境变量管理切勿将包含令牌的配置文件提交到版本控制系统。坚持使用.env文件并加入.gitignore或客户端提供的安全配置存储。网络考虑如果 MCP 服务器运行在你的本地电脑上那么它与 AI 客户端的通信是本地进程间通信相对安全。但如果你将服务器以 HTTP 模式运行在某个内网服务器上供团队使用请确保该服务器的访问受到防火墙保护并且使用安全的网络环境。5.4 与基础mcp-atlassian的协作记住mcp-atlassian-extended是扩展需要与基础的mcp-atlassian服务器同时运行并配置到你的 AI 客户端。你的 MCP 客户端配置文件中应该同时包含两个服务器的配置项。例如在 VS Code 的mcp.json中{ mcpServers: { atlassian-basic: { command: uvx, args: [mcp-atlassian], env: {JIRA_URL: ..., JIRA_USERNAME: ..., JIRA_API_TOKEN: ...} }, atlassian-extended: { command: uvx, args: [mcp-atlassian-extended], env: {JIRA_URL: ..., JIRA_USERNAME: ..., JIRA_API_TOKEN: ...} } } }这样AI 客户端就能同时看到来自两个服务器的工具形成一个完整的能力集合。当 AI 需要搜索问题或添加评论时它会调用mcp-atlassian的工具当需要管理附件或查询日历时则会调用mcp-atlassian-extended的工具。两者无缝协作共同为你服务。经过以上从原理到实践从配置到排错的全方位拆解相信你已经对mcp-atlassian-extended有了深入的理解。这个工具的精髓在于它通过 MCP 这个开放协议将 Atlassian 生态系统的强大 API 能力变成了 AI 助手可以理解和直接操作的“技能”。这不仅仅是节省几次点击更是将项目管理动作深度融入你的开发对话流中让 AI 从一个被动的建议者转变为一个能主动执行、帮你完成繁琐任务的智能协作者。