# MCP Gateway

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

通过一份 YAML 配置文件或运行时动态注册，自动将内部系统的 API 注册为 [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 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**：完整类型支持，易于扩展

## 快速开始

### 安装

```bash
pnpm install
pnpm build
```

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

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

```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 工具动态注册系统：

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

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

### 接入 AI 客户端

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

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

### 开发模式

```bash
pnpm dev
```

### 指定配置文件

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

## 认证方式

### SSO (OAuth2 Authorization Code + PKCE)

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

```yaml
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 刷新。

```yaml
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。

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

### Playwright 交互式登录

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

```yaml
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