Odata MCP Proxy

OData MCP 代理

配置驱动 MCP（模型上下文协议） 将OData和REST API作为MCP工具公开的服务器。这使得Claude等人工智能助手能够通过自然语言查询、管理和监控SAP后端。

该服务器在SAP BTP Cloud Foundry上运行，并使用BTP Destinations实现与OData API的安全、令牌管理的连接。

______________________________________________________________________

特性

• 32个OData实体集 在6个API类别中，自动注册为MCP工具
• 完全CRUD支持 --列出、获取、创建、更新和删除API允许的操作
• OData V2查询功能 -- $filter, $select, $expand, $orderby, $top, $skip，以及 $inlinecount
• 导航属性遍历 --相关实体的专用工具（例如iFlow配置、消息附件、错误详细信息）
• 基于类别的过滤 --通过配置仅启用所需的API类别
• 双重运输方式 --可流式HTTP用于BTP部署，stdio用于本地Claude Desktop使用
• 自动OAuth令牌管理 --令牌通过BTP目标服务透明地刷新

______________________________________________________________________

建筑

Claude / AI Assistant
        |
        | MCP Protocol (stdio or HTTP)
        v
 OData MCP Proxy
        |
        | OData V2 + JSON
        v
   OData Client
        |
        | OAuth2 (via BTP Destination Service)
        v
  BTP Destination
        |
        v
 SAP Cloud Integration
   OData Admin APIs

服务器在启动时解析BTP目标，以获取云集成租户URL和OAuth2凭据。在每个API调用上，都会重新解析目标，以确保令牌保持有效。OData客户端将MCP工具调用转换为OData V2 HTTP请求，并将结构化JSON结果返回给AI助手。

______________________________________________________________________

先决条件

• Node.js 20+（最低18+，建议20+）
• SAP BTP帐户 使用Cloud Foundry环境
• SAP集成套件 租户（云集成能力）
• BTP目的地 配置为指向具有OAuth2身份验证的云集成租户的OData API
• Cloud Foundry命令行界面 (cf)以及 MBT构建工具 (mbt)用于BTP部署

______________________________________________________________________

快速启动（地方发展）

1.克隆并安装

git clone 
cd odata-mcp-proxy
npm install

2.配置环境

cp .env.example .env

编辑 .env 并设置为最小值：

SAP_DESTINATION_NAME=your_ci_destination_name
MCP_TRANSPORT=stdio

注： 对于使用stdio传输的本地开发，您的环境中必须有可用的BTP目标服务凭据（例如，通过 VCAP_SERVICES 或a default-env.json 文件）。

3.构建和运行

npm run build
npm run start:stdio

或者使用开发监视器：

npm run dev

4.从克劳德桌面连接

将服务器添加到Claude Desktop MCP配置中(claude_desktop_config.json):

{
  "mcpServers": {
    "odata-mcp-proxy": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/path/to/odata-mcp-proxy",
      "env": {
        "SAP_DESTINATION_NAME": "your_ci_destination_name",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

______________________________________________________________________

用作npm包

你可以消费 odata-mcp-proxy 作为您自己项目中的依赖项——类似于 SAP应用程序路由器 作品。不需要TypeScript编译或构建步骤。

1.创建您的项目

mkdir my-mcp-server
cd my-mcp-server
npm init -y
npm install odata-mcp-proxy

2.添加启动脚本

在你的 package.json:

{
  "scripts": {
    "start": "odata-mcp-proxy"
  },
  "dependencies": {
    "odata-mcp-proxy": "^1.0.0"
  }
}

3.添加您的API配置

创建一个 api-config.json 在您的项目根目录中。CLI会自动从工作目录中拾取它。请参阅 捆绑配置文件 对于完整格式。

{
  "server": {
    "name": "my-mcp-server",
    "version": "1.0.0",
    "description": "My custom MCP server"
  },
  "apis": [
    {
      "name": "my-api",
      "destination": "MY_DESTINATION",
      "pathPrefix": "/api/v1",
      "csrfProtected": true,
      "entitySets": [
        {
          "entitySet": "Products",
          "description": "product entities",
          "category": "master-data",
          "keys": [{ "name": "Id", "type": "string" }],
          "operations": { "list": true, "get": true, "create": false, "update": false, "delete": false }
        }
      ]
    }
  ]
}

您还可以使用自定义文件名 --config 标志：

odata-mcp-proxy --config my-custom-config.json

或者通过环境变量进行设置：

API_CONFIG_FILE=my-custom-config.json npm start

如果在工作目录中找不到配置文件，则使用捆绑的默认值（SAP Cloud Integration API）。

4.配置凭据

为了地方发展，创建一个 .env 文件或 default-env.json 使用您的目的地凭据。env-var前缀来源于 destination 配置中的字段--将其大写，并将非字母数字字符替换为 _.

例如，目的地 "MY_DESTINATION" 映射到：

MY_DESTINATION_BASE_URL=https://my-api.example.com
MY_DESTINATION_TOKEN_URL=https://auth.example.com/oauth/token
MY_DESTINATION_CLIENT_ID=...
MY_DESTINATION_CLIENT_SECRET=...

在BTP上，请改用目标服务（凭据通过以下方式自动解析 VCAP_SERVICES).

5.项目结构

一个完整的消费者项目看起来像这样：

my-mcp-server/
├── package.json          # start script + dependency
├── api-config.json       # your API configuration
├── default-env.json      # local BTP credentials (gitignored)
├── .env                  # local env overrides (gitignored)
├── mta.yaml              # BTP deployment descriptor
└── xs-security.json      # XSUAA config (if using OAuth)

作为消费者项目部署到BTP

由于没有构建步骤 mta.yaml 很简单，就像SAP应用程序路由器一样：

_schema-version: "3.1"
ID: my-mcp-server
version: 1.0.0

parameters:
  enable-parallel-deployments: true

modules:
  - name: my-mcp-server
    type: nodejs
    path: .
    parameters:
      memory: 512M
      disk-quota: 1G
      buildpack: nodejs_buildpack
      health-check-type: http
      health-check-http-endpoint: /health
      command: npm start
    build-parameters:
      builder: npm
      ignore:
        - .git/
        - .env
        - default-env.json
    requires:
      - name: my-destination
      - name: my-connectivity
      - name: my-xsuaa

resources:
  - name: my-destination
    type: org.cloudfoundry.managed-service
    parameters:
      service: destination
      service-plan: lite

  - name: my-connectivity
    type: org.cloudfoundry.managed-service
    parameters:
      service: connectivity
      service-plan: lite

  - name: my-xsuaa
    type: org.cloudfoundry.managed-service
    parameters:
      service: xsuaa
      service-plan: application
      path: xs-security.json

与独立部署的关键区别： builder: npm 这就是你所需要的。MBT运行 npm install --production，安装预构建 odata-mcp-proxy 从注册表中删除包。没有TypeScript，没有自定义构建命令。

使用以下方式部署：

mbt build && cf deploy mta_archives/my-mcp-server_1.0.0.mtar

______________________________________________________________________

BTP部署（独立）

当直接使用源代码库（而不是作为npm依赖项）时，项目包含自己的 mta.yaml 用于部署到SAP BTP Cloud Foundry。MTA提供所需的服务实例（Destination、Connectivity、XSUAA），并使用HTTP传输将服务器部署为Node.js应用程序。

npm run build:btp    # Build the MTA archive
npm run deploy:btp   # Deploy to Cloud Foundry

有关详细的部署说明、目标配置和XSUAA设置，请参阅 文档/部署.md.

______________________________________________________________________

配置

所有配置都通过环境变量进行管理。服务器在启动时使用Zod验证配置，并在无效值时快速失败。

API类别

使用 ENABLED_API_CATEGORIES 要限制注册哪些工具组，请执行以下操作：

设置为 all （默认）启用每个类别。

______________________________________________________________________

可用工具

工具是根据实体集定义动态生成的。每个实体集最多可生成五个工具(_list, _get, _create, _update, _delete)以及导航属性工具，具体取决于OData API支持的内容。

集成内容

消息处理日志

消息存储

日志文件

安全内容

合作伙伴目录

工具命名约定

工具遵循模式 {EntitySet}_{operation}:

IntegrationPackages_list
IntegrationPackages_get
IntegrationPackages_create
IntegrationDesigntimeArtifacts_Configurations_list
MessageProcessingLogs_ErrorInformations_list

OData查询参数

全部 _list 工具接受标准OData V2查询选项：

• $filter --例如。， "Status eq 'FAILED'"
• $select --例如。， "Id,Name,Status"
• $expand --例如。， "Configurations"
• $orderby --例如。， "Name asc"
• $top --例如。， 10
• $skip --例如。， 20

______________________________________________________________________

运输方式

HTTP（流式HTTP）

用于BTP Cloud Foundry部署。服务器公开了一个 /mcp 支持MCP流式HTTP传输和会话管理的端点，以及 /health CF健康检查的终点。

MCP_TRANSPORT=http PORT=4004 npm start

标准

用于本地开发和与Claude Desktop的直接集成。通信通过标准输入/输出流进行。

MCP_TRANSPORT=stdio npm start

______________________________________________________________________

技术栈

• 运行时间： Node.js 20+，带ES模块
• 语言： TypeScript 5.7+
• MCP-SDK： @modelcontextprotocol/sdk 1.17+
• SAP云SDK： @sap-cloud-sdk/connectivity 和 @sap-cloud-sdk/http-client 4.x用于目标解析和HTTP调用
• 验证： Zod用于配置和输入验证
• HTTP框架： Express 4.x（仅限HTTP传输）
• 登录中： 温斯顿

______________________________________________________________________

许可证

麻省理工学院