Code To Apifox MCP

🚀 Code-to-ApiFox MCP Server

一個基於Node.js的MCP（Model Context Protocol）服務器，專門用於Swagger文檔生成和ApiFox平臺集成。藉助該服務器，你可以輕鬆地將Swagger文檔上傳到ApiFox平臺，提高API文檔管理的效率。

✨ 主要特性

• 🚀 標準MCP協議支持：完全兼容MCP協議規範，確保與支持MCP的工具無縫對接。
• 📝 Swagger規範生成：提供標準的Swagger JSON示例和最佳實踐，幫助你快速生成符合規範的API文檔。
• 🔗 ApiFox無縫集成：一鍵上傳API文檔到ApiFox平臺，簡化文檔管理流程。
• 🔄 雙模式運行：支持STDIO和HTTP兩種連接方式，滿足不同場景的使用需求。
• 🌐 雲端部署就緒：支持本地開發和生產環境部署，方便你在不同環境中使用。
• 🤖 AI助手友好：專為AI助手設計的工具集成，讓你可以直接在AI助手中使用相關功能。
• 🔐 配置文件管理：支持通過配置文件管理ApiFox憑據，提高工作效率和安全性。

🚀 快速開始

全局安裝（推薦）

# 全局安裝
npm install -g code-to-apifox-mcp

# 直接使用
code-to-apifox-mcp --stdio    # MCP客戶端模式
code-to-apifox-mcp            # HTTP服務模式

臨時使用

# 無需安裝，直接運行
npx code-to-apifox-mcp --stdio
npx code-to-apifox-mcp

本地開發

# 克隆項目
git clone https://github.com/xzg0919/code-to-apifox-mcp.git
cd code-to-apifox-mcp

# 安裝依賴
npm install

# 開發模式運行
npm run dev:stdio    # STDIO模式
npm run dev          # HTTP模式

💻 使用示例

基礎用法

1. MCP客戶端集成（推薦）

在支持MCP的AI助手（如Claude Desktop）中配置：

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

配置完成後，你可以直接在AI助手中使用：

• 獲取Swagger規範：

請幫我獲取Swagger規範示例

• 使用配置文件上傳： 如果你在項目根目錄創建了code-to-apifox.json文件：

請幫我上傳API文檔到ApiFox
- Swagger JSON: {...}

• 手動指定參數：

請幫我上傳API文檔到ApiFox：
- 項目ID: your-project-id
- 訪問令牌: your-access-token
- Swagger JSON: {...}

高級用法

2. HTTP API調用

啟動HTTP服務：

code-to-apifox-mcp  # 默認端口3033

獲取Swagger規範示例

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

上傳文檔到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"
  }'

健康檢查

curl http://127.0.0.1:3033/health

3. 編程方式使用

在Node.js項目中直接使用：

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);

// 獲取Swagger規範
const spec = await service.getSwaggerSpecification();
console.log(spec);

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

📚 詳細文檔

🛠️ 工具說明

getSwaggerSpecification

• 功能：獲取標準的Swagger JSON規範示例。
• 返回：包含完整Petstore示例的Swagger規範，以及詳細的使用說明和最佳實踐建議。新增包含code-to-apifox.json配置文件的使用說明。
• 適用場景：
  • 學習Swagger規範格式。
  • 作為API文檔模板。
  • 瞭解最佳實踐和注意事項。

uploadSwaggerToApiFox

• 功能：將Swagger JSON上傳到ApiFox平臺。
• 參數：
  • projectId (必填)：ApiFox項目ID。
  • accessToken (必填)：ApiFox訪問令牌。
  • swaggerJson (必填)：完整的Swagger JSON字符串。
• 返回：上傳結果和詳細信息。

⚙️ 配置說明

默認配置文件（推薦）

在項目根目錄創建code-to-apifox.json文件來配置默認的ApiFox項目ID和訪問令牌：

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

優勢：

• 🔐 避免每次手動輸入憑據。
• 🚀 提高工作效率。
• 📁 支持項目級配置管理。

安全提示：

⚠️ 重要提示

不要將此文件提交到版本控制系統，建議添加到.gitignore文件中。

應用配置文件

配置文件位置: 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文檔生成和ApiFox集成工具"
    }
  }
}

🌐 部署指南

本地部署

# 全局安裝
npm install -g code-to-apifox-mcp

# 啟動服務
code-to-apifox-mcp  # HTTP模式，端口3033

雲服務器部署

# 1. 上傳到服務器
scp -r . user@your-server.com:/opt/doc-mcp/

# 2. 在服務器上安裝和啟動
ssh user@your-server.com
cd /opt/doc-mcp
npm install -g code-to-apifox-mcp

# 3. 後臺運行
nohup code-to-apifox-mcp > mcp-server.log 2>&1 &

Docker部署

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端點

當以HTTP模式運行時，提供以下端點：

• GET /health - 服務健康檢查
• GET /sse - MCP客戶端SSE連接
• POST /tools/getSwaggerSpecification - 獲取Swagger規範
• POST /tools/uploadSwaggerToApiFox - 上傳到ApiFox

🧪 測試和驗證

# 運行單元測試
npm test

# 測試HTTP服務
curl http://127.0.0.1:3033/health

# 測試工具功能
npx code-to-apifox-mcp --stdio

📋 環境要求

❓ 常見問題

Q: 如何使用配置文件管理ApiFox憑據？

A: 在項目根目錄創建code-to-apifox.json文件，包含projectId和accessToken字段。這樣在使用uploadSwaggerToApiFox工具時就不需要每次都輸入憑據。

Q: 配置文件安全嗎？

A: 建議將code-to-apifox.json添加到.gitignore文件中，避免意外提交敏感信息到版本控制系統。

Q: 如何獲取ApiFox的項目ID和訪問令牌？

A: 登錄ApiFox，在項目設置 -> 開放API中可以找到項目ID和生成訪問令牌。

Q: 支持哪些Swagger版本？

A: 支持Swagger 2.0和OpenAPI 3.0格式。

Q: 如何在AI助手中使用？

A: 配置MCP客戶端後，直接用自然語言描述需求即可，如"幫我上傳API文檔到ApiFox"。

Q: 端口被佔用怎麼辦？

A: 修改config/config.json中的端口號，或設置環境變量PORT=your-port。

🔗 相關鏈接

• GitHub倉庫
• npm包
• ApiFox官網
• MCP協議文檔

如果這個工具對你有幫助，請給個⭐️支持一下！