内容
# SAP S/4HANA MCP 服务器
将 AI 助手（Claude、Cursor、Cline 和任何兼容 MCP 的客户端）直接连接到 SAP S/4HANA via OData。 用自然语言提出商业问题 — 服务器自主处理服务发现、元数据检查、查询执行和分析。
```
"显示我今年所有的 Azure 云发票，按成本中心分组"
→ Claude 调用 analyze_cloud_spend，查询 SAP，返回结构化的支出明细
```
---
## 快速入门
### 1. 克隆和安装
```bash
git clone https://github.com/Elhamkhorasani/sap-s4-mcp-server.git
cd sap-s4-mcp-server
npm install
npm run build
```
### 2. 配置您的 SAP 连接
```bash
cp .env.example .env
```
编辑 `.env`:
```env
# 必需
S4_ODATA_HOST=https://your-s4-system:44300
S4_ODATA_CLIENT=100
AUTH_METHOD=basic
S4_ODATA_USER=your_username
S4_ODATA_PASSWORD=your_password
# 可选
LOG_LEVEL=info
DRY_RUN=false
```
> **自签名证书？** 为具有内部 CA 的本地系统添加 `NODE_TLS_REJECT_UNAUTHORIZED=0` 到 `.env`。
### 3. 添加到您的 MCP 客户端
**Claude Desktop** — 编辑 `~/.claude/claude_desktop_config.json`（Mac/Linux）或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）：
```json
{
"mcpServers": {
"sap-s4": {
"command": "node",
"args": ["/absolute/path/to/sap-s4-mcp-server/dist/src/index.js"],
"env": {
"S4_ODATA_HOST": "https://your-s4-system:44300",
"S4_ODATA_CLIENT": "100",
"AUTH_METHOD": "basic",
"S4_ODATA_USER": "your_username",
"S4_ODATA_PASSWORD": "your_password"
}
}
}
}
```
**Claude Code / Cursor / Cline** — 将 `.mcp.json.example` 复制到项目根目录下的 `.mcp.json` 并填写您的值：
```bash
cp .mcp.json.example .mcp.json
# 编辑 .mcp.json — 永远不要提交此文件（它被 gitignore）
```
在任何配置更改后重启您的 MCP 客户端。
### 4. 验证连接
询问 Claude：
> *"测试我的 SAP 连接"*
您应该会看到一个响应，确认系统可达、身份验证方法、响应延迟。如果失败，响应会包含一个确切的提示，说明需要修复什么。
---
## 示例提示
**服务探索**
```
SAP 中有哪些与供应商发票相关的 OData 服务可用？
```
**数据检查**
```
显示 API_BUSINESS_PARTNER 的实体结构
```
**云支出分析**
```
查找公司代码 1000 中 2025 年的所有 Microsoft Azure 发票，并按供应商和月份分组
```
**数据质量**
```
对付款统计数据进行质量分析
```
**异常检测**
```
检查采购订单数据中的异常和重复项
```
**服务诊断**
```
为什么 API_SUPPLIERINVOICE_PROCESS_SRV 返回错误？
```
**直接查询**
```
获取公司代码 1000 中供应商 1000008 的最后 20 个未结采购订单
```
---
## 适用于同事：10 分钟内开始使用
> **您需要：** Node.js 18+、您的 SAP 用户名和密码，以及 Claude Desktop 或另一个 MCP 客户端。
> 您不需要了解 OData、SAP 事务或工具的内部工作原理。
### 步骤 1 — 克隆和构建（2 分钟）
```bash
git clone https://github.com/Elhamkhorasani/sap-s4-mcp-server.git
cd sap-s4-mcp-server
npm install
npm run build
```
### 步骤 2 — 设置您的凭证（2 分钟）
```bash
cp .mcp.json.example .mcp.json
```
打开 `.mcp.json` 并替换占位符值：
- `args`: 您机器上 `dist/src/index.js` 的完整绝对路径
- `S4_ODATA_HOST`: 您的 SAP 系统 URL（如果不确定，请询问您的 SAP 管理员）
- `S4_ODATA_USER` / `S4_ODATA_PASSWORD`: 您自己的 SAP 登录凭证
- 保持 `DRY_RUN` 为 `true`，直到您感到舒适 — 这可以防止任何意外的写入
> **重要：** 永远不要分享 `.mcp.json` 或将其提交到 git。它包含您的个人 SAP 凭证。
### 步骤 3 — 连接到 Claude（2 分钟）
在 Claude Desktop 中，转到设置 → 开发者 → 编辑配置并粘贴您的 `.mcp.json` 内容。
重启 Claude Desktop。
对于 Claude Code 或 Cursor，项目根目录中的 `.mcp.json` 会被自动拾取。
### 步骤 4 — 测试它是否有效（1 分钟）
在新的 Claude 对话中，输入：
> *"测试我的 SAP 连接"*
您应该会看到一个带有延迟的绿色状态。如果有问题，响应会告诉您需要修复什么。
### 首先尝试
连接后，首先尝试这些 — 它们是安全的只读操作：
```
此系统上有哪些 SAP 服务可用？
```
```
对采购订单数据运行摘要分析
```
```
查找过去 6 个月的所有发票，并显示金额最高的 10 个
```
### 安全注意事项
- `DRY_RUN=true`（示例中的默认值）阻止所有写入操作 — 可安全探索
- 每个写入尝试都会记录到服务器控制台，即使被阻止
- 每个用户都使用自己的 SAP 凭证 — 没有共享账户
- 您的 `.mcp.json` 保存在您的机器上，永远不会提交到 git
---
## 工具
### 连接
| 工具 | 功能 |
|---|---|
| `ping_sap_connection` | 测试 SAP 连接并报告状态、身份验证方法、客户端和延迟。先运行此工具。 |
### 基础层
| 工具 | 功能 |
|---|---|
| `discover_sap_services` | 在 SAP Gateway 目录中搜索可用的 OData 服务。始终使用返回的 `oDataName` 进行下游调用。 |
| `get_entity_metadata` | 检查实体集、关键字段和服务的属性。在查询之前使用以了解正确的字段名称。 |
| `get_field_values` | 查找字段的有效下拉/值列表选项。在写入之前使用以避免无效输入错误。 |
| `execute_odata_query` | 执行 OData 操作 — GET（返回 CSV）、POST、PATCH、DELETE。 |
### 服务检查层
| 工具 | 功能 |
|---|---|
| `check_service_status` | 检查特定的 OData 服务是否可达且处于活动状态。 |
| `analyze_service_activation` | 诊断服务为何无法激活并获取逐步修复说明。 |
| `list_active_vs_inactive_services` | 概览所有服务及其当前激活状态。 |
| `get_service_entity_relationships` | 映射实体关系和导航属性 — 显示哪些实体是连接的以及如何连接。 |
| `get_ddic_table_metadata` | 通过 ADT REST API 或 OData 回退检索 SAP DDIC 表和字段定义。 |
### 智能代理层
| 工具 | 功能 |
|---|---|
| `run_analysis` | 自主多步骤代理：自动发现适合纯语言主题的正确服务和实体，获取数据样本并运行有针对性的分析。模式：`anomalies`、`duplicates`、`summary`、`quality`、`trends`。 |
| `analyze_cloud_spend` | 端到端云支出工作流：搜索发票文本中的关键词（Azure、Microsoft、AWS），按供应商/月份/GL 账户/成本中心聚合，返回未结采购订单。 |
---
## 推荐工作流
处理不熟悉的 SAP 服务时，请按此顺序：
```
1. discover_sap_services → 查找正确的服务名称（使用 oDataName）
2. get_entity_metadata → 了解可用的字段和关键属性
3. get_field_values → 在过滤或写入之前查找有效值
4. execute_odata_query → 读取或写入实际数据
```
对于事先不知道服务的分析，直接使用 `run_analysis` 和纯语言主题。
---
## 配置参考
| 变量 | 必需 | 默认值 | 描述 |
|---|---|---|---|
| `S4_ODATA_HOST` | ✅ | — | 您的 SAP 系统的完整 URL，例如 `https://my-s4.example.com:44300` |
| `S4_ODATA_CLIENT` | — | `100` | SAP 客户端编号 |
| `AUTH_METHOD` | — | `basic` | `basic`（用户名/密码）或 `token`（承载令牌） |
| `S4_ODATA_USER` | 如果是 basic | — | SAP 用户名 |
| `S4_ODATA_PASSWORD` | 如果是 basic | — | SAP 密码 |
| `S4_ODATA_TOKEN` | 如果是 token | — | 承载令牌 |
| `LOG_LEVEL` | — | `info` | `debug` / `info` / `warn` / `error` |
| `DRY_RUN` | — | `false` | 设置 `true` 以阻止所有写入操作 |
| `NODE_TLS_REJECT_UNAUTHORIZED` | — | `1` | 为自签名证书设置 `0`（仅限本地） |
有关 CSRF 令牌处理和基于令牌的身份验证的详细信息，请参见 [docs/authentication.md](docs/authentication.md)。
---
## SAP 要求
此服务器调用标准的 SAP S/4HANA OData 服务。您的系统中需要激活以下服务：
| 服务 | 使用者 | 在哪里激活 |
|---|---|---|
| `CATALOGSERVICE;v=2` | `discover_sap_services` | `/IWFND/MAINT_SERVICE` |
| `API_SUPPLIERINVOICE_PROCESS_SRV` | `analyze_cloud_spend`（发票） | `/IWFND/MAINT_SERVICE` |
| `API_PURCHASEORDER_PROCESS_SRV` | `analyze_cloud_spend`（采购订单） | `/IWFND/MAINT_SERVICE` |
| 任意 OData 服务 | `run_analysis`、`execute_odata_query` | `/IWFND/MAINT_SERVICE` |
| `/sap/bc/adt`（ICF 节点） | `get_ddic_table_metadata` | `SICF` |
> 目录服务通常默认激活。如果您的系统中没有 `API_*` 服务，请将 `invoiceService` / `poService` 覆盖参数传递给 `analyze_cloud_spend`，使用您的系统公开的服务名称。
**最低 SAP 用户授权：** 每个 OData 服务的 `S_SERVICE`，如果使用 DDIC 元数据，则需要 `SAP_ADT_DEVELOPER_BASIC_READONLY`。
---
## 治理
写入操作通过 `DRY_RUN=true`（阻止所有写入并返回明确的错误）进行控制。所有写入尝试都会记录到 stderr，格式如下：
```
[audit] SUCCESS tool=execute_odata_query detail="POST API_SUPPLIERINVOICE_PROCESS_SRV/A_SupplierInvoice"
```
有关完整的策略模型，请参见 [docs/governance.md](docs/governance.md)。
---
## 开发
```bash
npm run dev # 使用 tsx 监视（热重载）运行
npm run build # 编译 TypeScript
npm run typecheck # 类型检查（不生成输出）
```
**添加新工具：**
1. 创建 `tools/your-tool.tool.ts` — 遵循现有工具的模式
2. 在 `src/server.ts` 中导入并注册
3. 添加一行到上面的工具表中
4. 运行 `npm run build`
---
## 路线图
### 阶段 1 — 安全性和治理
- [ ] 服务允许列表支持
- [ ] 实体阻止列表支持
- [ ] 基于角色的工具访问
- [ ] 更强的干运行强制执行
### 阶段 2 — 查询改进
- [ ] 带有字段验证的结构化 OData 查询生成器
- [ ] JSON 输出模式（除了 CSV）
- [ ] 元数据缓存
### 阶段 3 — 商业工具
- [ ] `find_supplier_invoices` — 按供应商、金额、日期搜索和过滤发票
- [ ] `find_purchase_orders` — 按供应商和类别显示未结承诺
- [ ] `trace_invoice_to_po` — 从发票到采购订单到合同的完整文档链
- [ ] `analyze_vendor_spend` — 支出集中度和趋势分析
### 阶段 4 — 企业功能
- [ ] SAP BTP 目的地服务身份验证
- [ ] OAuth2 客户端凭证
- [ ] Docker 支持
### 阶段 5 — 测试和 DX
- [ ] 用于本地测试的模拟 SAP OData 服务器
- [ ] 所有工具的单元测试
- [ ] GitHub Actions CI
---
## 许可证
MIT
