# rxmcp: Directum RX MCP server

<img src="assets/icon.svg" width="88" height="88" align="right" alt="rxmcp">

**Directum RX MCP server.** Connects an AI assistant (Claude, Cursor and any MCP host) to Directum RX: assignments, tasks, documents and their text, knowledge base, agile boards, project plans, any entity via OData, and search over the system help of your own RX version. Single binary, read-only by default. The rest of this page is in Russian; the tool list and settings are in [server.json](server.json).

MCP-сервер для Directum RX. Подключает ИИ-ассистента (Claude Desktop, Claude Code, Cursor и любой другой хост с поддержкой [Model Context Protocol](https://modelcontextprotocol.io)) к вашей системе: задания, задачи, документы, база знаний, agile-доски, проекты и планы.

Работает от имени пользователя RX через штатный сервис интеграции (OData). Прав сверх ваших не получает, схему не меняет, в базу и логи RX не заглядывает.

Один бинарник без зависимостей: Linux, Windows, macOS (Intel и Apple Silicon).

## Установка за две команды

```sh
curl -fsSL https://drxinfra.ru/dl/rxmcp/install.sh | sh   # или скачайте бинарник вручную
rxmcp setup
```

`setup` спросит адрес RX, логин и способ входа, проверит подключение только чтением и сам пропишет сервер в Claude Desktop, Claude Code и Cursor. Перезапустите клиент — в списке инструментов появится `rx`.

Без интернета и без скриптов: возьмите архив со страницы [Releases](https://github.com/drxinfra/rxmcp/releases), распакуйте, положите бинарник в `PATH` и запустите `rxmcp setup`. На macOS, если файл скачан браузером, система попросит снять карантин: `xattr -d com.apple.quarantine rxmcp`.

## Где лежат настройки

В профиле `~/.config/rxmcp/config.json` (Windows: `%AppData%\rxmcp\config.json`), права `0600`. В конфиге ИИ-клиента остаётся только путь к бинарнику:

```json
{ "mcpServers": { "rx": { "command": "/usr/local/bin/rxmcp" } } }
```

Так сделано, чтобы менять настройки одной командой, а не искать JSON клиента:

```sh
rxmcp config                                 # что настроено (секреты не печатаются)
rxmcp config set RXMCP_ALLOW_WRITE=1         # включить запись
rxmcp config set RXMCP_TZ=Europe/Moscow      # часовой пояс для дат
rxmcp check                                  # проверить связь с RX, только чтение
```

Переменные окружения имеют приоритет над профилем — в контейнере и в CI удобнее передавать их напрямую. Имена те же, полный список: `rxmcp help`.

### Секреты в связке ключей ОС

Пароль, cookie, токены и сессию провайдера входа можно хранить не в файлах каталога настроек, а в связке ключей: Keychain на macOS, диспетчер учётных данных на Windows, Secret Service (GNOME Keyring, KWallet) на Linux. `setup` предлагает это сам, если связка доступна.

```sh
rxmcp secrets            # где лежат секреты и доступна ли связка ключей
rxmcp secrets keyring    # перенести в связку ключей; перезапускать клиента не нужно
rxmcp secrets file       # вернуть в файлы 0600
```

В `config.json` после переноса остаются только несекретные настройки. На сервере Linux и в WSL без графического сеанса связки ключей нет, там секреты остаются в файлах. Что это защищает и что нет: [docs/security.md](docs/security.md#связка-ключей-ос).

## Несколько систем RX

Один процесс rxmcp работает с одной системой. Для второй (тестовый стенд, другой заказчик) заведите отдельный каталог настроек:

```sh
RXMCP_HOME=~/.config/rxmcp-test rxmcp setup
```

`setup` пропишет второй сервер в клиенты под своим именем, например `rx-test-company`, и передаст ему `RXMCP_HOME`. Запись `rx` для основной системы останется как была. Профиль, cookie и сессия провайдера у каждой системы свои, в названии и описании сервера указан хост, поэтому помощник понимает, какую систему спрашивать. Остальные команды для второй системы запускаются с тем же `RXMCP_HOME`: `RXMCP_HOME=~/.config/rxmcp-test rxmcp login`.

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

Раз в сутки rxmcp узнаёт, не вышла ли новая версия: спрашивает файл `drxinfra.ru/dl/rxmcp/latest.txt`, а если он недоступен, GitHub. Кроме номера своей версии в `User-Agent` ничего не отправляет. Если вышла, помощник скажет об этом один раз за сеанс, а `rxmcp version` и `rxmcp check` напишут строкой.

```sh
rxmcp update                              # скачать, сверить с SHA256SUMS, заменить бинарник
rxmcp config set RXMCP_UPDATE_CHECK=0     # не узнавать о новых версиях
```

После обновления перезапустите ИИ-клиент. Если rxmcp лежит в `/usr/local/bin` и ставился через `sudo`, обновлять тоже через `sudo rxmcp update`. В образе Docker проверка выключена: там версию меняют вместе с образом.

## Вход в RX

| Способ | Когда подходит | Что нужно сделать |
|---|---|---|
| `password` | в RX включён вход по паролю (обычно небольшие внедрения) | `rxmcp setup`, ввести пароль один раз |
| `cookie` + `--sso` | вход в RX через Keycloak или другой OIDC-провайдер | один раз `rxmcp login --sso`: дальше rxmcp сам берёт новую cookie RX, пока жива сессия провайдера |
| `cookie` | работает всегда, в том числе при SSO, Keycloak и домене | войти в RX в браузере, скопировать cookie `sungero_client`, `rxmcp login --paste` |
| `oidc` | ваш провайдер и заведённый для rxmcp клиент | `rxmcp login`, вход в браузере (PKCE) или по коду (device flow) |
| `bearer` | у вас уже есть токен | `RXMCP_TOKEN=...` |

### Вход через провайдера без администратора: `login --sso`

Если RX пускает через Keycloak (или другой OIDC-провайдер), протокол OIDC выполняет сам сервер RX: браузер уходит к провайдеру, тот по живой сессии сразу возвращает код, RX выдаёт cookie `sungero_client`. rxmcp повторяет ту же цепочку со своей копией сессии провайдера. Пароль он не видит, отдельный клиент в провайдере не нужен.

```sh
rxmcp login --sso
```

Команда сама узнает адрес провайдера и попросит скопировать заголовок `cookie` со страницы личного кабинета провайдера (вы там уже вошли, пароль не спросят). Дальше, когда RX отвечает 401, rxmcp получает новую cookie и повторяет запрос сам. Входить в браузере заново нужно, только когда истекает сессия провайдера: это срок, который задал его администратор, обычно от нескольких часов до нескольких дней.

Сессия провайдера лежит в `~/.config/rxmcp/sso-<адрес RX>.json` с правами `0600`. Она открывает вход во все приложения этого провайдера, а не только в RX: храните её как пароль. Удалить: `rxmcp logout`. Если RX просит второй фактор, такой вход rxmcp не пройдёт и скажет об этом.

### Cookie вручную

Cookie — обходной путь, зато без участия администратора. Сессия RX живёт недолго, поэтому обновление сделано в одну команду:

```sh
rxmcp login --paste    # взять cookie из буфера обмена
rxmcp login            # вставить cookie в терминал и нажать Enter, или просто Enter, если она в буфере
rxmcp login --stdin < cookie.txt   # из файла или конвейера
```

Длинную cookie можно вставлять прямо в терминал: на время ввода rxmcp снимает предел длины строки (1024 символа в macOS, 4096 в Linux). В WSL `--paste` и Enter берут cookie из буфера обмена Windows через `powershell.exe`, так что копировать в браузере Windows можно как обычно.

Cookie лежит отдельным файлом и перечитывается на каждом запросе: **перезапускать ИИ-клиент после обновления не нужно**. Если сессия истекла, сервер так и скажет в ответе вместо непонятной ошибки.

Про `oidc`: rxmcp умеет и вход в браузере (authorization code + PKCE, локальный redirect), и device flow (код на экране, без открытого порта). Для этого администратору нужно один раз завести в вашем провайдере публичный клиент — без этого остаётся `login --sso`, `cookie` или `password`.

## Что умеет

Чтение (всегда):

- `rx_whoami` — кто я в RX.
- `rx_my_assignments` — задания в работе, просроченные, непрочитанные, выполненные; уведомления.
- `rx_get_assignment`, `rx_get_task`, `rx_list_tasks` — карточки с перепиской, вложениями и заданиями.
- `rx_whats_new` — что нового с прошлого раза: пришедшие задания и уведомления, что горит сегодня, какие мои задачи завершились.
- `rx_find_documents`, `rx_get_document`, `rx_get_document_text` — поиск, карточка, текст версии (docx, xlsx, pptx, pdf, txt, md, csv, json, xml, html, rtf). Сканы и документы-картинки приходят изображениями страниц, текст с них читает сам помощник.
- `rx_find_employees` — найти сотрудника, чтобы адресовать задачу.
- База знаний: `rx_kb_areas`, `rx_kb_search`, `rx_kb_article` (статья в markdown).
- Agile-доски: `rx_boards`, `rx_board`, `rx_tickets`, `rx_ticket`.
- Проекты: `rx_projects`, `rx_project`, `rx_project_plans`, `rx_project_plan` (дерево работ, ответственные, просрочки).
- Справка системы: `rx_help_search`, `rx_help_topic`, `rx_help_toc`. Помощник отвечает на «как настроить» и «что значит это поле» по справке вашей версии RX и называет статью.
- Любая сущность: `rx_find_entity` (поиск по русскому или английскому названию), `rx_describe_entity` (поля и ссылки), `rx_query` (чтение по условию). Для данных, под которые нет готового инструмента: договоры, контрагенты, справочники, доработки заказчика.

Запись (только при `RXMCP_ALLOW_WRITE=1`, иначе инструменты не видны модели):

- `rx_create_ticket` — карточка на доске: колонка, срок, приоритет, план и факт в часах, теги, исполнители, вложения.
- `rx_update_ticket` — изменить карточку (в том числе план и факт в часах), перенести её в другую колонку, добавить вложения: ссылку, документ RX по Id или файл с диска (до 20 МБ). Поля, которые не передали, остаются как были, карточка остаётся на своём месте в колонке.
- `rx_comment_ticket` — добавить комментарий к карточке. Существующие комментарии с Id, авторами и временем показывает `rx_ticket`.
- `rx_edit_comment`, `rx_delete_comment` — исправить или удалить свой комментарий. Чужие не трогает.
- `rx_delete_tickets` — удалить карточки с доски, как удаление в интерфейсе доски: карточка получает статус Deleted (до 100 за раз).
- `rx_create_column` — колонка на доске: название, место, финальная, лимит карточек. Без места встаёт перед «Выполнено».
- `rx_complete_assignment` — выполнить задание: завершить, принять работы, согласовать (в том числе с замечаниями) или вернуть на доработку, отметить ознакомление. Результат подбирается по типу задания. Задания на подписание не выполняет: подпись ставится только в RX.
- `rx_send_for_acquaintance` — отправить документ на ознакомление сотрудникам.
- `rx_send_for_approval` — отправить документ на согласование: свободное с указанными людьми или по регламенту, по правилу RX.
- `rx_create_article`, `rx_update_article` — создать статью базы знаний в markdown или изменить её; новый текст ложится новой версией.
- `rx_create_simple_task` — создать и отправить простую задачу.
- `rx_abort_task` — прекратить задачу.
- `rx_call_action` — вызвать действие модуля по имени, если готового инструмента для него нет.

Плюс ресурсы `rx://assignment/{id}`, `rx://task/{id}`, `rx://document/{id}` и промпты «разбор заданий на сегодня», «краткое содержание документа».

### Наборы инструментов

По умолчанию видны все инструменты. Если нужна только часть, перечислите наборы в `RXMCP_TOOLS`: `core` (задания, задачи, документы, сотрудники, «что нового»; включён всегда), `boards`, `projects`, `kb`, `help`, `catalog`. Можно добавить и отдельные инструменты по имени.

```sh
rxmcp config set RXMCP_TOOLS=boards,kb          # задания, документы, доски и база знаний
rxmcp config set RXMCP_TOOLS=boards,rx_query    # плюс один инструмент из каталога
rxmcp config unset RXMCP_TOOLS                  # снова все
```

Это полезно малым локальным моделям: на 40 с лишним инструментах они заметно хуже выбирают нужный. Инструменты записи по-прежнему появляются только с `RXMCP_ALLOW_WRITE=1`.

Каждое пишущее действие показывает, что именно будет сделано, и спрашивает подтверждение (elicitation), если клиент это умеет. Некоторые клиенты заявляют, что умеют, но форму не показывают и сразу отвечают отказом: тогда каждый вызов заканчивается «Пользователь отменил действие». В этом случае `rxmcp config set RXMCP_CONFIRM=0` выключает форму, и подтверждением служит только разрешение на вызов инструмента в самом клиенте. Теги и исполнители ищутся по имени: чего не нашлось — про то будет сказано прямо в ответе, карточка при этом создастся.

Как это устроено внутри и почему именно так, история версий и что ещё не сделано: [docs/architecture.md](docs/architecture.md).

## Справка системы

Справка Directum RX принадлежит вендору, поэтому в поставке rxmcp её нет. Сервер скачивает её с вашего же стенда: там она лежит рядом с веб-клиентом и соответствует вашей версии системы.

```
rxmcp docs index          # скачать и проиндексировать, около трёх минут на 5000 статей
rxmcp docs search правило согласования договоров
rxmcp docs status
```

Команду можно не выполнять: при первом вопросе по справке сервер начнёт скачивание сам и ответит, когда закончит. Индекс лежит в каталоге настроек (`help-<хост>.idx.gz`, около 5 МБ), у каждого стенда свой. После обновления RX выполните `rxmcp docs index` ещё раз.

Поиск лексический, с учётом русских окончаний и с приоритетом заголовков. Модель для эмбеддингов не нужна: переформулировать вопрос терминами системы помощник умеет сам. Если справка лежит по нестандартному адресу, задайте `RXMCP_HELP_URL`.

## Docker

Для сервера и для HTTP-режима:

```sh
docker run --rm -p 127.0.0.1:8765:8765 \
  -e RXMCP_URL=https://rx.company.ru/Integration \
  -e RXMCP_LOGIN=ivanov -e RXMCP_PASSWORD=... \
  -e RXMCP_HTTP_ADDR=0.0.0.0:8765 -e RXMCP_HTTP_SECRET=... \
  ghcr.io/drxinfra/rxmcp serve --http
```

По stdio из контейнера тоже работает, но для настольного клиента проще бинарник: не нужны ни монтирование каталога с настройками (`-v ~/.config/rxmcp:/config -e RXMCP_HOME=/config`), ни проброс браузера для `oidc`.

## Сервер для компании: каждый под своей учёткой

В HTTP-режиме rxmcp можно поставить один на всю компанию так, что каждый сотрудник работает со своими правами в RX. Чат с входом через ваш провайдер (Keycloak или другой OIDC, обычно связанный с AD) передаёт rxmcp токен вошедшего сотрудника. rxmcp проверяет его по открытым ключам провайдера и с этим же токеном идёт в RX. Служебной учётки с широкими правами нет, помощник видит ровно то, что видит сотрудник.

```sh
docker run --rm -p 127.0.0.1:8765:8765 \
  -e RXMCP_URL=https://rx.company.ru/Integration \
  -e RXMCP_AUTH=passthrough \
  -e RXMCP_HTTP_ADDR=0.0.0.0:8765 \
  -e RXMCP_HTTP_AUTH=oidc \
  -e RXMCP_HTTP_OIDC_ISSUER=https://sso.company.ru/realms/company \
  -e RXMCP_HTTP_OIDC_AUDIENCE=rxmcp \
  -e RXMCP_HTTP_REQUIRE_ROLE=rx-assistant \
  ghcr.io/drxinfra/rxmcp serve --http
```

- Проверяются подпись токена (RS256/384/512, ES256/384 по ключам провайдера), издатель, срок, аудитория или `azp`. Токены без подписи и с общим секретом (`none`, `HS*`) не принимаются.
- `RXMCP_HTTP_REQUIRE_ROLE` пускает только сотрудников с ролью realm. Логин берётся из `preferred_username` (`RXMCP_HTTP_USER_CLAIM`).
- В журнал пишется каждый вызов: сотрудник, инструмент, имена параметров (без значений), успех, время.
- Справку в этом режиме скачивать нечем: подготовьте индекс заранее (`rxmcp docs index` под любой учёткой, файл `help-<хост>.idx.gz` в каталог настроек сервера).

Сервис интеграции RX должен принимать токены вашего провайдера. Это настройка самого RX и провайдера входа, а не rxmcp; её мы делаем при внедрении вместе с чатом и локальной моделью: [написать](https://drxinfra.ru/rxmcp.html#contact). Как это выглядит с моделью внутри контура — [демо](https://drxinfra.ru/ai-assistant-demo.html).

## Каталоги MCP

Сервер опубликован в официальном [MCP Registry](https://registry.modelcontextprotocol.io) под именем `io.github.drxinfra/rxmcp`. Запись обновляется автоматически при каждом релизе: описание лежит в `server.json`, образ в `ghcr.io/drxinfra/rxmcp`.

В каталоге [LobeHub](https://lobehub.com/mcp/drxinfra-rxmcp) сервер называется `drxinfra-rxmcp`. Его описание лежит в `lhm.plugin.json` и обновляется вручную: `npx -y @lobehub/market-cli plugin update --dir .` после смены версии в файле.

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

Подробно, для тех, кто согласует внедрение: [docs/security.md](docs/security.md). Там сетевые потоки, что лежит на диске при каждом способе входа, что видит провайдер модели и что настроить.

- Только сервис интеграции RX и только права вашего пользователя. Ни базы, ни файлов, ни логов системы. Других соединений нет, кроме проверки версии раз в сутки (выключается).
- Запись выключена по умолчанию. Без `RXMCP_ALLOW_WRITE=1` пишущих инструментов нет в списке — модель не может их вызвать.
- Секреты не попадают в конфиг ИИ-клиента: профиль, cookie и сессия провайдера лежат в `~/.config/rxmcp` с правами `0600`.
- Тексты из RX отдаются модели с пометкой, что это данные, а не инструкции. Файлы из каталога настроек rxmcp и каталогов с ключами (`~/.ssh` и т. п.) к карточкам не прикладываются.
- В логи сервера не пишутся ни cookie, ни токены, ни пароли.
- HTTP-режим слушает только то, что вы указали, и пускает либо по общему секрету в заголовке `Authorization`, либо по токену сотрудника от вашего провайдера входа (с проверкой подписи и роли).
- Архивы релизов подписаны подписью происхождения: `gh attestation verify <архив> --repo drxinfra/rxmcp`.

## Сборка из исходников

```sh
go build -o rxmcp .          # нужен Go 1.27+
hack/build.sh v0.13.0         # архивы под все платформы в dist/
go test ./...
```

## Лицензия

Apache-2.0. Текст из PDF извлекается копией библиотеки [ledongthuc/pdf](https://github.com/ledongthuc/pdf) (BSD-3-Clause) с правками, она лежит в `internal/thirdparty/pdf`. Directum RX — продукт Directum; проект с вендором не связан, торговые знаки принадлежат правообладателям.

Форк или производная работа должны сохранить файл [NOTICE](NOTICE) с указанием авторства. Права на имена «rxmcp» и «drxinfra» лицензия не даёт (раздел 6), так что форк выпускается под другим именем.


[![Directum RX MCP (rxmcp) MCP server – quality and maintenance score on Glama](https://glama.ai/mcp/servers/drxinfra/rxmcp/badges/card.svg)](https://glama.ai/mcp/servers/drxinfra/rxmcp)