cap-js

欢迎使用 @cap-js/mcp-server

关于本项目

适用于 SAP Cloud Application Programming Model (CAP) 的模型上下文协议（MCP）服务。 用于辅助开发 CAP 应用（Agentic 编码）。

该服务可帮助 AI 模型回答以下问题：

• 此项目中有哪些 CDS 服务？它们在哪里提供服务？
• 这些实体是什么？它们之间有什么关系？
• 如何在 CAP Node.js 中向 select 语句添加列？

目录

• 关于本项目
• 要求
• 设置
  • 在 VS Code 中使用
  • 在 Claude Code 中使用
  • 在 OpenAI Codex 中使用
  • 在 opencode 中使用
  • 命令行用法
  • 环境变量
• 可用工具
  • search_model
  • search_docs
• 支持、反馈与贡献
• 安全 / 漏洞披露
• 行为准则
• 许可
• 致谢

要求

请参阅入门指南，了解如何快速开始开发，并随着实践不断提升 SAP Cloud Application Programming Model 的使用能力。

设置

配置 MCP 客户端（Cline、opencode、Claude Code、GitHub Copilot 等），使用命令 npx -y @cap-js/mcp-server 启动服务，示例如下。

在 Claude Code 中使用

在 Claude Code 中注册服务。

用于所有项目（用户范围）：

claude mcp add --scope user cds-mcp -- npx -y @cap-js/mcp-server

仅用于当前项目（本地范围，不提交）：

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

仅用于当前项目（提交到代码库）：

claude mcp add --scope project cds-mcp -- npx -y @cap-js/mcp-server

若要设置环境变量，请在服务名称前添加 --env：

claude mcp add --scope user --env CDS_MCP_MODEL=nomic-ai/nomic-embed-text-v1.5 cds-mcp -- npx -y @cap-js/mcp-server

在 VS Code 中使用

VS Code 扩展 Cline 的示例：

{
  "mcpServers": {
    "cds-mcp": {
      "command": "npx",
      "args": ["-y", "@cap-js/mcp-server"],
      "env": {}
    }
  }
}

VS Code 全局 mcp.json 的示例：

注意：GitHub Copilot 使用 mcp.json 文件作为其 Agent 模式的来源。

{
  "servers": {
    "cds-mcp": {
      "command": "npx",
      "args": ["-y", "@cap-js/mcp-server"],
      "env": {},
      "type": "stdio"
    },
    "inputs": []
  }
}

若要设置环境变量，请将服务的空 env 对象替换为：

"env": {
  "CDS_MCP_MODEL": "nomic-ai/nomic-embed-text-v1.5"
}

更多 Agent 扩展请参阅 VS Code Marketplace。

在 OpenAI Codex 中使用

在 OpenAI Codex 中注册服务：

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

若要设置环境变量，请在命令前添加 --env：

codex mcp add cds-mcp --env CDS_MCP_MODEL=nomic-ai/nomic-embed-text-v1.5 -- npx -y @cap-js/mcp-server

在 opencode 中使用

将以下内容添加到项目中的 opencode.jsonc，或添加到 ~/.config/opencode/opencode.jsonc 以供全局使用：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "cds-mcp": {
      "type": "local",
      "command": ["npx", "-y", "@cap-js/mcp-server"],
      "environment": {
        "CDS_MCP_MODEL": "nomic-ai/nomic-embed-text-v1.5"
      },
      "enabled": true
    }
  }
}

这是 opencode v1 格式。在 opencode v2 中，使用相同的配置，但将服务嵌套在 "servers" 下——"mcp": { "servers": { "cds-mcp": { ... } } }——或者改用命令行：

opencode mcp add --global cds-mcp -- npx -y @cap-js/mcp-server

若要设置环境变量：

opencode mcp add --global cds-mcp \
  --env CDS_MCP_MODEL=nomic-ai/nomic-embed-text-v1.5 \
  -- npx -y @cap-js/mcp-server

环境变量

警告

以下环境变量仍处于实验阶段。

变量	描述
CDS_MCP_OFFLINE	设置为 true，即可使用本地缓存的嵌入向量，而不检查更新。接受 true 或 false。
CDS_MCP_MODEL	非空的嵌入模型名称。
CDS_MCP_MANIFEST_TIMEOUT	清单请求超时时间，以正整数毫秒为单位。默认为 15000。
CDS_MCP_DOWNLOAD_TIMEOUT	Bundle 响应标头超时时间，以正整数毫秒为单位。默认为 30000。
CDS_MCP_GENERIC_EMBEDDINGS	设置为 true，即可跳过运行时筛选并搜索所有运行时。默认情况下，search_docs 仅保留已检测到的项目运行时（Node.js 或 Java）的分块，以及与运行时无关的分块。
CDS_MCP_MAX_RESULTS	search_docs 结果数量的上限，必须为正整数。限制每次调用的 maxResults。
CDS_MCP_RERANK_ENABLED	设置为 true，即可使用本地交叉编码器模型对 search_docs 结果重新排序。接受 true 或 false；默认禁用。
CDS_MCP_RERANK_MODEL	重新排序时使用的非空交叉编码器模型名称。默认为 Xenova/ms-marco-MiniLM-L-6-v2。
CDS_MCP_RERANK_DTYPE	加载重新排序模型时使用的非空数据类型。默认为 q8；对于没有 model_quantized.onnx 的模型，设置为 fp32。
CDS_MCP_RERANK_EXTERNAL_DATA	对于 ONNX 权重存储在外部 .onnx_data 文件中的重新排序模型，设置为 true。接受 true 或 false。
CDS_MCP_RERANK_BATCH_SIZE	每个重新排序批次要处理的结果数量，必须为正整数。默认为 1。

规则

以下规则有助于 LLM 正确使用该服务：

- You MUST search for CDS definitions, like entities, fields and services (which include HTTP endpoints) with cds-mcp, only if it fails you MAY read \*.cds files in the project.
- You MUST search for CAP docs with cds-mcp EVERY TIME you create, modify CDS models or when using APIs or the `cds` CLI from CAP. Do NOT propose, suggest or make any changes without first checking it.

将这些规则添加到现有的全局或项目专属 AGENTS.md 文件中（具体方式可能因 MCP 客户端而异）。

CLI 用法

你也可以直接从命令行使用这些工具。

npm i -g @cap-js/mcp-server

警告

全局安装软件包后，npx 会使用已安装的版本，而不是从 npm 下载最新版本。你必须手动更新软件包：

npm update -g @cap-js/mcp-server

这将提供 cds-mcp 命令，你可以通过该命令直接调用工具，如下所示。

# Search CAP documentation
cds-mcp search_docs "how to add columns to a select statement in CAP Node.js" 1

# Search for CDS model definitions
cds-mcp search_model . Books entity

可用工具

说明

这些工具旨在供 AI 模型使用，不构成稳定的 API。

该服务为 CAP 开发提供以下工具：

search_docs

此工具使用向量嵌入，在本地搜索预处理后的 CAP 文档（以嵌入向量形式存储）。其工作流程如下：

1. 查询处理： 将你的搜索查询转换为嵌入向量。
2. 相似度搜索： 系统会查找与查询语义最相似的文档分块。

这种语义搜索方式让你即使没有使用文档中的确切关键词，也能在本机找到相关文档。

search_model

此工具会针对已编译 CDS 模型（核心模式表示法）中的定义名称进行模糊搜索。 CDS 会将所有 .cds 文件编译成统一的模型表示，其中包含：

• 所有定义及其关系
• 注解
• HTTP 端点

模糊搜索算法会匹配定义名称，并支持部分匹配，因此即使搜索“book”，也能轻松找到“Books”等实体。

支持、反馈与贡献

本项目欢迎通过 GitHub issues 提交功能请求／建议、错误报告等。我们鼓励并欢迎贡献和反馈。如需了解如何贡献、项目结构以及其他贡献信息，请参阅贡献指南。

安全性 / 漏洞披露

如果发现任何可能涉及安全问题的 Bug，请按照我们的安全策略中的说明进行报告。请不要针对与安全相关的疑问或问题创建 GitHub issue。

行为准则

作为社区成员、贡献者和领导者，我们承诺为所有人营造无骚扰的社区参与体验。参与此项目即表示你同意始终遵守我们的行为准则。

许可

版权所有 2025 SAP SE 或 SAP 关联公司及 @cap-js/cds-mcp 贡献者。版权和许可信息请参阅我们的 LICENSE。第三方组件及其许可和版权信息等详细信息可通过 REUSE 工具获取。

致谢

• onnxruntime-web 用于在本地创建嵌入向量。
• @huggingface/transformers.js 用于比较 WordPiece 分词器的输出。
• @modelcontextprotocol/sdk 提供 MCP SDK。