┌──────────────────────────────────────────┐
  MCP 客户端         │              mcp-api-bridge              │        REST 客户端
  (Claude Desktop,  │                                          │        (curl, Postman,
   Cursor, Cline,   │   POST /mcp          Streamable HTTP      │         ChatGPT Actions,
   Agent, ...)  ────┼──►  /mcp/{source}    (MCP 协议)            │◄────   自研服务, ...)
                    │                                          │
                    │   GET  /openapi.json  自动生成的 API 文档  │
                    │   POST /api/{source}/{tool}  (REST 调用)  │
                    └───────────────┬──────────────────────────┘
                                    │
              ┌─────────────────────┴──────────────────────┐
              │                                            │
      MCP Server（stdio / Streamable HTTP / SSE）    OpenAPI / Swagger 服务（HTTP + JSON）

cp bridge.config.example.yaml bridge.config.yaml   # 然后按需修改
docker compose up -d --build
curl http://localhost:8080/health

docker build -t mcp-api-bridge:latest .

docker run -d --name mcp-bridge \
  -p 8080:8080 \
  -v "$PWD/bridge.config.yaml:/app/bridge.config.yaml:ro" \
  -v "$PWD/data:/app/data" \
  -e PUBLIC_BASE_URL=http://localhost:8080 \
  mcp-api-bridge:latest

docker run -d --name mcp-bridge -p 8080:8080 \
  -v "$PWD/bridge.config.yaml:/app/bridge.config.yaml:ro" \
  -v "$PWD/data:/app/data" \
  ghcr.io/dtyg123/mcp-api-bridge:latest

npm install
npm run build
node dist/src/index.js --config bridge.config.example.yaml

GET  /health                    健康检查
GET  /openapi.json              生成的 OpenAPI 文档（全部 REST 侧工具）
GET  /tools                     工具清单 + JSON Schema
POST /api/{source}/{tool}       调用工具（body = 工具参数）
GET  /api/{source}/{tool}       调用工具（query = 工具参数，适合简单工具）
POST /mcp                       聚合 MCP 端点（Streamable HTTP）
POST /mcp/{source}              单个来源的 MCP 端点
GET  /admin                     Web 管理台（添加来源 / 测试 / 生成接入提示词）
POST /admin/reload              重新加载 spec / 刷新上游工具列表
GET  /admin/api/credentials     认证信息列表（值已掩码）
POST /admin/api/credentials     新增 / 更新认证信息
GET  /admin/api/transforms      数据编排列表
PUT  /admin/api/transforms      保存某来源 / 接口的编排
POST /admin/api/transforms/preview   用示例响应试算编排（不保存）
GET  /admin/api/sources/:kind/:name/discover?tool=  探测某接口返回，递归列出可用字段路径（用于编排）

volumes:
  - ./bridge.config.yaml:/app/bridge.config.yaml:ro
  - ./data:/app/data

mcpServers:
  - name: filesystem
    transport:
      type: stdio
      command: npx
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/data"]
    exposure:
      rest: true      # 暴露成 REST
      mcp: true       # 同时在 /mcp 上暴露
      prefix: ""      # 工具名前缀

  - name: remote
    transport:
      type: http                       # 也支持 type: sse
      url: https://example.com/mcp
      headers:
        Authorization: Bearer ${REMOTE_MCP_TOKEN}

# POST：body 就是工具参数
curl -X POST http://localhost:8080/api/filesystem/read_file \
  -H 'content-type: application/json' \
  -d '{"path":"/data/notes.md"}'

# GET：参数放 query（仅当参数都是基础类型时）
curl 'http://localhost:8080/api/filesystem/read_file?path=/data/notes.md'

{
  "ok": true,
  "source": "filesystem",
  "tool": "read_file",
  "name": "filesystem__read_file",
  "isError": false,
  "text": "文件内容……",
  "data": "文件内容……",
  "content": [{ "type": "text", "text": "文件内容……" }],
  "meta": { "source": "filesystem", "tool": "read_file" }
}

apis:
  - name: petstore
    spec: https://petstore3.swagger.io/api/v3/openapi.json
    baseUrl: https://petstore3.swagger.io/api/v3    # 可选，覆盖 servers[0].url
    headers:
      User-Agent: mcp-api-bridge
    include: ["GET /pet/*"]      # 可选：只暴露部分操作，支持 * 通配
    exclude: ["DELETE /pet/*"]   # 可选：排除操作
    security:                    # 可选：按 securitySchemes 注入凭证
      ApiKeyAuth: { token: ${PETSTORE_KEY} }
      BearerAuth: { token: ${PETSTORE_TOKEN} }
      BasicAuth:  { username: admin, password: ${PETSTORE_PASS} }
    exposure:
      rest: true
      mcp: true
      prefix: ""

apis:
  - name: rainyun
    spec: https://api.rainyun.com/openapi.json       # Swagger 2.0，217 个操作
    security:
      ApiKey: { token: ${RAINYUN_API_KEY} }          # -> 请求头 X-Api-Key

{
  "mcpServers": {
    "bridge": {
      "type": "http",
      "url": "http://localhost:8080/mcp",
      "headers": { "Authorization": "Bearer <BRIDGE_MCP_TOKEN>" }
    }
  }
}

docker run -i --rm \
  -v "$PWD/bridge.config.yaml:/app/bridge.config.yaml:ro" \
  mcp-api-bridge:latest --stdio

{
  "mcpServers": {
    "bridge": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-v", "/abs/bridge.config.yaml:/app/bridge.config.yaml:ro", "mcp-api-bridge:latest", "--stdio"]
    }
  }
}

apis:
  - name: rainyun
    spec: https://api.rainyun.com/openapi.json
    credentialRefs: [rainyun]      # 引用「认证信息」里名为 rainyun 的凭证
    headers:                        # 显式请求头优先，同名（忽略大小写）只保留一份
      User-Agent: mcp-api-bridge

{
  "root": "data",
  "passthrough": false,
  "blocks": [
    { "op": "field", "from": "Title", "as": "title" },
    { "op": "field", "from": "TimeStamp", "as": "time" },
    { "op": "count", "from": "", "as": "total" },
    { "op": "now", "as": "fetchedAt", "format": "iso" }
  ]
}

{
  "ok": true,
  "source": "petstore",
  "tool": "get_news",
  "transformed": true,
  "data": {
    "title": "……",
    "time": "2026-10-04T09:52:13.654Z",
    "total": 10,
    "fetchedAt": "2026-11-01T04:08:37.457Z"
  }
}

server:
  host: 0.0.0.0
  port: 8080
  publicBaseUrl: ${PUBLIC_BASE_URL:-}   # 生成 /openapi.json 里的 servers[0].url
  basePath: ""                          # 全局路径前缀，例如 /bridge
  cors: true
  bodyLimit: 10mb
  auth:
    rest: ${BRIDGE_REST_TOKEN:-}        # /api、/openapi.json、/tools
    mcp: ${BRIDGE_MCP_TOKEN:-}          # /mcp、/mcp/{source}
  adminToken: ${BRIDGE_ADMIN_TOKEN:-}   # /admin 管理台与 /admin/api/**
  admin:
    enabled: true                       # false = 完全关闭管理台
    path: /admin
    storeFile: ./data/managed-sources.json   # 管理台新增的来源（相对配置文件目录）
    specsDir: ./data/specs                   # 「粘贴 OpenAPI 文档」的存放目录
  mcp:
    path: /mcp
    sessionMode: stateful               # stateful | stateless
    jsonResponse: false                 # true = 用 JSON 响应替代 SSE 流
  rest:
    path: /api

openapi:
  version: "3.1"                        # 3.1 | 3.0
  title: MCP Bridge API

logging:
  level: info                           # debug | info | warn | error
  format: text                          # text | json

--config <path>     配置文件（YAML/JSON），默认 ./bridge.config.yaml 或 $BRIDGE_CONFIG
--host <host>       覆盖 server.host
--port <port>       覆盖 server.port
--stdio             以 stdio 方式提供 MCP（本地客户端用）
--list-tools        连接上游、打印工具清单后退出（自检用）
--print-config      打印合并后的配置
--log-level <lvl>   debug | info | warn | error
--version / --help

npm install
npm run build      # 编译到 dist/
npm test           # 编译 + 运行 node:test（含端到端：真实 MCP stdio 上游 + 模拟 REST 上游）
npm run dev        # tsx watch

src/
  index.ts                 CLI 入口（HTTP / stdio / 自检）
  config.ts                配置加载、环境变量插值、校验
  registry.ts              来源与工具注册表（热重载、命名去重、降级保留）
  convert/
    openapi-to-tools.ts    OpenAPI 操作 → MCP 工具（参数映射 + 请求构造 + 响应转换）
    tools-to-openapi.ts    MCP 工具 → OpenAPI 文档
    schema.ts               JSON Schema 提升 / 3.0 降级 / 对象化
  openapi/
    resolve.ts             $ref 内联（本地 + 外部、JSON/YAML、循环检测）
    loader.ts              文档加载、baseUrl 解析
  upstream/mcp.ts          MCP 客户端（stdio / Streamable HTTP / SSE）
  mcp/gateway.ts           聚合 MCP Server（动态 tools/list + tools/call）
  admin/
    store.ts               来源持久化与热重载（managed-sources.json）
    credentials.ts         认证信息保险库（credentials.json）
    transforms.ts          数据编排积木引擎（transforms.json）
    service.ts             来源连通性测试
    prompts.ts             接入提示词生成
  http/
    server.ts             Express 路由、鉴权、REST/RPC 封装
    mcp-endpoint.ts       Streamable HTTP 会话管理（stateful / stateless）
test/                      单元测试 + 端到端测试