apifox-write-mcp 1.0.0
MCP server for importing OpenAPI documents to Apifox
Requires Python: >=3.12

# 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

```bash
# 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`:

```bash
# 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

```bash
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:

```json
{
  "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:

```bash
# 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

```bash
# 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.