@cap-js/mcp-server

技能简介

@cap-js/mcp-server 是 SAP 官方推出的 Model Context Protocol（MCP）服务器，专为 SAP Cloud Application Programming Model（CAP）应用程序的 AI 辅助开发场景而设计。随着 AI 编码助手（如 Claude Code、GitHub Copilot、Cline）逐步成为开发者日常工作流的核心工具，如何让 AI 模型真正理解业务代码库的结构和 SAP 技术栈，一直是企业级 AI 落地的核心痛点。@cap-js/mcp-server 正是为了解决这一痛点而生——它将 CAP 应用的全量 CDS 模型定义和官方文档以 AI 可查询的方式暴露给 AI 模型，使 AI 编码助手能够准确回答"这个项目有哪些 CDS 服务"、"某个实体包含哪些字段"、"如何在 CAP Node.js 中为 SELECT 语句添加列"这类高度依赖项目上下文的技术问题。该 MCP 服务器由 SAP 官方维护，支持通过 npx 一键启动，配置极为简便，目前已支持 VS Code（通过 Cline 或 GitHub Copilot MCP 配置）、Claude Code、OpenAI Codex 和 opencode 等主流 AI 编码环境。

核心能力

• CDS 模型模糊搜索：基于编译后的 CDS（Core Schema Notation）模型进行模糊搜索，可快速定位项目中的实体（Entity）、服务（Service）、字段及它们之间的关联关系，AI 无需读取原始 .cds 文件即可掌握项目数据模型全貌。
• CAP 文档向量检索：利用本地运行的 HuggingFace Transformers.js 和 ONNX Runtime Web，将 CAP 官方文档预处理为向量嵌入存储于本地，AI 提出问题时通过语义相似度搜索找到最相关的文档片段，支持自然语言提问而非精确关键词匹配。
• 多 IDE 多客户端兼容：通过标准 MCP 协议暴露工具，VS Code（Cline/GitHub Copilot）、Claude Code、OpenAI Codex、opencode 等主流 AI 编码环境均可直接接入，无需额外适配。
• 零配置启动：一条 npx -y @cap-js/mcp-server 命令即可启动服务器，无需准备 API Key、无需连接外部向量数据库，所有处理均在本地完成。
• CLI 模式：除 MCP 协议集成外，还支持全局安装后通过 cds-mcp 命令行工具直接调用搜索功能，适合脱离 IDE 独立使用或集成到自定义工作流中。
• MCP 规则约束：服务器内置使用规则（Rules），指导 AI 优先通过 MCP 工具查询 CDS 定义和 CAP 文档，而非直接读取 .cds 源文件，确保查询结果与项目实际数据模型保持同步。

安装配置

前置条件：Node.js 环境（npx 运行时）。无数据库、无外部依赖，完全本地化运行。

方式一：npx 即时启动（推荐）

无需预先安装，直接在 AI 编码助手的 MCP 配置中使用 npx 启动：

// VS Code Cline 配置示例
{
  "mcpServers": {
    "cds-mcp": {
      "command": "npx",
      "args": ["-y", "@cap-js/mcp-server"]
    }
  }
}

方式二：全局安装 CLI

npm i -g @cap-js/mcp-server
# 之后可使用 cds-mcp 命令行工具
cds-mcp search_model . Books entity
cds-mcp search_docs "如何在 CAP Node.js 中添加列" 1

方式三：Claude Code / Codex 集成

# Claude Code
claude mcp add cds-mcp -- npx -y @cap-js/mcp-server

# OpenAI Codex
codex mcp add cds-mcp -- npx -y @cap-js/mcp-server

使用步骤

1. 在 AI 编码助手中添加 MCP 服务器：打开目标 IDE 的 MCP 配置文件（mcp.json / settings.json / .mcp.json），按上文示例添加 @cap-js/mcp-server 条目，保存后 IDE 自动连接。
2. 确认连接正常：在 AI 对话中尝试提问，例如"这个项目有哪些 CDS 实体？"或"如何在 CAP 中定义关联关系？"，AI 将通过 MCP 工具获取答案而非随意猜测。
3. 在修改 CDS 模型前查询文档：每当需要创建或修改 CDS 模型、使用 API 或执行 cds CLI 命令时，先通过 AI 助手向 MCP 服务器查询相关 CAP 文档，确保方案符合最新官方最佳实践。
4. CLI 独立使用（可选）：在终端直接执行 cds-mcp search_model 进行模型搜索，或 cds-mcp search_docs "" 查询文档。
5. 本地向量索引更新：CAP 文档嵌入库在首次运行时自动下载并构建，之后所有查询均在本地离线完成，无需互联网连接。

适用场景

• SAP CAP 项目开发：当开发者在一个包含多个 CDS 服务和实体的 CAP 项目中工作时，AI 助手可借助该 MCP 服务器准确理解数据模型，避免生成与项目实际结构不匹配的代码。
• AI 结对编程（Agentic Coding）：AI 编码助手在执行复杂业务逻辑开发任务时，需要频繁查阅 CAP 文档和模型定义，该服务器将这一步骤自动化并确保信息来源权威。
• 遗留 CAP 项目接手：新成员接手缺乏注释的 CAP 项目时，可通过 AI 助手基于 CDS 模型定义快速建立对项目结构的全局认知，无需逐文件阅读。
• 跨团队 CAP 应用集成：在涉及多个微服务或跨域数据模型的 SAP 架构中，AI 助手通过该服务器能够准确理解各服务边界和数据契约，降低集成出错的概率。
• 企业内部 AI 编码平台：企业若在内网环境部署 AI 编码平台，该 MCP 服务器的完全本地化运行特性（无需外网、无需 API Key）使其成为内网安全合规场景的理想选择。

适用人群

• 使用 SAP CAP 框架构建企业级应用的开发者
• 在 SAP 生态内引入 AI 编码助手的团队
• 需要维护或扩展现有 CAP 遗留项目的工程师
• AI 编码平台（Claude Code / Codex / Copilot）重度用户
• SAP 合作伙伴及咨询公司的技术顾问

工作原理

@cap-js/mcp-server 的底层架构分为两个核心模块：

CDS 模型搜索模块：服务器读取项目目录下经 cds compile 编译后的统一 CDS 模型文件（JSON 格式），该文件包含项目中所有 .cds 源文件定义的实体、关联、注解及 HTTP 服务端点信息。AI 提出查询请求时，服务器对模型定义名称执行模糊匹配算法（如"Books"可匹配"book"或"bookOrder"），返回最相关的定义及其完整字段信息。

CAP 文档向量检索模块：服务器使用 HuggingFace Transformers.js 在本地对 CAP 官方文档进行分块并生成向量嵌入，存储于本地 SQLite 或文件系统中。AI 提问时，将问题转换为向量，在本地向量库中执行语义相似度搜索，返回最相关的文档片段。该模块完全运行在浏览器或 Node.js 环境中，不依赖任何外部 API 服务。

两部分能力均通过标准 MCP 协议工具（search_model 和 search_docs）暴露给 AI 模型使用。