McpBPMSoft

Name: McpBPMSoft
Availability: InStock
Author: Catter58

Free

Enables natural language interaction with BPMSoft CRM by handling OData complexity, lookup resolution, and safe CRUD operations through 32 MCP tools.

by Catter58

GitHub

About

Enables natural language interaction with BPMSoft CRM by handling OData complexity, lookup resolution, and safe CRUD operations through 32 MCP tools.

README

Подключение BPMSoft 1.8 к LLM-агенту (Claude Desktop, Cursor, любой клиент Model Context Protocol) — чтобы спросить «найди контакты из Москвы за последний месяц» или «зарегистрируй Иванова из Ромашки», а не вручную набирать OData-фильтры.

Сервер берёт на себя всё, что обычно мешает:

авторизацию, CSRF-токены и сессии BPMSoft;
разницу между OData v3 и v4 (форматы ID, имена полей, $batch);
перевод «Город = Москва» в CityId = <UUID> через справочники;
защиту от случайного массового удаления, переполнения контекста модели и SSRF;
запуск бизнес-процессов через ProcessEngineService.

В коробке 32 инструмента, 6 prompts, 4 ресурса — от низкоуровневого CRUD до готовых сценариев «зарегистрировать контакт + контрагента» и «найти всё про Иванова».

Что это решает

BPMSoft (форк Creatio) предоставляет OData-API, который мощный, но очень многословный. Запрос «контакты из Москвы, созданные на этой неделе» на чистом OData выглядит так:

GET /0/odata/Contact?$filter=City/Name eq 'Москва' and CreatedOn ge 2026-04-26T00:00:00Z&$select=Id,Name,Email
Cookie: BPMSESSIONID=...; BPMCSRF=...
BPMCSRF: <csrf>
ForceUseSession: true

LLM-агенту, который пытается его собрать, нужно знать:

где живёт OData (для .NET 8 — /odata, для .NET Framework — /0/odata, для v3 — отдельный путь);
что строки в одинарных кавычках, GUID-ы у v3 в guid'…', у v4 без обёртки;
что лимит ответа 20 000 строк, $batch только в v4 и не больше 100 подзапросов;
что lookup-поля у v4 заканчиваются на Id, а у v3 — нет;
что русские названия полей доступны только через системную таблицу SysEntitySchemaColumn;
и десяток других мелочей.

Этот сервер прячет всё это за человеческим интерфейсом:

Пользователь:  Найди контакты из Москвы за последние 30 дней
Агент → tool:  bpm_search_records
                 collection: "Contact"
                 criteria: [
                   { field: "Город",         op: "равно",            value: "Москва" },
                   { field: "Дата создания", op: "за последние N дней", value: 30 }
                 ]
Сервер →       Скомпилирует $filter, разрешит «Москва» в UUID города,
               применит лимит max_records (от переполнения контекста),
               вернёт сводку + первые 5 записей + cursor для следующих.

Быстрый старт за 5 минут

Требуется: Node.js 18+, инстанс BPMSoft 1.8 с включённым OData (по умолчанию — да).

# 1. Склонировать репозиторий
git clone https://github.com/Catter58/mcpBPMSoft.git
cd mcpBPMSoft

# 2. Установить зависимости
npm install

# 3. Собрать
npm run build

# 4. Прописать подключение в .env (или передать переменные среды)
cp .env.example .env
# открыть .env, заполнить BPMSOFT_URL / USERNAME / PASSWORD

# 5. Запустить (с переменными среды)
npm start

Сервер общается через stdio — это стандартный транспорт MCP. Самостоятельный запуск нужен только для отладки; в реальной жизни сервер запускает MCP-клиент (Claude Desktop, Cursor и т.п.) — см. ниже.

Альтернатива: интерактивная инициализация

Если не хочешь хранить пароль в .env, запусти сервер без переменных и попроси LLM вызвать инструмент bpm_init:

Агент: bpm_init
       url:      https://mycompany.bpmsoft.com
       username: Supervisor
       password: ***

Сервер сразу проверит подключение, и все остальные инструменты станут доступны.

Подключение к Claude Desktop

В файле ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) или %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "bpmsoft": {
      "command": "node",
      "args": ["/абсолютный/путь/к/mcpBPMSoft/build/index.js"],
      "env": {
        "BPMSOFT_URL":      "https://mycompany.bpmsoft.com",
        "BPMSOFT_USERNAME": "Supervisor",
        "BPMSOFT_PASSWORD": "пароль",
        "BPMSOFT_ODATA_VERSION": "4",
        "BPMSOFT_PLATFORM":      "net8"
      }
    }
  }
}

Перезапустить Claude Desktop. В чате появится бейдж bpmsoft, и список из 32 инструментов будет доступен модели.

Если предпочитаешь интерактивный логин — оставь блок env пустым и попроси Claude вызвать bpm_init в начале диалога.

Полный пример — в examples/claude_desktop_config.json.

Примеры диалогов

Пример 1 — поиск с человеческим языком

Пользователь: покажи активные сделки на сумму больше 500 тысяч,
              где менеджер — Иванова

Claude → bpm_search_records
  collection: "Opportunity"
  criteria: [
    { field: "Сумма",     op: "больше", value: 500000 },
    { field: "Owner",     op: "равно",  value: "Иванова" },
    { field: "Stage",     op: "не равно", value: "Закрыта (выиграна)" }
  ]
  format: "markdown"

Сервер вернёт:
  Скомпилированный $filter:
    Amount gt 500000 and OwnerId eq <UUID Ивановой>
    and StageId ne <UUID этапа закрыта>
  Получено записей: 7

  | Id  | Title              | Amount  | Stage      | Owner    |
  |-----|--------------------|---------|------------|----------|
  | ... | Поставка софта     | 1200000 | В работе   | Иванова  |
  ...

Пример 2 — регистрация нового контакта

Пользователь: создай контакт Петров Пётр, телефон +7-999-1234567,
              работает в ООО Орбита

Claude → bpm_register_contact
  name: "Петров Пётр"
  phone: "+7-999-1234567"
  account_name: "ООО Орбита"

Сервер:
  1. Ищет Account по Name='ООО Орбита' → не нашёл → создаёт.
  2. Получает accountId.
  3. Создаёт Contact с подставленным AccountId.
  4. Возвращает оба UUID.

Пример 3 — массовое обновление со страховкой

Пользователь: закрой все мои задачи старше года

Claude → bpm_search_records      (узнать сколько таких)
  collection: "Activity"
  criteria: [
    { field: "Owner",     op: "равно",         value: "<текущий пользователь>" },
    { field: "CreatedOn", op: "меньше",        value: "2025-05-02T00:00:00Z" },
    { field: "Status",    op: "не равно",      value: "Завершено" }
  ]

[ответ: 12 записей]

Пользователь: ага, закрывай

Claude → bpm_update_by_filter
  collection: "Activity"
  filter: "OwnerId eq <UUID> and CreatedOn lt 2025-05-02T00:00:00Z and StatusId ne <UUID Завершено>"
  data: { Status: "Завершено" }
  expected_count: 12       # страховка: если найдено иное число — операция отменится

Пример 4 — запуск бизнес-процесса

Пользователь: запусти процесс «UsrCalculatePipeline» и покажи результат

Claude → bpm_run_process
  process_name: "UsrCalculatePipeline"
  parameters: { period_days: "30" }
  result_parameter_name: "UsrPipelineSummary"

Сервер:
  GET /ServiceModel/ProcessEngineService.svc/UsrCalculatePipeline/Execute
       ?period_days=30&ResultParameterName=UsrPipelineSummary
  Парсит XML-обёртку <string>...</string>, JSON.parse содержимого.
  Возвращает структуру в structuredContent.

Пример 5 — комментарий в ленте записи

Пользователь: оставь в ленте этой сделки заметку «звонил, обещали вернуться в среду»

Claude → bpm_post_feed
  collection: "Opportunity"
  id: "<UUID сделки>"
  message: "звонил, обещали вернуться в среду"

Сервер:
  POST /odata/SocialMessage
  body: { Message: "...", EntitySchemaName: "Opportunity", EntityId: "..." }

Все 32 инструмента — кратко

Подключение

Инструмент	Зачем
`bpm_init`	Подключиться к BPMSoft (URL, логин/пароль, OData v3/v4, платформа)

Чтение

Инструмент	Зачем
`bpm_get_records`	Получить записи коллекции с фильтром/select/expand/order/top/skip; safe-pagination + token-aware форматы (compact/full/markdown); поддерживает opaque cursor
`bpm_get_record`	Одна запись по UUID
`bpm_count_records`	Количество записей по фильтру
`bpm_search_records`	Поиск с критериями на русском — массив `{field, op, value}`, операторы «равно», «содержит», «за последние N дней» и т.п.; компилирует в OData $filter

Запись

Инструмент	Зачем
`bpm_create_record`	Создать запись; lookup-поля резолвятся по тексту, ключи можно на русском
`bpm_update_record`	Обновить по UUID
`bpm_delete_record`	Удалить по UUID
`bpm_update_by_filter`	Массовое обновление с обязательным `expected_count` (страховка)
`bpm_delete_by_filter`	Массовое удаление с обязательным `expected_count`

Схема и справочники

Инструмент	Зачем
`bpm_get_collections`	Список доступных EntitySet
`bpm_get_schema`	Поля коллекции с русскими подписями, типами, lookup-связями
`bpm_lookup_value`	Найти UUID справочного значения; `fuzzy=true` — нечёткий поиск через `contains()`
`bpm_get_enum_values`	Все значения справочника, к которому привязано lookup-поле (например, все ActivityCategory)
`bpm_workflow_catalog`	Карта типичных сценариев + связи между сущностями + ограничения BPMSoft 1.8. Хорошо вызывать в начале сессии.
`bpm_find_field`	Найти поле по фрагменту русского/английского названия в уже загруженных схемах
`bpm_describe_instance`	Сводка по инстансу за один вызов: главные сущности, их счётчики, кастомные коллекции/поля (`Usr*`). Кеш 5 мин.

Пакетные операции (только OData v4)

Инструмент	Зачем
`bpm_batch_create`	Создать N записей одним $batch
`bpm_batch_update`	Обновить N записей одним $batch
`bpm_batch_delete`	Удалить N записей одним $batch

Все три поддерживают continue_on_error.

Файлы

Инструмент	Зачем
`bpm_upload_file`	Загрузить локальный файл в `SysImage` + опционально привязать к записи
`bpm_download_file`	Скачать файл из `SysImage`
`bpm_field_upload`	PUT бинарных данных в произвольное поле сущности (`{Coll}({id})/{Field}`)
`bpm_field_download`	GET бинарных данных из поля сущности
`bpm_field_delete`	Очистить бинарное поле

Готовые workflow-инструменты

Инструмент	Зачем
`bpm_register_contact`	Создать Account (или найти) + создать Contact + привязать
`bpm_log_activity`	Создать Activity с резолвом типа/владельца по тексту, опц. привязка к Contact/Account/Opportunity
`bpm_set_status`	Сменить статус по человеческому имени; сервер сам найдёт правильное status-поле и его справочник
`bpm_search_unified`	Сквозной поиск по подстроке в Contact/Account/Lead/Opportunity (плоский список)

Бизнес-процессы и лента

Инструмент	Зачем
`bpm_run_process`	Запустить БП через `ProcessEngineService.svc`, опц. забрать результат через `result_parameter_name`
`bpm_exec_process_element`	Возобновить элемент уже выполняющегося процесса по UID
`bpm_post_feed`	Опубликовать сообщение в ленту записи (через коллекцию `SocialMessage`)

Готовые сценарии (MCP prompts)

LLM-клиенты с поддержкой prompts (Claude Desktop, Cursor) могут вызвать готовый сценарий за одну команду — модель получит сразу шаблон с инструкциями и нужными tool-ами:

Prompt	Аргументы	Что делает
`getting_started`	—	Обзор сервера, главные сущности, типичные сценарии
`quick_search`	`query`	Сквозной поиск + детали при необходимости
`create_contact_flow`	`name, account?, email?, phone?`	Регистрация контакта в один заход
`weekly_report`	`period_days?`	Отчёт: новые контакты, активные сделки, завершённые задачи
`cleanup_duplicates_check`	`collection, field?`	Поиск потенциальных дубликатов (без удаления)
`pipeline_analysis`	`stage_field?`	Анализ воронки Opportunity: распределение по стадиям, средняя сумма

Ресурсы (MCP resources)

Браузабельные URI, которые модель может «прочитать» вместо tool-вызова — дешевле по токенам, удобно для карточек:

bpmsoft://collections                    — список всех EntitySet
bpmsoft://collection/{name}              — карточка коллекции (поля + record_count)
bpmsoft://entity/{collection}/{id}       — карточка одной записи
bpmsoft://schema/{name}                  — только схема коллекции (быстрее, без count)

Конфигурация

Все параметры — через переменные окружения. Минимально необходимы первые три, остальные имеют разумные defaults:

Переменная	По умолчанию	Описание
`BPMSOFT_URL`	— (обязательно)	URL приложения, например `https://mycompany.bpmsoft.com`
`BPMSOFT_USERNAME`	— (обязательно)	Логин
`BPMSOFT_PASSWORD`	— (обязательно)	Пароль
`BPMSOFT_ODATA_VERSION`	`4`	`4` или `3`
`BPMSOFT_PLATFORM`	`net8`	`net8` или `netframework`
`BPMSOFT_PAGE_SIZE`	`5000`	Размер страницы при автопагинации
`BPMSOFT_MAX_BATCH_SIZE`	`100`	Лимит подзапросов в `$batch`
`BPMSOFT_LOOKUP_CACHE_TTL`	`300`	TTL кеша lookup в секундах
`BPMSOFT_REQUEST_TIMEOUT`	`30000`	Таймаут одного HTTP-запроса (мс)
`BPMSOFT_MAX_FILE_SIZE`	`10485760`	Лимит размера файла (10 МБ)
`BPMSOFT_DEBUG`	`off`	`1` — логировать `method url status duration`; `trace` — ещё и тела с маскированием паролей и токенов

Без переменных среды сервер всё равно стартует, но любой инструмент кроме bpm_init ответит «сервер не инициализирован».

Скрипты

npm run build         # компиляция TS -> JS в build/
npm start             # запустить собранный сервер
npm run dev           # tsc --watch на время разработки
npm test              # vitest run (95 тестов: unit + интеграция через MSW)
npm run test:watch    # тесты в watch-режиме
npm run lint          # eslint (typescript-eslint, рекомендованный preset)
npm run lint:fix      # автоисправление
npm run format        # prettier --write
npm run format:check  # prettier --check (для CI)

Отладка

Самый быстрый способ увидеть, что именно уходит в BPMSoft — включить BPMSOFT_DEBUG:

BPMSOFT_DEBUG=1 npm start
# -> [HttpClient][req] GET https://.../odata/Contact?$top=10
# -> [HttpClient][res] GET .../odata/Contact -> 200 (143ms)

BPMSOFT_DEBUG=trace npm start
# -> также выводит headers и тела запросов/ответов;
#    BPMCSRF/Cookie/UserPassword автоматически маскируются.

Для проверки подключения без MCP-клиента можно запустить сервер напрямую — он выводит в stderr:

[Server] Configuration loaded from environment variables
  Target: https://mycompany.bpmsoft.com
  OData: v4, Platform: net8
MCP BPMSoft OData Server running on stdio
Registered 32 tools (bpm_init + 31 operational)
Registered 6 prompts, 4 resource templates

Ограничения BPMSoft 1.8

Ограничение	Значение
Максимум строк в OData-ответе	20 000
Максимум подзапросов в `$batch`	100
Максимальный размер файла	10 МБ (настраивается)
Длина query string в OData v3	4 000 символов
`$batch` в OData v3	не поддерживается (используйте v4)
Создание системных пользователей	не поддерживается
Прямой HTTP-API для EntitySchemaQuery	не предусмотрен — используйте обёртку через бизнес-процесс (см. сценарий `esq-via-process` в `bpm_workflow_catalog`)

Часто задаваемые вопросы

LLM путается в OData-синтаксисе. Что делать? Используйте bpm_search_records с criteria-массивом. Он принимает поля по русской подписи, операторы по-русски, сам экранирует значения и ставит правильный синтаксис. Сырые $filter нужны только для очень специфичных случаев.

Сервер вернул 20 000 строк в одном ответе и контекст модели «лопнул». По умолчанию bpm_get_records ограничивает выдачу max_records=1000 и пагинация выключена. Если хотите всё — передайте auto_paginate: true и увеличьте max_records. Для пошагового перебора возвращается cursor — передайте его в следующий вызов и получите следующую страницу без перенабора параметров.

Как назвать поле — «Город» или «City»? Любым. Сервер хранит двусторонний словарь caption ↔ name (по SysSchema/SysEntitySchemaColumn) и переводит сам. Если не угадал — в ошибке будут «Похоже на: …».

Lookup-значения — UUID или текст? Текст. Сервер сам резолвит «Москва» → <UUID> через bpm_lookup_value. Если найдено несколько кандидатов — вернёт список и попросит уточнить.

OData v3 на .NET Framework — будет работать? Да, кроме $batch (его в v3 BPMSoft нет). При попытке bpm_batch_* на v3 получите явную ошибку, а не молчаливое 404.

Как запустить кастомный бизнес-процесс? bpm_run_process с process_name (имя схемы процесса) и parameters. Если процесс возвращает результат — добавьте result_parameter_name. Сервер заберёт XML-обёртку и распакует JSON-payload в structuredContent.

Что если на инстансе нет коллекции SocialMessage? bpm_post_feed вернёт ошибку 404 с понятным сообщением «На этом инстансе нет коллекции SocialMessage; функция ленты не настроена». Лента в BPMSoft может быть выключена настройками безопасности.

Архитектура (для разработчиков)

src/
  client/         HttpClient (binary-aware, contentKind, SSRF, 429+Retry-After)
                  ODataClient (v3/v4, $batch, nextLink, бинарные поля)
  process/        ProcessEngineClient (XML envelope parsing)
  metadata/       MetadataManager (fast-xml-parser, caption maps, suggestions)
  lookup/         LookupResolver (caption-aware, LRU, fuzzy fallback)
  utils/          errors, odata, suggest, filter-compiler, render, cursor
  prompts/        registry + register
  resources/      4 resource templates
  tools/          init, read, write, schema, describe-instance, enum,
                  workflow-catalog, batch, stream, process
  workflows/      register-contact, log-activity, set-status, search-unified

tests/            95 тестов (vitest + MSW): юнит + интеграция HTTP

Подробнее — в CLAUDE.md (для разработчиков, добавляющих новые tool-ы)

Лицензия

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

Дополнительно (не юридически обязательно): если планируете существенное переиспользование, интеграцию в коммерческий продукт или редистрибуцию под собственным брендом — автор будет признателен за короткое сообщение в GitHub: @Catter58. Это не требование лицензии, а просьба «дайте знать, чтобы я мог помочь и был в курсе».

Полный текст — в LICENSE.

How to install

Add this to claude_desktop_config.json and restart Claude Desktop.

{
  "mcpServers": {
    "mcpbpmsoft": {
      "command": "npx",
      "args": []
    }
  }
}

McpBPMSoft

About

README

Содержание

Что это решает

Быстрый старт за 5 минут

Альтернатива: интерактивная инициализация

Подключение к Claude Desktop

Примеры диалогов

Пример 1 — поиск с человеческим языком

Пример 2 — регистрация нового контакта

Пример 3 — массовое обновление со страховкой

Пример 4 — запуск бизнес-процесса

Пример 5 — комментарий в ленте записи

Все 32 инструмента — кратко

Подключение

Чтение

Запись

Схема и справочники

Пакетные операции (только OData v4)

Файлы

Готовые workflow-инструменты

Бизнес-процессы и лента

Готовые сценарии (MCP prompts)

Ресурсы (MCP resources)

Конфигурация

Скрипты

Отладка

Ограничения BPMSoft 1.8

Часто задаваемые вопросы

Архитектура (для разработчиков)

Лицензия

How to install

Related MCPs

GitHub

Supabase

Everything

Filesystem

Command Palette

McpBPMSoft

About

README

Содержание

Что это решает

Быстрый старт за 5 минут

Альтернатива: интерактивная инициализация

Подключение к Claude Desktop

Примеры диалогов

Пример 1 — поиск с человеческим языком

Пример 2 — регистрация нового контакта

Пример 3 — массовое обновление со страховкой

Пример 4 — запуск бизнес-процесса

Пример 5 — комментарий в ленте записи

Все 32 инструмента — кратко

Подключение

Чтение

Запись

Схема и справочники

Пакетные операции (только OData v4)

Файлы

Готовые workflow-инструменты

Бизнес-процессы и лента

Готовые сценарии (MCP prompts)

Ресурсы (MCP resources)

Конфигурация

Скрипты

Отладка

Ограничения BPMSoft 1.8

Часто задаваемые вопросы

Архитектура (для разработчиков)

Лицензия

How to install

Related MCPs

GitHub

Supabase

Everything

Filesystem