airouting-mcp

AI Routing 后台管理的 MCP server。覆盖两类能力：

• 通用资源 CRUD：对 平台 / 分组 / 账户 / 组织 / 渠道 / 套餐 / 代理 七个资源各提供「增删改查」五个工具（共 35 个）。
• 专项工具与流程：平台模型映射、账号 OAuth / API Key 授权建号、批量建代理、IP 质量检测报告、套餐复制与售卖统计，以及两条可一键唤起的编排 Prompt。
• 问题排查 / 诊断（只读）：账号为何挂、用户（邮箱）为何调用异常、整站故障盘点三个一键诊断,加 Ops / SLA 底层查询。

支持多组账号配置（profile），按 profile 各自登录与会话续期。

安装

pnpm add -g airouting-mcp
# 或在 MCP 客户端里用 pnpm dlx 直接拉起

配置

在工作目录创建 .airouting.json，顶层是「profile 名 → 账号配置」的映射（参考 .airouting.example.json，值全部用占位符，按需替换）：

{
  "prod": {
    "baseUrl": "https://your-airouting-host.com",
    "email": "[email protected]",
    "password": "your-password"
  },
  "staging": {
    "baseUrl": "https://staging.your-airouting-host.com/api/v1",
    "email": "[email protected]",
    "password": "your-password"
  }
}

• baseUrl：站点地址或完整 API base。填 https://host 会自动补 /api/v1；已含 /api/vN 则原样使用。
• email / password：管理员登录凭据（username 可作 email 别名）。server 启动后首次调用时自动登录，token 临近过期自动 refresh，401 自动重登。
• 开启了两步验证（2FA）的账号暂不支持。

配置文件路径解析优先级：--config <path> 参数 → AIROUTING_CONFIG 环境变量 → 当前目录 .airouting.json。

⚠️ 凭据安全（务必）

• .airouting.json 内含明文 baseUrl / 邮箱 / 密码，已在 .gitignore 中——切勿提交。仓库内只保留占位符的 .airouting.example.json。
• 批量授权用的清单文件（如 accounts.batch.yaml）会写入 API Key、代理账密、回调 code 等敏感信息，同样不要提交、不要外发。
• 账号授权类工具（account_oauth_* / account_apikey_create）的返回里包含 token / credentials 明文，仅用于即时建号，不要落盘到会被分享的位置。

在 MCP 客户端注册

{
  "mcpServers": {
    "airouting": {
      "command": "pnpm",
      "args": ["dlx", "airouting-mcp", "--config", "/abs/path/.airouting.json"]
    }
  }
}

不传 --config 时，会读运行目录下的 .airouting.json。

工具

1. 资源 CRUD（7 资源 × 5 = 35 个）

命名 <资源>_<动作>：

| 资源 | 工具 | |---|---| | 平台 platform | platform_list platform_get platform_create platform_update platform_delete | | 分组 group | group_list group_get group_create group_update group_delete | | 账户 account | account_list account_get account_create account_update account_delete | | 组织 organization | organization_list organization_get organization_create organization_update organization_delete | | 渠道 channel | channel_list channel_get channel_create channel_update channel_delete | | 套餐 plan | plan_list plan_get plan_create plan_update plan_delete | | 代理 proxy | proxy_list proxy_get proxy_create proxy_update proxy_delete |

公共参数

• profile（可选）：用哪套配置。只有一个 profile 时可省略；多个时必须指定。
• fields（可选，所有工具支持）：输出裁剪——只保留结果（列表则是每条记录）的指定顶层字段。查列表只为拿 ID 时务必用它，如 fields: ["id","name"]；分页元信息不受影响。
• _list：page、page_size、filters（过滤对象，可用键见各工具描述）。
• _get / _delete：id。
• _create：data（请求体对象）。
• _update：id + data（部分更新）。

data / filters 为直通对象——字段直接对应后端请求体，各工具 description 里列了必填项与常用可选项。

输出处理

所有工具的返回统一经过：fields 投影 → 剔除 null / 空字符串字段 → 紧凑序列化（无缩进）→ 超长截断（超 5 万字符截断并提示用 page_size / filters / fields 缩小查询）。

2. 平台模型映射（6 个）

| 工具 | 作用 | |---|---| | platform_model_list | 列平台下的模型 | | platform_model_upsert | 新增 / 覆盖模型 | | platform_model_update | 改单个模型 | | platform_model_delete | 删模型 | | platform_model_mapping_list | 列模型映射 | | platform_model_mapping_replace | 全量替换模型映射 |

3. 账号授权建号

两种授权方式，三家通吃（provider: anthropic / openai / gemini）：

| 工具 | 方式 | 说明 | |---|---|---| | account_oauth_start | OAuth 第 1 步 | 生成授权链接，返回 { auth_url, session_id, state? } | | account_oauth_exchange | OAuth 第 2 步 | 用回调 code 换 token，并自动建号 | | account_apikey_create | API Key 直填 | api_key(+ 可选 base_url，gemini 可选 tier_id) 原样作 credentials 直接建号 |

• OAuth：start 拿链接 → 真人浏览器授权、只复制 code → exchange 换码建号。proxy_id 在 start / exchange / 建号三处贯穿（代理↔账号 1:1，不可复用）。
  • anthropic：换码只需 code。
  • openai：换码需 code + auth_url（state 嵌在其中，工具自动解析）。
  • gemini：start 前先选 oauth_type + tier_id（+ 可选 project_id）；start 返回 state，换码需 code + state + oauth_type。
• API Key：直填型，无授权链接 / 无换码 / 无 token 交换。gemini 的 tier_id 仅 aistudio_free / aistudio_paid。

4. 代理扩展（3 个）

| 工具 | 作用 | |---|---| | proxy_create_batch | 一次创建多条代理，并按 name 反查回填生成的 ID | | proxy_quality_check | 检测单个代理的 IP 质量，返回后端原始检测结果 | | proxy_quality_report | 批量检测 IP 质量并输出汇总报告（不传 ids 则测全部活跃代理，默认并发 5） |

5. 套餐扩展（3 个）

| 工具 | 作用 | |---|---| | plan_duplicate | 复制套餐，生成同配置的新套餐 | | plan_purchases | 分页列出某套餐的购买记录（购买组织、额度、状态等） | | plan_summary | 套餐汇总统计：订阅/按量上架数与售出数、下架数、总营收 |

套餐分两类：subscription（订阅，月额度 + 有效月数）和 topup（按量加购，充值额度 + 赠送额度 + 有效期天数）。类型创建后不可修改。

6. 问题排查 / 诊断（只读）

把后台 Ops（运维）与 SLA 监控端点编排成可一句话触发的诊断工具。全部只读，不做任何处置写操作（清错误 / 重试等不在本板块）。

编排型一键诊断（内部串联多端点直接出结论，附轻量排查提示 hints）：

| 工具 | 回答的问题 | 编排内容 | |---|---|---| | account_diagnose | 某账号为什么挂了 | 账号详情与状态 + 今日统计 + 账号可用性 + 错误归因（按账号 / 按错误码）+（若绑定代理）IP 质检 | | user_diagnose | 某用户（邮箱）为什么调用异常 | 邮箱定位 user_id → 用户详情 + 该用户请求错误明细 + 用量 + 订阅/额度 | | platform_health | 整站现在哪里有故障 | 运维概览 + SLA 概览（按业务语义分类的错误计数）+ 错误分布/趋势 + 错误归因（错误码/账号/模型三维）+ 异常账号清单 |

底层只读查询（一对一封装，供自由组合排查）：

| 工具 | 作用 | |---|---| | ops_request_errors | 请求错误明细（支持 user_id / api_key_id 过滤） | | ops_error_list / ops_error_get | 错误日志列表 / 单条详情（with_retries 可带重试记录） | | ops_upstream_errors | 上游错误列表 | | ops_account_availability | 全部账号可用性概览 | | ops_concurrency / ops_user_concurrency | 并发统计 / 用户维度并发 | | ops_dashboard | 运维仪表盘（kind: overview / snapshot / error-distribution / error-trend） | | sla_overview | SLA 概览：可用率 + 按业务语义分类的 error_breakdown | | sla_error_attribution | 错误归因（dimension: status_code / account / model / user / type） | | user_search | 按邮箱/关键词搜用户，返回 [{ id, email }] |

诊断窗口参数 period 取 1h / 6h / 24h / 7d；platform 可选 anthropic / openai / gemini / antigravity。

Prompts（编排流程）

两条 MCP Prompt，在 Claude Code 里以 slash 命令唤起，正文随项目内 prompts/*.md 实时更新：

| 命令 | 作用 | |---|---| | /mcp__airouting__account_batch_authorize [doc] [stage] [profile] | 文档驱动的批量「建代理 → OAuth 授权 → 建号」，可断点续跑，失败行跳过并汇总后重走 | | /mcp__airouting__routing_bind "<自然语言绑定需求>" [profile] | 分组 / 渠道 / 组织 的创建与绑定（加入组、组入渠道、渠道绑组织），按需即兴组合 |

开发

pnpm install
pnpm build      # tsc → dist/
pnpm dev        # tsx 直接跑 src/cli.ts

端点对照

七个资源端点形态统一，挂在 /admin/* 下：

list    GET    /admin/<resource>            ?page&page_size&<filters>
get     GET    /admin/<resource>/{id}
create  POST   /admin/<resource>
update  PUT    /admin/<resource>/{id}
delete  DELETE /admin/<resource>/{id}

（<resource> = platforms / groups / accounts / organizations / channels / plans / proxies）

授权类专项端点：

OAuth   POST /admin/accounts/generate-auth-url · /admin/accounts/exchange-code      (anthropic)
        POST /admin/openai/generate-auth-url   · /admin/openai/exchange-code        (openai)
        POST /admin/gemini/oauth/auth-url      · /admin/gemini/oauth/exchange-code  (gemini)
APIKey  POST /admin/accounts                   (credentials 直填)
Proxy   POST /admin/proxies/batch              (批量)