apifox-write-mcp

A Model Context Protocol (MCP) server for importing OpenAPI documents to Apifox projects.

Overview

This MCP server provides tools for importing OpenAPI 3.0 specifications into Apifox projects. It validates OpenAPI documents, handles configuration management, and communicates with the Apifox API to perform imports.

Features

• OpenAPI 3.0 document validation
• Configurable import options
• Error handling and retry logic
• MCP protocol compliance
• Python 3.12+ support
• Async/await support

Installation

# Using uv (recommended)
uv sync

# Or using pip
pip install -e .

Run Without Installing (uvx)

After publishing to PyPI (or from a local path), you can run the server with uvx:

# From PyPI
uvx --from apifox-write-mcp apifox-write-mcp

Configuration

Set the following environment variables or create an apifox.config.json file:

Environment Variables

export APIFOX_PROJECT_ID="your-project-id"
export APIFOX_ACCESS_TOKEN="your-access-token"
export APIFOX_BASE_URL="https://api.apifox.com"  # Optional
export LOG_LEVEL="2"  # Optional: 0=ERROR, 1=WARN, 2=INFO, 3=DEBUG

Configuration File

Create apifox.config.json in your project root:

{
  "projectId": "your-project-id",
  "accessToken": "your-access-token",
  "baseUrl": "https://api.apifox.com",
  "apiVersion": "v1",
  "retryAttempts": 3,
  "timeout": 30000
}

Usage

As MCP Server

Run the server:

# Installed console script
apifox-write-mcp

# Or module execution
python -m apifox_write_mcp

# Or legacy (repo-only) entrypoint
python main.py

The server will listen on stdio for MCP protocol messages.

MCP Tool: import_openapi_to_apifox

Import an OpenAPI document to Apifox:

Parameters:

• document (required): OpenAPI document as JSON string
• options (optional): Import configuration options
  • targetEndpointFolderId: Target folder ID for endpoints
  • targetSchemaFolderId: Target folder ID for schemas
  • endpointOverwriteBehavior: How to handle existing endpoints (OVERWRITE_EXISTING, AUTO_MERGE, KEEP_EXISTING, CREATE_NEW)
  • schemaOverwriteBehavior: How to handle existing schemas
  • updateFolderOfChangedEndpoint: Whether to update folder of changed endpoints
  • prependBasePath: Whether to prepend base path
  • targetBranchId: Target branch ID
  • moduleId: Target module ID

Project Structure

.
├── apifox_write_mcp/
│   ├── client/          # Apifox API client
│   ├── config/          # Configuration management
│   ├── services/        # Import service orchestration
│   ├── types/           # Type definitions and error classes
│   ├── utils/           # Logging and error handling utilities
│   ├── validator/       # OpenAPI document validation
│   └── server.py        # MCP server entrypoint (console script)
├── main.py              # Legacy wrapper entrypoint
├── pyproject.toml       # Project configuration
└── README.md           # This file

Development

Running Tests

# Install dev dependencies
uv sync --dev

# Run tests
pytest

Code Structure

The project follows a modular architecture:

1. Types (apifox_write_mcp/types/): Data models and error definitions
2. Utils (apifox_write_mcp/utils/): Logging and error handling
3. Config (apifox_write_mcp/config/): Configuration management
4. Validator (apifox_write_mcp/validator/): OpenAPI document validation
5. Client (apifox_write_mcp/client/): HTTP client for Apifox API
6. Services (apifox_write_mcp/services/): Import workflow orchestration
7. Server (apifox_write_mcp/server.py): MCP server implementation

Migration from TypeScript

This is a Python port of the TypeScript implementation located in the ts/ directory. The main differences:

• Uses httpx instead of axios for HTTP requests
• Uses Python's native asyncio instead of Node.js promises
• Uses dataclasses instead of TypeScript interfaces
• Uses Python's logging module concepts adapted for structured logging

License

See the TypeScript implementation for license information.