企业官网建设流程全解析

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 核心需求与场景解析

在深入技术细节之前，我们先明确一下，到底谁需要这个工具，以及它解决了哪些具体痛点。

目标用户画像：

1. 软件开发团队：尤其是使用 Scrum 或 Kanban 的敏捷团队。开发人员、测试人员、Scrum Master 和产品负责人都会从中受益。
2. DevOps 或 SRE 工程师：需要快速创建、跟踪和关闭事件工单，并关联文档或日志附件。
3. 技术项目经理：负责跨团队协调、版本发布规划和资源调度。
4. 任何频繁使用 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 服务器会向客户端宣告三样东西：

1. 工具 (Tools)：客户端可以调用的函数，例如jira_create_issue。
2. 资源 (Resources)：客户端可以读取的静态或动态内容，例如resource://guides/jql-library这个 URI 指向的 JQL 查询指南文档。
3. 提示词 (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 API）；HTTPX 和 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：

1. 登录到https://id.atlassian.com/manage-profile/security/api-tokens。
2. 点击“创建 API 令牌”。
3. 为令牌起一个名字，例如MCP-Server-Prod。
4. 重要：记录下生成的令牌字符串。它只会显示一次，丢失后需要重新创建。
5. 这个令牌需要和你用于登录 Jira/Confluence 的邮箱地址（JIRA_USERNAME/CONFLUENCE_USERNAME）配合使用，进行 HTTP Basic Auth。

对于 Jira/Confluence Data Center (自托管)：

1. 在 Jira/Confluence 管理界面中，为用户生成一个个人访问令牌。
2. 确保该令牌具有足够的权限（项目浏览、问题创建、附件管理等，详见后文权限章节）。
3. 服务器支持通过JIRA_PAT、JIRA_PERSONAL_TOKEN或JIRA_TOKEN环境变量读取该令牌（按此顺序查找）。建议使用JIRA_PAT以保持清晰。

权限梳理清单：在创建令牌或配置用户权限时，请对照下表检查。权限不足会导致工具调用返回403 Forbidden错误。

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.email@company.com", "JIRA_API_TOKEN": "your_api_token_here", "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki", "CONFLUENCE_USERNAME": "your.email@company.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_ONLY=true：这是我最推荐的初始调试配置。将其设为true后，所有会修改数据的工具（创建、更新、删除、上传）都会被服务器端直接拒绝，返回只读错误。这让你可以安全地测试查询类工具，而不用担心误操作产生脏数据。
• JIRA_TIMEOUT/CONFLUENCE_TIMEOUT：默认 30 秒。如果你的网络到 Atlassian 实例较慢，或者处理大量数据（如导出所有项目版本），可以适当调高，例如60。
• JIRA_SSL_VERIFY/CONFLUENCE_SSL_VERIFY：生产环境务必保持true。仅当你的自托管实例使用了自签名证书，且你完全信任内部网络时，才可将其设为false。设为false会带来中间人攻击风险。

.env文件的使用：服务器会自动从工作目录的.env文件中加载环境变量。这对于本地开发或不想在配置文件中明文存储令牌的情况非常有用。

1. 在项目根目录（或你启动服务器的目录）创建.env文件。
2. 内容格式如下：

   JIRA_URL=https://mycompany.atlassian.net JIRA_USERNAME=me@company.com JIRA_API_TOKEN=your_token_here CONFLUENCE_URL=https://mycompany.atlassian.net/wiki CONFLUENCE_USERNAME=me@company.com CONFLUENCE_API_TOKEN=your_token_here ATLASSIAN_READ_ONLY=false

3. 确保.env文件被添加到.gitignore中，避免敏感信息泄露。

部分配置的灵活性：服务器设计得很灵活。如果你只设置了JIRA_*变量，那么启动后只有 Jira 相关的工具可用，Confluence 工具不会注册。反之亦然。这允许你根据实际需要只集成部分服务。

4. 核心工具使用场景与实战示例

配置好之后，我们来看看这些工具在实际对话中如何发挥作用。以下是一些结合了 AI 助手（如 Claude）对话语境的典型用例。

4.1 问题与附件管理实战

场景一：通过对话创建包含复杂字段的工单。

• 用户对 AI 说：“在 PROJECT 项目里创建一个类型为‘缺陷’的新问题，摘要写‘登录页面在 Safari 浏览器上 CSS 错位’，描述里附上重现步骤，优先级设为‘高’，把‘客户影响’自定义字段设为‘中等’，故事点设为 3。”
• AI 的理解与执行：AI 识别出这是一个创建问题的请求。它会调用jira_create_issue工具。
  • project_key="PROJECT"
  • summary="登录页面在 Safari 浏览器上 CSS 错位"
  • issue_type="Bug"
  • fields={"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 的执行序列：
  1. 调用jira_upload_attachment(issue_key="PROJECT-567", file_path="./app_error_20250415.log")。这里file_path是 AI 所在环境的本地路径，需要确保文件存在且可读。
  2. 调用jira_create_link(link_type="Blocks", inward_issue="PROJECT-568", outward_issue="PROJECT-567")。这里inward和outward的关系是：inward_issue(PROJECT-568)被outward_issue(PROJECT-567)阻塞。理解这个方向对建立正确的依赖关系很重要。

4.2 敏捷冲刺与版本规划实战

场景三：规划下一个冲刺并考虑团队休假。

• 用户：“帮我规划看板 ID 为 5 的下一个冲刺。先看看团队（成员是 Alice, Bob, Charlie）在冲刺期间（3月10日到21日）的休假情况，然后评估一下容量，再从待办列表里选一些高优先级的故事加进去。”
• AI 的工作流：
  1. 容量计算：调用confluence_sprint_capacity(team_members=["Alice", "Bob", "Charlie"], sprint_start="2025-03-10", sprint_end="2025-03-21")。这个工具会查询 Confluence 日历，扣除成员的休假时间，返回一个考虑了有效工作日的团队总容量（通常以人天计）。
  2. 查看待办列表：调用jira_backlog(board_id=5, max_results=100)，获取看板待办事项列表，并可能结合 JQL 过滤出高优先级的故事。
  3. 分析并建议：AI 结合容量和待办事项的复杂度（故事点），给出一个建议的冲刺范围列表，例如["PROJECT-101", "PROJECT-102", "PROJECT-105"]。
  4. 执行移动：用户确认后，AI 调用jira_move_to_sprint(sprint_id=next_sprint_id, issue_keys=["PROJECT-101", "PROJECT-102", "PROJECT-105"])。

场景四：管理项目版本。

• 用户：“PROJECT 项目的下一个版本 ‘v2.1.0’ 计划在 4月1日发布，帮我创建这个版本，并把状态标记为‘未发布’。”
• AI 执行：调用jira_create_version(project_key="PROJECT", name="v2.1.0", release_date="2025-04-01", released=False)。released=False对应“未发布”状态。当版本实际发布后，你可以用jira_update_version(version_id=version_id, released=True)来更新状态。

4.3 资源与提示词的巧妙运用

场景五：利用资源文档指导工作。

• 用户：“我不太确定这个用户故事的定义是否完整，有什么标准可以参考吗？”
• AI 的响应：AI 可以加载resource://rules/jira-ticket-writing和resource://rules/acceptance-criteria这两个资源。然后，它会根据这些结构化指南来评估你的故事描述，并给出具体的改进建议，比如“根据最佳实践，一个完整的用户故事描述应该包含角色、目标和价值。你的描述中缺少了‘作为一个…’的角色定义部分。”

场景六：使用预设提示词快速关闭工单。

• 用户：“使用/close_ticket流程来关闭问题 PROJECT-789。”
• AI 触发提示词：AI 会执行close_ticket提示词定义的工作流。这个流程可能包括：
  1. 检查问题的“完成定义”清单是否全部满足（可能需要调用jira_get_issue工具，该工具可能来自基础的mcp-atlassian服务器）。
  2. 检查是否有关联的合并请求（MR）或代码提交（可能需要集成 GitLab/GitHub 的 MCP 服务器）。
  3. 将问题状态过渡到“已完成”。
  4. 添加一条格式规范的关闭评论。 这个过程将多个手动检查步骤自动化，确保了工单关闭的规范性和完整性。

5. 常见问题排查与安全实践

在实际使用中，你可能会遇到一些问题。下面是我总结的一些常见错误及其解决方法，以及必须注意的安全事项。

5.1 连接与认证问题排查

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 安全最佳实践

安全是重中之重，尤其是在处理企业敏感数据和操作权限时。

1. 最小权限原则：为 MCP 服务器使用的 API 令牌申请最小必要权限。如果只是用于查询，只给“浏览项目”权限。如果需要创建问题，再加上“创建问题”。绝对不要直接使用具有管理员全局权限的账户令牌。
2. 善用只读模式：在初次配置、测试或让不熟悉的团队成员试用时，务必设置ATLASSIAN_READ_ONLY=true。这是一个服务器端的硬性开关，能有效防止任何意外的数据修改或删除。
3. 令牌隔离：为 MCP 服务器单独创建一个 API 令牌，不要与其他自动化脚本共享。这样，如果出现问题，你可以单独撤销这个令牌，而不影响其他服务。
4. 环境变量管理：切勿将包含令牌的配置文件提交到版本控制系统。坚持使用.env文件（并加入.gitignore）或客户端提供的安全配置存储。
5. 网络考虑：如果 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 从一个被动的建议者，转变为一个能主动执行、帮你完成繁琐任务的智能协作者。