Cloud Jira MCP

MCP Streamable HTTP на TypeScript для управления несколькими экземплярами Jira Cloud, привязки рабочих областей, создания и редактирования issues, переходов по workflow, чтения вложений и администрирования всего через веб-интерфейс.

Запуск

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

• Health: http://127.0.0.1:37242/health/ready

Перед первым использованием измените MCP_SERVER_BEARER_TOKEN, MCP_ADMIN_PASSWORD и JIRA_CREDENTIALS_MASTER_KEY. Сгенерируйте ключ учётных данных командой:

openssl rand -base64 32

Токен каждого Jira вводится только через административный интерфейс. Он проверяется через Jira и шифруется с помощью AES-256-GCM перед сохранением в SQLite.

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 и бэкенды Node.js с TypeScript. Datadog и OpenAPI применяются как оверлеи только в том случае, если они уже есть в проекте. Он создаёт или обновляет только AGENTS.md, docs/constitution.md, docs/sdd/templates/, docs/sdd/.instrumentation.json и управляемые командой Cloud в .claude/commands/.

Также инструментация устанавливает .claude/commands/sdd-task.md. Команда /sdd-task направляет агента осмотреть проект, структурировать историю, предложить наблюдаемые критерии и записывать вопросы, не придумывая бизнес-правил. Она вызывает jira_get_workspace_binding и использует профиль, проект и customFieldMap подключённого Jira. После явного подтверждения пользователя создаётся issue через существующий инструмент jira_create_task. Старая управляемая команда 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, выполняет одобренные задачи и завершает issue только после QA: PASS.

В 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 и проверками. Сервер выполняет рендеринг управленческого дашборда PNG в 4K с помощью SVG и Sharp, выбирает горизонтальную или вертикальную ориентацию, разбивает длинные таблицы на страницы и сохраняет изображение в docs/sdd/specs/<ISSUE-KEY>/report/. Jira получает только текстовый комментарий с краткой сводкой разработки, временами, задачами, QA, ванализациями и локальным путём к дашборду. Сбой локального рендеринга отображается как предупреждение и не отменяет одобренную сборку.

Сбои сети, тайм-ауты, rate limit или ответы Jira 5xx повторяются один раз. Ошибки агента/конфигурации, прав доступа, входных данных, артефактов или проверки блокируют выполнение немедленно. Поток никогда не подменяет незаметно sdd-implementer универсальным агентом. События Jira, ожидающие загрузки, остаются в workflow.json schema v2 и до возобновления должны быть синхронизированы.

Перед созданием этих документов /sdd-plan выполняет refinement gate, вдохновлённый Spec Kit. Он оценивает цель, действующее лицо, объём, независимые сценарии, Given/When/Then, правила, разрешения, данные, интеграции, состояния ошибок, нефункциональные требования, зависимости и вложения. Существенные пробелы приводят к NEEDS CLARIFICATION и блокируют процесс без создания папки спецификации и подзадач. Ответы должны быть подтверждены, записаны в Jira и оценены заново. Только PASS позволяет создавать spec, чек-лист, исследование и план.

Все три команды применяют JIRA_GATE до начала любой работы: рабочая область должна быть связана с активным профилем и действующим проектом Jira. Если такая связь отсутствует, агент перечисляет варианты, спрашивает, какой использовать, выполняет привязку и проверяет заново. Без успешного прохождения gate не создаются issues, документы speccc, подзадачи и изменения кода.

Во время /sdd-plan все доступные file docs/sdd/specs/<ISSUE-KEY>/assets/. Локальные имена получают ID Jira в качестве префикса и санитаризируются; assets/manifest.json содержит MIME-типы, размеры, SHA-256, пути и возможные ошибки. Биографические файлы декодируются без записи Base64 в логи. Вложения считаются ненадёжными данными и никогда не выполняются. Если обязательный контракт или ссылку не удаётся скачать, планирование блокируется. /sdd-build сравнивает список Jira и локальные хэши с манифестом и требует новое планирование при изменении.

Установленные агенты:

• 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 сервер использует MCP Roots, когда клиент предоставляет ровно один root. Jira необязателен только для процесса; операционные команды SDD требуют привязки. Когда рабочая область привязана, профиль и проект соответствуют в конституции.

В Docker настройте соответствие между путями, переданными клиентом, и томом, подключённым в контейнере:

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

Docker Compose

Рекомендуемый путь на Mac — Docker Compose с именованным томом для сохранения SQLite между пересборками.

Первоначальная настройка:

./scripts/docker-setup.sh

Скрипт создаёт .env со случайными Bearer-токеном, административным паролем и AES-ключом. Файл получает права 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, настройте MCP_DOCKER_PORT в .env; сервис всё равно слушает порт 37242 внутри контейнера.