mdk-mcp-server

欢迎使用 @sap/mdk-mcp-server

Mobile Development Kit (MDK) MCP 服务是什么？

这个开源服务为 AI Agent 提供全面的 MDK 知识和工具。通过结合最佳实践指南、项目感知上下文信息、用于创建新项目的模板，以及对 MDK CLI 工具的访问权限，MDK MCP 服务可将 AI Agent 转变为 MDK 开发专家。

Mobile Development Kit 是什么？

Mobile Development Kit 是一个功能强大的框架，支持开发者使用元数据驱动的方法构建跨平台移动应用。它是 SAP Business Technology Platform 的一部分，并与 SAP Mobile Services 紧密集成。 SAP 的一些规模较大且复杂的移动应用都是使用 MDK 构建的。例如，SAP Service and Asset Manager。

目录

• 设置
• 可用工具
• 导入 GitHub 知识（高级）
• 离线 OData 查询（高级）
• 支持、反馈与贡献
• 遥测
• 安全 / 漏洞披露
• 行为准则
• 许可
• 致谢

设置

平台支持

MDK MCP 服务支持以下平台：

• macOS：仅限 Apple Silicon（ARM64）
  • ⚠️ 注意：由于 onnxruntime-node ≥1.24 不再提供 darwin/x64 二进制文件，v0.4.0+ 不支持 Intel Mac（x64）
• Linux：x64、ARM64 及其他架构
• Windows：x64、ARM64

如果你使用的是 Intel Mac，可能需要：

• 使用 Rosetta 2 运行 ARM64 版本（性能可能有所不同）
• 或继续使用采用 onnxruntime-node <1.24 的早期版本

安装步骤

1. 安装 node.js 24.11.1。

2. 安装 MDK MCP 服务有两种方式：

   a. 使用 npm 从公共 npmjs 注册表 @sap/mdk-mcp-server 安装。

   npm install -g @sap/mdk-mcp-server
   

   b. 克隆开源代码仓库 https://github.com/SAP/mdk-mcp-server，并使用 npm 安装。

   git clone https://github.com/SAP/mdk-mcp-server.git 
   cd mdk-mcp-server 
   npm i
   npm run build
   npm i -g @sap/mdk-mcp-server@. 
   

3. 配置 MCP 客户端（AI Agent）以连接到服务。请注意，配置会因所使用的 AI Agent 而异。

   VS Code 中的 Cline： 使用 Cline 扩展的示例。

   • 打开 Cline 后，在提示词框下方找到并点击 Manage MCP Servers。
   • 在对话框中，点击 Settings。MCP Servers 页面随即打开。
   • 点击 Configure MCP Servers。这会在编辑器中打开 cline_mcp_settings.json 文件。
   • 在 JSON 设置文件的 mcpServers 部分中，为 MDK MCP 服务添加配置块，然后保存文件。支持的架构版本包括 26.9（默认）、26.6、26.3、25.9、25.6、24.11 和 24.7。

   {
     "mcpServers": {
       "mdk-mcp": {
         "type": "stdio",
         "command": "mdk-mcp",
         "args": ["--schema-version", "26.9"]
       }
     }
   }
   

   注意： 如果 Cline 扩展没有立即列出 MCP 服务及其可用工具，请重启 VS Code。

   展开：在 Claude Code（VS Code 扩展）中使用

   Claude Code 会从其配置中发现 MCP 服务。

   1. 打开（或创建）Claude Code 配置文件：

   ~/.claude.json
   

   2. 添加以下 MCP 服务配置：

   {
     "mcpServers": {
       "mdk-mcp": {
         "type": "stdio",
         "command": "mdk-mcp",
         "args": ["--schema-version", "26.9"]
       }
     }
   }
   

   **注意：**如果 ~/.claude.json 已存在，请将 mdk-mcp 条目合并到现有的 mcpServers 部分，而不要替换整个文件。

   3. 重新加载 VS Code 窗口（或重启 VS Code）。

   验证安装

   在 VS Code 中打开 Claude Code 面板并运行：

   /mcp
   

   你应会看到 mdk-mcp 列在可用 MCP 服务中。

   展开：在 OpenCode 中使用

   使用 OpenCode 的示例：

   {
     "mcp": {
       "mdk-mcp": {
         "type": "local",
         "command": ["mdk-mcp", "--schema-version", "26.9"],
         "enabled": true
       }
     }
   }
   

   展开：在 Cursor 中使用

   编辑文件 ~/.cursor/mcp.json：

   {
     "mcpServers": {
       "mdk-mcp": {
         "type": "stdio",
         "command": "mdk-mcp",
         "args": ["--schema-version", "26.9"]
       }
     }
   }
   

   展开：在 Claude Desktop 中使用

   在 Claude Desktop 配置文件中使用 Node.js 的绝对路径。

   1. 运行终端命令查找 Node.js 的安装路径：

      which node
      

      输出可能类似于 /usr/local/bin/node 或 /opt/homebrew/bin/node。

   2. 编辑 ~/Library/Application Support/Claude/claude_desktop_config.json，并更新 command 字段以使用绝对路径：

      {
        "mcpServers": {
          "mdk-mcp": {
            "command": "/usr/local/bin/node",
            "args": ["/usr/local/lib/node_modules/@sap/mdk-mcp-server/build/index.js", "--schema-version", "26.9"]
          }
        }
      }
      

   3. 重启 Claude Desktop。

   **注意：**请根据实际的 Node.js 和 MDK MCP 服务安装位置调整路径。

   配置完成后，你的 AI Agent 就可以使用 MDK MCP 服务。根据 IDE 设置，你可能需要批准首次工具调用。

4. 创建规则文件：为确保 AI 编码助手恰当地使用适用于项目的 MCP 服务，请在名为 AGENTS.md 的文件中定义规则和指南。在 VS Code 的 Cline 扩展中，点击提示词框下方的 Manage Cline Rules & Workflows 图标，然后点击 + 创建新的规则文件（例如 AGENTS.md），并添加以下示例规则：

   - 不要生成 `.service.metadata` 文件。
   - 不要在 `Services` 文件夹中生成 `.xml` 文件。
   - 不要更改 `.project.json` 文件。
   

5. 验证大模型提供商和 AI 模型。

   将 Cline 添加到 VS Code 后，它会成为默认 API 提供商。你可以选择其他大模型提供商，例如 SAP AI Core。 若要在 VS Code 的 Cline 扩展中添加 SAP AI Core API 提供商，请按以下步骤操作：

   • 打开 Cline 后，在提示词框下方找到并点击 Select Model / API Providers。
   • 选择你的 API 提供商（例如 SAP AI Core）并输入详细信息。有关详细设置说明，请参阅此处。
   • 选择你偏好的 AI 模型。

6. 与 SAP Mobile Services 集成： 要创建新的 MDK 应用，MCP 服务会使用 Cloud Foundry CLI 和 .service.metadata 文件，其中包含：

   • SAP Mobile Services 实例中定义的移动应用。
     • Mobile Services API 端点
     • Mobile Services App ID
   • 移动目标，包括 OData 服务元数据。

   我们在 VS Code 扩展：Mobile development kit extension for VS Code 中提供了一个工具，可帮助创建或更新此文件。你可以通过以下步骤使用该工具创建或更新 .service.metadata 文件：

   1. 安装 Mobile development kit extension for VS Code 1.32.0 或更高版本。
   2. 安装 Cloud Foundry CLI。
   3. 登录 SAP BTP Cloud Foundry 环境。更多详情请参阅此帮助文档。

   cf login -a <your target endpoint> --sso
   

   4. 在计算机上创建一个空文件夹，并在 VS Code 中打开它。
   5. 在 VS Code 中打开命令面板，然后选择 MDK: Open Mobile App Editor。
   6. 创建新的移动应用，或选择现有应用。
   7. 选择一个目标。
   8. 点击 Add App to Project。

7. 现在，环境已准备就绪，可以使用 MCP 服务进行 MDK 开发。你可以输入提示词来：

   • 生成一个新的 MDK 项目，用于显示 OData 实体信息。
   • 通过在指定页面添加更多 UI 控件来增强现有项目。
   • 验证当前 MDK 项目架构。
   • 将旧版 MDK 项目迁移到最新架构。
   • 部署 MDK 项目。
   • 生成入门二维码。
   • 解释特定属性。
   • 查找控件属性或文档中任何方面的信息。

可用工具

说明

工具供 AI 模型使用，并不构成稳定的 API。

此版本的 MDK MCP 服务包含以下工具，可供你的 AI Agent 使用：

工具	描述	参数
mdk-create	使用模板（CRUD、列表详情、基础）创建 MDK 项目或实体元数据。用于初始化新项目，或向现有项目添加实体元数据。	- folderRootPath: 当前项目根文件夹的路径。 - scope: 创建范围： • project：使用完整结构初始化新的 MDK 项目 • entity：向现有项目添加实体元数据 - templateType: 要使用的模板类型（crud、list detail、base）。注意：base 模板仅适用于 project 范围。 - oDataEntitySets: 与用户提示词相关的 OData 实体集，以逗号分隔。 - offline: 是否以离线模式生成项目（仅适用于 project 范围）。除非明确指定离线模式，否则设为 false。
mdk-gen	生成 MDK 构件，包括页面、操作、i18n 文件和规则引用。返回供大模型处理的提示词（页面、操作、i18n），或搜索规则示例。	- artifactType: 要生成的构件类型： • page：生成带数据绑定或布局的 MDK 页面文件（.page） • action：生成 MDK 操作文件（.action） • i18n：生成国际化文件（.properties） • rule：搜索并返回相关的 JavaScript 规则示例 - folderRootPath: 当前项目根文件夹的路径（rule 构件类型不需要此参数）。 页面构件： - pageType: 页面类型 page）： • databinding：将控件绑定到 OData 的数据驱动页面 • layout：采用特定布局、侧重结构的页面 - controlType: 数据绑定页面的控件类型（当 pageType 为 databinding 时必填）。可用类型：ObjectTable、FormCell、KeyValue、ObjectHeader、ContactTable、SimplePropertyCollection、ObjectCard、DataTable、KPIHeader、ProfileHeader、ObjectCollection、Timeline、TimelinePreview、Calendar。 - oDataEntitySets: 可选：用于页面生成的 OData 实体集，以逗号分隔（仅当 pageType 为 databinding 时必填）。 - layoutType: 布局页面的布局类型（当 pageType 为 layout 时必填）。可用类型：Section、BottomNavigation、FlexibleColumnLayout、SideDrawerNavigation、Tabs、Extension。 操作构件： - actionType: 操作类型（当 artifactType 为 action 时必填）。可用类型：CreateODataEntity、UpdateODataEntity、DeleteODataEntity、CreateODataMedia、InitializeOfflineOData、DownloadOfflineOData、UploadOfflineOData、CancelDownloadOfflineOData、CancelUploadOfflineOData、ClearOfflineOData、CloseOfflineOData、CreateODataRelatedEntity、CreateODataRelatedMedia、CreateODataService、DeleteODataMedia、DownloadMediaOData、LogMessage、Message、Navigation、OpenODataService、ProgressBanner、PushNotificationRegister、PushNotificationUnregister、ReadODataService、RemoveDefiningRequest、SendRequest、SetLevel、SetState、ToastMessage、UndoPendingChanges、UploadLog、UploadODataMedia、UploadStreamOData、ChatCompletion、PopoverMenu、CheckRequiredFields、ChangeSet、OpenDocument、Banner、Filter。 - oDataEntitySets: 可选：用于操作生成的 OData 实体集，以逗号分隔（仅当 artifactType 为 action 时必填）。 i18n 构件： - 除 folderRootPath 外，无需其他参数。 规则构件： - query: 规则参考的搜索查询（当 artifactType 为 rule 时必填）。示例：get app name、handle form validation、navigate to page 等。
mdk-manage	全面的 MDK 项目管理工具，可处理构建、部署、验证、迁移、显示二维码和移动应用编辑器操作。	- folderRootPath: 当前项目根文件夹的路径。 - operation: 要对 MDK 项目执行的操作。可用操作： • build：构建 MDK 项目 • deploy：将 MDK 项目部署到 Mobile Services • validate：验证 MDK 项目 • migrate：将 MDK 项目迁移到最新 MDK 版本 • show-qrcode：显示 MDK 项目的二维码 • open-mobile-app-editor：说明如何打开 Mobile App Editor 来创建 .service.metadata 文件 - externals: 可选：要包含在部署中的外部软件包名称数组（例如 [@nativescript/geolocation]）。如果未指定，将自动从项目的 .vscode/settings.json 中读取 mdk.bundlerExternals。如果两者都未提供，则默认为空数组。
mdk-docs	用于访问 MDK 文档的统一工具，包括搜索、组件架构、属性详情和示例。	- operation: 要执行的文档操作类型： • search：通过语义搜索从 MDK 文档返回排名靠前的 N 条结果，并按相关性排序 • component：根据组件名称返回 MDK 组件的架构 • property：返回 MDK 组件特定属性的文档 • example：返回 MDK 组件的用法示例 • search-samples：搜索 GitHub 上的 MDK 教程示例和代码示例 - folderRootPath: 当前项目根文件夹的路径。用于确定适用的 MDK 架构版本。 - query: 搜索查询字符串（search 和 search-samples 操作必填）。 - component_name: 组件名称（component、property 和 example 操作必填）。 - property_name: 属性名称（property 操作必填）。 - N: 搜索操作要返回的结果数量（默认值：5）。
mdk-fetch-mobile-metadata	从 Mobile Services 目标位置获取 OData $metadata 文档，并将其保存为 MDK 项目中的 .service.metadata 文件。mdk-create 和 mdk-gen 工具需要此文件来生成数据绑定页面/操作。需要通过 CF CLI 进行身份验证（cf login）。	- folderRootPath: 将保存 .service.metadata 的 MDK 项目根文件夹路径。 - appId: Mobile Services 应用 ID（例如 myapp.mdk.demo）。 - destination: 在 Mobile Services 中配置的目标名称（例如 IncidentManagement）。 - pathSuffix: 可选，要附加在 /$metadata 之前的路径后缀（例如 /api/v1）。如不需要，请留空。 - landscapeType: Mobile Services 环境类型。生产环境使用 Standard（默认值），预览环境使用 Preview。

导入 GitHub 知识（高级）

MDK MCP 服务可以从 GitHub 仓库导入其他知识，以增强 search-samples 操作。这让 AI Agent 能够搜索 MDK 教程示例和代码示例。

导入的内容

默认情况下，服务会导入以下内容：

• MDK 教程示例：https://github.com/SAP-samples/cloud-mdk-tutorial-samples
• MDK 示例和 Showcase 应用：https://github.com/SAP-samples/cloud-mdk-samples

何时运行导入

通常只有在以下情况下才需要运行导入：

• 首次设置（如果要使用 search-samples 操作）
• 更新知识库（GitHub 仓库中添加了新示例时）
• 克隆仓库后（导入的数据不包含在仓库中）

**注意：**导入过程是可选的。服务无需导入即可运行，但在完成导入之前，search-samples 操作不会返回结果。

如何导入

基本导入（如果有缓存数据，则使用缓存）：

npm run ingest

全新导入（忽略缓存，重新下载所有内容）：

npm run ingest:fresh

使用 GitHub 令牌（建议使用，以获得更高的速率限制）：

export GITHUB_TOKEN="your_github_token_here"
npm run ingest

自定义选项：

npm run build
node build/ingest-github-knowledge.js --no-cache --github-token "your_token" --chunk-size 800

命令行选项

选项	说明	默认值
--no-cache	强制重新下载所有内容，忽略缓存	使用缓存
--github-token <token>	用于 API 请求的 GitHub 个人访问令牌	$GITHUB_TOKEN 环境变量
--vector-db <path>	存储向量数据库的路径	./knowledge.db
--chunk-size <number>	用于嵌入的文本块大小	1000
--chunk-overlap <number>	文本块之间的重叠长度	200

设置 GitHub 令牌

为避免 GitHub API 速率限制，请创建个人访问令牌：

1. 前往 https://github.com/settings/tokens
2. 点击 Generate new token（classic）
3. 选择范围：public_repo（对公共仓库的读取权限）
4. 复制令牌并将其设置为环境变量：

   export GITHUB_TOKEN="ghp_your_token_here"
   

导入输出

导入过程将会：

1. 从配置的 GitHub 仓库获取内容
2. 将内容分块，便于处理
3. 使用 AI 模型生成嵌入
4. 将嵌入存储在向量数据库中
5. 通过 search-samples 操作启用语义搜索

输出示例：

Fetching from MDK Tutorial Samples...
Chunking content: 150 chunks created
Generating embeddings: 150/150 (100%)
✓ Ingestion complete!

故障排除

问题：超出 GitHub API 速率限制

• 解决方案：设置 GitHub 令牌（见上文）

问题：导入耗时过长

• 解决方案：仅在必要时使用 --no-cache；使用缓存运行的速度要快得多

问题：内存不足

• 解决方案：减小 --chunk-size，或减少要处理的仓库数量

离线 OData 查询（高级）

MDK MCP 服务可以通过 ilodata 命令行工具帮助你查询离线 OData 存储。这适用于调试离线应用，或在开发期间检查设备上本地存储的数据。

前提条件

1. MDK SDK
2. ilodata 工具：从 MDK SDK 中的 SAPOfflineOData-xx.xx.xx-Tools.zip 解压
3. 离线存储文件：来自离线应用的一对 .udb 和 .rq.udb 文件

设置步骤

1. 解压 ilodata 工具：

   # Download MDK SDK and locate the tools zip file
   unzip SAPOfflineOData-*.zip -d ~/ilodata-tools
   

2. 准备离线存储文件：

   # Copy your offline store files to the ilodata folder
   cp /path/to/your/app/*.udb ~/ilodata-tools/
   cp /path/to/your/app/*.rq.udb ~/ilodata-tools/
   

查询离线存储

设置完成后，你可以使用自然语言提示词，通过 MDK MCP 服务查询离线存储：

提示词示例：

基本查询：

Open and query the CustomerStore offline store located at ~/ilodata-tools/CustomerStore.udb 
and retrieve the top 5 entities from the Customers entity set

筛选查询：

Query the SalesOrders offline store at ~/ilodata-tools/SalesOrders.udb 
and get all orders where CustomerID equals `ALFKI`

指定字段：

Open the Products offline store at ~/ilodata-tools/Products.udb 
and retrieve ProductID, ProductName, and UnitPrice from the Products entity set

统计实体数量：

Query the Employees offline store at ~/ilodata-tools/Employees.udb 
and count the total number of records in the Employees entity set

工作原理

AI Agent 将会：

1. 理解你的自然语言查询
2. 构建适当的 ilodata 命令
3. 针对离线存储执行命令
4. 以易读的格式返回结果

支持、反馈与贡献

本项目欢迎通过 GitHub issues 提交功能请求、建议、错误报告等。我们鼓励并始终欢迎贡献和反馈。

贡献

以下说明将帮助贡献者设置项目、测试代码并维护代码质量。所有命令都应在终端中的项目文件夹内运行。

• 测试： npm test
• 构建： npm run build
• 代码检查： npm run lint:all

有关如何贡献、项目结构以及其他贡献信息，请参阅我们的贡献指南。

遥测

你可以启用或禁用分析数据收集。默认情况下，系统会收集无法识别个人身份的信息，以帮助了解你如何使用该产品并改进 MDK MCP Server。如果你想选择退出，可以通过以下两种方式禁用遥测：

方法 1：配置文件

创建或修改文件 ~/.fioritools/telemetrysettings.json：

{
  "telemetrysettings": {
    "telemetrySetting": {
      "enableTelemetry": false
    }
  }
}

将 enableTelemetry 设为 false，即可禁用遥测数据收集。

方法 2：环境变量

将环境变量 SAP_UX_FIORI_TOOLS_DISABLE_TELEMETRY 设为 true：

export SAP_UX_FIORI_TOOLS_DISABLE_TELEMETRY=true

设置此环境变量会禁用遥测客户端。

安全与披露

如果你发现可能造成安全问题的错误，请按照我们的安全政策中的说明进行报告。请勿针对与安全相关的疑虑或问题创建 GitHub issues。

行为准则

作为社区成员、贡献者和领导者，我们承诺营造一个让所有人都能免受骚扰地参与社区活动的环境。参与本项目即表示你同意始终遵守我们的行为准则。

许可

版权所有 2025 SAP SE 或 SAP 关联公司。有关版权和许可信息，请参阅我们的 LICENSE。有关第三方组件及其许可和版权信息的详细信息，请见 。

致谢

• @huggingface/transformers.js 用于比较 WordPiece 分词器的输出。
• @modelcontextprotocol/sdk 提供 MCP 的 SDK。