# 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)
- [Версии](#версии)
- [Лицензия](#лицензия)

## Что умеет

В поставляемой настройке включено 75 инструментов из 98, которые есть
в 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». Вставить оба токена в скрытые поля, сохранить.

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

## Настройки

| Параметр | Значение |
|---|---|
| `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.0.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.0.0 python test_e2e.py
```

На Windows без Docker:

```
pip install -r requirements.txt
python test_e2e.py
```

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

## Обновление 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.