bcs-mcp-atlassian 0.2.1

The Model Context Protocol (MCP) Atlassian integration is an open-source implementation that bridges Atlassian products (Jira and Confluence) with AI language models following Anthropic's MCP specification. This project enables secure, contextual AI interactions with Atlassian tools while maintaining data privacy and security. Key features include:

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 должны оставаться локальными.