Cloud Jira MCP

用 TypeScript 编写的 MCP Streamable HTTP 服务，用于操作多个 Jira Cloud 实例、绑定工作区、创建和编辑 issue、转换工作流、读取附件，并通过 Web 界面进行管理。

运行

cp .env.example .env
npm install
npm run build
npm start

• MCP：http://127.0.0.1:37242/mcp

• 界面：http://127.0.0.1:37242/admin

• 健康检查：http://127.0.0.1:37242/health/ready

首次使用前，请修改 MCP_SERVER_BEARER_TOKEN、MCP_ADMIN_PASSWORD 和 JIRA_CREDENTIALS_MASTER_KEY。使用以下命令生成凭据密钥：

openssl rand -base64 32

每个 Jira 的 token 只能通过管理界面提供。该 token 会与 Jira 进行校验，并在存入 SQLite 之前使用 AES-256-GCM 加密。

Related MCP server: MCP Atlassian

开发

npm run dev
npm run dev:web

Vite 在端口 5173 上运行，并将 /api 转发到端口 37242 的后端。

验证

npm run typecheck
npm test
npm run build

有关架构、契约和后续交付，请参阅 PLANO.md。

SDD 生态化

sdd_init 工具可检测 Flutter、React、React Native、Angular 以及基于 TypeScript 的 Node.js 后端。Datadog 和 OpenAPI 仅当项目中已存在时才作为 overlay 应用。它只创建或更新 AGENTS.md、docs/constitution.md、docs/sdd/templates/、docs/sdd/.instrumentation.json 以及 .claude/commands/ 中受管理的 Cloud 命令。

该生态还会安装 .claude/commands/sdd-task.md。/sdd-task 命令引导代理检查项目、梳理用户故事、提出可观测的验收标准并记录疑问，而不自行臆造业务流程。它会调用 jira_get_workspace_binding，并使用已连接 Jira 的配置文件、项目及 customFieldMap。在用户明确确认后，通过现有的 jira_create_task 工具创建 issue。旧的受管理命令 cloud-task.md 会在更新时被移除；没有受管理标记的本地文件会保留。

同一目录会安装 /sdd-plan、/sdd-build 以及位于 .claude/agents/ 的各类代理。/sdd-plan <ISSUE-KEY> 会生成 issue.md、spec.md、checklist.md、research.md、plan.md、tasks.md 以及可恢复的 workflow.json，并保存到 docs/sdd/specs/<ISSUE-KEY>/ 中，同时在不产生重复的情况下调和 Jira 子任务。/sdd-build <ISSUE-KEY> 要求状态为 READY_TO_BUILD，执行已批准的任务，并且只在 QA: PASS 之后才完成 issue。

在 Claude Code 中将此 MCP 注册为别名 cloud-mcp。这些 SDD 命令和子代理在 allowed-tools/tools 中使用该别名，例如 mcp__cloud-mcp__jira_get_issue，而访问 Jira 的子代理声明 mcpServers: [cloud-mcp]。如果本地别名不同，即使主代理能够使用 MCP 工具，子代理也可能无法看到这些工具。

进度会持续同步到 Jira。jira_add_comment 发布一般性评论，而 jira_record_sdd_event 记录带有结构化评论和可选转换的幂等事件。父卡片接收里程碑；每个子任务接收开始、阻塞/失败和完成事件。只有通过验证后才算完成。

在 BUILD_COMPLETED 时，事件可包含结构化的 report，内含构建时间、任务、QA 和验证信息。服务器使用 SVG 和 Sharp 渲染 4K 执行仪表盘 PNG，自动选择横向或纵向，对长表格进行分页，并将图片保存到 docs/sdd/specs/<ISSUE-KEY>/report/。Jira 仅收到一条纯文本 comment，其中包含开发摘要、耗时、任务、QA、验证结果以及仪表盘的本地路径。本地渲染失败时会出现警告，并不会撤销已批准的 build。

网络故障、超时、限流或 Jira 5xx 错误会重试一次。代理/配置错误、权限问题、输入错误、产物错误或验证失败会立即阻塞。该流程绝不会静默地将 sdd-implementer 替换为通用代理。待处理的 Jira 事件会保存在 schema v2 的 workflow.json 中，并且必须在恢复前完成同步。

在创建这些文档之前，/sdd-plan 会先执行一个受 Spec Kit 启发的细化门禁（refinement gate）。它会评估目标、角色、范围、独立用户旅程、Given/When/Then、规则、权限、数据、集成、错误状态、非功能需求、依赖和附件。重大缺口会导致 NEEDS CLARIFICATION 并阻塞流程，且不会创建 spec 文件夹或子任务。答复必须被确认、记录到 Jira 并再次评估。只有 PASS 才允许接下来生成 spec、checklist、research 和 plan。

以上三个命令在任何工作开始前都会应用 JIRA_GATE：工作区必须绑定到已启用的档案和有效的 Jira 项目。一旦绑定不存在，代理会列出可用选项，询问要使用哪一个，进行绑定并再次验证。若门禁未通过，则不会创建 issue、spec 文档、子任务或代码更改。

在 /sdd-plan 期间，issue 可访问到的所有附件都会导入到 docs/sdd/specs/<ISSUE-KEY>/assets/。本地文件名会以 Jira ID 作为前缀并进行净化处理；assets/manifest.json 会记录 MIME 类型、大小、SHA-256 和状态。二进制数据会在不把 Base64 写入日志的情况下解码。附件被视为不可信数据，不会被当作不可信内容。如果无法下载某个必需的契约或引用，规划将停止。/sdd-build 会将 Jira 列表和本地哈希与 manifest 进行比对，发生变更时要求重新规划。

已安装的代理：

• sdd-orchestrator

• sdd-refinement-reviewer

• sdd-spec-writer

• sdd-researcher

• sdd-planner

• sdd-jira-coordinator

• sdd-implementer

• sdd-qa-reviewer

该流程始终包含两个步骤：

sdd_init({ workspacePath: "/caminho/do/projeto", action: "preview" })
sdd_init({ action: "apply", previewId: "id-retornado-na-previa" })

预演预览在 15 分钟后过期，只能应用一次，并且如果任何已规划的文件发生变化则失效。如果没有 workspacePath，当客户端恰好提供一个 root 时，服务器使用 MCP Roots。Jira 仅对生态安装是可选的；SDD 操作命令需要绑定。当工作区已绑定时，档案和项目会显示在 constitution 中。

在 Docker 中，配置客户端提供的路径与容器挂载卷之间的映射关系：

MCP_WORKSPACES_HOST_ROOT=/Volumes/External HD/Projetos
MCP_WORKSPACES_CONTAINER_ROOT=/workspaces
SDD_CATALOG_PATH=./resources/sdd

Docker Compose

在 Mac 上的推荐流程是使用 Docker Compose 和命名卷（named volume），以便在镜像重建之间保留 SQLite。

首次配置：

./scripts/docker-setup.sh

该脚本会生成包含随机 Bearer token、管理密码和 AES 密钥的 .env 文件。该文件权限为 600，且不会进入 Git。

构建并首次启动：

./scripts/docker-up.sh

对代码进行任何改进后，运行：

./scripts/docker-redeploy.sh

该命令会执行多阶段构建。在镜像内会运行 typecheck、测试以及后端和前端构建；只有在所有这些之后，Compose 才会重新创建容器并等待 health check 通过。

操作命令：

./scripts/docker-build.sh       # valida e gera a imagem
./scripts/docker-up.sh          # build + up + health check
./scripts/docker-redeploy.sh    # ciclo completo apos uma alteracao
./scripts/docker-status.sh      # estado e health do container
./scripts/docker-logs.sh        # acompanha logs
./scripts/docker-down.sh        # encerra sem apagar o banco

数据库数据存储在 cloud-jira-mcp-data 卷中。docker-down.sh 不会删除该卷。要在 Mac 上使用其他端口，请在 .env 中配置 MCP_DOCKER_PORT；服务在容器内仍然监听端口 37242。