apifox

# Apifox MCP + CLI A tool for Apifox/OpenAPI documentation that supports both `MCP` and `CLI`. ## Development Installation The project uses `Yarn 3`. ```bash yarn install yarn build ``` Common development commands: ```bash yarn build yarn typecheck yarn lint ``` ## Source Types The tool supports three source types, choose one: - `--projectId` - `--siteId` - `--oas` Note: - Source parameters must be explicitly passed through the command line - Not supported through environment variables: `projectId`, `siteId`, `oas` ## Environment Variables Supports the following environment variables: - `APIFOX_ACCESS_TOKEN` - `APIFOX_API_BASE_URL` - `APIFOX_API_VERSION` - `APIFOX_API_PAGE_SIZE` - `APIFOX_DATA_LOCATION` Example: ```bash export APIFOX_ACCESS_TOKEN="your_access_token" export APIFOX_DATA_LOCATION="/tmp" ``` ## MCP Usage If a source parameter is already passed when starting, MCP will register a tool name with a suffix for easy distinction between multiple instances. Example: ```bash apifox-mcp --projectId=12345 apifox-mcp --siteId=abcde apifox-mcp --oas=https://petstore.swagger.io/v2/swagger.json ``` If no source parameter is passed when starting, MCP will register a tool name without a suffix: - `read_apifox_oas` - `read_apifox_oas_ref_resources` - `refresh_apifox_oas` - `get_apifox_cache_info` The schema of these tools will have `oneOf`, requiring one of the following to be passed when calling: - `projectId` - `siteId` - `oas` If a source parameter is passed when starting, the tool schema will no longer require duplicate source passing. ### MCP Configuration Example Using `projectId` as an example: ```json { "mcpServers": { "api-docs": { "command": "npx", "args": ["-y", "@acehubert/apifox-mcp@latest", "--projectId=12345"], "env": { "APIFOX_ACCESS_TOKEN": "your_access_token" } } } } ``` ## CLI Usage All CLI commands require explicit source parameter passing. ### View Documentation ```bash apifox oas view --projectId=12345 apifox oas view --siteId=abcde apifox oas view --oas=/tmp/openapi.json ``` ### Refresh Cache ```bash apifox oas refresh --projectId=12345 apifox oas refresh --oas=https://petstore.swagger.io/v2/swagger.json ``` ### Read `$ref` Resources ```bash apifox refs read \ --projectId=12345 \ --path=/paths/_users.json \ --path=/components/schemas/User.json ``` ### View Cache Information ```bash apifox cache info --projectId=12345 ``` The returned content includes: - `cacheDir` - `cacheFile` - `exists` - `source` - `lastUpdatedAt` ### CLI Help ```bash apifox --help apifox oas --help apifox refs --help apifox cache --help ``` ## Cache Behavior After pulling the documentation, a local cache will be generated, and the OpenAPI document will be split into: - Main index `index.json` - `paths/*.json` - `components/**/*.json` The `lastUpdatedAt` in `cache info` uses the modification time of the cache file `index.json`. ## Current Directory Convention - `skills/` is the project's internal skills source directory - `.claude/skills` is symlinked to `skills/` ## Notes - Reading `projectId` source requires a valid `APIFOX_ACCESS_TOKEN` - `siteId` and `oas` sources do not require a token - The `oas` suffix naming will be based on the input address or path to generate a stable hash