# MCP-сервер для BPMSoft

Позволяет ИИ-помощнику работать с BPMSoft: искать записи, создавать и изменять данные, загружать файлы и запускать бизнес-процессы. Действия выполняются с правами того пользователя, чья сессия передана в запросе.

Ниже — установка через Docker за три шага. Устанавливать Node.js отдельно не нужно.

## 1. Подготовьте компьютер и скачайте проект

Установите [Docker Desktop](https://www.docker.com/products/docker-desktop/) и [Git](https://git-scm.com/downloads). Для Linux вместо Docker Desktop можно установить [Docker Engine](https://docs.docker.com/engine/install/). Запустите Docker.

Откройте терминал. Команды ниже подходят для Linux и macOS; в Windows используйте терминал Ubuntu в WSL 2 с включённой интеграцией Docker Desktop.

Скачайте проект и перейдите в его папку:

```bash
git clone https://github.com/Catter58/mcpBPMSoft.git
cd mcpBPMSoft
docker version
```

Последняя команда должна показать версии клиента и сервера Docker. Если она сообщает, что не может подключиться к Docker, сначала запустите Docker Desktop или службу Docker.

Все следующие команды выполняйте из папки `mcpBPMSoft`.

## 2. Укажите свой BPMSoft

Создайте в папке проекта файл **`.env`** и вставьте в него:

```dotenv
BPMSOFT_URL=https://bpm.example.ru
BPMSOFT_ODATA_VERSION=4
BPMSOFT_PLATFORM=net8
MCP_TRANSPORT=http
MCP_HTTP_HOST=0.0.0.0
MCP_HTTP_PORT=8007
MCP_ALLOWED_HOSTS=127.0.0.1:8007,localhost:8007
```

Замените `https://bpm.example.ru` адресом своего приложения BPMSoft. Например: `https://crm.company.ru`. Не добавляйте `/odata`, путь страницы, логин или пароль. Если приложение установлено в подпапке, сохраните её в адресе: `https://crm.company.ru/bpm`.

Версию OData и платформу выберите по настройкам своего стенда. Если не знаете их, уточните у администратора BPMSoft:

| Стенд                   | `BPMSOFT_ODATA_VERSION` | `BPMSOFT_PLATFORM` |
| ----------------------- | ----------------------- | ------------------ |
| .NET 8, OData 4         | `4`                     | `net8`             |
| .NET Framework, OData 4 | `4`                     | `netframework`     |
| .NET Framework, OData 3 | `3`                     | `netframework`     |

Логины и пароли пользователей в `.env` для этого запуска не нужны. Коннектор передаёт текущие cookies и токен пользователя. За обновление пользовательской сессии отвечает BPMSoft. Файл `.env` исключён из Git и Docker-образа.

<details>
<summary>Если один контейнер должен обслуживать несколько стендов</summary>

Создайте рядом с `.env` файл **`tenants.local.json`**. В нём перечислите свои стенды; вместо адресов из примера укажите настоящие:

```json
{
  "tenants": [
    { "id": "crm-a", "url": "https://bpm-a.example.ru", "odata_version": 4, "platform": "net8" },
    { "id": "crm-b", "url": "https://bpm-b.example.ru", "odata_version": 3, "platform": "netframework" }
  ]
}
```

`id` — короткое имя стенда для адреса подключения. Используйте латинские буквы, цифры, дефис или подчёркивание; начните с буквы или цифры. Каждое имя должно быть уникальным.

Добавьте в `.env` две строки:

```dotenv
BPMSOFT_MULTITENANT=true
BPMSOFT_TENANTS_FILE=/config/tenants.json
```

В этом режиме адреса берутся из JSON, а `BPMSOFT_URL` не используется. Пользователи и данные разных стендов разделены. Файл `tenants.local.json` также исключён из Git и Docker-образа.

**Без `BPMSOFT_MULTITENANT=true` сервер работает как раньше: один `BPMSOFT_URL`, подключение через `/mcp` или `/`.** Даже указанный файл тенантов без флага игнорируется.

</details>

## 3. Запустите сервис и подключитесь к нему

Соберите образ — при первом запуске это может занять несколько минут:

```bash
docker build -t mcp-bpmsoft .
```

Запустите сервер для **одного стенда**:

```bash
docker run -d --name mcp-bpmsoft --restart unless-stopped \
  --cpus=1 --memory=512m --memory-swap=512m \
  --env-file .env \
  -p 127.0.0.1:8007:8007 \
  --mount type=volume,source=mcp-bpmsoft-files,target=/app/files \
  --mount type=volume,source=mcp-bpmsoft-state,target=/app/state \
  mcp-bpmsoft
```

Docker сам создаст постоянные хранилища для файлов и журнала. Они сохранятся при замене контейнера. Сервер работает в фоне и автоматически запускается после перезапуска Docker.

Если вы включили режим нескольких стендов на шаге 2, вместо предыдущей команды выполните эту. Она дополнительно подключает ваш JSON-файл только для чтения:

```bash
docker run -d --name mcp-bpmsoft --restart unless-stopped \
  --cpus=1 --memory=512m --memory-swap=512m \
  --env-file .env \
  -p 127.0.0.1:8007:8007 \
  --mount type=volume,source=mcp-bpmsoft-files,target=/app/files \
  --mount type=volume,source=mcp-bpmsoft-state,target=/app/state \
  --mount "type=bind,source=$(pwd)/tenants.local.json,target=/config/tenants.json,readonly" \
  mcp-bpmsoft
```

Адреса подключения: `http://127.0.0.1:8007/tenants/crm-a/mcp` и `http://127.0.0.1:8007/tenants/crm-b/mcp`. Каждый запрос должен передавать сессию пользователя именно выбранного стенда. Изменения JSON-файла применяются после `docker restart mcp-bpmsoft`.

Проверьте, что сервис запущен:

```bash
curl -fsS http://127.0.0.1:8007/healthz
```

Ответ вида `{"status":"ok","version":"1.0.0"}` означает, что MCP-сервис работает. Эта проверка не обращается к BPMSoft.

В своём MCP-клиенте выберите подключение **Streamable HTTP** и укажите **`http://127.0.0.1:8007/mcp`**. В режиме нескольких стендов используйте соответствующий `/tenants/<id>/mcp`.

Коннектор должен передавать с каждым запросом заголовки `BPMCSRF` и `Cookie` с актуальной сессией пользователя BPMSoft. Одного адреса подключения недостаточно. Обновлённую сессию передаёт коннектор; сервер использует полученные токен и cookies.

Для проверки подключения попросите помощника: **«Вызови `bpm_whoami` и покажи, под каким пользователем BPMSoft ты работаешь»**. В ответе должен появиться ваш пользователь. Затем можно попросить найти несколько контактов или показать повестку.

### Проверка BPMSoft без MCP-клиента

Войдите в BPMSoft через браузер. Откройте инструменты разработчика (F12), вкладку «Сеть» / Network, и выполните поиск в BPMSoft. Выберите запрос `SelectQuery` или OData и скопируйте из заголовков запроса значения `BPMCSRF` и `Cookie` целиком.

В терминале выполните команды ниже и вставьте значения по запросу. Они не сохраняются в файлах проекта:

```bash
printf 'Вставьте BPMCSRF: '
read -r BPM_CHECK_CSRF
printf 'Вставьте Cookie: '
read -r BPM_CHECK_COOKIE
curl -sS http://127.0.0.1:8007/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "BPMCSRF: $BPM_CHECK_CSRF" \
  -H "Cookie: $BPM_CHECK_COOKIE" \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"bpm_whoami","arguments":{}}}'
unset BPM_CHECK_CSRF BPM_CHECK_COOKIE
```

Для нескольких стендов замените `/mcp` в команде на `/tenants/crm-a/mcp` или другой настроенный маршрут. Используйте сессию этого же стенда. Успешный ответ содержит сведения о вашем пользователе BPMSoft.

</details>

**Готово: сервис запущен, подключение проверено, можно работать с BPMSoft через помощника.**

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

| Что произошло                                  | Что сделать                                                                                                                                                                  |
| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Сервис не отвечает                             | Выполните `docker logs --tail 50 mcp-bpmsoft` и проверьте адрес BPMSoft и настройки `.env`.                                                                                  |
| Ошибка авторизации                             | Войдите в BPMSoft заново и проверьте передачу актуальных `BPMCSRF` и cookies коннектором.                                                                                    |
| `403 Forbidden` при подключении к MCP          | В `MCP_ALLOWED_HOSTS` укажите Host без `http://`, `https://` и пути: например, `localhost:8007` или `mcp.company.ru`. Для браузера может понадобиться `MCP_ALLOWED_ORIGINS`. |
| `404` на адресе стенда                         | Проверьте флаг нескольких стендов и совпадение имени в JSON с `/tenants/<id>/mcp`.                                                                                           |
| Docker сообщает, что имя контейнера уже занято | Если обновляете прежний сервис, используйте порядок обновления ниже.                                                                                                         |

### Подключение с другого компьютера

Команда выше открывает порт только на компьютере, где запущен Docker. Для удалённых пользователей настройте HTTPS через reverse proxy, например `https://mcp.company.ru/mcp`. Добавьте его внешний Host в `.env`: `MCP_ALLOWED_HOSTS=mcp.company.ru,127.0.0.1:8007,localhost:8007`. Для браузерного клиента добавьте `MCP_ALLOWED_ORIGINS=https://mcp.company.ru`.

Proxy должен иметь доступ к локальному порту `8007` и передавать пользовательские заголовки авторизации. После изменения `.env` пересоздайте контейнер: обычный перезапуск не перечитывает `--env-file`.

### Обновление сервиса

Сохраните `.env`, `tenants.local.json`, если он используется, и постоянные хранилища Docker. В папке проекта выполните:

```bash
git pull
docker build -t mcp-bpmsoft .
docker stop mcp-bpmsoft
docker rm mcp-bpmsoft
```

Затем повторите свою команду `docker run` из шага 3 и проверку `/healthz`. Не удаляйте тома `mcp-bpmsoft-files` и `mcp-bpmsoft-state`: в них хранятся пользовательские файлы и журнал. Если обновление делаете без получения нового кода, пропустите `git pull` и сборку образа.

### Файлы и проверка операций

HTTP-файлы доступны только своему пользователю на своём стенде. Относительные `file_path` и `save_path` относятся к его личному каталогу. Старые файлы из общего каталога переносит администратор после проверки владельца; автоматически раздавать их пользователям нельзя. Содержимое файла также можно передать через `content_base64`.

В режиме нескольких стендов журнал изменений включён автоматически. Для одного стенда его можно включить строкой `BPMSOFT_JOURNAL_ROOT=/app/state/operations` в `.env` и пересоздать контейнер. После потери ответа используйте `bpm_get_operation` с полученным `operation_id` или без него, чтобы найти свои операции. Не повторяйте изменение вслепую: оно могло уже выполниться в BPMSoft.

Сервер допускает до 500 одновременно выполняемых HTTP-запросов. Возможности реального стенда и необходимую память проверяйте на своих данных; показанная конфигурация ресурсов — начальный профиль. Если чтение слишком большое, запрашивайте меньше записей и полей.

Лицензия: [MIT](LICENSE).