Oro Commerce Mcp Server

🏪 ORO Commerce MCP サーバー

ORO Commerce とシームレスに統合できる、動的な Model Context Protocol（MCP）サーバーです。ORO Commerce API スキーマからツールを自動生成し、Claude などの AI アシスタントを通じて、利用可能なすべてのエンドポイントにすぐにアクセスできます。

✨ 特長

🚀 動的な API 統合

• ORO Commerce の Swagger スキーマから、すべての API エンドポイントを自動検出
• API を完全にカバー — すべてのエンドポイントが利用可能な MCP ツールになります
• 自動更新 — 新しい API エンドポイントが自動的に利用可能になります
• API 呼び出しのハードコードは不要 — すべて実行時に生成されます

🔧 インテリジェントなツール生成

• スマートなエンドポイント選択 — まず最も有用な API に焦点を当てます
• OpenAPI スキーマを使用したパラメーターの自動検証
• 包括的なエラー処理とレスポンスの整形
• カテゴリ別の整理（アカウント、顧客、製品など）

🏪 ORO Commerce を包括的にカバー

• アカウントと顧客の管理 — B2B 顧客のライフサイクル全体をカバー
• 製品カタログとキット品目 — 製品、カテゴリ、キット構成、カスタムフィールド
• 注文処理 — 注文、キットの詳細を含む明細、ステータス追跡
• アクティビティ管理 — 通話、メール、メモ、タスク
• 拡張エンティティ — カスタムフィールドとエンティティ拡張
• リレーションシップと複雑な操作 — 高度な機能を含むすべての API エンドポイント

🔐 エンタープライズ対応

• トークンを自動管理する OAuth2 認証
• デフォルトで読み取り専用 — 本番環境でも安全に使用できます
• 設定可能なエンドポイントフィルタリング — 公開する API を制御できます
• 包括的なログ記録とデバッグサポート

🚀 クイックスタート

1. インストール

npm install -g oro-commerce-mcp-server

または、ローカルで実行します。

git clone https://github.com/clicktrend/oro-commerce-mcp-server.git
cd oro-commerce-mcp-server
npm install
npm run build

2. ORO Commerce の設定

ORO Commerce バックエンドで OAuth アプリケーションを作成します。

1. System → Integrations → OAuth Applications に移動します
2. Client Credentials グラントタイプで新しいアプリケーションを作成します
3. Client ID と Client Secret を控えます
4. クエリするエンティティの API アクセス権限を付与します

3. API スキーマの更新

現在の API スキーマを生成してコピーします。

ORO Commerce サーバー上で実行：

# In your ORO Commerce application directory
console api:swagger:dump > oro_commerce_swagger_dump.json

MCP プロジェクトディレクトリにコピー：

# Copy the file to where you'll run the MCP server
# Example: scp from remote server
scp user@oro-server:/path/to/oro_commerce_swagger_dump.json ./oro_commerce_swagger_dump.json

# Or: Copy from local ORO Commerce installation
cp /path/to/oro-commerce/oro_commerce_swagger_dump.json ./oro_commerce_swagger_dump.json

注： oro_commerce_swagger_dump.json ファイルは、MCP サーバーの起動ディレクトリと同じディレクトリに配置する必要があります。

4. サーバーの起動

# Set environment variables
export ORO_SHOP_URL="https://your-oro-commerce.com"
export ORO_CLIENT_ID="your_client_id"
export ORO_CLIENT_SECRET="your_client_secret"

# For local/development with self-signed certificates:
export NODE_ENV=development
# OR use this for production with self-signed certs:
export DISABLE_SSL_VERIFY=true

# Start server
npm start

5. MCP Inspector でテスト（開発）

開発やテストには、MCP Inspector を使用できます。

# Install and run MCP Inspector in the project directory
npx @modelcontextprotocol/inspector

# In the browser interface:
# - Command: "node"
# - Arguments: "dist/index.js"
# - Click "Connect"

これにより、Claude Desktop／Code にデプロイする前に、すべてのツールを対話形式でテストできます。

SSL 証明書の処理：

• 開発／ローカル： NODE_ENV=development を設定すると、SSL 証明書エラーが自動的に無視されます
• 自己署名証明書を使用する本番環境： DISABLE_SSL_VERIFY=true を設定すると、SSL 検証が無効になります
• 有効な証明書を使用する本番環境： 追加の設定は不要です

5. Claude Desktop または Claude Code で使用

Claude Desktop の設定：

Claude Desktop の設定に追加します。

{
  \"mcpServers\": {
    \"oro-commerce\": {
      \"command\": \"oro-commerce-mcp-server\",
      \"env\": {
        \"ORO_SHOP_URL\": \"https://your-oro-commerce.com\",
        \"ORO_CLIENT_ID\": \"your_client_id\", 
        \"ORO_CLIENT_SECRET\": \"your_client_secret\",
        \"NODE_ENV\": \"development\"
      }
    }
  }
}

Claude Code の設定：

Claude Code のプロジェクトでは、サンプル設定をコピーします。

# Copy example configuration
cp .mcp.json.example .mcp.json

# Edit with your credentials
nano .mcp.json

または、プロジェクトのルートに .mcp.json を手動で作成します。

{
  \"mcpServers\": {
    \"oro-commerce\": {
      \"command\": \"oro-commerce-mcp-server\",
      \"env\": {
        \"ORO_SHOP_URL\": \"https://your-oro-commerce.com\",
        \"ORO_CLIENT_ID\": \"your_client_id\",
        \"ORO_CLIENT_SECRET\": \"your_client_secret\",
        \"NODE_ENV\": \"development\"
      },
      \"description\": \"Dynamic ORO Commerce API integration\"
    }
  }
}

注： .mcp.json ファイルは再起動時に Claude Code によって自動的に読み込まれ、認証情報の漏えいを防ぐため .gitignore に追加されます。

🛠️ 利用可能なツール

このサーバーは、30 種類以上の動的に生成されたツールを提供します。

コアツール（4）

• configure_oro_connection - API 接続を設定します
• test_connections - API への接続を確認します
• list_dynamic_tools - 利用可能なすべてのツールを表示します
• get_dynamic_tool_info - ツールの詳細なドキュメントを取得します

動的ツール（26以上）

ORO Commerce API から自動生成されます：

アカウント管理（15個のツール）

• accounts_get - すべてのアカウントを一覧表示
• accounts_id_get - 特定のアカウントの詳細を取得
• accounts_id_contacts_get - アカウントの連絡先を取得
• accounts_id_b2bcustomers_get - B2B 顧客を取得
• その他のアカウント関連エンドポイント…

B2B 顧客管理（11個以上のツール）

• b2bcustomers_get - B2B 顧客を一覧表示
• b2bcustomers_id_get - 顧客の詳細を取得
• b2bcustomers_id_orders_get - 顧客の注文を取得
• その他の顧客関連エンドポイント…

その他のカテゴリ

• 商品・カタログ管理
• 注文処理・追跡
• 在庫・価格設定
• アクティビティ管理（通話、メール、タスク）
• カスタムエンティティ拡張

📖 使用例

基本的なデータクエリ

// List all accounts
{
  \"name\": \"accounts_get\",
  \"arguments\": {}
}

// Get specific customer details  
{
  \"name\": \"b2bcustomers_id_get\",
  \"arguments\": { \"id\": \"123\" }
}

// Search tools by category
{
  \"name\": \"list_dynamic_tools\", 
  \"arguments\": { \"category\": \"accounts\" }
}

高度な統合

// Get comprehensive account data
{
  \"name\": \"accounts_id_get\",
  \"arguments\": { 
    \"id\": \"1\",
    \"include\": \"contacts,addresses,activities\"
  }
}

// Filter B2B customers by criteria
{
  \"name\": \"b2bcustomers_get\",
  \"arguments\": {
    \"filter[name]\": \"Acme Corp\",
    \"page[limit]\": 10
  }
}

⚙️ 設定

環境変数

# Required
ORO_SHOP_URL=https://your-oro-commerce.com
ORO_CLIENT_ID=your_oauth_client_id
ORO_CLIENT_SECRET=your_oauth_client_secret

# Optional  
DEBUG=mcp:*
NODE_ENV=development
DISABLE_SSL_VERIFY=true

スキーマを最新の状態に保つ

重要： すべてのツールに現在の ORO Commerce の設定が反映されるよう、API スキーマを定期的に更新してください。

# Update schema after:
# - Installing new ORO Commerce bundles
# - Adding custom entities/fields  
# - Upgrading ORO Commerce versions
# - Modifying API configurations

# On ORO Commerce server:
console api:swagger:dump > oro_commerce_swagger_dump.json

# Copy to MCP project directory and restart server:
cp oro_commerce_swagger_dump.json /path/to/mcp-project/
# Restart MCP server to reload tools

🏗️ アーキテクチャ

動的なツール生成

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│ ORO Commerce    │───▶│ Swagger Schema   │───▶│ MCP Tools       │
│ API Endpoints   │    │ oro_commerce_    │    │ (Generated      │
│ (3500+ total)   │    │ swagger_dump.json│    │ Automatically)  │
└─────────────────┘    └──────────────────┘    └─────────────────┘

スマートなエンドポイント選択

サーバーは、最も有用なエンドポイントをインテリジェントに選択します。

• 人気のエンティティ（アカウント、顧客、注文、商品）
• 読み取り専用の操作（本番環境でも安全）
• パラメーターが明確に記載されたドキュメントの充実したエンドポイント
• ユーザーが圧倒されないよう、カテゴリでフィルタリング

🔧 開発

プロジェクト構成

src/
├── index.ts              # Main MCP server
├── oro-client.ts         # ORO Commerce OAuth2 client  
├── swagger-parser.ts     # Dynamic schema parser
├── dynamic-client.ts     # API execution engine
└── types.ts              # TypeScript definitions

ソースからのビルド

git clone https://github.com/clicktrend/oro-commerce-mcp-server.git
cd oro-commerce-mcp-server
npm install
npm run build
npm start

サーバーの拡張

// Add more endpoint categories in swagger-parser.ts
getEndpointsByTags([
  'products', 'orders', 'categories', 
  'inventory', 'prices', 'promotions'
])

🚀 ユースケース

Eコマース管理

• 顧客関係管理 - 顧客のプロフィール全体にアクセス
• 注文処理 - 注文、明細項目、フルフィルメントを追跡
• 商品カタログ管理 - 商品、属性、カテゴリを照会
• 在庫モニタリング - 在庫数と入手可能状況を確認

ビジネスインテリジェンス

• 売上分析 - 注文パターンと顧客行動を分析
• 顧客インサイト - 顧客のライフサイクルと好みを把握
• 商品パフォーマンス - ベストセラーと在庫回転率を追跡
• アカウント管理 - B2B 顧客との関係をモニタリング

統合・自動化

• データ同期 - 外部システムと ORO Commerce のデータを同期
• レポート生成 - ORO Commerce のデータからカスタムレポートを作成
• ワークフロー自動化 - ORO Commerce のイベントに基づいてアクションを実行
• AI を活用したインサイト - AI アシスタントでビジネスデータを分析

🤝 貢献

皆さまからの貢献を歓迎します。ガイドラインについては、CONTRIBUTING.md をご覧ください。

簡単な貢献ガイド

1. リポジトリを フォーク します
2. フィーチャーブランチを 作成 します：git checkout -b feature/amazing-feature
3. 変更を コミット します：git commit -m 'Add amazing feature'
4. ブランチに プッシュ します：git push origin feature/amazing-feature
5. プルリクエストを 作成 します

📋 要件

• Node.js 18+ - ランタイム環境
• TypeScript 5.3+ - 開発時の依存関係
• ORO Commerce インスタンス - API アクセスが有効になっていること
• OAuth2 認証情報 - ORO Commerce から取得したクライアント ID とシークレット

🐛 トラブルシューティング

よくある問題

認証エラー：

# Test OAuth2 credentials manually
curl -X POST https://your-oro-commerce.com/oauth2-token \\
  -d \"grant_type=client_credentials&client_id=YOUR_ID&client_secret=YOUR_SECRET\"

ツールが見つからない場合：

# Update your API schema
console api:swagger:dump > oro_commerce_swagger_dump.json
# Restart the server
npm restart

接続の問題：

# Enable debug logging
DEBUG=mcp:* npm start

ヘルプ

• 問題報告： GitHub Issues
• ディスカッション： GitHub Discussions
• ドキュメント： Wiki

📄 ライセンス

このプロジェクトは MIT ライセンスのもとで公開されています。詳細は LICENSE ファイルをご覧ください。

🙏 謝辞

• ORO Commerce - 包括的な API ドキュメントを提供してくださったことに感謝します
• Model Context Protocol - AI アシスタントとの連携を可能にしてくださったことに感謝します
• Anthropic Claude - インテリジェントな API インタラクションの着想を与えてくださったことに感謝します

---

Clicktrend が ❤️ を込めて作成
Claude.ai の支援を受けて構築

ORO Commerce のデータを、AI が活用できるインサイトに変換しましょう