SAP Business One MCP Server Sample

• SAP Business One MCP Server Sample

  • Введение

  • Обзор архитектуры

  • Доступные MCP-инструменты

    • Базовые инструменты обнаружения и выполнения

      • Поэтапное обнаружение в 3 шага

    • Инструменты выбора компании

    • Вспомогательные инструменты рабочих процессов

    • MCP-ресурсы

  • Предварительные требования

  • Установка

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

    • Прямой режим (только для разработки)

    • Режим OAuth (продакшн, режим по умолчанию)

    • HTTPS / транспорт

  • Запуск сервера

  • Подключение ИИ-клиента

    • Cline (VS Code)

    • GitHub Copilot (VS Code)

    • Goose (Desktop)

    • MCP Inspector (браузер)

  • Интеграция MCP-клиента

  • Подтверждение пользователя (MCP-элиситация)

  • Классификация персональных данных

    • Как классифицируются поля

    • Где отображается классификация

    • Защита во время выполнения

    • Поведение маскирования результатов чтения

  • Поддержка UDO/UDT/UDF

    • Именование UDO

    • Задержка обнаружения

  • Поддержка мультитенантности

  • Примеры использования

    • Запросы на естественном языке

    • Примеры рабочих процессов

      • Базовый CRUD-процесс

      • Процесс «От заказа до оплаты» (пошагово)

    • Запросы бизнес-аналитики

    • Манипулирование данными

  • Тестирование сервера

    • Модульные тесты

    • Интеграционные тесты

    • Полная проверка качества

  • Журналирование

    • Журналы приложения

    • Журналы аудита

  • Вопросы безопасности

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

    • Авторизация

    • Продакшн-конфигурация

  • Устранение неполадок

    • Проблемы с сервером или подключением

    • Аутентификация и контекст компании

    • Проблемы с сущностями, полями или записью

    • Включение параметров отладки

  • Справочник по конфигурации

  • Ограничение

Введение

Начиная с версии SAP Business One 10.0 FP2608, предоставляется образец сервера SAP Business One MCP Server, демонстрирующий, как OData-сервисы SAP B1 Service Layer можно представлять в виде динамических инструментов для ИИ-агентов, поддерживающих Model Context Protocol (MCP).

Образец сервера спроектирован как минималистичный и лёгкий для понимания, но при этом раскрывает основные паттерны и возможности MCP-сервера. Вместо регистрации сотен отдельных CRUD-инструментов (по одному на сущность × операцию) сервер использует архитектуру поэтапного обнаружения, которая сводит сотни возможных инструментов к нескольким интеллектуальным многоразовым инструментам.

Такое проектирование позволяет ИИ-ассистентам:

• Обнаруживать релевантные сущности B1 с помощью лёгкого семантического поиска

• Понимать полные схемы сущностей, включая свойства, типы и возможности

• Выполнять аутентифицированные операции CRUD с автоматической генерацией OData-запросов

Запросы на естественном языке, такие как "Покажи мне топ-10 клиентов по остатку" или "Создай заказ на покупку для поставщика V00001", автоматически преобразуются в полноценные вызовы API Service Layer.

Этот проект предоставляется в качестве образца и предназначен только для ознакомления и изучения. Он не обязательно является готовым к продакшену продуктом. Партнёрам и разработчикам SAP B1 рекомендуется изучить архитектуру, адаптировать код, оценить встроенные возможности и создать собственные реализации MCP-сервера с учётом их конкретных бизнес-требований и условий развертывания.

Требования к версии. Для работы этого MCP-сервера требуется SAP Business One 10.0 FP2608 или новее. Он использует API Service Layer, представленные в FP2608, и не будет работать корректно с более ранними версиями.

Версия протокола MCP. Этот образец реализует версию протокола MCP 2025-11-25, которая является самой актуальной версией спецификации Model Context Protocol для SAP Business One 10.0 FP2608. MCP-клиенты, подключающиеся к этому серверу, также должны поддерживать версию протокола 2025-11-25. Поскольку протокол MCP продолжает развиваться, этот образец будет обновляться в соответствии с новыми выпусками спецификации.

Related MCP server: SAP OData MCP Server

Обзор архитектуры

MCP-сервер находится между ИИ-агентом (Cline, GitHub Copilot, Cursor и т.д.) и Service Layer в SAP B1. Сервер SAP Business One MCP Server реализует современную многоуровневую архитектуру, которая преобразует контракты OData-сервисов в понятные для ИИ MCP-инструменты. Архитектура построена вокруг паттерна поэтапного обнаружения, сочетающего эффективность использования токенов и всестороннее раскрытие возможностей.

В этой архитектуре MCP-клиент ИИ-агента взаимодействует с MCP-сервером через безопасный транспортный уровень HTTP, реализующий протокол MCP. Для аутентификации MCP-сервер использует OAuth2 с Keycloak. MCP-клиент или ИИ-агент регистрируется в качестве OAuth-клиента в Extension SSO Manager и получает маркер доступа в ходе стандартного потока OAuth2. Используя этот токен, клиенты могут по желанию получать список компаний из SLD, чтобы включать в запросы правильный контекст компании. Сервер проверяет каждый входящий запрос, сверяя Bearer-токен с Keycloak и тем самым гарантируя доступ к MCP-инструментам только для аутентифицированных клиентов, а также проверяет параметр audience, чтобы убедиться, что токен предназначен именно для этого сервера.

Доступные MCP-инструменты

Важно. Инструменты используются моделями ИИ и не образуют стабильный API. Названия инструментов, параметры и их поведение могут меняться между версиями. Не создавайте жёстких зависимостей от конкретных сигнатур инструментов.

Базовые инструменты обнаружения и выполнения

Сервер использует 4 базовых инструмента обнаружения/выполнения вместо сотни отдельных CRUD-инструментов:

Progressive 3-Step Discovery

Сервер позволяет избежать избыточного количества инструментов, объединяя всё в 3-шаговый процесс:

Step 1: b1_find_entities        → Lightweight semantic search; returns entity names and categories
Step 2: b1_get_entity_schema    → Full schema for a selected entity (properties, types, keys)
Step 3: b1_read / b1_write      → Execute the read or write operation with schema-informed parameters

• Экономичность токенов: Шаг 1 возвращает ~90% меньше данных, чем полные схемы

• Чёткое разделение: LLM может получить и выбрать перед обращением к полной схеме

• Прогрессивная детализация: Составные типы можно детализировать вызовом Шага 2.2, не запрашивая всё и в один раз

Инструменты выбора компании

В режиме OAuth выберите компанию перед вызовом инструментов сущностей:

Вспомогательные Workflow-инструменты

Два вспомогательных инструмента Workflow упрощают типовые бизнес-процессы B1:

Обнаружение workflow инструментов во время выполнения:

Show me what workflow tools are available in the B1 MCP server

ИИ-агент вызывает b1_find_entities с category: 'workflow' и получает полные описания b1_copy_document и b1_create_payment.

MCP-ресурсы

Два типа ресурсов предоставляют эти знания без вызовов инструментов:

Преимущества: ИИ-ассистенты могут получать доступ к этим ресурсам мгновенно, без вызовов инструментов — это эффективнее в рабочих процессах!

Предварительные требования

Установка

1. Загрузите пакет b1-mcp-server.zip из интерактивной справки, распакуйте его и перейдите в распакованную папку проекта.

2. Установите зависимости и выполните компиляцию:

npm install
npm run build

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

Все настройки управляются через файл .env в корне проекта. Скопируйте .env.example в качестве отправной точки:

cp .env.example .env

Полный справочник по всем доступным переменным приведён в главе Справочник по конфигурации.

Прямой режим (только для разработки)

Используйте этот режим, когда SAP B1 Service Layer доступен по имени пользователя и паролю. Он подходит только для быстрого прототипирования в локальной среде разработки и тестирования.

Примечание: Несмотря на использование имени пользователя и пароля в .env, это не HTTP-базовая аутентификация. Учётные данные используются MCP-сервером для получения сессионного токена от SAP B1 Service Layer через его API входа (/b1s/v2/Login), и все последующие запросы аутентифицируются этим сессионным токеном.

NODE_ENV=development
AUTHENTICATION_MODE=direct

# B1 Service Layer host (server appends /b1s/v2/ internally)
SERVICE_LAYER_ROOT_URL=https://servicelayer.b1.example.com:50000

B1_COMPANY_DB=yourCompanyDB
B1_USERNAME=yourUsernameHere
B1_PASSWORD=yourPasswordHere

# Accept self-signed certs for local development/testing only
AUTH_ALLOW_SELF_SIGNED=true

Режим OAuth (производственный, по умолчанию)

Используйте этот режим по умолчанию, так как Service Layer всегда находится за Keycloak. Входящие bearer-токены проверяются через OAuth-провайдера до того, как любой запрос B1 будет переадресован.

# Default mode, validate incoming requests via OAuth 2.0 / OIDC (requires OAUTH_BASE_URL and OAUTH_CLIENT_ID)
AUTHENTICATION_MODE=oauth

SERVICE_LAYER_ROOT_URL=https://servicelayer.b1.example.com:50000
SLD_ROOT_URL=https://sld.b1.example.com:40000

OAUTH_BASE_URL=https://keycloak.b1.example.com/auth/realms/sapb1/
OAUTH_CLIENT_ID=your-client-id
OAUTH_CLIENT_SECRET=your-client-secret

HTTPS / Транспорт

По умолчанию сервер использует HTTPS и самозаверенный сертификат для локальной разработки. При желании можно переключиться на HTTP.

HTTPS (по умолчанию):

HTTPS_ENABLED=true
HTTPS_KEY_PATH=./certs/server.key
HTTPS_CERT_PATH=./certs/server.crt
PORT=3000

# Optional:
# HTTPS_CA_PATH=./certs/ca.crt
# HTTPS_PASSPHRASE=your-cert-passphrase

HTTP:

Если вы хотите использовать HTTP вместо HTTPS из-за локального тестирования, желания избежать предупреждений безопасности в браузере или по другим причинам (например, у вас уже есть вышестоящий HTTPS-шлюз или обратный прокси), установите:

HTTPS_ENABLED=false
PORT=3000

Объявляемый публичный URL (MCP_BASE_URL):

По умолчанию сервер выводит объявляемый URL из настроек активного слушателя. Если сервер находится за обратным прокси или клиентам нужно использовать конкретный базовый URL для метаданных OAuth и конечных точек MCP, задайте его явно:

MCP_BASE_URL=https://mcp.example.com

Оставьте это значение пустым для локальной разработки — сервер автоматически определит правильный URL.

Запуск сервера

Запустите сервер:

npm start

Проверьте, что он работает:

curl http://localhost:3000/health

Сервер предоставляет три встроенные REST-конечной точки:

Примечание по OAuth: В режиме OAuth вызов GET /mcp требует действительного bearer-токена в заголовке Authorization.

Пример ответа GET /health:

{
  "status": "healthy",
  "timestamp": "2026-06-17T03:50:58.338Z",
  "version": "1.0.0",
  "checks": {
    "auditLogger": { "healthy": true },
    "personalFieldCache": { "healthy": true }
  }
}

Пример ответа GET /mcp:

{
  "name": "b1-mcp-server",
  "version": "1.0.0",
  "protocol": { "version": "2025-11-25", "transport": "streamable-http" },
  "capabilities": { "tools": {}, "resources": {}, "logging": {} },
  "features": [
    "Dynamic SAP Business One Service Layer OData service discovery",
    "CRUD operations for all discovered entities",
    "Natural language query support",
    "Session-based HTTP transport",
    "Real-time service metadata"
  ],
  "endpoints": { "health": "/health", "mcp": "/mcp", "docs": "/docs" },
  "activeSessions": 1
}

Подключение ИИ-клиента

Сервер предоставляет MCP-конечную точку Streamable HTTP по следующему адресу:

http(s)://<host>:<port>/mcp

Любой MCP-совместимый ИИ-клиент может подключиться к этой конечной точке. В таблице ниже кратко перечислены ключевые возможности поддерживаемых клиентов:

MCP Elicitation используется для подтверждения операций записи и чувствительных чтений человеком. Если ваш клиент не поддерживает её, установите в .env значение MCP_HUMAN_CONFIRMATION_ENABLED=false; в противном случае такие операции будут отклоняться. Подробнее см. в разделе Подтверждение человеком (MCP Elicitation).

Cline (VS Code)

Инструкции по установке, конфигурацию LLM-провайдера, настройку OAuth / Keycloak и примеры тестов, охватывающие все CRUD-операции и инструменты рабочих процессов, см. в docs/B1_CLINE_INTEGRATION_GUIDE.md.

GitHub Copilot (VS Code)

Инструкции по установке, настройку OAuth / Keycloak, статический идентификатор клиента, выбор компании OAuth и примеры тестов с elicitation см. в docs/B1_GITHUB_COPILOT_INTEGRATION_GUIDE.md.

Goose (Desktop)

Инструкции по настройке, параметры конфигурации, настройку OAuth / Keycloak и примеры использования см. в docs/B1_GOOSE_INTEGRATION_GUIDE.md.

MCP Inspector (браузерен)

Используйте MCP Inspector для интерактивного просмотра инструментов и инспектирования исходных MCP-сообщений. Полные инструкции — включая получение bearer-токена и установку требуемых заголовков в режиме OAuth — см. в docs/MCP_INSPECTOR.md.

Интеграция MCP-клиента

Если вы создаёте собственное приложение MCP-клиента, которое подключается к серверу в режиме OAuth, интеграция представляет собой стандартный поток PKCE OAuth 2.0:

1. Обнаружите метаданные OAuth через GET /mcp (сервер сообщает свои конечные точки авторизации и токена).

2. Инициируйте запрос авторизации PKCE и перенаправьте пользователя в Keycloak.

3. Обменяйте код авторизации на токены (access token + refresh token).

4. Получите список из доступных компаний с помощью b1_list_companies.

5. Предложите пользователю выбрать компанию и вызовите b1_select_company.

6. Включайте access token и идентификатор компании в каждый MCP-запрос:

   • Authorization: Bearer <access_token>

   • x-b1-companyID: <companySchemaName>

7. Обновляйте токен до истечения срока действия; при сбое обновления повторно запускайте поток PKCE.

Полный рабочий пример с аннотированным кодом — включая регистрацию клиента, поток OAuth, выбор компании и ожидаемый результат — см. в docs/SIMPLE_MCP_CLIENT.md.

Подтверждение человеком (MCP Elicitation)

MCP Elicitation — это механизм на уровне протокола, который позволяет MCP-серверу приостановить вызов инструмента на середине операции и запросить у подключённого клиента дополнительные данные или подтверждение перед продолжением. В отличие от простого приглашения, elicitation встроен в протокол MCP: сервер отправляет клиенту структурированный запрос, клиент показывает его пользователю (обычно в виде встроенного диалога или формы), а сервер ожидает ответа, чтобы решить, продолжать или прервать. Это сохраняет человеку контроль над чувствительными операциями, не требуя от ИИ-агента изобретать собственный механизм подтверждения.

Когда MCP_HUMAN_CONFIRMATION_ENABLED=true (значение по умолчанию), сервер приостанавливается перед:

• Записи операциями (create, update, delete) — запрашивается явное подтверждение пользователя

• Чувствительными чтениями — запрашивается подтверждение, когда запрос выбирает поля, отнесённые к персональным данным (email, phone, идентификационные номера)

Клиенты, поддерживающие elicitation (например, GitHub Copilot), отображают встроенное диалоговое окно подтверждения. Пользователь должен подтвердить действие, прежде чем сервер продолжит; отказ отменяет операцию без изменения каких-либо данных.

Пример запроса на подтверждение записи:

CONFIRM WRITE OPERATION | OPERATION: update | ENTITY: BusinessPartners |
TARGET: C00001 | FIELDS: Phone1=+1 555-1234 |
RISK: This action will modify SAP Business One data. |
ACTION: Set confirmed=true only if you intend to continue.

Клиенты без поддержки elicitation (например, Cline v4.0.8):

Сервер будет отклонять чувствительные чтения и операции записи, а не не выполнять без подтверждения. Чтобы обойти это в автоматизированных конвейеров, установите:

MCP_HUMAN_CONFIRMATION_ENABLED=false

Классификация персональных данных

Сервер использует метаданные SAP Business One PersonalFieldsSetups (разрешаемые по каждой таблице через PersonalFieldsSetupsService_GetPersonalFieldsByTable) для классификации чувствительных полей и применения защитных мер при чтении и записи.

Как классифицируются поля

• Источник классификации: записи персональных полей в таблице контекста Service Layer, возвращаемые функцией PersonalFieldsSetupsService_GetPersonalFieldsByTable.

• Правило соответствия: свойство помечается как персональное при том, когда имя таблицы + имя поля соответствует строке PersonalFieldsSetups.

• Охват: классификация применяется как к свойствам сущности верхнего уровня, так и к вложенным свойствам сложных типов.

• Разрешённое разрешение вложенности: для сложных свойств контекст таблицы переключается на дочернее описание и продолжается рекурсивно для более глубокой вложенности.

Где классификация применяется

• В схеме шага 2, возвращаемая через b1_get_entity_schema, персональные свойства отмечаются флагом isPersonalField.

• Это включает скалярные поля и вложенные структурные свойства, если сопоставление помечает их как персональные.

Защита при выполнении

Когда MCP_HUMAN_CONFIRMATION_ENABLED=true:

• Операции записи (create, update, delete) требуют явного подтверждения через MCP elicitation.

• Для чувствительных чтений требуется подтверждение, если selectString явно включает персональные поля верхнего уровня.

Если клиент не поддерживает MCP elicitation, такие защищённые операции блокируются.

Поведение редактирования для результатов чтения

Модерация результатов чтения зависит от того, есть ли в selectString значимые данные:

• Нет selectString (или значение пусто / состоит из пробелов): применяется рекурсивное маскирование всего ответа для персональных полей как в данных верхнего уровня, так и во вложенных сложных данных.

• Значимый selectString только со скалярными выборками: выбранные скалярные поля возвращаются в запрошенном виде.

• Значимый selectString со сложными свойствами: выбранные скалярные поля остаются видимыми, а персональные поля внутри выбранных сложных свойств маскируются рекурсивно.

Это означает, что выбранное скалярное персональное поле верхнего уровня может быть видимым после подтверждения, в то время как вложенные персональные поля внутри выбранных сложных свойств остаются замаскированными.

Более подробные сведения о настройке персональных данных см. по ссылке: SAP Business One Help Portal - Protecting Personal Data. (We need keep URL exact). Wait high risk if not copying. Let's use original URL exactly:

https://help.sap.com/docs/SAP_BUSINESS_ONE/68a2e87fb29941b5bf959a184d9c6727/ca9f2bc4ad4045f92960dab98a0a98.html?state=...

From user: https://help.sap.com/docs/SAP_BUSINESS_ONE/68a2e87fb29941b5bf959a... Actually exact from prompt:

https://help.sap.com/docs/SAP_BUSINESS_ONE/68a2e87fb29941b5bf959a184d9c6727/ca81efc2aaad404eb852a946d0daba48.html?state=DRAFT\&locale=en-US\&version=10.0\&q=Privacy

Let's verify string: https://help.sap.com/docs/SAP_BUSINESS_ONE/68a2e87fb29941b5bf959a184d9c6727/ca81efc2aaad404eb852a946d0daba48.html?state=DRAFT\&locale=en-US\&version=10.0\&q=data+privacy

Need copy exactly. Also initial path: "68a2e87fb29941b5bf959a184d9c6727" and "ca81efc2aaad404eb852a946d0daba48". Yes.

Use URL in final.

I'll include exact string.

Additionally, "docs/MCP_INSPECTOR.md" and "docs/SIMPLE_MCP_CLIENT.md" etc preserve backslashes. Need ensure we don't accidentally normalize. In markdown, backslash in link text should be preserved. We'll write exactly.

Also heading ### MCP Inspector (Browser) we translate "(браузер)" maybe okay.

But note "MCP Inspector (Browser)" -> "MCP Inspector (браузер)" is fine.

Need "Use MCP Inspector " etc.

Let's craft final carefully, with all placeholder tokens.

We also need make sure no backticks around placeholder. Yes.

Let's output now| Шаблон URI ресурса | Описание | | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | b1://service-layer/metadata | Метаданные службы и сущностей для Service Layer. | | b1://constants/{type} | Справочные данные, включая objectTypes, documentFlows, fieldPatterns, statuses, paymentTypes и all. Пример: b1://constants/objectTypes |

Преимущества: ИИ-ассистенты могут получать доступ к этим ресурсам мгновенно, без вызовов инструментов — это эффективнее для рабочих процессов!

Предварительные требования

Установка

1. Загрузите пакет b1-mcp-server.zip из интерактивной справки, распакуйте его и перейдите в распакованную папку проекта.

2. Установите зависимости и выполните компиляцию:

npm install
npm run build

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

Все настройки управляются через файл .env в корне проекта. Скопируйте .env.example как начальную точку:

cp .env.example .env

Полный справочник всех доступных переменных приведён в главе Справочник по конфигурации.

Прямой режим (только для разработки)

Используйте этот режим, когда SAP B1 Service Layer доступен по имени пользователя и паролю. Подходит только для быстрого прототипирования в локальной среде разработки и тестирования.

Примечание: Несмотря на использование имени пользователя и пароля в .env, это не базовая аутентификация HTTP. Учётные данные используются MCP-сервером для получения токена сессии от SAP B1 Service Layer через его API входа (/b1s/v2/Login), и все последующие запросы аутентифицируются с помощью этого токена.

NODE_ENV=development
AUTHENTICATION_MODE=direct

# B1 Service Layer host (server appends /b1s/v2/ internally)
SERVICE_LAYER_ROOT_URL=https://servicelayer.b1.example.com:50000

B1_COMPANY_DB=yourCompanyDB
B1_USERNAME=yourUsernameHere
B1_PASSWORD=yourPasswordHere

# Accept self-signed certs for local development/testing only
AUTH_ALLOW_SELF_SIGNED=true

Режим OAuth (производственный режим, по умолчанию)

Используйте этот режим по умолчанию, так как Service Layer всегда находится за Keycloak. Входящие bearer-токены проверяются через OAuth-провайдера перед любым запросом B1.

# Default mode, validate incoming requests via OAuth 2.0 / OIDC (requires OAUTH_BASE_URL and OAUTH_CLIENT_ID)
AUTHENTICATION_MODE=oauth

SERVICE_LAYER_ROOT_URL=https://servicelayer.b1.example.com:50000
SLD_ROOT_URL=https://sld.b1.example.com:40000

OAUTH_BASE_URL=https://keycloak.b1.example.com/auth/realms/sapb1/
OAUTH_CLIENT_ID=your-client-id
OAUTH_CLIENT_SECRET=your-client-secret

HTTPS / Транспорт

Сервер использует HTTPS по умолчанию и самзаверяющий сертификат для локальной разработки. Вы также можете переключиться на HTTP, если предпочитаете.

HTTPS (по умолчанию):

HTTPS_ENABLED=true
HTTPS_KEY_PATH=./certs/server.key
HTTPS_CERT_PATH=./certs/server.crt
PORT=3000

# Optional:
# HTTPS_CA_PATH=./certs/ca.crt
# HTTPS_PASSPHRASE=your-cert-passphrase

HTTP:

Если вам нужен HTTP вместо HTTPS, из-за локального тестирования или чтобы избежать предупреждений безопасности браузера, либо по другим причинам (например, у вас уже есть вышестоящий HTTPS-шлюз или обратный прокси), установите:

HTTPS_ENABLED=false
PORT=3000

Объявляемый публичный URL (MCP_BASE_URL):

По умолчанию сервер выводит свой объявляемый URL из настроек активного слушателя. Если сервер находится за обратным прокси или нужен конкретный базовый URL для метаданных OAuth и конечных точек MCP, задайте его явно:

MCP_BASE_URL=https://mcp.example.com

Оставьте это пустым для локальной разработки — сервер подберёт правильный URL автоматически.

Запуск сервера

Запустите сервер:

npm start

Проверьте, что он работает:

curl http://localhost:3000/health

Сервер предоставляет три встроенные конечные точки REST:

ПРИМЕЧАНИЕ OAuth: В режиме OAuth для GET /mcp требуется допустимый bearer-токен в заголовке Authorization.

GET /health — пример ответа:

{
  "status": "healthy",
  "timestamp": "2026-06-17T03:50:58.338Z",
  "version": "1.0.0",
  "checks": {
    "auditLogger": { "healthy": true },
    "personalFieldCache": { "healthy": true }
  }
}

GET /mcp — пример ответа:

{
  "name": "b1-mcp-server",
  "version": "1.0.0",
  "protocol": { "version": "2025-11-25", "transport": "streamable-http" },
  "capabilities": { "tools": {}, "resources": {}, "logging": {} },
  "features": [
    "Dynamic SAP Business One Service Layer OData service discovery",
    "CRUD operations for all discovered entities",
    "Natural language query support",
    "Session-based HTTP transport",
    "Real-time service metadata"
  ],
  "endpoints": { "health": "/health", "mcp": "/mcp", "docs": "/docs" },
  "activeSessions": 1
}

Подключение ИИ-клиента

Сервер предоставляет конечную точку Streamable HTTP MCP по адресу:

http(s)://<host>:<port>/mcp

Любой MCP-совместимый ИИ-клиент может подключиться к этой конечной точке. В таблице ниже кратко перечислены ключевые возможности поддерживаемых клиентов:

MCP Elicitation используется для подтверждения человеком операций записи и чувствительных чтений. Если ваш клиент не поддерживает её, укажите в .env флаг MCP_HUMAN_CONFIRMATION_ENABLED=false; в противном случае такие операции будут отклоняться. См. подробнее Human Confirmation (MCP Elicitation).

Cline (VS Code)

Инструкции по установке, настройке LLM-провайдера, OAuth / Keycloak и примеры тестов, охватывающие все CRUD-операции и инструменты рабочих процессов, см. в документе docs/B1_CLINE_INTEGRATION_GUIDE.md.

GitHub Copilot (VS Code)

Инструкции по настройке, OAuth / Keycloak, статический ID клиента, поток выбора компании OAuth и примеры тестов эликсейшена см. в документе docs/B1_GITHUB_COPILOT_INTEGRATION_GUIDE.md.

Goose (Desktop)

Инструкции по настройке, параметры конфигурации, OAuth / Keycloak и примеры использования см. в docs/B1_GOOSE_INTEGRATION_GUIDE.md.

MCP Inspector (браузер)

Используйте MCP Inspector для интерактивного просмотра инструментов и просмотра необработанных MCP-сообщений. Полные инструкции по использованию — включая получение bearer-токена и установку требуемых заголовков в режиме OAuth — см. в docs/MCP_INSPECTOR.md.

Интеграция MCP-клиента

Если вы создаёте пользовательское приложение MCP-клиента, подключающееся к серверу в режиме OAuth, интеграция выполняется по стандартному потоку PKCE OAuth 2.0:

1. Получить метаданные OAuth из GET /mcp (сервер рекламирует свои конечные точки авторизации и токенов).

2. Выполнить запрос авторизации PKCE и перенаправить пользователя на Keycloak.

3. Обменять код авторизации на токены (access token + refresh token).

4. Загрузить список доступных компаний с помощью b1_list_companies.

5. Дать пользователя выбрать компанию и вызвать b1_select_company.

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

   • Authorization: Bearer <access_token>

   • x-b1-companyID: <companySchemaName>

7. Обновить токен до истечения срока; заново запустить поток PKCE при ошибке обновления.

Полный рабочий пример с аннотированным кодом — включая регистрацию клиента, OAuth-поток, выбор компании и ожидаемый результат — см. в docs/SIMPLE_MCP_CLIENT.md.

Подтверждение человеком (MCP Elicitation)

MCP Elicitation — это механизм уровня протокола, который позволяет MCP-серверу приостановить выполнение вызова инструмента и запросить у подключённого клиента дополнительные входные данные или подтверждение. В отличие от простого подсказки, elicitation встроен в протокол MCP: сервер отправляет структурированный запрос, клиенту представляет его пользователю (обычно в виде диалога или формы), и сервер ждёт ответа, прежде чем решить, continue или abort. Это оставляет human in the loop для чувствительных операций без необходимости изобретать собственный поток подтверждения.

Когда MCP_HUMAN_CONFIRMATION_ENABLED=true (по умолчанию), сервер приостанавливается перед:

• Write operations (create, update, delete) — требует явного подтверждения пользователем

• Sensitive reads — запрашивает, когда запрос выбирает поля, отнесённые к личным данным (email, phone, identity numbers)

Клиенты, поддерживающие Elicitation (например, GitHub Copilot), отображают встроенный диалог подтверждения. Пользователь должен согласиться, прежде чем сервер продолжит; отклонение отменяет операцию без изменения данных.

Пример запроса подтверждения при записи:

CONFIRM WRITE OPERATION | OPERATION: update | ENTITY: BusinessPartners |
TARGET: C00001 | FIELDS: Phone1=+1 555-1234 |
RISK: This action will modify SAP Business One data. |
ACTION: Set confirmed=true only if you intend to continue.

Клиенты без поддержки Elicitation (например, Cline v4.0.8):

Сервер будет отклонять чувствительные чтения и операции записи, а не продолжать без подтверждения. Чтобы пропустить это в автоматизированных или тестовых конвейерах, установите:

MCP_HUMAN_CONFIRMATION_ENABLED=false

Классификация персональных данных

Сервер использует метаданные SAP Business One PersonalFieldsSetups (получаемые по таблице через PersonalFieldsSetupsService_GetPersonalFieldsByTable) для классификации чувствительных полей и применения защиты при чтении и записи.

Как классифицируются fields

• Источник классификации: записи персональных полей области таблицы Service Layer, которые возвращает PersonalFieldsSetupsService_GetPersonalFieldsByTable.

• Правило соответствия: свойство помечается как личное, когда имя таблицы + имя поля соответствует строке PersonalFieldsSetups.

• Scope: классификация применяется как к свойствам верхнего уровня сущности, так и к вложенным свойствам сложных типов.

• Вложенное разрешение: для сложных свойств, настройка таблицы переключается с использованием mapping дочерней таблицы и продолжается рекурсивно для глубокой вложенности.

Где классификация показывается

• В выводе схемы шага 2 через b1_get_entity_schema, персональные свойства помечаются полем isPersonalField.

• Это включает скалярные поля и вложенные свойства структурных типов, когда сопоставление таблицы помечает их как личные.

Защита во время выполнения

Когда MCP_HUMAN_CONFIRMATION_ENABLED=true:

• Операции записи (create, update, delete) требуют явного подтверждения MCP elicitation.

• Чувствительные чтения require confirmation when selectString explicitly includes personal top-level fields.

Если клиент не поддерживает MCP-elication, защищённые операции блокируются.

Поведение редактирования (redaction) при чтении results

Редактирование при чтении зависит от meaningful selectString:

• Если selectString пуст (или содержит только пробелы): применять полное редактирование reс участвующими по персональным полям как на верхнем уровне, так и во вложенных сложных данных.

• Если selectString содержит только скалярные выборки: выбранные скалярные поля возвращаются как есть.

• Если selectString включает сложные свойства: выбранные скалярные поля остаются видимыми, а персональные поля внутри выбранных сложных свойств редактируются рекурсивно.

Это означает, что выбранное скалярное персональное поле верхнего уровня может быть видимым после согласия пользователя, тогда как вложенные персональные поля внутри выбранных сложных свойств остаются отредактированными.

Дополнительные сведения о конфигурации личных данных см. ссылку: SAP Business One Help Portal - Protecting Personal Data.

Поддержка UDO/UDT/UDF

Сервер автоматически находит и публикует User-Defined Objects (UDO), User-Defined Tables (UDT) и User-Defined Fields (UDF) наряду со стандартными сущностями SAP B1 — дополнительной настройки не требуется.

• UDO, зарегистрированные в SAP B1, выполняются как запрашиваемые и записываемые сущности в b1_find_entities, доступные под их назначенной бизнес-категорией.

• UDT (пользовательские таблицы с префиксом @) отображаются как обычные сущности и используются те же CRUD-операции, что и стандартные.

• UDF, добавленные в стандартные или пользовательские таблицы, автоматически включаются в схему, выдаваемую b1_get_entity_schema, с корректными типами и метаданными.

Это означает, что любые настройки, выполненные в SAP B1 — партнёрские расширения, локализационные дополнения или специфические для клиента поля, — становятся немедленно доступны ИИ-агентам через тот же трёхэтапный процесс обнаружения, без каких-либо изменений на стороне сервера.

Именование UDO

Коды UDO должны соответствовать правилам идентификаторов OData, чтобы быть распознанными Service Layer. Используйте только буквы, цифры и символы подчёркивания — без пробелов и других специальных символов (например, используйте MY_CUSTOM_OBJECT, а не My Custom Object). UDO с несоответствующими кодами не будут обнаружены.

Задержка обнаружения

UDO и UDT, добавленные или изменённые через клиент SAP B1, веб-клиент или дополнения (add-ons), не отражаются на MCP-сервере немедленно. Сервер кэширует метаданные OData, полученные из Service Layer, на настраиваемый период (по умолчанию: 30 минут, управляется через METADATA_CACHE_TTL_MINUTES). Новые или изменённые UDO/UDT станут обнаруживаемыми только после естественного истечения срока действия кэша либо после перезапуска MCP-сервера. Во время активной разработки пользовательских объектов уменьшите METADATA_CACHE_TTL_MINUTES до меньшего значения (например, 5), чтобы быстрее получать изменения.

Поддержка мультитенантности

Один экземпляр MCP-сервера может обслуживать несколько компаний SAP Business One без изменения конфигурации. В режиме OAuth активный тенант или компания выбирается динамически во время выполнения с помощью System Landscape Directory (SLD).

Как это работает:

1. Клиент MCP вызывает b1_list_companies, чтобы получить список всех доступных компаний, зарегистрированных в SLD, а также их статус.

2. Пользователь (или ИИ-агент под руководством пользователя) выбирает целевую компанию, вызывая b1_select_company с выбранным CompanySchemaName.

3. Все последующие вызовы инструментов (b1_find_entities, b1_read, b1_write и т.д.) направляются в базу данных Service Layer выбранной компании на протяжении всей сессии.

4. Чтобы переключить компанию, повторно вызовите b1_select_company с другим именем схемы — перезапуск сервера не требуется.

Ключевые характеристики:

• Привязка к сессии: Выбор компании привязан к сессии MCP. Различные сессии ИИ-клиентов могут одновременно работать с разными компаниями на одном экземпляре сервера.

• На основе SLD: Список компаний берётся напрямую из SLD и отражает актуальное состояние зарегистрированных компаний. Поддерживается статический список компаний в конфигурации.

• Только OAuth: Переключение компаний в мультитенантном режиме требует режима OAuth. Прямой режим поддерживает только одну компанию (B1_COMPANY_DB задаётся в .env).

Примечание: Если в запросе уже присутствует допустимый заголовок x-b1-companyID, MCP-сервер использует его напрямую — вызовы b1_list_companies и b1_select_company не требуются. Назначение этих инструментов — просто помочь ИИ-агенту или пользователю определить правильное имя схемы компании и задать контекст компании, если он ещё не известен. Как только нужная компания становится известной, её идентификатор (полученный из CompanySchemaName) можно передавать напрямую в заголовке x-b1-companyID каждого последующего MCP-запроса.

Примеры использования

Запросы на естественном языке

Примеры рабочих процессов

Чтобы реализовать дополнительные бизнес-процессы или добавить новые MCP-инструменты, см. docs/DEVELOPER_GUIDE.md.

Базовый CRUD-процесс

1. b1_find_entities → "BusinessPartners"
  ↓ Returns: List of matching entities

2. b1_get_entity_schema → "BusinessPartners"
  ↓ Returns: scalar properties plus structuralProperties[]

3. b1_get_entity_schema → "BusinessPartners", structuralPropertyName="ContactEmployees"
  ↓ Returns: sub-properties for that structural property when needed

4. b1_read or b1_write → execute the selected operation
   ✓ Executes operation with proper parameters

Процесс «От заказа до оплаты» (по шагам)

1. b1_write → Create Sales Order
   ↓ Returns: DocEntry 123

2. b1_copy_document → Order → Delivery
   ↓ Returns: DocEntry 456 (automatic BaseType handling)

3. b1_copy_document → Delivery → Invoice
   ↓ Returns: DocEntry 789 (automatic BaseType handling)

4. b1_create_payment → Create Payment
   ✓ Validates and creates payment (automatic balance checking)

Запросы бизнес-аналитики

User: "Show me top 10 customers by balance"
→ Tool: b1_read
→ Parameters:
  {
    "entityName": "BusinessPartners",
    "operation": "read",
    "filterString": "CardType eq 'cCustomer'",
    "orderbyString": "CurrentAccountBalance desc",
    "topNumber": 10
  }

User: "How many open sales orders are there?"
→ Tool: b1_read
→ Parameters:
  {
    "entityName": "Orders",
    "operation": "read",
    "filterString": "DocumentStatus eq 'bost_Open'",
    "selectString": "DocEntry"
  }

Работа с данными

User: "Update supplier V10000 to have phone number 123-456-7890"
→ Tool: b1_write
→ Parameters:
  {
    "entityName": "BusinessPartners",
    "operation": "update",
    "parameters": {
      "CardCode": "V10000",
      "Phone1": "123-456-7890"
    }
  }

Тестирование сервера

Модульные тесты

npm test

Это сокращение для npm run test:unit. Модульные тесты находятся в src/tests/unit/.

Интеграционные тесты

Интеграционные тесты требуют работающий MCP-сервер с доступным Service Layer и OAuth-провайдером. Также требуется настройка области доступа b1_mcp:access в Keycloak — см. KEYCLOAK_SETUP.md с инструкциями по установке. Настройте тестовые учётные данные в .env, а затем выполните:

npm run test:integration

Ключевые переменные для интеграционных тестов:

Интеграционные тесты находятся в src/tests/integration/.

Примечание: Если тест не проходит после обновления зависимостей, сначала выполните npm run build — ошибки компиляции часто проявляются именно там, а не через среду выполнения тестов.

Полная проверка качества

Запустите линтер, сборку и модульные тесты последовательно:

npm run lint
npm run build
npm test
npm run test:integration

Логирование

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

Журналы приложения

Журналы приложения содержат информацию об обработке запросов, диспетчеризации инструментов, жизненном цикле сессий и вызовах Service Layer. Уровень по умолчанию — info. Включите подробное логирование во время разработки, чтобы отслеживать, что делает сервер:

APP_LOG_LEVEL=debug
APP_LOG_CONSOLE_ENABLED=true

Журналы по умолчанию записываются в ротируемый файл (APP_LOG_FILE_ENABLED=true). Размер файла и срок хранения управляются параметрами APP_LOG_MAX_SIZE_BYTES (по умолчанию 10 МБ) и APP_LOG_RETENTION_DAYS (по умолчанию 90 дней).

Журналы аудита

Журналы аудита регистрируют события, связанные с безопасностью: подтверждения записи, начало и истечение сессий, сбои аутентификации. По умолчанию они записываются в ротируемый файл и должны оставаться включёнными в production.

Чтобы дополнительно выводить события аудита в консоль во время разработки:

AUDIT_LOG_CONSOLE_ENABLED=true

Размер файла и срок хранения задаются параметрами AUDIT_LOG_MAX_SIZE_BYTES (по умолчанию 10 МБ) и AUDIT_LOG_RETENTION_DAYS (по умолчанию 365 дней).

Полный список переменных логирования см. в docs/CONFIGURATION_REFERENCE.md.

Пошаговые инструкции по настройке Keycloak для мода OAuth — включая регистрацию клиента MCP-сервера, область доступа клиента, маппер аудитории и доверенные хосты — см. в docs/KEYCLOAUDIO_SETUP.md.

Вопросы безопасности

Примечание: Этот проект является примером. Перед развертыванием в производственной среде проверьте и усильте все параметры безопасности в соответствии со стандартами безопасности вашей организации и требованиями их соответствия.

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

Этот MCP-сервер выступает в роли сервера ресурсов (RS) в рамках OAuth 2.0 и использует стандартный механизм аутентификации MCP. Каждый запрос от ИИ-агента должен содержать действующий bearer-токен доступа; сервер проверяет токен перед обработкой любого запроса.

Bear nose-токены доступа можно получить от службы управления идентификацией и аутентификацией SAP Business One с использованием действительных учётных данных пользователя. Эта служба построена на Keycloak и может быть настроена для подключения к SAP IAS (Identity Authentication Service) или других поставщикам идентификации для аутентификации пользователей.

Авторизация

Авторизация применяется на двух уровнях:

Уровень 1 — MCP-сервер: проверяет утверждения scope и aud (аудитория) токена доступа, чтобы определить, разрешено ли ИИ-агенту вызывать запрошенные MCP-инструменты. Принимаются только токены, содержащие требуемую область b1_mcp:access и адресованные этому серверу.

Уровень 2 — Service Layer SAP B1: передаёт решение о доступе к данным Service Layer, который проверяет пользовательские роли и разрешения, связанные с токеном, в рамках стандартной модели контроля доступа SAP Business One. Администраторы могут настраивать гранулярные политики доступа для каждого пользователя и группы. Если Service Layer возвращает HTTP 403 (Forbidden), MCP-сервер информирует ИИ-агента об ошибке, указывающей на недостаточные права, и не возвращает данные.

Производственная конфигурация

Пересмотрите следующие настройки перед любым рабочим развертыванием.

Транспорт

• HTTPS_ENABLED — по умолчанию true. Always use HTTPS in production. Release only if a TLS-terminating reverse proxy is used.

• AUTH_ALLOW_SELF_SIGNED — по умолчанию false. Never enable in production; use a valid CA or NODE_EXTRA_CA_CERTS.

Проверка токена

• TOKEN_VALIDATION_MODE — use introspection or introspection-with-jwt-fallback (default) in production. Avoid switching to jwt-only without a short life ф (less than 5 minutes), because revoked okens will remain valid until expiration.

• VALIDATE_AUDIENCE — set to true by default. Its failure allows tokens issued for other services to authenticate; disable only if your OAuth provider cannot restrict the aud claim.

• OAUTH_VERIFY_SCOPES / OAUTH_REQUIRED_SCOPES — keep the scope check enabled and limit it to the minimum required scope (b1_mcp:access).

Сеть и контроль доступа

• MCP_ALLOWED_HOSTS — list all hostnames through which the server is reachable. Requests with an unreliable Host header are rejected (DNS rebind protection).

• REQUEST_BODY_LIMIT — keep small (default 1mb) to limit memory and reduce the risk of DoS.

• CORS_ALLOWED_ORIGINS — leave unset (CORS disabled) unless browser-based clients require it. Avoid * in production.

• MCP_RATE_LIMIT_WINDOW_MINUTES / MCP_RATE_LIMIT_MAX — tune to match the expected client load.

Session and write safety

• SESSION_TIMEOUT_MINUTES — idle sessions are expired and audited. Keep short value in production (default: 30 min).

• MCP_HUMAN_CONFIRMATION_ENABLED — defaults to true. Require user confirmation before each write. Disable only in fully automated, non-interactive pipelines.

Audit logging

• AUDIT_LOG_FILE_ENABLED — defaults to true. Audit logs record all write confirmations and session events. Keep enabled in production and set AUDIT_LOG_RETENTION_DAYS to meet your compliance requirements.

Troubleshooting

Issues with the server or connection

• Verify Node.js >= 22.22.3 (node --version) and that npm run build completes without errors.

• Check that SERVICE_LAYER_ROOT_URL contains the host only — no /b1s/v2/ path (e.g. https://servicelayer.b1.example.com:50000).

• Confirm that the server is running: curl http://localhost:3000/health.

• Make sure the MCP endpoint URL in the client configuration matches the server address; restart VS Code if the tools do not appear.

Аутентификация и контекст компании

• Прямой режим: проверьте B1_COMPANY_DB, B1_USERNAME и B1_PASSWORD.

• OAuth-режим: проверьте OAUTH_BASE_URL, OAUTH_CLIENT_ID, OAUTH_CLIENT_SECRET и SLD_ROOT_URL. If Service Layer uses a self-signed certificate, set AUTH_ALLOW_SELF_SIGNED=true (development only).

• Check the Trusted Hosts in Keycloak if the VS Code client fails with Failed to verify remote host — see docs/KEYCLOAK_SETUP.md.

• In OAuth mode, always call b1_list_companies, then b1_select_company before any entity tool invocation. If no company is selected, the tools will not return SAP B1 data.

Проблемы с сущностями, полями или записью

• Используйте b1_find_entities, чтобы подтвердить правильное имя сущности (с учётом регистра), и b1_get_entity_schema, чтобы проверить имена свойств перед составлением строк фильтра или выбора.

• Если операции записи отклоняются и MCP_HUMAN_CONFIRMATION_ENABLED=true, клиент должен поддерживать MCP Elicitation. Используйте GitHub Copilot или установите MCP_HUMAN_CONFIRMATION_ENABLED=false для автоматизированных конвейеров.

Включение параметров отладки

Включите подробное журналирование, чтобы отслеживать обработку запросов и вызовы Service Layer:

APP_LOG_LEVEL=debug
APP_LOG_CONSOLE_ENABLED=true
AUDIT_LOG_CONSOLE_ENABLED=true

Справочник по конфигурации

Полный список переменных окружения, сгруппированных по категориям (аутентификация, HTTPS, OAuth, сеанс, кэширование, журналирование), см. в docs/CONFIGURATION_REFERENCE.md.

Ограничение

• Транспорт stdio не поддерживается. Поддерживается только streamable HTTP.

• Действия/функции OData не поддерживаются в текущем примере сервера MCP. Доступны только стандартные операции CRUD над сущностями.

• Загрузка/выгрузка вложений/изображений не поддерживается в текущем примере сервера MCP.

• Пакетные операции OData не поддерживаются в текущем примере сервера MCP. Каждая операция над сущностью должна выполняться отдельно.

• Расширенные запросы OData поддерживаются не полностью. В инструментах MCP реализованы только базовые $filter, $select, $top и $orderby.