8.3 KiB

Raw Blame History

name	description
apifox-mcp	Reads OpenAPI Spec from Apifox project for API-driven code generation. Use when defining interfaces, implementing declareRequest, generating API client code, or when the user mentions Apifox, API documentation, or OpenAPI specs.

Apifox MCP 工具

通过 apifox-mcp-server 将 Apifox 项目中的 OpenAPI Spec 提供给 AI，用于按接口文档生成代码、实现 declareRequest、定义请求模型等。

数据源优先级（必读）

回答某条接口的字段、类型、结构，或据此写代码时：

先用本地契约：根据 path + HTTP 方法 按下文规则算出 <operation-folder>，检查项目根目录是否存在 .api/<operation-folder>/spec.json 与 type.d.ts。
若两者皆存在：不得为此接口调用 Apifox MCP（read_project_oas_* / read_project_oas_ref_resources_* / refresh_project_oas_*）。直接用 Read 等工具读取上述文件，向用户说明内容或据此生成代码即可。
仅在下述情况才调用 MCP：
- 本地无对应目录，或缺少 spec.json / type.d.ts 之一；
- 用户 明确要求 与 Apifox 同步 / 刷新 / 更新 / 对齐最新文档（或同义表述）；
- 用户点名要从 Apifox / OpenAPI 源拉取（而非使用仓库内 .api）。
MCP 拉取或修正接口后：按「.api 本地契约目录」回写或新建 spec.json 与 type.d.ts，供下次走规则 1–2。

Apifox `int64` 与 Java `Long`（前端精度，必读）

Java Snowflake / 分布式 Long 主键 常超出 Number.MAX_SAFE_INTEGER（2^53−1）。Apifox 从后端导入时往往把 Long 标成 OpenAPI 的 integer + format: int64，容易和「前端用 number / Number(x)」混在一起，导致 ID 在 JS 里被静默改值。

落盘 .api 与写业务代码时：

不要用 Number()、parseInt 清洗仅用于透传的 主键、外键类 Long ID，除非你已确认值必然在安全整数范围内且后端只接受数字 JSON。
优先在 spec.json / type.d.ts 里把这类字段写成 string（或与后端约定的字符串形态），并在 description 里注明「后端 Long / Apifox 显示 int64；前端按字符串保证精度」。这样仓库内契约与实现一致，也不会误导后续只读 OpenAPI 的自动化生成。
若 Apifox 源 Spec 仍为 integer/int64，以 本仓库 .api 校正后的类型 为协作准绳；需要与文档门户完全一致时，再在 Apifox 里改模型或注明字符串序列化策略。

触发场景

默认：用户问某接口详情或要对接实现时，若 .api 已有契约 → 只读本地文件，不触发 MCP。
需调用 MCP 时：本地无契约、不完整，或用户要求 同步 Apifox / 刷新 Spec；或用户明确要对照线上 OpenAPI。
其余：实现 declareRequest、表格列、表单字段、路径与参数说明等，在有本地契约时均以 .api 为准。

核心工具

调用前需查阅 mcps/user-apifox/tools/*.json 获取当前项目的工具名与参数 schema，工具名可能带项目后缀（如 _qzukxd）。

工具类型	用途	典型参数
`read_project_oas_*`	读取默认模块的 OpenAPI Spec 完整内容	无必需参数
`read_project_oas_ref_resources_*`	读取 Spec 内 `$ref` 引用的子文件内容	`path`: 字符串数组，如 `["/paths/_get_pet.json"]`
`refresh_project_oas_*`	从服务器重新下载最新 Spec（Apifox 有更新时）	无必需参数

调用方式

使用 call_mcp_tool 调用，server 为 user-apifox：

{
  "server": "user-apifox",
  "toolName": "read_project_oas_qzukxd",
  "arguments": {}
}

读取 $ref 引用文件示例：

{
  "server": "user-apifox",
  "toolName": "read_project_oas_ref_resources_qzukxd",
  "arguments": {
    "path": ["/paths/_get_xxx.json", "/components/schemas/User.json"]
  }
}

典型流程

解析目标：确定接口 path、HTTP 方法，算出 <operation-folder>（见下文章节）。
本地命中：若 .api/<operation-folder>/ 下已有 spec.json 与 type.d.ts → 读这两个文件即完成，不写 MCP；向用户输出协议内容或继续写 src/api 等业务代码。
本地未命中或用户要求同步：再调用 read_project_oas_*（及按需 read_project_oas_ref_resources_*）解析 paths / components；必要时先 refresh_project_oas_*。
落盘：新建或更新 .api/<operation-folder>/spec.json 与 type.d.ts。
生成业务代码：按项目规范（declareRequest、jjb-common-lib http 等）在 src/api 等目录实现；类型可从 .api/.../type.d.ts 引用（纯 JS 项目可用 jsconfig.json 的 include；TS 项目配置 tsconfig.json 的 include / paths 使 .api 可被解析）

从 Apifox MCP 解析某条接口后，必须在仓库根目录维护并行结构，便于人机查阅、diff 与少刷 MCP。

目录结构

.api/
  <operation-folder>/
    spec.json    # OpenAPI 3.x 自包含片段（paths + 本接口涉及的 components.schemas）
    type.d.ts    # 与 spec 对齐的 TypeScript 声明（仅类型，不参与 declareRequest 逻辑）

`<operation-folder>` 命名规则

取 OpenAPI path，去掉首字符 /，其余 / 改为 -（kebab-case 路径段串联）。
末尾拼接 HTTP 方法小写：-get、-post、-put、-delete、-patch 等。

示例

path	method	目录名
`/ai/conversation/message/page`	GET	`ai-conversation-message-page-get`
`/ai/conversation/message/{id}`	GET	`ai-conversation-message-id-get`（若 Spec 中为字面量 `{id}`，文件夹名用字面量 `id`，与团队约定一致即可）

同一路径多方法时：每个方法单独一层目录（如 ...-get 与 ...-delete）。

`spec.json` 要求

顶层为合法 OpenAPI 3.x 文档最小子集：openapi、info（可简要说明同步来源）、paths（仅当前接口）、components.schemas（仅当前接口响应/请求体引用的模型）。
禁止使用未解析的 $ref 指向仓库外文件；从 MCP 取到的引用应 内联展开 或合并进本文件的 components.schemas。
info.version 可用 1.0.0；若 Apifox 有变更，以 更新 spec + type 为准。

`type.d.ts` 要求

导出 Query / Path / Body（按接口实际存在项）及 响应体 中与业务相关的类型；命名可与后端 CO/VO 一致，或与 spec.json 中 schema 标题一致。
字段可选性、枚举用注释标出合法取值，与 spec.json 保持一致。
integer / int64（尤其对应 Java Long 的主键/外键）：在 JS 侧若存在超大整数风险，本地契约与类型应使用 string，不得默认定为 number；见上文「Apifox int64 与 Java Long」。
文件顶部用简短注释标明 METHOD + path，并指向同目录 spec.json。

与 MCP 的配合

spec.json + type.d.ts 齐全时：视为权威快照，禁止仅为「再看一眼字段」而调用 MCP；以 Read 工具输出的本地文件为准。
例外：用户说 同步/刷新/对齐 Apifox，或本地缺一文件、或新接口尚未落盘 → 再调用 MCP，并回写两个文件。
新增接口：从 MCP 拉全量或按需拉 $ref 后，新建对应 <operation-folder>，勿与既有目录合并混淆。

最佳实践

先 .api 后 MCP：有齐套本地契约则不调用 MCP（见上文「数据源优先级」）。
调用 MCP 时先查 schema：阅读 mcps/user-apifox/tools/ 下对应工具 descriptor，确认 toolName 与 arguments。
同步意图：仅当用户要求或本地缺失时 refresh_project_oas_* / 读 Spec；通过后 必更新 spec.json 与 type.d.ts。
结合规范：生成接口代码时遵循项目 api-data-layer、11-接口与数据层规范 等技能

前置条件

mcp.json 中已配置 apifox，且 --site-id（或 --project-id）指向正确项目
私有部署需配置 APIFOX_ACCESS_TOKEN 或对应环境变量
Spec 数据本地缓存，Apifox 更新后需手动 refresh

8.3 KiB Raw Blame History Unescape Escape