Skip to main content
Glama
deenesjakoruzh
leonardows1

SAP B1 ServiceLayer MCP Server

by leonardows1
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

SAP B1 ServiceLayer MCP Server

用于将 AI 助手（opencode、Claude 等）连接到本地网络中的 SAP Business One 10.0 ServiceLayer 的 MCP（Model Context Protocol）服务器。可通过 npx 直接从此 GitHub 仓库运行，无需在 PC 上安装任何东西。

功能特性

  • 默认只读：设置 SAP_B1_READONLY=true（默认）时，仅注册查询类工具（GET）。写入类工具（POST/PATCH/DELETE）在服务器上不存在，也无法被调用。

  • 完全发现：sap_list_entities、sap_get_entity_schema 和 sap_list_actions 查询 GET /$metadata（每个进程仅下载一次并缓存），并公开 ServiceLayer 的约 140 个 CRUD 实体（包括用户表 @ 和 UDO）以及数百个服务方法。

  • 可选写入模式：设置 SAP_B1_READONLY=false 时，将为 ServiceLayer 实体启用 sap_create、sap_update、sap_delete，并为服务方法启用 sap_call_action（这些操作可能产生副作用）。

  • 通过 npx github: 运行：无需手动安装。

  • 会话管理：使用 CompanyDB/用户名/密码隐式登录，B1SESSION + ROUTEID cookie 保存在内存中（支持多节点 ServiceLayer），遇到 401 自动重新登录，并在进程关闭时保证注销（另有 sap_logout 工具）。

  • 自签名 TLS：通过 SAP_B1_VERIFY_TLS=false 支持 ServiceLayer 的自签名证书（在本地环境中很常见）。

  • 无遥测、无外部调用：HTTP 客户端仅指向配置的 URL（SAP_B1_SERVER_URL）。

  • 安全限制：每次查询的 top 限制为 200 条记录。

Related MCP server: SAP Business One MCP Server

工具

读取（始终可用）

工具

说明

sap_query

对任意 OData 实体的通用 GET，支持 select、filter、top（≤200）、skip、orderby、expand

sap_list_entities

列出 ServiceLayer 暴露的所有 OData 实体（来自 $metadata，已缓存）；包括用户表（@）和 UDO。可通过可选的 filter 进行筛选

sap_get_entity_schema

实体的架构：属性（类型/键）以及 navigationProperties（可用于 $expand）；解析共享同一 EntityType 的实体集

sap_list_actions

列出服务方法（function imports，例如 CompanyService_GetCompanyInfo）及其参数

sap_sql_query

通过 POST /sql_query 执行只读 SQL（SELECT/WITH；拒绝 INSERT/UPDATE/DELETE/DDL）——仅适用于较新的 ServiceLayer v2/FP；在旧版 v1 中返回明确错误

sap_get_business_partners

业务伙伴（客户/供应商），可按 card_type 筛选

sap_get_items

目录中的物料

sap_get_sales_orders

销售订单；在 v1 中行（DocumentLines）已包含在响应中，无需 expand（expand 仅适用于 v2）

sap_get_stock

按 ItemCode 查询物料库存（可选加 WarehouseCode）；如果 ServiceLayer 中不存在 ItemStock（旧版 v1），则返回明确错误

sap_session_status

当前会话的状态

sap_logout

显式关闭会话

写入（仅当 SAP_B1_READONLY=false 时）

工具

说明

sap_create

在实体中创建记录（POST）

sap_update

按键更新记录（PATCH）

sap_delete

按键删除记录（DELETE）

sap_call_action

调用服务方法（POST）；可能产生副作用（Cancel、UpdateCompanyInfo、Import 等）

要求

  • Node.js 18+

  • SAP Business One 10.0，并启用 ServiceLayer（典型路径 https://<host>:50000/b1s/v1）

  • opencode（或任何 MCP 客户端）

配置（环境变量）

变量

必填

默认值

说明

SAP_B1_SERVER_URL

是

-

ServiceLayer 的基础 URL（例如：https://<host>:50000/b1s/v1）

SAP_B1_DATABASE

是

-

CompanyDB 名称（例如：SBODEMO_XX）

SAP_B1_USERNAME

是

-

ServiceLayer 用户

SAP_B1_PASSWORD

是

-

用户密码

SAP_B1_READONLY

否

true

设为 false 启用写入工具

SAP_B1_VERIFY_TLS

否

true

设为 false 以支持自签名证书

SAP_B1_MAX_TOP

否

200

每次查询 top 的最大限制

与 opencode 一起使用

在项目的 opencode.json 中：

{
  "mcp": {
    "sap-b1-servicelayer": {
      "type": "local",
      "command": ["npx", "-y", "github:leonardows1/sap-b1-servicelayer-mcp"],
      "environment": {
        "SAP_B1_SERVER_URL": "https://<host>:50000/b1s/v1",
        "SAP_B1_DATABASE": "<CompanyDB>",
        "SAP_B1_USERNAME": "<usuario>",
        "SAP_B1_PASSWORD": "<password>",
        "SAP_B1_SESSION_TIMEOUT": "30",
        "SAP_B1_VERIFY_TLS": "false",
        "SAP_B1_READONLY": "true"
      },
      "enabled": true
    }
  }
}

保存配置后重启 opencode。

安全性

  • 凭据和会话 cookie 永远不会记录在日志中。

  • 进程仅与 SAP_B1_SERVER_URL 通信。

  • 在 READONLY=true 模式下，写入工具不会被注册：按设计，无法创建/更新/删除记录。

  • 启动时校验配置：缺少 SAP_B1_SERVER_URL、SAP_B1_DATABASE、SAP_B1_USERNAME 或 SAP_B1_PASSWORD 时，进程中止并给出明确提示。

  • 实体名称经过校验（^[A-Za-z][A-Za-z0-9_]*$）：无法注入路径（例如 BusinessPartners/...）。

  • OData 中的键值和筛选条件已转义（单引号加倍）：包含 ' 的 id 或 ItemCode 不会破坏 URL 或 $filter。

  • 密码以明文形式保存在 MCP 客户端配置中。如果共享仓库，请考虑使用密钥管理器。

  • npx github: 没有 semver 版本管理：每次执行都会获取 main 分支的最新版本。更新仓库后，请使用 npm cache clean --force 强制重新加载。

结构

务实的六边形架构（ESM，无框架）：领域层和用例不感知 MCP 传输层或 HTTP；基础设施层实现 ServiceLayerPort 端口（DIP），MCP 工具是轻量控制器。

sap-b1-servicelayer-mcp/
├── package.json                  # Definición del paquete npm (bin: server.js)
├── server.js                     # Composition root: cablea dependencias y arranca stdio
├── src/
│   ├── config/
│   │   └── config.js             # Configuración desde env, validada e inmutable
│   ├── domain/
│   │   ├── errors.js             # Excepciones tipadas (Configuration/InvalidArgument/ServiceLayer)
│   │   ├── oData.js              # Helpers puros: query string, filtros, clamp de $top, validación de entidad
│   │   └── edmx.js               # Parseo puro de $metadata: entity sets, esquemas, function imports
│   ├── application/
│   │   ├── ports.js              # Puerto ServiceLayerPort (contrato, DIP)
│   │   ├── helpers.js            # ensureOk / ensureSuccess / unwrapValue
│   │   └── services/
│   │       ├── queryService.js   # Consulta GET genérica a entidades OData
│   │       ├── catalogService.js # Socios de negocio y artículos (compone QueryService)
│   │       ├── salesService.js   # Pedidos de venta y stock
│   │       ├── sessionService.js # Estado y cierre de sesión
│   │       ├── writeService.js   # create / update / delete
│   │       ├── metadataService.js # Descubrimiento: $metadata cacheado, entidades, esquemas y actions
│   │       └── sqlService.js     # SQL de solo lectura (SELECT/WITH) vía POST /sql_query
│   └── infrastructure/
│       ├── http/
│       │   ├── httpClient.js     # Cliente HTTP mínimo (http/https)
│       │   ├── cookies.js        # Manipulación pura de cookies de sesión
│       │   └── serviceLayerClient.js # Adaptador del puerto: login, 401, logout
│       └── mcp/
│           ├── result.js         # ok / err / serialize / handle (controladores delgados)
│           └── tools.js          # Registro de tools MCP
├── test/                         # node:test (sin dependencias externas)
│   ├── config.test.js
│   ├── oData.test.js
│   ├── edmx.test.js              # parseo EDMX v3/v4 (entity sets, esquemas, function imports)
│   ├── cookies.test.js
│   ├── client.test.js
│   ├── fakePort.js               # fake tipado del puerto ServiceLayerPort (compartido)
│   ├── services.test.js          # casos de uso con cliente fake (anti-inyección)
│   ├── metadataService.test.js   # descubrimiento y acciones con fake
│   ├── sqlService.test.js        # SQL solo-lectura (rechazos, Service Not Found)
│   └── tools.test.js             # integración MCP in-memory (registro y llamadas)
├── .gitignore
└── README.md

适配真实架构（已针对 ServiceLayer 10.0 v1 验证）

服务器会动态适配每个实例的 $metadata，没有硬编码任何内容。以下是在真实实例（v1，OData v3）上验证的事实：

  • 实体集共享 EntityType：Orders/Invoices/DeliveryNotes → SAPB1.Document。sap_get_entity_schema 会自动解析真实类型。

  • 文档行：在 v1 中是 复杂集合（DocumentLines、DocumentInstallments），会内联在响应中；$expand 仅适用于 navigationProperties（架构会列出这些属性，例如 BusinessPartner、Currency）。

  • 财务字段：在 v1 中 BusinessPartners 没有 Balance；请使用 CurrentAccountBalance、OpenOrdersBalance、OpenDeliveryNotesBalance。发票没有 BalanceDue：未结余额为 DocTotal − PaidToDate。

  • 旧版 v1 中没有 ItemStock 或 /sql_query：sap_get_stock 会以发现的真实库存实体发出提示；sap_sql_query 返回明确错误。

  • v3 function imports 带有 IsBindable="true" 的会被列为 bound（不能独立调用），以免污染 sap_list_actions。

配方：余额账龄报告（30/60/90）

无需 SQL，仅使用 sap_query（适用于任何 v1/v2）：

  1. 未结发票（如果很多，使用 skip 按 ≤200 条分批翻页）：

    sap_query('Invoices',
  filter='PaidToDate lt DocTotal',
  select='CardCode,CardName,DocNum,DocDate,DocDueDate,DocTotal,PaidToDate,DocumentStatus,ControlAccount')

  2. 对每张发票：saldo = DocTotal − PaidToDate；días = hoy − DocDueDate。

  3. 按 0-30 / 31-60 / 61-90 / 90+ 区间和客户分组（或按 ControlAccount 查看总账科目视图）。

  4. 按客户/科目的合计：sap_get_business_partners 包含 CurrentAccountBalance（当前余额）和 CreditLimit。

使用 sap_sql_query（v2）时，同一报表只需对 OINV/OINV3/OFRJ/OCRD 执行一条查询。

开发

npm install     # dependencias
npm test        # tests (node:test)
npm run typecheck  # verificación de tipos estricta (tsc --noEmit sobre JSDoc)
npm start       # arranque local (requiere variables de entorno)

所有 JS 代码均通过 JSDoc 使用严格 TypeScript 检查（checkJs + strict + noUncheckedIndexedAccess）：tsconfig.json 无需构建步骤，服务器直接用 node 运行。

手动验证（通过 stdio 的 JSON-RPC）

echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | \
  SAP_B1_SERVER_URL=... SAP_B1_DATABASE=... SAP_B1_USERNAME=... SAP_B1_PASSWORD=... \
  npx -y github:leonardows1/sap-b1-servicelayer-mcp

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • SAP OData MCP Server

    GutjahrAI
    F
    license
    A
    quality
    D
    maintenance
    Enables AI assistants to integrate with SAP systems via OData REST APIs for querying entity sets, performing CRUD operations, and executing function imports. It features automatic service discovery, CSRF token management, and smart connection handling without requiring the SAP RFC SDK.
    11
    12
    -

  • SAP Business One MCP Server

    OscarGalloGarcia
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables interaction with SAP Business One via Service Layer REST API to retrieve and create business data such as partners, orders, invoices, items, and stock levels through natural language.
    1
    -

  • MCP SAP Business One

    jhsementes
    F
    license
    Not graded
    quality
    C
    maintenance
    Enables interaction with SAP Business One Service Layer through MCP, providing tools for querying entities, checking sessions, and executing OData requests with optional write protection.
    -

  • guniweb-sap-mcp

    guniweb
    A
    license
    Not graded
    quality
    A
    maintenance
    Enables AI assistants and n8n workflows to interact with SAP S/4HANA and ECC systems via OData, IDoc, and RFC/BAPI, with governed read-only-by-default access and multiple authentication types.
    3
    ISC