MCP Gateway

统一认证网关 —— 让 AI 快速接入企业内部系统。

通过一份 YAML 配置文件或运行时动态注册，自动将内部系统的 API 注册为 MCP (Model Context Protocol) Tools，统一处理 SSO / JWT / 用户名密码 / Playwright 交互式认证，AI 客户端（Claude Desktop、Cursor 等）即装即用。

特性

配置驱动：新增系统只需编辑 systems.yaml，无需写代码
无状态模式：不写配置文件也能用，AI 客户端通过 system_register 工具运行时动态注册系统
四种认证：SSO (OAuth2 + PKCE)、JWT (自动刷新)、用户名密码 (Cookie 管理)、Playwright (浏览器交互式登录)
自动重认证：Token 过期自动刷新，401/403 自动重新登录
Playwright 浏览器登录：无 OAuth2 clientId、验证码/2FA/滑块等复杂场景，打开浏览器手动登录后自动复用会话
SSO 浏览器登录：OAuth2 系统自动打开浏览器，登录后回调自动完成
TypeScript：完整类型支持，易于扩展

快速开始

安装

pnpm install
pnpm build

方式一：配置文件预加载（传统模式）

编辑 src/config/systems.yaml，按示例添加你的内部系统：

systems:
  - name: my-system
    description: 我的内部系统
    baseUrl: https://app.example.com
    auth:
      type: sso          # sso | jwt | basic | playwright
      sso:
        authorizeUrl: https://sso.example.com/oauth2/authorize
        tokenUrl: https://sso.example.com/oauth2/token
        clientId: your-client-id
        scope: user_id
        callbackPort: 9527
    tools:
      - name: get_data
        method: GET
        path: /api/data
        description: 获取数据

方式二：无状态动态注册（推荐）

不创建任何配置文件，直接启动 Gateway，由 AI 客户端通过 MCP 工具动态注册系统：

# 无需 systems.yaml，直接启动
node dist/index.js

AI 客户端连接后，调用 system_register 工具传入系统配置 JSON 即可动态注册，使用完毕后调用 system_remove 注销。

接入 AI 客户端

在 Claude Desktop 的 claude_desktop_config.json 或 Cursor 的 MCP 设置中添加：

{
  "mcpServers": {
    "gateway": {
      "command": "node",
      "args": ["/path/to/mcp-gateway/dist/index.js"]
    }
  }
}

开发模式

pnpm dev

指定配置文件

MCP_GATEWAY_CONFIG=/path/to/your/systems.yaml node dist/index.js

认证方式

SSO (OAuth2 Authorization Code + PKCE)

适用于接入企业 SSO 的系统。首次调用时自动打开浏览器完成登录，Token 自动缓存和刷新。

auth:
  type: sso
  sso:
    authorizeUrl: https://sso.example.com/oauth2/authorize
    tokenUrl: https://sso.example.com/oauth2/token
    loginPortal: https://sso.example.com/login    # 可选：统一登录门户
    clientId: your-client-id
    scope: user_id
    callbackPort: 9527

JWT

适用于有独立登录 API 的系统。支持自动 Token 刷新。

auth:
  type: jwt
  jwt:
    loginUrl: https://api.example.com/auth/login
    refreshUrl: https://api.example.com/auth/refresh
    tokenField: access_token
    refreshField: refresh_token
    expiresIn: 3600

用户名密码

适用于传统 Web 系统。自动管理 Cookie/Session。

auth:
  type: basic
  basic:
    loginUrl: https://erp.example.com/api/login
    cookieName: SESSION_ID

Playwright 交互式登录

适用于没有 OAuth2 clientId、或登录流程复杂（验证码/2FA/滑块）的系统。首次登录打开浏览器让用户手动操作，登录后自动保存会话并复用。

auth:
  type: playwright
  playwright:
    loginUrl: https://sso.example.com/login        # 登录页 URL（必填）
    successUrl: dashboard                           # 登录成功标志（必填）
    probeUrl: https://app.example.com/api/profile  # 会话探测 URL（可选）
    expiresIn: 1800000                             # 会话有效期（默认 30 分钟）
    channel: chrome                                 # 使用系统 Chrome（可选，避免下载 Chromium）
    # script: ./scripts/login.ts                    # 可选：录制脚本自动登录，失败降级交互式

浏览器引擎说明（无需手动安装）：

默认使用 Playwright 内置 Chromium，首次运行时自动下载（约 150MB）
设 channel: chrome 直接使用系统已安装的 Chrome，无需下载
设 channel: msedge 直接使用系统已安装的 Edge，无需下载
设 executablePath 指定浏览器路径（优先级最高）

内置管理 Tool

认证管理

Tool	说明
`auth_status`	查看所有系统的认证状态
`auth_login`	登录指定系统（SSO/Playwright 弹浏览器，JWT/Basic 传用户名密码）
`auth_logout`	登出指定系统或所有系统

系统管理（无状态模式）

Tool	说明
`system_register`	动态注册系统及 API 工具，传入系统配置 JSON
`system_list`	列出所有已注册系统的名称、类型、工具列表和认证状态
`system_remove`	注销指定系统，移除其所有工具和认证信息

项目结构

src/
├── index.ts              # MCP Server 入口 + Tool 注册
├── system-manager.ts     # 动态系统注册/注销 + 工具增删管理
├── config/
│   ├── systems.yaml      # 系统配置（可选，无状态模式不需要）
│   ├── types.ts          # 类型定义
│   └── loader.ts         # 配置加载（无配置时返回空列表）
├── auth/
│   ├── types.ts          # AuthProvider 接口
│   ├── sso-provider.ts   # OAuth2 SSO 认证
│   ├── jwt-provider.ts   # JWT 认证 + 自动刷新
│   ├── basic-provider.ts # 用户名密码认证
│   ├── playwright-provider.ts # Playwright 交互式登录
│   └── manager.ts        # 统一认证管理
└── proxy/
    └── requester.ts      # HTTP 请求 + 凭据注入 + 自动重认证

License

MIT