Code To Apifox MCP

🚀 Code-to-ApiFox MCP Server

A Node.js-based MCP (Model Context Protocol) server dedicated to Swagger document generation and integration with the ApiFox platform.

✨ Features

• 🚀 Standard MCP Protocol Support - Fully compliant with the MCP protocol specification.
• 📝 Swagger Specification Generation - Provides standard Swagger JSON examples and best practices.
• 🔗 Seamless ApiFox Integration - Upload API documents to the ApiFox platform with a single click.
• 🔄 Dual-Mode Operation - Supports both STDIO and HTTP connection methods.
• 🌐 Ready for Cloud Deployment - Supports local development and production environment deployment.
• 🤖 Friendly to AI Assistants - Tool integration designed specifically for AI assistants.
• 🔐 Configuration File Management - Supports managing ApiFox credentials through a configuration file.

🚀 Quick Start

Global Installation (Recommended)

# Install globally
npm install -g code-to-apifox-mcp

# Use directly
code-to-apifox-mcp --stdio    # MCP client mode
code-to-apifox-mcp            # HTTP service mode

Temporary Use

# Run directly without installation
npx code-to-apifox-mcp --stdio
npx code-to-apifox-mcp

Local Development

# Clone the project
git clone https://github.com/xzg0919/code-to-apifox-mcp.git
cd code-to-apifox-mcp

# Install dependencies
npm install

# Run in development mode
npm run dev:stdio    # STDIO mode
npm run dev          # HTTP mode

💻 Usage Examples

1. MCP Client Integration (Recommended)

Configure in an AI assistant that supports MCP (e.g., Claude Desktop):

{
  "mcpServers": {
    "doc-mcp-server": {
      "command": "code-to-apifox-mcp",
      "args": ["--stdio"]
    }
  }
}

After configuration, you can use it directly in the AI assistant:

Get Swagger Specification:

Please help me get a Swagger specification example.

Upload Using Configuration File: If you create a code-to-apifox.json file in the project root directory:

Please help me upload the API document to ApiFox.
- Swagger JSON: {...}

Specify Parameters Manually:

Please help me upload the API document to ApiFox:
- Project ID: your-project-id
- Access Token: your-access-token
- Swagger JSON: {...}

2. HTTP API Calls

Start the HTTP service:

code-to-apifox-mcp  # Default port 3033

Get Swagger Specification Example

curl -X POST http://127.0.0.1:3033/tools/getSwaggerSpecification

Upload Document to ApiFox

curl -X POST http://127.0.0.1:3033/tools/uploadSwaggerToApiFox \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "your-project-id",
    "accessToken": "your-access-token",
    "swaggerJson": "your-swagger-json-string"
  }'

Health Check

curl http://127.0.0.1:3033/health

3. Programmatic Usage

Use directly in a Node.js project:

import { SwaggerUploadService } from 'code-to-apifox-mcp';

const config = {
  apifox: {
    api: {
      baseUrl: 'https://api.apifox.com',
      version: '2024-03-28'
    }
  }
};

const service = new SwaggerUploadService(config);

// Get Swagger specification
const spec = await service.getSwaggerSpecification();
console.log(spec);

// Upload to ApiFox
const result = await service.uploadSwaggerToApiFox(
  'project-id',
  'access-token', 
  'swagger-json'
);
console.log(result);

📚 Documentation

getSwaggerSpecification

Function: Get a standard Swagger JSON specification example.

Return: A Swagger specification containing a complete Petstore example, along with detailed usage instructions and best practice recommendations.

New: Instructions on using the code-to-apifox.json configuration file are included.

Use Cases:

• Learn the Swagger specification format.
• Use as an API document template.
• Understand best practices and precautions.

uploadSwaggerToApiFox

Function: Upload a Swagger JSON to the ApiFox platform.

Parameters:

• projectId (Required): ApiFox project ID.
• accessToken (Required): ApiFox access token.
• swaggerJson (Required): Complete Swagger JSON string.

Return: Upload result and detailed information.

🔧 Configuration Instructions

Default Configuration File (Recommended)

Create a code-to-apifox.json file in the project root directory to configure the default ApiFox project ID and access token:

{
  "projectId": "your-project-id",
  "accessToken": "your-access-token"
}

Advantages:

• 🔐 Avoid manually entering credentials every time.
• 🚀 Improve work efficiency.
• 📁 Support project-level configuration management.

Security Tip:

• ⚠️ Do not commit this file to the version control system.
• It is recommended to add it to the .gitignore file.

Application Configuration File

Configuration file location: config/config.json

{
  "app": {
    "name": "doc-mcp",
    "port": 3033
  },
  "apifox": {
    "api": {
      "baseUrl": "https://api.apifox.com",
      "version": "2024-03-28"
    }
  },
  "mcp": {
    "server": {
      "name": "doc-mcp-server",
      "version": "1.0.0",
      "instructions": "Swagger document generation and ApiFox integration tool"
    }
  }
}

🌐 Deployment Guide

Local Deployment

# Install globally
npm install -g code-to-apifox-mcp

# Start the service
code-to-apifox-mcp  # HTTP mode, port 3033

Cloud Server Deployment

# 1. Upload to the server
scp -r . user@your-server.com:/opt/doc-mcp/

# 2. Install and start on the server
ssh user@your-server.com
cd /opt/doc-mcp
npm install -g code-to-apifox-mcp

# 3. Run in the background
nohup code-to-apifox-mcp > mcp-server.log 2>&1 &

Docker Deployment

FROM node:18-alpine
RUN npm install -g code-to-apifox-mcp
EXPOSE 3033
CMD ["code-to-apifox-mcp"]

docker build -t doc-mcp .
docker run -p 3033:3033 doc-mcp

🔗 API Endpoints

When running in HTTP mode, the following endpoints are provided:

• GET /health - Service health check.
• GET /sse - MCP client SSE connection.
• POST /tools/getSwaggerSpecification - Get the Swagger specification.
• POST /tools/uploadSwaggerToApiFox - Upload to ApiFox.

🧪 Testing and Verification

# Run unit tests
npm test

# Test the HTTP service
curl http://127.0.0.1:3033/health

# Test tool functionality
npx code-to-apifox-mcp --stdio

📋 Environment Requirements

• Node.js: >= 18.0.0
• npm: >= 8.0.0
• Operating System: Windows, macOS, Linux

❓ Frequently Asked Questions

Q: How do I use a configuration file to manage ApiFox credentials?

A: Create a code-to-apifox.json file in the project root directory, containing the projectId and accessToken fields. This way, you don't need to enter credentials every time when using the uploadSwaggerToApiFox tool.

Q: Is the configuration file secure?

A: It is recommended to add code-to-apifox.json to the .gitignore file to avoid accidentally committing sensitive information to the version control system.

Q: How do I obtain the ApiFox project ID and access token?

A: Log in to ApiFox, and you can find the project ID and generate an access token in Project Settings -> Open API.

Q: Which Swagger versions are supported?

A: Swagger 2.0 and OpenAPI 3.0 formats are supported.

Q: How do I use it in an AI assistant?

A: After configuring the MCP client, you can directly describe your requirements in natural language, such as "Help me upload the API document to ApiFox".

Q: What if the port is occupied?

A: Modify the port number in config/config.json, or set the environment variable PORT=your-port.

🔗 Related Links

• GitHub Repository
• npm Package
• ApiFox Official Website
• MCP Protocol Documentation

If this tool is helpful to you, please give it a ⭐️ to show your support!