apifox-url-mcp

按 URL 直查 Apifox 接口的 MCP server：调用 Apifox 内部 export/openapi 端点的 apiDetailId 模式做单接口精准导出，输出干净的 OpenAPI 3.0 YAML，不全量拉取项目。

安装

apifox-url-mcp 是一个 MCP server，无需手动装包或写配置文件——把下面的 prompt 发给 Claude Code，让它自己把连接配好即可。分两步：A 段配好 MCP 连接，B 段绑定到具体项目。

APIFOX_TOKEN 在 Apifox 个人头像 → 账号设置 → API 访问令牌创建。

A 段：配好 Apifox MCP 连接

把下面整段发给 Claude Code，并先把 afxp_xxx 换成你自己的 Apifox API 访问令牌。

你的任务：在本机为 Claude Code 配置好 Apifox 的 MCP server，配完要能正常调用。

## 背景
- 用的包是 apifox-url-mcp（URL 版，不是官方 apifox-mcp-server），通过 Apifox 文档链接取数据。
- 鉴权用环境变量 APIFOX_TOKEN，值为：afxp_xxx

## 要做的事
1. 先查现状：运行 `claude mcp list`，看是否已存在名为 apifox 的 server。已存在就先 `claude mcp remove apifox` 删掉，避免重复或旧配置干扰。
2. 添加（user 作用域，全局可用）：
   claude mcp add-json apifox --scope user '{"type":"stdio","command":"npx","args":["-y","apifox-url-mcp@latest"],"env":{"APIFOX_TOKEN":"afxp_xxx"}}'

## 验收（必须做）
- 运行 `claude mcp list`，确认 apifox 状态为 ✓ Connected。
- 失败就检查 token 是否正确写入、启动器是否在 PATH 里，把报错原样贴出来，不要静默跳过。

完成后用一句话汇报：配好了没、连接状态如何。注意此时只是连接就绪，还没绑定具体项目。

B 段：给定 projectId 后配好项目

在 <在此填入你的 projectId> 处填上目标项目的 projectId，再把整段发给 Claude Code。

你的任务：把 Apifox MCP 绑定到指定项目，绑定后要能直接查到接口。

## 前提
- Apifox MCP（名为 apifox）已配置且连接正常。若未就绪，先停下提示我去配。
- 目标项目 projectId：<在此填入你的 projectId>

## 要做的事
1. 调用 list_project_meta(projectId=<上面的projectId>)，拿到该项目的分支（branches）和模块（modules）列表。
2. 调用 init_project，把 projectId 以及选定的 branchId/moduleId 持久化到当前目录的 .apifox.json。
   - 分支默认选 isMain=true 的主分支；模块如无特别要求选第一个或全部。
3. 调用 list_apis 拉一次接口列表，确认能取到数据。

## 验收（必须做）
- .apifox.json 已生成，内含正确的 projectId。
- list_apis 返回了非空的接口索引；若为空或报错，原样贴出报错，不要静默跳过。

完成后用一句话汇报：绑定了哪个项目、主分支是哪个、共取到多少个接口。

项目配置：.apifox.json

MCP server 启动时读取启动目录（cwd）下的 .apifox.json。

{
  "projectId": 123456,
  "moduleId": 234567,
  "branchId": 345678
}

可直接提交 git（不含 token）。

推荐：用 projectId 一步初始化（0.3.0+）

不必再手抄 moduleId / branchId。只要有 projectId，让模型调 init_project 即可自动发现分支/模块并写好 .apifox.json：

• 想先看有哪些分支/模块再挑 → 调 list_project_meta（传 projectId），它返回 branches[] + modules[]；
• 选定后调 init_project（带上选中的 branchId/moduleId）写盘；
• 懒人模式：直接调 init_project 只给 projectId（甚至启动时已通过 --project-id 注入则零参数），自动选主分支（isMain）+ 默认模块（type=DEFAULT）并落盘。

0.3.0 起，缺 .apifox.json 且未传 --project-id 不再直接退出，而是允许运行时通过 init_project 用 projectId 初始化。

参数优先级

tool input > --project-id CLI 参数 > .apifox.json > 报错

CLI 参数

| 参数 | 说明 | |---|---| | --project-id | 全局默认项目 id | | --module-id | 模块 id | | --branch-id | 分支 id | | --api-base-url | 默认 https://api.apifox.com（私有化部署改这里） | | --cache-ttl | 索引缓存有效期（分钟，默认 60） | | --tool-suffix | 工具名后缀，多项目并存时用 | | --client-version | x-client-version 请求头值（默认 2.8.28-alpha.1，也可用 APIFOX_CLIENT_VERSION 环境变量覆盖） | | --open-api-version | 官方公开 API 的 X-Apifox-Api-Version 头（默认 2024-03-28，供 update_api 用；也可用 APIFOX_OPEN_API_VERSION 覆盖） |

工具

| 名称 | 说明 | |---|---| | lookup_api | 按 {method, path} 或 url 查单接口，返回 YAML。/users/123 自动匹配 /users/{id} | | list_apis | 列轻索引（支持 keyword / tag / limit） | | export_apis | 批量传 [{method, path}]，合并导出 | | refresh_index | 强制重拉 api-tree-list 缓存 | | list_project_meta | 传 projectId，列出项目的 branches[]（含 isMain）+ modules[]（含 type），供选择 | | init_project | 传 projectId（可选 branchId/moduleId/dir），写入 .apifox.json；缺省自动选主分支 + 默认模块 | | update_api | 写操作。传一份完整 OpenAPI 3.0 文档（openapi 字符串），按 path+method 匹配已有接口，覆盖/合并其定义——用来补全缺失的入参 / 出参。走 Apifox 官方公开 API | | add_api | 写操作。传 OpenAPI 3.0 文档新增接口；写入前先查重，命中已有接口则不写入并列出冲突，让你用 onConflict 决定。走 Apifox 官方公开 API |

更新接口（update_api）

用于给已有接口补齐 / 修正入参、出参（写接口定义的两个工具之一，另一个是新增用的 add_api）：

1. 先用 lookup_api 拉到该接口当前的 YAML；
2. 在其中补上缺失的 parameters / requestBody / responses（及引用到的 components.schemas）；
3. 把这份完整的 OpenAPI 文档作为 openapi 传给 update_api。

接口按 method + path 与项目中已有接口匹配，行为由 endpointOverwriteBehavior 决定：

| 值 | 含义 | |---|---| | OVERWRITE_EXISTING（默认） | 覆盖：用你传的定义整体替换匹配到的接口，所以要传完整定义而非增量 | | AUTO_MERGE | 智能合并 | | KEEP_EXISTING | 保留原接口，跳过 | | CREATE_NEW | 总是新建接口 |

schemaOverwriteBehavior 同义，作用于数据模型（schema），默认同样 OVERWRITE_EXISTING。

该工具走 Apifox 官方公开 API（POST /v1/projects/{projectId}/import-openapi，带 X-Apifox-Api-Version 头），针对项目主分支生效；APIFOX_TOKEN 用同一个账号设置里的 API 访问令牌即可。

新增接口（add_api）

新增一个或多个接口。和 update_api 走同一个官方端点，但写入前会先查重:

1. 传一份完整 OpenAPI 3.0 文档（openapi），paths 里声明要新建的接口；
2. 工具先强制刷新索引，逐个 method + path 比对项目中是否已存在；
3. 若有冲突且未传 onConflict → 一行不写，返回冲突清单，让你决定;
4. 带上 onConflict 重新调用，或本就无冲突 → 直接创建。

onConflict 取值:

| 值 | 含义 | |---|---| | KEEP_EXISTING | 保留已有接口,只创建真正不存在的 | | OVERWRITE_EXISTING | 用你传的定义覆盖已有接口 | | CREATE_NEW | 一律新建（可能产生同 path+method 的重复接口） |

schemaOverwriteBehavior 默认 AUTO_MERGE(合并而非覆盖,保护公共数据模型)。同样针对主分支。

分支 / 模块作用范围

• branchId → 作为 x-branch-id 请求头，决定 api-tree-list 拉哪个分支的接口树。
• moduleId → api-tree-list 一次返回全模块接口（每条自带 moduleId），本包在收到数据后按配置的 moduleId 过滤，因此 lookup_api / list_apis / export_apis 只在该模块范围内匹配。未设 moduleId 时不过滤；项目接口未带 module 标记时自动跳过过滤，避免误清空。

缓存位置

~/.cache/apifox-url-mcp/tree-<projectId>[-<branchId>].json

Troubleshooting

400105 Client version too low

api-tree-list 400: {"success":false,"errorCode":"400105","errorMessage":"Client version too low"}

Apifox 服务端按 projectId 灰度推了一个新校验：请求头必须带 x-client-version，缺则 400105。本包 0.2.1+ 默认带上 2.8.28-alpha.1，正常情况下无需关心。

如果 Apifox 后续继续抬版本门槛，无需等本包发版，临时覆盖即可：

APIFOX_CLIENT_VERSION=2.9.0 npx apifox-url-mcp
# 或 CLI flag
npx apifox-url-mcp --client-version 2.9.0

值参考 web 端真实请求头（DevTools → Network → 任一 api/v1/* 请求 → Request Headers → x-client-version）。

License

MIT