Metadata-Version: 2.4
Name: bcs-mcp-atlassian
Version: 0.2.1
Summary: 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:
Author-email: nvkzshadow <anton.mikhalev.92@gmail.com>
Requires-Python: >=3.10
Requires-Dist: atlassian-python-api>=4.0.0
Requires-Dist: beautifulsoup4>=4.12.3
Requires-Dist: cachetools>=5.0.0
Requires-Dist: click>=8.1.7
Requires-Dist: fakeredis<2.35.0,>=2.32.1
Requires-Dist: fastmcp<2.15.0,>=2.13.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: keyring>=25.6.0
Requires-Dist: markdown-to-confluence<0.4.0,>=0.3.4
Requires-Dist: markdown>=3.7.0
Requires-Dist: markdownify>=0.11.6
Requires-Dist: mcp<2.0.0,>=1.8.0
Requires-Dist: pydantic<3.0,>=2.10.6
Requires-Dist: python-dateutil>=2.9.0.post0
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: requests[socks]>=2.31.0
Requires-Dist: starlette>=0.49.1
Requires-Dist: thefuzz>=0.22.1
Requires-Dist: trio>=0.29.0
Requires-Dist: truststore>=0.10.0
Requires-Dist: types-cachetools>=5.5.0.20240820
Requires-Dist: types-python-dateutil>=2.9.0.20241206
Requires-Dist: tzdata>=2024.1; platform_system == 'Windows'
Requires-Dist: unidecode>=1.3.0
Requires-Dist: urllib3>=2.6.3
Requires-Dist: uvicorn>=0.27.1
Description-Content-Type: text/markdown

# BCS MCP Atlassian

Форк [sooperset/mcp-atlassian](https://github.com/sooperset/mcp-atlassian): MCP-сервер для Jira и Confluence.

Оригинальный README в переводе вынесен отдельно: [Readme.original.ru.md](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.

```json
{
  "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-сервер вместо нового процесса на каждую клиентскую сессию.

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

```bash
scripts/docker_build_local_ci.sh
scripts/docker_run_local.sh
```

Endpoint:

```text
http://localhost:9000/mcp
```

Healthcheck:

```text
http://localhost:9000/healthz
```

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

```json
{
  "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:

```toml
[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

Команды:

```bash
# 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.

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

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

```bash
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 выполняет:

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

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

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

```text
$CI_REGISTRY/$CI_PROJECT_NAMESPACE/$CI_PROJECT_NAME:$CI_COMMIT_REF_NAME
```

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

```text
bcs-mai/mcp/bcs-mcp-atlassian
```

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

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

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

```text
Target image ...
```

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

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

```bash
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](https://pypi.org/project/bcs-mcp-atlassian/), запуск через `uvx bcs-mcp-atlassian`. Скрипты `scripts/publish_pypi.sh` / `scripts/publish_pypi.ps1`, переменные — [docs/RELEASES.md](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](https://github.com/sooperset/mcp-atlassian)
- Original docs: [mcp-atlassian.soomiles.com](https://mcp-atlassian.soomiles.com)
- Перевод upstream README: [Readme.original.ru.md](Readme.original.ru.md)

## Security

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