Priority REST API MCP Server

MCP-сервер, который подключает ИИ-ассистентов — Claude и другие — напрямую к ERP-системе Priority. Каждая операция OData (запрос, создание, обновление, удаление, пакетная обработка, вложения, текстовые поля) представлена как инструмент MCP, поэтому ИИ-агенты могут читать и записывать оперативные бизнес-данные без написания пользовательского интеграционного кода.

Версия: 0.2.0 · Транспорт: Streamable HTTP (SSE опционально) · Среда выполнения: Node.js 18 · Инструменты: 19

Быстрый старт

1. Клонируйте репозиторий и установите зависимости

git clone https://github.com/priority-mcp/priority-odata-mcp priority-mcp
cd priority-mcp
npm install

2. Создайте файл .env из примера

cp .env.example .env

Как минимум задайте эти четыре переменные:

PRIORITY_BASE_URL=https://<host>/odata/Priority/<tabula.ini>/<company>/
PRIORITY_AUTH_TYPE=basic
PRIORITY_USERNAME=myuser
PRIORITY_PASSWORD=mypassword

3. Запустите сервер

# Development (from source)
node src/index.js

# Production (bundled)
npm run build
node dist/index.js

При первом запуске, если ODATA_MCP_TOKEN не задан, генерируется случайный Bearer-токен и выводится в stdout. Скопируйте его для следующего шага.

4. Подключитесь из Claude Code

Добавьте в конфигурацию MCP:

{
  "mcpServers": {
    "priority": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer <ODATA_MCP_TOKEN>"
      }
    }
  }
}

Related MCP server: mcp_sdk_eyra_accelerator

Транспорт

Сервер использует Streamable HTTP в качестве основного транспорта — каждый запрос POST /mcp полностью не сохраняет состояние. Новые McpServer и StreamableHTTPServerTransport создаются для каждого запроса и уничтожаются после его завершения.

Примечание: Конечные точки OAuth 2.1 существуют для удовлетворения процедуры установления соединения Streamable HTTP в Claude Code. Они автоматически одобряют все запросы и не предназначены для реального контроля доступа — эту функцию выполняет ODATA_MCP_TOKEN.

Аутентификация

Аутентификация работает на двух независимых уровнях.

Уровень 1 — защита этого сервера

Все маршруты (кроме /health и конечных точек OAuth) требуют:

Authorization: Bearer <ODATA_MCP_TOKEN>

Задайте ODATA_MCP_TOKEN в файле .env. Если он отсутствует, при запуске генерируется случайный UUID и выводится в stdout.

Уровень 2 — вызовы Priority ERP

Управляется переменной PRIORITY_AUTH_TYPE:

• basic — базовая HTTP-аутентификация с использованием PRIORITY_USERNAME + PRIORITY_PASSWORD

• pat — Bearer-токен через PRIORITY_PAT

• oauth2 — то же, что и pat (передайте PAT как Bearer-токен)

• none — без заголовка аутентификации (только для локального тестирования)

Операции записи (POST/PATCH/DELETE) автоматически получают и повторяют запрос с заголовком X-CSRF-Token, если первоначальный запрос отклонён, следуя схеме защиты CSRF в Priority.

Опциональные заголовки лицензии приложения отправляются с каждым запросом к Priority, если заданы PRIORITY_APP_ID и PRIORITY_APP_KEY (X-App-Id / X-App-Key).

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

Скопируйте .env.example в .env. Сервер ищет файл .env в следующем порядке: ENV_FILE_PATH → ./mcp-servers/Priority-REST-API-MCP-Server/.env → ./.env.

Обязательные параметры

Аутентификация Priority (опционально)

HTTP-сервер

Тайм-ауты и TLS

Отладка

Инструменты

Все 19 инструментов определены в src/tools/ и зарегистрированы в src/tools/priorityTools.js.

Система и метаданные

Запросы

Создание / Обновление / Удаление

Текстовые поля

Вложения

Конфигурация и справка

Промпты и ресурсы

Сервер регистрирует MCP промпты (многоразовые шаблоны инструкций) и ресурсы (живые конечные точки данных).

Промпты (src/prompts/)

Ресурсы (src/resources/)

Пример вызова инструмента

Запросить три самых последних заказа на продажу для клиента 1011 — отправлено как JSON-RPC 2.0 на POST /mcp:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "query_run",
    "arguments": {
      "entity":  "ORDERS",
      "filter":  "CUSTNAME eq '1011'",
      "select":  ["ORDNAME", "CUSTNAME", "CURDATE", "TOTPRICE"],
      "top":     3,
      "orderby": "CURDATE desc"
    }
  }
}

Сервер выдаёт:

GET /odata/Priority/.../ORDERS?$format=json&$filter=CUSTNAME+eq+'1011'
  &$select=ORDNAME,CUSTNAME,CURDATE,TOTPRICE&$top=3&$orderby=CURDATE+desc

Ответ:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"value\":[{\"ORDNAME\":\"SO25000001\",\"CUSTNAME\":\"1011\",\"CURDATE\":\"2025-07-15T00:00:00+03:00\",\"TOTPRICE\":15000.0},...],\"_mcp_metadata\":{\"entity\":\"ORDERS\",\"resultCount\":2,\"filterApplied\":true}}"
    }],
    "isError": false
  }
}

Формат даты: Priority возвращает даты в формате ISO 8601 со смещением часового пояса (например, 2025-07-15T00:00:00+03:00), а не в UTC Z. Используйте синтаксис CURDATE ge 2025-01-01 в фильтрах по датам — не формат ISO-Z.

Развёртывание

Docker

# Build
docker build -t priority-mcp .

# Run
docker run --env-file .env -p 3000:3000 priority-mcp

Dockerfile использует node:18-slim, выполняет npm run build для сборки src/ → dist/ через esbuild, затем запускает dist/index.js. Конфигурация Docker Compose и локальный генератор TLS-сертификатов находятся в deployment/local/.

Контрольный список для продакшена

• Установите ODATA_MCP_TOKEN явно — не полагайтесь на автоматически сгенерированный

• Установите TLS_REJECT_UNAUTHORIZED=true

• Установите STRICT_DATA_INTEGRITY=true (по умолчанию)

• Установите LOG_LEVEL=INFO (по умолчанию — подавляет служебный шум)

• Привяжите HTTP_HOST к конкретному интерфейсу, если не публикуете наружу

Известные ограничения

Особенности поведения Priority ERP, о которых стоит знать перед разработкой.

Ограничение частоты запросов — 100 вызовов/минуту на пользователя Priority Cloud ограничивает до 100 вызовов API в минуту на пользователя, максимум 10 параллельных запросов, тайм-аут 3 минуты на вызов. Проектируйте агентов так, чтобы по возможности группировать операции.

Ограничение ответа — MAXFORMLINES Priority молча обрезает ответы на уровне системной константы MAXFORMLINES независимо от $top. Используйте пагинацию на основе $skip, если нужны все записи.

Подформы не являются самостоятельными сущностями Прямой запрос PORDERITEMS_SUBFORM возвращает HTTP 404. Доступ к подформам должен осуществляться через родительскую сущность с $expand=PORDERITEMS_SUBFORM. metadata_schema_get автоматически определяет это и перенаправляет.

$apply=aggregate не поддерживается query_sum всегда переключается на полное сканирование с пагинацией, поскольку $apply=aggregate(...) не поддерживается в этой версии Priority.

GET /ENTITY/$count возвращает 500 Вместо этого используйте ?$top=0&$count=true. Внутренне tryEstimateCount() сначала пробует /$count, затем выполняет пагинацию пакетами по 500 записей (с ограничением 10 000).

contains()/startswith() не поддерживаются для некоторых полей EPROG.ENAME и EREP.ENAME поддерживают только точное совпадение eq — строковые функции возвращают HTTP 501.

Обновление метаданных на уровне сущности возвращает 400 metadata_refresh игнорирует аргумент entity и всегда выполняет полный сброс кэша, поскольку Priority отклоняет запросы на очистку кэша в рамках одной сущности.

Кодирование URL в пакетных запросах URL-адреса внутри запросов batch_operations никогда не кодируются автоматически. Пробелы и специальные символы должны быть вручную закодированы в процентах (пробелы → %20).

Составные ключи Некоторые сущности используют составные ключи, например FORMLIMITED: ENAME='X',TYPE='F'; AINVOICES: IVNUM='T9696',IVTYPE='A',DEBIT='D'. Передавайте полную строку составного ключа в entity_update и entity_delete.

Структура проекта

/
├── src/
│   ├── index.js                    Entry point — creates and starts PriorityMCPServer
│   ├── server.js                   Express app, all routes, auth guard, OAuth 2.1 PKCE
│   ├── sseServer.js                SSE connection manager
│   ├── config.js                   Reads all env vars, resolves .env path
│   ├── version.js                  SERVER_VERSION, KNOWN_ISSUES list
│   │
│   ├── priority/
│   │   └── client.js               PriorityClient — axios instance, auth headers,
│   │                               all API methods (runQuery, createEntity, …)
│   │
│   ├── mcp/
│   │   ├── handler.js              JSON-RPC 2.0 dispatcher (SSE path)
│   │   ├── registry.js             ToolRegistry — registerTool, callTool, listTools
│   │   ├── prompt-registry.js
│   │   ├── resource-registry.js
│   │   ├── priority-mcp-sdk-server.js   Wires registries into McpServer (SDK path)
│   │   ├── tool-call-runner.js          Executes tool, wraps result for MCP response
│   │   └── json-schema-to-zod.js        JSON Schema → Zod conversion
│   │
│   ├── tools/                      One file per tool + priorityTools.js (registration)
│   ├── prompts/                    One file per prompt + priorityPrompts.js
│   ├── resources/                  One file per resource + priorityResources.js
│   └── utils/
│       ├── data-integrity.js       ensureNoMockData(), validateApiResponse()
│       ├── date-handling.js        Date parsing and validation helpers
│       ├── errors.js               createPriorityApiError(), FilterNotAppliedError
│       ├── filter-resolver.js      OData filter string building
│       ├── expand-resolver.js      $expand normalization
│       ├── entity-resolver.js      Entity name / subform name resolution
│       ├── resolve-query-args.js
│       └── subform-query-resolver.js
│
├── data/
│   └── entity-relationships.json   Hardcoded subform map (PORDERS, ORDERS, …)
│
├── tests/
│   ├── scripts/                    Manual test scripts
│   └── results/                    Saved JSON/Markdown test output
│
├── docs/                           Design docs (DATA_INTEGRITY_POLICY, DATE_HANDLING_RULES, …)
├── postman/                        Postman collection for manual API testing
├── deployment/local/               Docker Compose + TLS cert generator
├── build.js                        esbuild bundler: src/ → dist/
└── .env.example                    All env vars documented with descriptions

Тесты

Автоматизированного тестового раннера нет. Тесты — это ручные скрипты, требующие живого подключения к Priority:

# Read operations
node tests/scripts/test-priority-operations.js

# Write operations (interactive — asks for confirmation)
node tests/scripts/test-write-operations.js

# Test all 19 MCP tools via the running server
node tests/scripts/test-all-mcp-tools-via-server.js

# Standalone resolver smoke tests
node test-keyresolver.js
node test-resolver.js

Предупреждение: Тесты на запись создают, обновляют и удаляют реальные записи. Запускайте только на компании для разработки.

Технологический стек

• Среда выполнения: Node.js 18, ES-модули ("type": "module")

• MCP SDK: @modelcontextprotocol/sdk ^1.29.0

• HTTP-сервер: express ^4.21.1

• HTTP-клиент: axios ^1.7.7

• Проверка схем: zod ^4.3.6

• Сборщик: esbuild ^0.25.0 (через npm run build)

• Прочее: cors, dotenv, form-data, uuid, http-errors