BCS MCP Atlassian

Форк sooperset/mcp-atlassian: MCP-сервер для Jira и Confluence.

Оригинальный README в переводе вынесен отдельно: Readme.original.ru.md. Этот файл описывает именно BCS-форк: что добавлено, как использовать, как дорабатывать и как публиковать.

Что Это За Проект

Репозиторий предоставляет Jira/Confluence tools через Model Context Protocol (MCP). Форк ориентирован на BCS-инфраструктуру и внутренние сценарии:

• дефолты для jira.bcs.ru и confluence.bcs.ru;
• long-running HTTP MCP service через streamable-http;
• Docker-first разработка без Python/uv на хосте;
• GitLab CI pipeline: wheel -> unit tests -> Docker image -> GitLab Container Registry;
• маскирование контента через CONTENT_MASK_SERVICE_URL.

Что Добавлено В Форке

• Dockerfile.local для локальной сборки из исходников.
• Dockerfile.ci для CI/prod-style образа из готового wheel.
• Скрипты локальной Docker-разработки:
  • scripts/docker_test_local_docker.sh
  • scripts/docker_build_local_ci.sh
  • scripts/docker_run_local.sh
  • scripts/docker_package_wheel_local.sh
• .gitlab-ci.yml для сборки wheel, тестов и публикации Docker image.
• Runtime-дефолты в Docker image:
  • JIRA_URL=https://jira.bcs.ru
  • CONFLUENCE_URL=https://confluence.bcs.ru
  • выбранные TOOLSETS / ENABLED_TOOLS
  • CONTENT_MASK_SERVICE_URL
• Маскирование, кэширование, retry и расширенные логи в src/mcp_atlassian/utils/content_mask.py.
• Черновики и рабочие гипотезы в todos/.

Пути Использования

Есть два основных варианта.

Python Package / uvx

Подходит, если MCP-клиент запускает subprocess и пакет опубликован в PyPI или корпоративный Python index.

{
  "mcpServers": {
    "bcs-mcp-atlassian": {
      "command": "uvx",
      "args": ["bcs-mcp-atlassian"],
      "env": {
        "JIRA_URL": "https://jira.bcs.ru",
        "JIRA_PERSONAL_TOKEN": "<put-your-token-here>",
        "CONFLUENCE_URL": "https://confluence.bcs.ru",
        "CONFLUENCE_PERSONAL_TOKEN": "<put-your-token-here>",
        "CONTENT_MASK_SERVICE_URL": "https://apis.tusvc.bcs.ru/mai-ms-masking-it-proxy/mask/chat"
      }
    }
  }
}

Этот путь требует uvx на машине, где запускается MCP-клиент.

Docker HTTP Service

Подходит, если нужен один долгоживущий MCP-сервер вместо нового процесса на каждую клиентскую сессию.

Локально из исходников:

scripts/docker_build_local_ci.sh
scripts/docker_run_local.sh

Endpoint:

http://localhost:9000/mcp

Healthcheck:

http://localhost:9000/healthz

Минимальная MCP-конфигурация для HTTP transport:

{
  "mcpServers": {
    "bcs-mcp-atlassian-http": {
      "url": "http://localhost:9000/mcp"
    }
  }
}

Контейнер не обязан хранить Atlassian credentials. В shared-service HTTP-схеме клиент может передавать авторизацию в headers:

• Authorization: Bearer <oauth_token>
• Authorization: Token <personal_access_token>
• Authorization: Basic <base64(email:api_token)>
• X-Atlassian-Cloud-Id: <cloud_id> для Cloud, если нужно

Пример Codex config:

[mcp_servers.bcs-mcp-atlassian]
url = "http://localhost:9000/mcp"
http_headers = { "X-Atlassian-Jira-Url" = "https://jira.bcs.ru", "X-Atlassian-Confluence-Url" = "https://confluence.bcs.ru" }
env_http_headers = { "X-Atlassian-Jira-Personal-Token" = "JIRA_PERSONAL_TOKEN", "X-Atlassian-Confluence-Personal-Token" = "CONFLUENCE_PERSONAL_TOKEN" }

Пути Доработки

Есть два поддерживаемых workflow.

Без Python/uv На Хосте

Предпочтительный лёгкий вариант: редактируем файлы на хосте, а restore зависимостей, тесты и сборку выполняем внутри Docker.

На хосте нужны:

• Git
• Docker

Команды:

# Unit tests внутри Docker.
scripts/docker_test_local_docker.sh

# Runtime image из текущих исходников.
scripts/docker_build_local_ci.sh

# Запуск собранного image.
scripts/docker_run_local.sh

Dockerfile.local использует builder image с uv, поэтому Python tooling живёт внутри контейнера, а не на хосте.

С Python/uv На Хосте

Подходит, если нужна локальная virtualenv, прямые pytest-запуски, сборка wheel или публикация Python package.

uv sync --frozen --all-extras --dev
uv run pytest tests/unit/ -q
uv build -o dist/

Prod-style локальный image из wheel:

scripts/docker_package_wheel_local.sh

Этот скрипт требует uv на хосте, потому что сначала собирает dist/*.whl, а затем запускает Dockerfile.ci.

Docker Images

• Dockerfile.local — local/dev image из исходников. Используйте для разработки без host Python tooling.
• Dockerfile.ci — CI/prod image из dist/*.whl. Используйте для проверки той же формы артефакта, которую публикует CI.

Локальные скрипты поддерживают переменные:

• IMAGE_NAME, default bcs-mcp-atlassian
• IMAGE_TAG, default latest для runtime build и test для test image
• DOCKER_IMAGE, полный image reference для scripts/docker_run_local.sh
• PYTHON_RUNTIME_IMAGE
• HTTP_PROXY, HTTPS_PROXY, NO_PROXY
• UV_INDEX_URL, UV_EXTRA_INDEX_URL, UV_BUILD_TOOLS_INDEX_URL

Локальные override можно положить в scripts/docker-build-local.env. Не коммитьте этот файл.

Docker images по умолчанию включают MCP_VERBOSE=true и MCP_LOGGING_STDOUT=true, чтобы runtime INFO-логи, включая content masking timings/cache hits, были видны через docker logs и docker attach.

GitLab CI И Registry

После push в branch или tag GitLab CI выполняет:

build:wheel -> test:wheel -> docker:mcp-atlassian

Последняя job собирает image через Dockerfile.ci и публикует его в GitLab Container Registry.

Шаблон имени image:

$CI_REGISTRY/$CI_PROJECT_NAMESPACE/$CI_PROJECT_NAME:$CI_COMMIT_REF_NAME

Для этого проекта путь в GitLab относительно registry host:

bcs-mai/mcp/bcs-mcp-atlassian

Страница опубликованных образов в GitLab:

https://gitlab.bcs.ru/bcs-mai/mcp/bcs-mcp-atlassian/container_registry/9503

Если имя ветки содержит /, в Docker tag оно заменяется на -. Точный target печатается в логе job docker:mcp-atlassian строкой:

Target image ...

Подробный процесс релиза, соглашение об именах веток release/X.Y.Z и извлечение номера версии из ветки — docs/RELEASES.md. Release notes — docs/RELEASE_NOTES.md.

Запуск опубликованного image локально:

docker login registry.gitlab.bcs.ru
docker pull registry.gitlab.bcs.ru/bcs-mai/mcp/bcs-mcp-atlassian:<branch-or-tag>
DOCKER_IMAGE=registry.gitlab.bcs.ru/bcs-mai/mcp/bcs-mcp-atlassian:<branch-or-tag> \
  scripts/docker_run_local.sh

docker pull из GitLab Registry может требовать логин. Используйте корпоративную учётную запись или GitLab token с правом чтения registry.

Варианты Распространения

Проект можно распространять двумя независимыми способами:

• Python package: публикация в PyPI, запуск через uvx bcs-mcp-atlassian. Скрипты scripts/publish_pypi.sh / scripts/publish_pypi.ps1, переменные — docs/RELEASES.md (раздел «Публикация на PyPI»), шаблон scripts/publish-pypi.env.example.
• Docker image: публикация в GitLab Container Registry, запуск как long-running HTTP MCP service.

Python package ближе к upstream-сценарию. Docker image — основной операционный путь BCS-форка.

Content Masking

Если задан CONTENT_MASK_SERVICE_URL, в masking service перед возвратом MCP-клиенту отправляется:

• Jira контент (jira_get_issue, jira_search): description, comments[].body (длинный текст — с чанкингом)
• Jira user-поля: reporter, assignee, comments[].author (display_name, email и т.д.)
• Confluence (страницы): content.value, author
• Confluence (комментарии): body, author

Не маскируются через proxy: diff версий страниц Confluence.

Длинный контент разбивается на последовательные запросы к proxy (по умолчанию до 4000 символов на запрос), ответы склеиваются. User-поля — короткие отдельные запросы без чанкинга.

Полезные настройки:

• CONTENT_MASK_SERVICE_URL
• CONTENT_MASK_CHUNK_MAX_CHARS (default 4000; 0 — без чанкинга)
• CONTENT_MASK_REQUEST_TIMEOUT_SECONDS
• CONTENT_MASK_REQUEST_RETRY_COUNT
• CONTENT_MASK_MAX_CONCURRENCY
• CONTENT_MASK_CACHE_MAX_SIZE
• CONTENT_MASK_CACHE_TTL_SECONDS

Логи masking содержат correlation_id, path, размер текста, chunk_index / chunk_count, номер попытки, elapsed time, cache hits и найденные masked fragments.

Карта Репозитория

Path	Purpose
src/mcp_atlassian/	Python source
src/mcp_atlassian/servers/	MCP server definitions
src/mcp_atlassian/jira/	Jira client and mixins
src/mcp_atlassian/confluence/	Confluence client and mixins
src/mcp_atlassian/utils/content_mask.py	Content masking integration
tests/	Unit, integration, and e2e tests
scripts/	Local Docker, packaging, OAuth, docs, and data scripts
docs/RELEASES.md	Процесс релиза: ветки release/X.Y.Z, CI, Docker tags
docs/RELEASE_NOTES.md	Release notes по версиям
todos/	Working notes and hypotheses
Readme.original.ru.md	Russian translation of upstream README

Upstream Документация

Общую документацию по MCP Atlassian смотрите в upstream:

• Original repository: sooperset/mcp-atlassian
• Original docs: mcp-atlassian.soomiles.com
• Перевод upstream README: Readme.original.ru.md

Security

Не коммитьте токены и локальные env-файлы. Предпочитайте передачу Atlassian credentials из окружения MCP-клиента или HTTP headers. .env и scripts/docker-build-local.env должны оставаться локальными.