Skip to main content
Glama
README.md
# atlassian-mcp — Jira и Confluence в чате Open WebUI под своей учёткой

MCP-сервер, через который модель в [Open WebUI](https://github.com/open-webui/open-webui)
читает и правит задачи Jira и страницы Confluence (Server / Data Center).

Главное свойство: **каждое действие выполняется личным токеном того, кто пишет
в чат.** Общей служебной учётки нет ни в каком виде. В истории задачи или
страницы стоит имя пользователя, права Jira и Confluence действуют как обычно:
человек не сделает через чат того, чего не может сделать сам.

Токен пользователь вводит один раз в интерфейсе Open WebUI, в скрытом поле
личных настроек. В переписку он не попадает, модель его не видит.

Внутри — [mcp-atlassian](https://github.com/sooperset/mcp-atlassian) 0.23.1 и
встроенный посредник, который подставляет в каждый запрос токены пользователя.

## Содержание

- [Что умеет](#что-умеет)
- [Как устроено](#как-устроено)
- [Безопасность](#безопасность)
- [Требования](#требования)
- [Установка](#установка)
- [Как пользователь вводит токен](#как-пользователь-вводит-токен)
- [Картинки из чата](#картинки-из-чата)
- [Настройки](#настройки)
- [Если что-то не работает](#если-что-то-не-работает)
- [Проверка](#проверка)
- [Обновление mcp-atlassian](#обновление-mcp-atlassian)
- [Версии](#версии)
- [Лицензия](#лицензия)

## Что умеет

В поставляемой настройке включено 77 инструментов: 75 из mcp-atlassian
и два для загрузки картинок из чата. Набор меняется параметрами `TOOLSETS` и `EXCLUDED_TOOLS`.

**Jira**

| Группа | Что умеет |
|---|---|
| Задачи | Поиск по JQL, чтение задачи со всеми полями, включая дополнительные; создание, в том числе пакетом; изменение любых полей; перенос; назначение исполнителя; история изменений |
| Поля | Поиск поля по названию, допустимые значения полей со списком |
| Комментарии | Добавить, изменить |
| Статусы | Доступные переходы, смена статуса |
| Проекты | Типы задач, поля для создания задачи, версии, компоненты; создание и правка версий |
| Связи | Связать задачи между собой, с эпиком, с внешней ссылкой; убрать связь |
| Agile | Доски, спринты, задачи спринта; создание и правка спринта, перенос задач в спринт и в бэклог |
| Учёт времени | Посмотреть и добавить списание |
| Вложения | Скачать вложения, получить картинки задачи, загрузить картинку из чата |
| Пользователи | Профиль, кого можно назначить исполнителем |
| Наблюдатели | Список, добавить, убрать |
| Даты и SLA | История смены статусов с датами, расчёт SLA |
| Анализ проекта | Иерархия эпиков, связи между проектами |

**Confluence**

| Группа | Что умеет |
|---|---|
| Страницы | Поиск, чтение, создание, правка целиком и по разделу, копирование, перенос, дерево страниц, история и сравнение версий, ограничения доступа |
| Комментарии | Обычные и к фрагменту текста, ответы |
| Вложения | Загрузка, в том числе картинок из чата, скачивание, картинки страницы |

**Не включено:** Jira Service Management, формы ProForma, сведения о разработке
(ветки, коммиты); в Confluence — метки, проверка прав, поиск пользователей,
статистика просмотров, шаблоны (работают только в облаке). **Скрыто удаление**
задач, страниц и вложений.

## Как устроено

```
 Пользователь (браузер)
     │  чат + форма «Ключи Jira и Confluence» (⚙)
     ▼
┌──────────────────────── Open WebUI ─────────────────────────┐
│ • личные настройки пользователя: токен Jira, токен Confluence│
│   (хранятся в базе Open WebUI, могут быть зашифрованы)       │
│ • подключение MCP к atlassian-mcp, вход «Сессия»             │
└──────┬─────────────────────────────────────────▲────────────┘
       │ 1. вызов инструмента                    │ 2. «чья это сессия?
       │    + сессия пользователя                │    дай его токены»
       ▼                                         │
┌──────────────────────── atlassian-mcp ─────────┴────────────┐
│ посредник (server.py)                                        │
│ 3. убирает сессию, подставляет токены пользователя           │
│    и адреса Jira/Confluence из своих настроек                │
│ mcp-atlassian                                                │
│ 4. проверяет токены, выполняет операцию                      │
└──────┬───────────────────────────────┬──────────────────────┘
       ▼                               ▼
   Jira Server / DC              Confluence Server / DC
```

1. Модель вызывает инструмент. Open WebUI отправляет вызов на сервер
   и прикладывает сессию пользователя: так работает режим входа «Сессия».
2. Посредник с этой сессией запрашивает у Open WebUI личные настройки
   инструмента-формы этого пользователя
   (`GET /api/v1/tools/id/<ID формы>/valves/user`). Подделать пользователя нельзя:
   кто это, подтверждает сам Open WebUI.
3. Посредник убирает сессию из запроса и добавляет заголовки
   `X-Atlassian-Jira-Url`, `X-Atlassian-Jira-Personal-Token` и такие же для
   Confluence. Это штатный способ передать mcp-atlassian учётные данные
   пользователя на один запрос.
4. mcp-atlassian проверяет токен в Jira или Confluence и выполняет операцию.

**Почему посредник встроен, а не отдельный сервис.** Open WebUI не умеет
подставлять личный секрет пользователя в подключение к MCP-серверу: ключ
подключения один на всех. Поэтому кто-то должен сопоставить сессию и токены.
Посредник встроен в процесс mcp-atlassian: он подменяет `AtlassianMCP.http_app`
и оборачивает приложение. Так получается один контейнер и одна точка входа.
Плата за это — посредник зависит от внутреннего устройства mcp-atlassian,
поэтому версия закреплена, а обновление идёт только через тест (см.
[Обновление mcp-atlassian](#обновление-mcp-atlassian)).

**Форма для токена** — это обычный инструмент Open WebUI без функций
([openwebui_tool.py](openwebui_tool.py)). Open WebUI сам рисует для него форму
личных настроек со скрытыми полями.

## Безопасность

- **Только личные токены.** Сервер не запустится, если в настройках есть общая
  учётка (логин, токен, OAuth, сертификат) или отключена проверка личных
  токенов (`ALLOW_GLOBAL_CRED_FALLBACK`, `IGNORE_HEADER_AUTH`).
- **Без сессии Open WebUI — отказ.** Запрос без сессии или с чужой
  (недействительной) сессией получает ответ 401.
- **Без токена ничего не уходит.** Если пользователь не заполнил форму, модель
  получает подсказку, где ввести токен, а запрос в Jira или Confluence
  не отправляется.
- **Учётные заголовки от клиента отбрасываются.** Токены и адреса подставляет
  только посредник; адреса Jira и Confluence берутся из настроек сервера.
- **Скрытые инструменты нельзя вызвать по имени.** Это обеспечивает
  mcp-atlassian: фильтр действует и на список, и на вызов.
- **Хранение токенов.** Токены лежат в базе Open WebUI. Включите встроенное
  шифрование (`ENABLE_VALVE_ENCRYPTION=true`, есть с Open WebUI 0.10.0). Тогда
  от утечки защищены копия базы, резервная копия, администратор базы
  и выгрузка базы из интерфейса.
- **Кому приходится доверять.** Администраторы Open WebUI и сервера — доверенные
  лица при любом шифровании. Владелец секретного ключа Open WebUI
  (`WEBUI_SECRET_KEY`) может выдать себя за любого пользователя. Администратор
  Open WebUI может добавить инструмент со своим кодом, который выполнится
  на сервере. Держите эту роль у немногих.
- **Сеть.** Порт сервера наружу не публикуется, к нему ходит только Open WebUI.
  Посредник видит сессии пользователей и ничего о них не пишет в журнал.
- **Срок токенов.** Выпускайте личные токены Jira и Confluence с ограниченным
  сроком действия.
- **Уязвимость CVE-2026-77244** (обход проверки токенов в mcp-atlassian до
  0.22.0) к закреплённой версии 0.23.1 не относится.

## Требования

- Open WebUI с поддержкой MCP и шифрования настроек инструментов, 0.10.0 или
  новее. Проверено по исходному коду 0.12.3.
- Jira и Confluence Server / Data Center с личными токенами доступа (Jira 8.14+,
  Confluence 7.9+). Облако Atlassian не поддерживается: там другой вид токенов.
- Docker, в той же сети, что и Open WebUI.
- Адреса Jira и Confluence — **по имени сервера, не по IP**: mcp-atlassian
  отсекает IP-адреса внутренних сетей.

## Установка

**1. Форма для токенов в Open WebUI.**
«Рабочее пространство → Инструменты → Новый инструмент». Вставить код из
[openwebui_tool.py](openwebui_tool.py), ID инструмента — `atlassian_tokens`.
В «Доступ» дать чтение группе пользователей, которые будут работать с Jira.
В «Панель администратора → Пользователи → Группы → Разрешения» у этой группы
должно быть включено «Разрешить параметры чата» (по умолчанию включено).

**2. Шифрование токенов.** В настройках запуска Open WebUI:

```
ENABLE_VALVE_ENCRYPTION=true
WEBUI_SECRET_KEY=<постоянный ключ>
```

Ключ не менять и хранить отдельно от резервных копий базы. При смене ключа
токены не расшифруются, и пользователям придётся вводить их заново (входы
в Open WebUI тоже сбросятся).

**3. Сервер.** Заполнить адреса в [docker-compose.yml](docker-compose.yml):
`OWUI_URL` — адрес Open WebUI внутри сети Docker, `JIRA_URL`, `CONFLUENCE_URL`.
Указать сеть, в которой работает Open WebUI. Затем:

```
docker compose up -d --build
```

Если сертификат Jira или Confluence выпущен внутренним центром
сертификации, положите корневой сертификат рядом с `Dockerfile` как
`corp-ca.crt` и раскомментируйте две строки в [Dockerfile](Dockerfile).

**4. Подключение в Open WebUI.**
«Панель администратора → Настройки → Интеграции → Внешние серверы инструментов →
Добавить соединение»:

| Поле | Значение |
|---|---|
| Тип | MCP (Streamable HTTP) |
| Адрес | `http://atlassian-mcp:8000/mcp` |
| Вход | **Сессия** |
| Доступ | Группы, которые работают с Jira и Confluence |

**5. Пользователи** создают токены и вставляют их в форму, см. следующий раздел.

## Как пользователь вводит токен

1. Создать токен в Jira: аватар → «Профиль» → раздел Personal Access Tokens →
   создать токен со сроком действия. Скопировать: Jira показывает его один раз.
2. То же в Confluence: аватар → «Настройки» → Personal Access Tokens.
3. В чате Open WebUI: «Интеграции → Инструменты» → ⚙ у «Ключи Jira
   и Confluence». Вставить оба токена в скрытые поля, сохранить.

Если нужен только один из сервисов, второе поле можно оставить пустым. Тогда
при обращении к этому сервису модель подскажет, где ввести токен.

## Картинки из чата

С версии 1.1.0 MCP передаёт картинки из хранилища Open WebUI в Jira и Confluence.
Песочница и общий диск не нужны; содержимое файла и токены не передаются через модель.

| Инструмент | Параметры |
|---|---|
| `jira_upload_chat_attachment` | `issue_key`, `file_id` |
| `confluence_upload_chat_attachment` | `content_id` (ID страницы), `file_id` |

Модель берёт полный UUID файла из метаданных вложения в сообщении. MCP получает
оригинал с `OWUI_URL/api/v1/files/<file_id>/content` с сессией текущего пользователя.
Open WebUI проверяет право чтения. Затем файл загружается личным токеном Jira
или Confluence. Сессия Open WebUI остаётся только в контексте запроса.

**Загрузка и вставка в текст — два шага.** После подтверждения загрузки возвращаются
имя вложения, его номер, размер, SHA-256 и разметка:

- Jira: `jira_wiki`, затем существующий `jira_update_issue` для изменения описания.
- Confluence: `confluence_storage`, затем `confluence_update_page` с
  `content_format="storage"`. Существующую страницу сначала прочитать в storage,
  сохранить её текст и добавить разметку изображения без преобразования в Markdown.

Загрузчик текст не меняет: ответ содержит `description_updated=false` или
`page_updated=false`. Если изменение текста не удалось, вложение уже может быть
на месте: проверить его, затем повторить только изменение текста.

Ограничения:

- PNG, JPEG, GIF и WebP, максимум 10 МиБ. Формат определяется по сигнатуре,
  содержимое не перекодируется. В Jira/Confluence может действовать меньший лимит.
- Нужен существующий файл Open WebUI и полный UUID. Путь `/mnt/uploads/...`, URL
  и Base64 не принимаются. Картинку, созданную только в песочнице, сначала нужно
  сохранить как вложение Open WebUI.
- При вставке из буфера требуется сохранение оригинала в хранилище Open WebUI,
  например уже используемым фильтром `paste_images_to_sandbox.py`. Если метаданных
  файла нет, попробовать обычное прикрепление. Не угадывать UUID из имени `pasted_...`.
- Имя вложения: `chat-<полный UUID>.<формат>`. Разные файлы с исходным именем
  `image.png` не сталкиваются. Повторный вызов для того же файла может создать
  дубль в Jira; Confluence Server/DC отклоняет совпадающее имя. Проверять уже
  имеющееся вложение перед повтором; автоматического удаления или замены нет.
- Скачивание ограничено 30 секундами и не следует перенаправлениям. Загрузка
  использует тайм-аут клиента Atlassian; автоматические повторы загрузки отключены.
- Режим чтения и исключение инструментов действуют и на новые команды.

Пример запроса: «Приложи эту картинку к задаче TEST-1 и вставь в конец описания,
сохранив прежний текст». Для Confluence указать согласованную тестовую страницу.

### Обновление с 1.0.0

1. Обновить файлы, включая `chat_attachments.py`, и пересобрать сервер:
   `docker compose up -d --build`. Адреса и личные токены остаются прежними.
2. Обновить список инструментов подключения MCP в Open WebUI. Должны появиться
   две команды из таблицы. Группы `jira_attachments` и `confluence_attachments`
   уже включены в поставляемый пример настроек.
3. Прикрепить картинку в чате. В тестовой задаче и странице проверить загрузку,
   отображение внутри текста, открытие оригинала и сохранность прежнего текста.
   На рабочей установке эта проверка обязательна: локально сервисы заменены заглушками.

## Настройки

| Параметр | Значение |
|---|---|
| `OWUI_URL` | Адрес Open WebUI внутри сети Docker, например `http://open-webui:8080`. Обязателен |
| `OWUI_TOOL_ID` | ID инструмента-формы в Open WebUI, по умолчанию `atlassian_tokens` |
| `JIRA_URL`, `CONFLUENCE_URL` | Адреса серверов, по имени, не по IP. Можно указать только один |
| `TOOLSETS` | Группы инструментов mcp-atlassian через запятую. Поставляемое значение — в [docker-compose.yml](docker-compose.yml) |
| `EXCLUDED_TOOLS` | Скрытые инструменты через запятую. Сейчас скрыто удаление задач, страниц и вложений. При опечатке в названии сервер не запустится |
| `READ_ONLY_MODE` | `true` — только чтение, удобно на время пробы |
| `MCP_ALLOWED_URL_DOMAINS` | Задаётся автоматически по `JIRA_URL` и `CONFLUENCE_URL` |

Остальные параметры mcp-atlassian (таймауты, прокси, фильтр проектов
`JIRA_PROJECTS_FILTER`, фильтр пространств `CONFLUENCE_SPACES_FILTER`) работают
как описано в его документации. Учётные параметры запрещены.

## Если что-то не работает

| Что видно | Что проверить |
|---|---|
| Контейнер сразу останавливается, в журнале «Ошибка настройки: …» | Текст ошибки называет параметр: общая учётка в настройках, IP вместо имени сервера, неизвестный инструмент в `EXCLUDED_TOOLS`, не задан `OWUI_URL` |
| Open WebUI не может подключиться, ответ 401 | В подключении выбран вход «Сессия» |
| Модель отвечает «Личный токен … не задан» | Пользователь не заполнил форму; `OWUI_TOOL_ID` совпадает с ID инструмента-формы |
| Ответ «Open WebUI недоступен» или «Open WebUI ответил …» | `OWUI_URL` и общая сеть Docker |
| Jira или Confluence отвечает ошибкой авторизации | Токен истёк или отозван: создать новый и вставить в форму |
| Ошибка сертификата | Внутренний корневой сертификат, см. шаг 3 установки |
| Нет нужного инструмента | `TOOLSETS` и `EXCLUDED_TOOLS` |

## Проверка

[test_e2e.py](test_e2e.py) поднимает заглушки Open WebUI, Jira и Confluence,
запускает сервер и проверяет:

- инструменты видны, скрытый инструмент отсутствует и не вызывается по имени;
- чтение задачи со всеми полями и запись поля идут токеном Jira пользователя;
- чтение страницы идёт токеном Confluence;
- без токена приходит подсказка, запросов в Jira нет;
- без сессии и с чужой сессией — отказ.

В образе, то есть в той же среде, что и на сервере:

```
docker build -t atlassian-mcp:1.1.0 .
docker run --rm -v "$PWD:/src:ro" -w /src -e STUB_HOST=stub.test \
  --add-host stub.test:127.0.0.1 atlassian-mcp:1.1.0 python test_e2e.py
```

На Windows без Docker:

```
pip install -r requirements.txt
python test_e2e.py
python -m unittest test_chat_attachments -v
python test_chat_e2e.py
```

Успех — строка `OK: все проверки прошли`.

Для картинок unittest должен завершиться `OK`, а `test_chat_e2e.py` — тремя
строками `OK: chat attachments`: обычный режим, режим чтения, исключённые инструменты.
В образе использовать ту же команду `docker run`, заменив последнюю команду Python.
Все проверки работают на заглушках и не обращаются к корпоративным сервисам.

## Обновление mcp-atlassian

Посредник опирается на внутреннее устройство mcp-atlassian, поэтому версия
закреплена вместе со всеми зависимостями в [requirements.txt](requirements.txt).
Обновлять только так:

1. Поменять версию и пересобрать список зависимостей:
   `uv pip compile --no-annotate --no-header --python-platform linux --python-version 3.12 requirements.in -o requirements.txt`,
   где в `requirements.in` одна строка `mcp-atlassian==<версия>`.
2. Собрать образ и прогнать тест в нём (раздел [Проверка](#проверка)).
3. Если тест прошёл — выложить новую версию сервера.

## Версии

Номер версии — `основная.дополнительная.исправление`:

- **основная** меняется, когда нужно что-то менять у себя: настройки сервера,
  форму в Open WebUI, подключение;
- **дополнительная** — новые возможности без изменений у себя;
- **исправление** — исправления.

История — в [CHANGELOG.md](CHANGELOG.md).

## Лицензия

MIT, см. [LICENSE](LICENSE). mcp-atlassian распространяется под лицензией MIT.