内容
# cds-kb-mcp
无数据 **MCP 服务器**，提供 **7,355 个 SAP S/4HANA CDS 视图**的访问权限，通过语义搜索和结构化分类。无需 **视图数据** — 您可以在本地或从 GitHub 自动获取。
整个服务器打包成 **一个文件** (`dist/cds-kb-mcp.mjs`, 约 784 KB)，可在任何安装了 Node ≥ 18 的机器上运行。
与 **Claude Desktop**、**Claude Code**、**Antigravity IDE** 和任何 MCP 兼容的客户端完美配合。
---
## 目录
- [快速开始](#快速开始)
- [安装](#安装)
- [数据源配置](#数据源配置)
- [工具参考](#工具参考)
- [客户端注册](#客户端注册)
- [数据丰富与分类](#数据丰富与分类)
- [架构](#架构)
- [环境变量](#环境变量)
- [故障排除](#故障排除)
---
## 快速开始
### 1. 零配置运行（在线模式）
最简单的开始方式。它将自动下载搜索索引并按需从官方 GitHub 仓库获取视图。
```bash
git clone https://github.com/truongdva2/cds-kb-mcp.git
cd cds-kb-mcp
# 无需任何参数！默认在线远程模式。
node dist/cds-kb-mcp.mjs
```
### 2. 本地数据运行（离线模式）
获得最快的零延迟体验。
```bash
# 克隆服务器和数据仓库
git clone https://github.com/truongdva2/cds-kb-mcp.git
git clone --recurse-submodules https://github.com/truongdva2/cds-kb-mcp.git # 或手动克隆 cds-kb-data
# 运行指向本地数据文件夹
node dist/cds-kb-mcp.mjs --data ./cds-kb-data
```
---
## 安装
### 选项 A：使用预构建的捆绑包（推荐）
`dist/cds-kb-mcp.mjs` 文件已提交到仓库 — 无需构建步骤。
```bash
git clone https://github.com/truongdva2/cds-kb-mcp.git
# 就是这样。服务器已经准备好运行。
```
### 选项 B：从源代码构建
```bash
git clone https://github.com/truongdva2/cds-kb-mcp.git
cd cds-kb-mcp
npm install
npm run build # → dist/cds-kb-mcp.mjs (~784 KB, 自包含)
```
### 先决条件
- **Node.js ≥ 18** （使用原生 `fetch`，ES 模块）
- 无其他运行时依赖 — 所有内容都捆绑到单个文件中。
---
## 数据源配置
服务器按照以下优先级顺序解析其数据源。**本地优先**。如果未提供任何内容，则安全地默认为 **远程（在线）** 模式。
| 优先级 | 参数 | 环境变量 | 模式 |
|---|---|---|---|
| 1 | `--data <path>` | `CDS_KB_DATA` | **本地** — 读取克隆的数据仓库。离线，最快。 |
| 2 | `--remote <url>` | `CDS_KB_REMOTE` | **远程** — 下载索引一次，延迟获取视图，缓存。 |
| 3 | *(无)* | *(无)* | **默认远程** — 自动指向 `https://raw.githubusercontent.com/truongdva2/cds-kb-data/main`。 |
### 远程模式缓存
1. 下载 `search_index.json` (~5 MB) 和 `taxonomy.json` 一次 → 缓存到 `~/.cache/cds-kb/<hash>/`
2. 调用 `get_cds_view` 时按需获取各个视图 → 也缓存
3. 缓存自动过期时间 **24 小时** （可通过 `CDS_KB_CACHE_TTL_HOURS` 配置）
4. 强制重新下载：设置 `CDS_KB_REFRESH=1`
---
## 工具参考
服务器暴露 **5 个高度优化的 MCP 工具**：
### 1. `search_cds`
按业务含义、名称或传统 SAP 关键词（例如 `VBAK`）搜索 CDS 视图。返回排名靠前的候选列表。
| 参数 | 类型 | 必需 | 描述 |
|---|---|---|---|
| `query` | 字符串 | ✅ | 自然语言或关键词查询 |
| `module` | 字符串 | ❌ | 模块代码 (`FI`, `SD`, `MM`) 或名称 (`Finance`, `Procurement`) |
| `lob` | 字符串 | ❌ | 业务线过滤器（部分匹配） |
| `bo` | 字符串 | ❌ | 业务对象过滤器（部分匹配） |
| `limit` | 数字 | ❌ | 最大结果数，1–50（默认：10） |
**示例：**
```javascript
// 按自然语言搜索
search_cds("逾期客户发票", module="Finance")
// 按传统 SAP T-Code 或表名搜索（感谢同义词丰富！）
search_cds("VBAK")
search_cds("BSEG")
// 搜索特定 BO 过滤器
search_cds("物料库存", bo="Inventory")
```
### 2. `get_taxonomy`
检索知识库的语义映射。它将所有视图分组到 **业务线（LOB）** 和 **业务对象（BO）** 中，提供丰富的关键词。
使用此功能在搜索前了解数据组织方式，或发现 `get_views_by_tag` 的有效标签。
| 参数 | 类型 | 必需 | 描述 |
|---|---|---|---|
| *(无)* | — | — | — |
**示例输出：**
```markdown
SAP CDS 知识库分类
## 业务线（12）
- **lob:finance** （财务） — 关键词：FI，FIN，总账，应付账款，资产核算，税务...
- **lob:sales & distribution** （销售和分销） — 关键词：SD，销售订单，计费，定价...
## 业务对象（829 个，总计，30 个样本）
- **bo:salesorder** — 关键词：SO，SD-SLS，客户订单，VBAK
- **bo:journalentry** — 关键词：FI-GL，BSEG，BKPF，会计凭证
...
```
### 3. `get_views_by_tag`
检索具有特定标签（例如 `bo:salesorder` 或 `lob:finance`）的所有 CDS 视图的确定性分页列表。使用此功能准确浏览类别，无需依赖语义搜索。
| 参数 | 类型 | 必需 | 描述 |
|---|---|---|---|
| `tag` | 字符串 | ✅ | 要过滤的确切标签，例如 "bo:salesorder" |
| `limit` | 数字 | ❌ | 最大结果数（默认 50） |
**示例：**
```javascript
get_views_by_tag("bo:salesorder")
get_views_by_tag("lob:controlling")
```
### 4. `get_cds_view`
返回一个 CDS 视图的完整（或部分）Markdown 定义。
| 参数 | 类型 | 必需 | 描述 |
|---|---|---|---|
| `name` | 字符串 | ✅ | 确切的视图名称（不区分大小写） |
| `sections` | 字符串[] | ❌ | 过滤到特定部分（节省令牌） |
**可用部分：** `metadata`, `fields`, `associations`, `source`
**示例：**
```javascript
get_cds_view("I_PurchaseOrderAPI01") // 完整视图
get_cds_view("I_PurchaseOrderAPI01", sections=["metadata", "fields"]) // 62% 更小，推荐！
get_cds_view("C_PURCHASEORDERDEX", sections=["source"]) // 仅 DDL 源代码
```
> **💡 令牌节省：** 对于大型视图（某些视图为 50–95 KB），使用 `sections` 可以节省 **60–80%** 的上下文窗口令牌。始终首先使用 `["metadata", "fields"]` 来了解视图结构！
### 5. `kb_info`
报告活动数据源、视图数量、丰富度覆盖率和索引构建时间。
---
## 客户端注册
### Claude Code
```bash
# 零配置（默认在线）
claude mcp add cds-kb -- node /abs/path/to/cds-kb-mcp/dist/cds-kb-mcp.mjs
# 本地数据
claude mcp add cds-kb -- node /abs/path/to/cds-kb-mcp/dist/cds-kb-mcp.mjs --data /abs/path/to/cds-kb-data
```
### Claude Desktop
编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"cds-kb": {
"command": "node",
"args": [
"/abs/path/to/cds-kb-mcp/dist/cds-kb-mcp.mjs"
]
}
}
}
```
> 编辑后重启 Claude Desktop。
### Antigravity IDE
通过 IDE 的 MCP 设置 UI 添加：
| 设置 | 值 |
|---|---|
| **命令** | `node` |
| **参数** | `["/abs/path/to/cds-kb-mcp/dist/cds-kb-mcp.mjs"]` |
---
## 数据丰富与分类
搜索索引附带 **7,160 个丰富视图** （97.3%），从 DDL 源中的 `@EndUserText.label` 注解中提取了人类可读的 `semanticDescription`。
它还集成了精心策划的 **分类** （`taxonomy.json`）。当构建索引时，诸如 `VBAK`、`EKKO`、`BSEG` 之类的关键词会动态注入到相关业务对象的 `synonyms` 字段中。这允许 AI 使用传统的 SAP 术语进行搜索，即使这些词不在官方视图描述中！
### 在数据更新后重新运行丰富
```bash
cd cds-kb-mcp
node enrich_index.mjs /path/to/cds-kb-data
npm run build
```
这将：
1. 扫描所有 7,355 个视图文件以获取 `@EndUserText.label`
2. 在索引中填充 `semanticDescription` 字段
3. 加载 `taxonomy.json` 并将关键词注入到约 6,900 个视图的 `synonyms` 字段中。
4. 从头开始重建 MiniSearch 索引。
5. 创建原始索引的 `.bak` 备份。
---
## 架构
```
┌─────────────────────────────────────────────────────┐
│ AI 代理 / 客户端 │
│ （Claude，Antigravity IDE 等） │
└──────────────────────┬──────────────────────────────┘
│ MCP（stdio JSON-RPC）
▼
┌─────────────────────────────────────────────────────┐
│ cds-kb-mcp（此仓库） │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌────────────┐ │
│ │ search_cds │ │ get_cds_view │ │get_taxonomy│ │
│ └──────┬───────┘ └──────┬───────┘ └─────┬──────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────────────────────────────────────────┐ │
│ │ MiniSearch（内存 BM25） │ │
│ │ 提升：name(3x) semantic(2.5x) synonyms(2x) │ │
│ └──────────────────────┬───────────────────────┘ │
│ │ │
│ ┌──────────────────────▼───────────────────────┐ │
│ │ 数据源（本地或远程，可插拔） │ │
│ │ - LocalDataSource：直接文件读取 │ │
│ │ - RemoteDataSource：HTTP + 磁盘缓存（24 小时） │ │
│ └──────────────────────┬───────────────────────┘ │
└─────────────────────────┼───────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ cds-kb-data（单独仓库） │
│ │
│ index/taxonomy.json （LOB，BO，关键词） │
│ index/search_index.json （~5 MB，自描述） │
│ views/*.md （7,355 个 CDS 视图文件） │
└─────────────────────────────────────────────────────┘
```
### 关键设计决策
| 决策 | 理由 |
|---|---|
| **数据/代码分离** | 数据更新独立于服务器代码 |
| **分类路由** | 通过 `get_taxonomy` 和 `get_views_by_tag` 进行确定性浏览，无需文件膨胀 |
| **同义词注入** | 允许搜索传统 SAP T-Code/表（例如 `VBAK`） |
| **基于部分的检索** | `get_cds_view(sections)` 节省 60–80% 的读取令牌 |
| **单文件捆绑** | `dist/cds-kb-mcp.mjs` — 目标上无需安装 |
| **零配置远程** | 默认自动从 GitHub 在线获取 |
| **缓存 TTL** | 远程缓存每 24 小时自动刷新 |
---
## 环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
| `CDS_KB_DATA` | — | 本地数据仓库路径（替代 `--data`） |
| `CDS_KB_REMOTE` | `https://.../main` | 原始 GitHub URL（替代 `--remote`） |
| `CDS_KB_REFRESH` | `0` | 设置为 `1` 以强制远程索引重新下载 |
| `CDS_KB_CACHE_TTL_HOURS` | `24` | 远程模式缓存过期时间（小时） |
---
## 故障排除
### 搜索结果不佳
检查 `kb_info` 输出 — 如果 `enriched: 0`，则索引未丰富。
**修复：**
```bash
node enrich_index.mjs /path/to/cds-kb-data
```
### 远程缓存已过时
```bash
# 强制重新下载
CDS_KB_REFRESH=1 node dist/cds-kb-mcp.mjs
```
### 视图未找到
视图名称 **不区分大小写** 但必须准确。使用 `search_cds` 或 `get_views_by_tag` 首先找到正确的名称。
---
## 项目结构
```
cds-kb-mcp/
├── src/
│ ├── server.mjs # MCP 服务器 — 工具定义，搜索逻辑
│ └── datasource.mjs # 数据访问层（本地 + 远程后端）
├── dist/
│ └── cds-kb-mcp.mjs # 预构建的单文件捆绑包（~784 KB）
├── cds-kb-data/ # Git 子模块（如果使用 --recurse-submodules 克隆）
├── build.mjs # esbuild 捆绑器配置
├── enrich_index.mjs # 索引丰富脚本
├── test_tools.mjs # 集成烟雾测试
├── package.json
└── README.md
```
## 许可证
MIT
