b1-mcp-server for SAP B1

b1-mcp-server

一个安全的 Model Context Protocol 服务，可让 AI 客户端（例如 Claude Code）通过数据库（HANA / MS SQL）和 Service Layer OData API，受控地访问 SAP Business One。

功能

• 7 个 MCP 工具：connect_database、execute_sql、execute_service_layer（GET）、execute_service_layer_write（PATCH / POST / DELETE）、execute_service_layer_write_unattended（相同的写入操作，但无需审批，仅限开发配置文件）、get_schema_info、check_connection。
• 多环境：通过命名连接配置文件在运行时切换客户端数据库。无需重启。
• 默认只读：SQL 路径仅执行 SELECT。服务器端会阻止所有 INSERT/UPDATE/DELETE/DROP/CREATE/ALTER/EXEC，且无法绕过确认——写入操作会交由人工在实际数据库客户端中执行。
• 服务器端防护措施：提交给 execute_sql 的所有原始 SQL，无论由用户还是 AI 编写，都会经过相同的验证。匿名 DO BEGIN..END 块会根据其中最危险的语句进行分类，因此即使写入操作隐藏在末尾的 SELECT 之前，仍会被识别为写入操作。
• 审计跟踪：会将所选配置文件的连接尝试，以及进入策略检查或执行阶段的数据库和 Service Layer 调用记录为 JSON Lines，其中包括策略拒绝记录。
• 按工具进行滑动窗口速率限制。

安装

需要 Node.js 20 或更高版本。

npx b1-mcp-server

或者添加到 Claude Code MCP 配置中：

{
  "mcpServers": {
    "b1-db": {
      "command": "npx",
      "args": ["-y", "b1-mcp-server"]
    }
  }
}

依赖项

有 5 个运行时依赖项：@modelcontextprotocol/sdk、zod、@sap/hana-client 和 mssql（以及为 HANA 连接池提供支持的 generic-pool）。数据库访问使用本地驱动 src/db/directDb.ts，直接基于 HANA 和 MS SQL 客户端构建；Service Layer 流量则通过 src/sl/serviceLayerAdapter.ts 中的严格 TLS 适配器，使用 Node 自带的 fetch 和 https。不使用 HTTP 框架、axios 或 PostgreSQL 驱动。

全新安装后审计结果为 found 0 vulnerabilities，无需 overrides 区块。这也意味着运行 npx -y b1-mcp-server 不会产生问题——npx 在没有根目录 package.json 的情况下运行，因此不会应用 overrides。

连接配置文件

服务启动时不会连接任何数据库。连接配置从 ~/.claude/connections.json 加载（每个环境一个配置文件），AI 会在运行时通过 connect_database 工具选择连接。

connect_database 中的配置文件匹配行为：

• 优先按 id 或 dbName 精确匹配。
• 仅当部分匹配结果对应唯一配置文件时才接受。
• 如果部分匹配结果不唯一，则会拒绝请求并列出候选项。

~/.claude/connections.json 示例：

[
  {
    "id": "client_a_prd",
    "dbType": "hana",
    "dbServer": "10.0.0.10:30015",
    "dbName": "SBO_CLIENT_A",
    "dbUser": "B1ADMIN",
    "dbPassword": "•••",
    "slUrl": "https://10.0.0.10:50000/b1s/v2",
    "slUser": "manager",
    "slPassword": "•••",
    "slAllowedMethods": ["GET", "PATCH", "POST"]
  },
  {
    "id": "client_b_hmg",
    "dbType": "mssql",
    "dbServer": "10.0.0.20:1433",
    "dbName": "SBO_CLIENT_B_HMG",
    "dbUser": "SA",
    "dbPassword": "•••"
  }
]

每个配置文件都必须包含 id、dbType 和 dbName。添加 dbServer 和 dbUser 以配置 DirectDb；添加 slUrl 和 slUser 以配置 Service Layer。 每个已配置的端都必须提供非空密码（dbPassword 或 slPassword）。缺失或为空的密码会在本地直接报错，不会尝试登录， 从而避免不必要的失败计入已配置的登录策略所规定的账户锁定次数。 非空密码字符串会原样传递，不会进行去除空白处理。一个配置文件可以配置 任一端，也可以同时配置两端。

slAllowedMethods（可选）用于列出该配置文件的 Service Layer 工具可以发送的 HTTP 动词：可选 GET、PATCH、POST、DELETE 中的任意项 （不区分大小写）。未设置时，配置文件为只读（["GET"]）；必须明确列出每个写入动词。 不支持 PUT，因为它会替换整个实体，并清除请求正文中未包含的所有字段。无效 值（未知动词、空列表、非数组）会导致跳过该配置文件，而不是进行猜测。该列表会在连接时应用，并由 connect_database 打印；编辑该列表后，下次调用 connect_database 时会重新登录 Service Layer。 允许写入动词并不意味着免于审批：每次写入仍须获得 安全策略部分所述的逐次人工批准。

slWriteApproval（可选）用于选择由谁批准写入操作。"elicitation" （默认）：服务器通过 MCP 审批表单发起请求。"client"：服务器不发送表单， 依赖 MCP 客户端自己的权限提示——适用于表单无法送达用户的配置，例如 Claude Code Remote Control，它会转发权限提示，但不会转发 MCP 表单。只有当 MCP 客户端将自身标识为 Claude Code 时，才会遵循 client；其他任何客户端都会回退到 elicitation。服务器无法看到该提示，因此此模式的安全性仅取决于客户端的权限设置：将 mcp__<server-name>__execute_service_layer_write 列在 permissions.ask 下，绝不能列在 allow 下，也不要与 --dangerously-skip-permissions 一起使用。 否则，在第一次提示中回答“Yes, don't ask again”会保存一条 allow 规则，之后的每次写入都会不再提示而直接执行。生产环境配置文件应保持为 elicitation。connect_database 会打印适用于当前客户端的模式；编辑该模式后会重新登录 Service Layer。

"none" 适用于每次写入都提示会拖慢工作进度的开发公司。execute_service_layer_write 的行为与 client 模式相同，而该配置文件还会解锁 execute_service_layer_write_unattended，它会以完全不审批的方式执行相同的写入操作，适用于任何 MCP 客户端。该工具会拒绝所有未设为 "none" 的配置文件，因此你可以将 mcp__<server-name>__execute_service_layer_write_unattended 列在 permissions.allow 下，并将普通写入工具列在 permissions.ask 下： 开发配置文件无需提示即可执行，其他所有配置文件仍会提示。启用选项只保存在连接文件中，因此安全性完全取决于该文件： 绝不要将指向生产数据的配置文件设为 "none"。

支持 SAP Service Layer 的两种根路径：OData v3 使用 /b1s/v1，OData v4 使用 /b1s/v2。登录、健康检查和相对 Service Layer 请求 都使用配置文件中设置的确切根路径。请求验证与版本无关；调用方只需传入相对端点（例如 Items?$select=ItemCode&$top=1）。OData 查询和载荷的差异仍由调用方负责；请配置目标 SAP B1 安装所支持的根路径。SAP 自 SAP Business One 10.0 FP 2405 起弃用 OData v3，并将 OData v4 设为主要协议，因此如果目标 安装支持 /b1s/v2，请优先使用；参见 Service Layer API 参考。

安全模型

服务不会主动将配置文件中的密码插入 MCP 工具响应或审计记录。 服务进程会从 ~/.claude/connections.json 读取密码，并将其直接传递给已配置的数据库或 Service Layer 端点以进行登录。Service Layer 适配器之后只保留会话 Cookie，不保留用户名或密码。不过，为便于诊断，数据库驱动和 Service Layer 的错误消息会原样返回并记录到审计日志中，因此不会对任意上游错误文本进行通用的机密信息脱敏。请勿将机密信息放入配置文件 ID、数据库名称、URL 或其他非密码元数据中。这种协议层面的保护也无法阻止拥有不受限制的同一用户 shell 或文件系统访问权限的 AI 主机直接打开该文件；请参阅下方的钩子指南。

默认情况下，Service Layer 连接必须使用 HTTPS，并进行常规证书验证。对于内部证书颁发机构，请在启动 MCP 进程前将 NODE_EXTRA_CA_CERTS 设置为 CA 证书包。

对于无法续期证书的旧版 SAP 安装，首次调用 connect_database 时会检查 TLS，但不会发送凭据，并会通过 MCP 表单征询请求明确批准。获批证书会按规范化的 https://host:port 源存储在 ~/.claude/service-layer-trust.json（模式 0600）中，因此共用同一 SL 端点的配置文件也会共用同一证书固定记录。只有在明确批准，或成功迁移与之匹配的旧版手动配置文件固定记录后，才会创建此文件；其中不包含凭据。证书发生变化时，必须重新获得批准；不支持征询功能的客户端会默认拒绝连接。旧版手动配置文件固定字段仅在首次迁移到此本地存储时接受。

证书固定后，唯一的验证依据就是该精确指纹，不会再额外进行主机名验证。SAP B1 会为其短名称（DNS:MYSERVER）签发自签名的 Service Layer 证书，而客户端通常通过 FQDN 连接，因此再次验证名称会导致已批准的证书被拒绝，且没有办法接受它。因此，slTlsServerName 仅用于在握手期间发送 SNI 名称，适用于按名称提供不同证书的主机；若要通过 FQDN 建立已固定证书的连接，则无需设置此项。Service Layer URL 可以使用 DNS 名称、IPv4 或 IPv6。对于 IP URL，除非 slTlsServerName 提供 DNS 主机名，否则不会发送 SNI；旧版取值为 IP 的 slTlsServerName 也会被接受，但不起作用。较早的信任存储记录可能仍包含作为兼容性回退项的 serverName，但新的 SNI 配置应放在连接配置文件中，而不是证书信任元数据中。

每次调用 connect_database 时都会重新加载配置文件。DB-only 配置文件可以在其 DB 连接处于活动状态时添加 slUrl、slUser 和 slPassword；下次调用时会保留该 DB 连接，并仅初始化 Service Layer。

绝不支持全局禁用证书验证：如果存在 NODE_TLS_REJECT_UNAUTHORIZED=0，适配器会拒绝连接。

AI 调用 connect_database 并传入 "list" 时可以看到：

• 配置文件 id
• dbName、dbType
• 能力标记（DB、SL、DB+SL）
• 如果任一已配置侧当前处于连接状态，则显示 active 标记

connections.json 安全建议：

• 将文件权限限制为仅当前用户可访问。
  • Linux/macOS：chmod 600 ~/.claude/connections.json。
  • Windows：icacls "%USERPROFILE%\.claude\connections.json" /inheritance:r /grant:r "%USERNAME%:F"。
• 请勿将其提交到任何 git 仓库，也不要通过云同步共享。
• 在 POSIX 系统上，如果配置文件向组用户或其他用户授予了任何权限，服务会默认拒绝加载该文件。
• 每位用户都应维护自己的副本。凭据绝不会来自此 npm 包。

Claude Code 钩子与沙箱指南

使用集中管理的 Claude Code PreToolUse 钩子或等效的主机策略，拒绝 AI 访问 connections.json 的规范解析路径。覆盖所有具备文件系统访问能力的工具（Read、Grep、Glob、编辑/写入工具和文件系统 MCP 服务），而不只是匹配字面文件名。Shell 命令是难点：仅匹配路径文本并不足够，因为命令、工作目录和符号链接都可能间接访问该文件。优先使用会拒绝访问凭据路径的主机文件系统沙箱；否则，对工作区之外的 Shell 访问要求审批。

钩子/策略必须存放在 AI 无法写入的项目设置和用户设置之外。对于 Claude Code 企业部署，应将其安装在平台管理的设置中，确保项目指令无法覆盖它。同样，禁止 AI 写入 service-layer-trust.json；读取该文件并不涉及秘密，但其完整性决定了信任哪个旧版证书。

钩子提供的是纵深防御，并非操作系统安全边界。它们约束通过 AI 主机发起的工具调用；无法阻止此 MCP 进程、其他本地进程，或以同一操作系统用户身份运行的恶意 npm 包读取权限为 0600 的文件。要实现强隔离，必须使用专用操作系统身份、沙箱或远程托管的凭据代理。请参阅 Claude Code 钩子和 服务器管理的设置指南。

配置（环境变量）

全部为可选项。

没有 .env 文件。 服务会直接读取 process.env，且不会加载 dotenv 文件，因此在其旁边放置 .env 文件不会有任何作用。对于 stdio MCP 服务，环境由客户端负责管理——在 MCP 配置的 env 块中设置变量，客户端会将其传递给启动的进程：

{
  "mcpServers": {
    "b1-db": {
      "command": "npx",
      "args": ["-y", "b1-mcp-server"],
      "env": {
        "MCP_QUERY_TIMEOUT_MS": "120000",
        "MCP_SL_WRITES_ENABLED": "false"
      }
    }
  }
}

凭据不能通过这种方式配置——它们仅存储在 connections.json 中，该文件会从你的主目录解析，因此无论从哪里运行 npx 都能找到。

变量	默认值	用途
MCP_CONNECTIONS_FILE	~/.claude/connections.json	配置文件的路径
MCP_AUDIT_LOG_PATH	~/.claude/logs/b1-mcp-audit.jsonl	审计日志 JSONL 文件。未设置或为空时使用默认路径
MCP_LOG_LEVEL	info	标准错误输出的详细程度：debug / info / warn / error。不影响 JSONL 文件日志记录
MCP_MAX_QUERY_LENGTH	8000	SQL 最大字符数
MCP_RATE_LIMIT_MAX_CALLS	60	每个工具在每个时间窗口内的最大调用次数
MCP_RATE_LIMIT_WINDOW_MS	60000	速率限制时间窗口
MCP_QUERY_TIMEOUT_MS	60000	语句执行时限。查询在此时仍在运行时会被中止。如果合法报表需要更长时间，请调高此值
MCP_SL_TIMEOUT_MS	30000	Service Layer 登录/请求超时时间
MCP_SL_TRUST_FILE	~/.claude/service-layer-trust.json	本地非机密证书信任存储
MCP_SL_MAX_URL_LENGTH	2048	相对 OData URL 的最大长度
MCP_SL_MAX_BODY_CHARS	50000	序列化后的 PATCH/POST 正文最大长度
MCP_SL_WRITES_ENABLED	true	用于禁用所有 Service Layer 写入操作（PATCH、POST、DELETE）的紧急开关；true/false 不区分大小写，无效值会禁用写入。此设置取代了不再读取的 MCP_SL_PATCH_ENABLED——但旧变量名只要设置为 true 以外的任何值，仍会禁用写入，因此升级后不会意外重新开放写入
MCP_ELICITATION_TIMEOUT_MS	120000	等待人工回答审批表单（证书信任、Service Layer 写入）的时长，超时后将安全地拒绝操作
MCP_MAX_RESULT_ROWS	500	返回给模型的最大行数；超出行数会被截断并告知
MCP_MAX_RESULT_CHARS	100000	结果 JSON 的最大字符数，在行数上限生效后应用
MCP_DRY_RUN	false	精确值 true 会验证原始 SQL 和 Service Layer 写入操作，但不执行；连接和 Service Layer GET 仍会执行

上述数值限制必须为正整数。未设置或仅包含空白字符时使用默认值。任何其他无效值（包括 0、负数或非整数）都会在标准错误输出中提示回退，并使用默认值——限制配置错误绝不意味着“无限制”。MCP_LOG_LEVEL 未设置或为空时同样使用 info，其他无效值会提示回退。

防护措施摘要

SQL 路径为只读，因此实时回答不受所操作表的影响：

操作	任意表（SAP 核心表、UDT、自定义表、临时表）
SELECT	允许，但须遵守下方针对 SELECT 的限制
INSERT / UPDATE / DELETE / DROP	阻止——请自行在数据库客户端中执行
CREATE / ALTER	阻止
EXEC / EXECUTE / CALL	阻止——无法通过此服务执行存储过程

此外，还会阻止：多语句查询（BEGIN..END 之外的分号）、未终止的引号或方括号、序列递增（NEXTVAL / NEXT VALUE FOR）、OPENQUERY / OPENROWSET / OPENDATASOURCE、SELECT ... INTO <table>，以及影响较大的 SQL Server 锁提示（UPDLOCK、XLOCK、TABLOCK、TABLOCKX、HOLDLOCK、SERIALIZABLE、REPEATABLEREAD）。

Service Layer 请求仅允许配置文件的 slAllowedMethods 中指定的 HTTP 方法（默认为仅 GET）；始终不允许 PUT。PATCH 和 DELETE 必须使用带有直接键值的实体端点；POST 可接受实体集、服务操作，或对带键实体执行的一个操作（Orders(12)/Close）；写入请求不得带查询选项。写入通过单独的工具 execute_service_layer_write 执行，因此客户端可以按工具名称对其进行控制，同时让 GET 请求无需提示。每次写入都必须指定目标 database，且必须与已连接的 Service Layer 匹配。默认情况下，每次写入都必须通过 MCP 表单征询获得用户明确同意。审批界面会绑定数据库、Service Layer 根路径、端点、确切请求正文、字段列表和 SHA-256 正文哈希。不支持征询的客户端无法执行写入。配置了 slWriteApproval: "client" 的配置文件会以 Claude Code 的权限提示取代表单；配置了 slWriteApproval: "none" 的配置文件还会允许通过 execute_service_layer_write_unattended 执行未经审批的写入（参见上方的配置文件字段）。 MCP_DRY_RUN=true 时绝不执行写入， 而 MCP_SL_WRITES_ENABLED=false 会全局禁用所有写入。

按表分类的模型（SAP_CORE / SAP_USER / CUSTOM / TEMP 及各自的操作规则）仍保留在 src/guardrails/rules/ 中，并已通过完整测试，但在只读服务上无法从实时路径访问。完整模型及其已知限制请参阅 SECURITY.md。

Agent 技能

skills/b1-mcp-server/SKILL.md 会教 AI Agent 如何使用这些工具：先连接、各类拒绝意味着什么以及如何处理、为什么 HANA 超时会报告套接字已断开、截断后的结果是什么样，以及如何审批 Service Layer 写入。要在 Claude Code 中安装，请将文件夹复制到 ~/.claude/skills/；其他会读取 SKILL.md 文件的 Agent 则从各自的技能目录中获取。

开发

npm install
npm run build
npm run test
npm run test:watch
# Optional aliases (same behavior, useful if you prefer explicit naming):
npm run test:bash
npm run test:watch:bash

仅从源代码检出目录中，使用 connections.json 中的配置文件运行此快速连接检查（npm 压缩包中不包含 scripts/）：

npx tsx scripts/test-connection.ts <profile-id>

许可证

MIT——请参阅 LICENSE。