ebaolife

将亿保健康的 O2O 和直付 API 暴露为 MCP (Model Context Protocol) 工具，让 Claude Code、Trae、Cursor 等 AI 编程工具可以直接调用 API、生成集成代码、调试接口。

工作原理

客户在 AI 编程工具中对话
        |
        v
  AI 调用 MCP 工具 (o2o_accept, directpay_querySwipeAmount, ...)
        |
        v
  MCP Server 自动处理鉴权签名 (AES/MD5)
        |
        v
  请求发送到亿保 API (或本地 Mock)
        |
        v
  AI 拿到真实返回，生成正确的集成代码

快速开始

方式一：npx 直接运行（推荐，发布到 npm 后）

无需安装，在 AI 编程工具配置中直接使用 npx -y ebaolife：

Claude Code

编辑 ~/.claude/claude_desktop_config.json（或项目根目录的 .mcp.json）：

{
  "mcpServers": {
    "ebaolife": {
      "command": "npx",
      "args": ["-y", "ebaolife"],
      "env": {
        "YIBAO_APP_ID": "your_app_id",
        "YIBAO_APP_KEY": "your_aes_key",
        "YIBAO_DP_UN": "your_dp_username",
        "YIBAO_DP_PW": "your_dp_password"
      }
    }
  }
}

Cursor

编辑 ~/.cursor/mcp.json，使用同样的配置格式。

Trae

在 Trae 设置 > MCP 中添加同样的配置。

方式二：本地开发模式

git clone <repo-url> ebaolife
cd ebaolife
npm install

本地配置示例（将 npx 换成 node，args 指向本地 index.js）：

{
  "mcpServers": {
    "ebaolife": {
      "command": "node",
      "args": ["/absolute/path/to/ebaolife/index.js"],
      "env": {
        "YIBAO_APP_ID": "your_app_id",
        "YIBAO_APP_KEY": "your_aes_key"
      }
    }
  }
}

使用

配置完成后，在 AI 编程工具中直接对话：

帮我写一个接单的接口对接代码（Java）

AI 会自动：

1. 调用 o2o_accept 工具测试接口
2. 拿到真实返回结构
3. 生成正确的 Java 集成代码（含鉴权签名）

环境变量

默认使用测试环境

开箱即用，默认连接亿保测试环境，方便集成开发与测试。切换生产环境只需设置对应的 *_BASE_URL。

凭证（必填）

| 变量 | 必填 | 说明 | |------|------|------| | YIBAO_APP_ID | O2O 是 | 亿保提供的 app_id | | YIBAO_APP_KEY | O2O 是 | AES 签名密钥（测试服：123456） | | YIBAO_DP_UN | 直付是 | 直付用户名 | | YIBAO_DP_PW | 直付是 | 直付密码（明文，MCP Server 自动 MD5） |

后端系统地址（选填，默认测试环境）

亿保有三套后端系统：

| 系统 | 用途 | 测试地址（默认） | 生产地址 | 涉及接口 | |------|------|-----------------|----------|----------| | O2O | 门店对接（订单、商品、库存、流水） | https://facade-yyb-erp.test.ebaoyf.com | https://facade-yyb-erp.ebaoyf.com | 17 个 O2O 接口 | | CASH | 收银系统（交易询问、收银、冲正、网药消费） | https://cash.test3.ebaolife.net | https://www.ebaolife.net | 4 个直付接口 |

对应的环境变量：

| 变量 | 默认值 | |------|--------| | YIBAO_O2O_BASE_URL | https://facade-yyb-erp.test.ebaoyf.com | | YIBAO_CASH_BASE_URL | https://cash.test3.ebaolife.net |

切换生产环境示例：

{
  "env": {
    "YIBAO_O2O_BASE_URL": "https://facade-yyb-erp.ebaoyf.com",
    "YIBAO_CASH_BASE_URL": "https://www.ebaolife.net"
  }
}

调试与 Mock

| 变量 | 默认 | 说明 | |------|------|------| | YIBAO_MOCK | 否 | true 时路由到本地 Prism Mock | | YIBAO_MOCK_O2O_PORT | 4010 | Mock O2O 端口 | | YIBAO_MOCK_CASH_PORT | 4011 | Mock CASH 端口 | | YIBAO_DEBUG | 否 | true 时输出请求/响应详情到 stderr |

Mock 模式

开发阶段无需真实凭证，使用 Mock 模式：

1. 启动 Mock 服务器：

cd ../openapi
./start-mock.sh

2. 配置 MCP Server 使用 Mock：

{
  "env": {
    "YIBAO_MOCK": "true",
    "YIBAO_APP_ID": "test_app_id",
    "YIBAO_APP_KEY": "test_aes_key",
    "YIBAO_DP_UN": "test_user",
    "YIBAO_DP_PW": "test_pass"
  }
}

3. AI 调用工具时，请求会路由到本地 Prism Mock，返回模拟数据。

可用工具

O2O 接口（17 个工具）

| 工具名 | 说明 | 方法 | |--------|------|------| | o2o_accept | 接单 | POST /order/accept | | o2o_refuse | 拒单 | POST /order/refuse | | o2o_refund | 退单 | POST /order/refund | | o2o_express | 发货/配送 | POST /order/express | | o2o_express_cancel | 取消配送 | POST /order/express/cancel | | o2o_arrived | 送达确认 | POST /order/{order_no}/arrived | | o2o_store_orders | 查询门店订单 | GET /store/{erp_store_id}/orders | | o2o_product_stock | 更新商品库存价格 | POST /product/stock | | o2o_product_import | 查询导入批次 | GET /product/import | | o2o_product_import_create | 导入商品 | POST /product/import | | o2o_product_delete | 删除商品 | POST /product/delete | | o2o_product | 查询门店商品 | GET /product/{erp_store_id} | | o2o_store_business | 门店营业状态 | POST /store/{erp_store_id}/business | | o2o_company_stock | 查询公司库存 | POST /company/stock | | o2o_company_store_flow | 查询门店流水 | POST /company/store/flow | | o2o_company_store_flows | 批量查询流水 | POST /company/store/flows | | o2o_state_change | 订单状态变更 | POST /order/state/change |

直付接口（4 个工具）

| 工具名 | 说明 | 方法 | |--------|------|------| | directpay_querySwipeAmount | 交易询问 | POST /interface/querySwipeAmount | | directpay_chargeWithoutDetail | 收银 | POST /interface/chargeWithoutDetail | | directpay_cancel | 冲正退货 | POST /interface/cancel | | directpay_pay | 网药消费 | POST /pay.php |

资源（Resources）

AI 可随时读取以下资源：

| URI | 说明 | |-----|------| | yibao://specs/o2o | O2O API 完整 OpenAPI 规范 | | yibao://specs/direct-pay | 直付 API 完整 OpenAPI 规范 | | yibao://docs/quickstart | 集成快速入门指南 |

鉴权说明

MCP Server 内置鉴权，AI 不需要处理签名细节：

O2O 鉴权

• 请求头：app_id、timestamp、sign
• 签名算法：sign = AES-ECB(queryString + timestamp, appKey) → 大写 HEX
• queryString 由请求参数按 key 排序拼接

直付鉴权

• 请求体字段：un（用户名）、pw（MD5 密码）
• MCP Server 自动注入并 MD5 加密

客户使用示例

配置好 MCP Server 后，客户在 AI 编程工具中的典型对话：

场景 1：生成集成代码

> 帮我写一个 O2O 接单的 Java 集成代码

AI: [调用 o2o_accept 工具测试接口]
    [拿到返回 {rc:0, msg:..., data:...}]
    [生成完整的 Java 代码，含 HTTP 调用、AES 签名、错误处理]

场景 2：调试接口

> 接口报错了，帮我看看 /order/refund 的参数对不对

AI: [调用 o2o_refund 工具，用客户的参数]
    [发现 erp_store_id 是必填字段但没传]
    [提示客户补上，并生成修正后的代码]

场景 3：批量生成

> 帮我把 O2O 所有订单操作接口都生成 Python SDK

AI: [读取 yibao://specs/o2o 资源]
    [逐个调用工具验证]
    [生成完整的 Python SDK 包]

技术细节

• MCP 协议版本：2024-11-05
• 传输方式：stdio（标准输入输出）
• OpenAPI 版本：3.1.0
• 运行时：Node.js 18+
• 依赖：@modelcontextprotocol/sdk、js-yaml

目录结构

ebaolife/
├── index.js              # MCP Server 主程序
├── package.json
├── test.js               # 测试脚本
├── specs/
│   ├── o2o.yaml          # O2O OpenAPI 规范
│   └── direct-pay.yaml   # 直付 OpenAPI 规范
├── config-examples/
│   ├── claude-code.json  # Claude Code 配置示例
│   ├── cursor.json       # Cursor 配置示例
│   ├── trae.json         # Trae 配置示例
│   └── mock-mode.json    # Mock 模式配置示例
└── README.md