Code To Apifox MCP

🚀 Code-to-ApiFox MCP Server

このサーバーは、Node.jsに基づくMCP（Model Context Protocol）サーバーで、Swaggerドキュメントの生成とApiFoxプラットフォームとの統合に特化しています。

✨ 主な機能

• 🚀 標準MCPプロトコルのサポート - MCPプロトコル仕様と完全に互換性があります。
• 📝 Swagger仕様の生成 - 標準のSwagger JSONのサンプルとベストプラクティスを提供します。
• 🔗 ApiFoxとのシームレスな統合 - 1クリックでAPIドキュメントをApiFoxプラットフォームにアップロードできます。
• 🔄 2種類のモードでの実行 - STDIOとHTTPの2種類の接続方式をサポートします。
• 🌐 クラウドデプロイメントに対応 - ローカル開発と本番環境でのデプロイをサポートします。
• 🤖 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

📋 環境要件

• Node.js: >= 18.0.0
• npm: >= 8.0.0
• オペレーティングシステム: Windows、macOS、Linux

❓ よくある質問

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プロトコルドキュメント

このツールが役に立った場合は、⭐️ を付けてサポートしてください！