Mcp Server Gelato

Gelato MCP サーバー

Gelato のプリントオンデマンド API と連携するための MCP（Model Context Protocol）サーバーです。このサーバーは、注文の検索、注文詳細の取得、商品カタログの確認に使用できるツールとリソースを提供します。

機能

🔧 ツール

• search_orders：複数のフィルター（ステータス、国、日付範囲など）を使用した高度な注文検索
• get_order_summary：特定の注文の詳細を取得
• search_products：フィルター機能を使ってカタログ内の商品を検索
• get_product：特定の商品の詳細情報を取得
• get_product_prices：商品の価格情報を取得
• check_stock_availability：地域ごとの在庫状況を確認
• list_shipment_methods：利用可能な配送方法を取得

📚 リソース

• orders://{order_id}：注文の詳細情報を取得
• orders://recent：直近 10 件の注文を取得
• orders://drafts：すべての下書き注文を取得
• catalogs://list：利用可能なすべての商品カタログを一覧表示
• catalogs://{catalog_uid}：カタログの詳細情報を取得
• catalogs://summary：すべてのカタログの概要をすばやく確認

前提条件

• Python 3.13+
• Gelato API キー（Gelato API Portalから取得してください）

インストール

Claude Desktop へのクイックインストール

Claude Desktop にこのサーバーを追加する最も簡単な方法です。

claude mcp add gelato --env GELATO_API_KEY="your_gelato_api_key_here" -- uvx mcp-server-gelato

your_gelato_api_key_here を、Gelato API Portalで取得した実際の Gelato API キーに置き換えてください。

別の方法：API キーなしでインストールし、後から設定することもできます。

claude mcp add gelato -- uvx mcp-server-gelato

その後、Claude 内で configure_gelato ツールを使用して API キーを設定してください。

手動インストール

オプション 1：PyPI からインストール（推奨）

# Install the package
uv install mcp-server-gelato
# or
pip install mcp-server-gelato

# Run the server
GELATO_API_KEY="your_api_key_here" uvx mcp-server-gelato

# Or install as a tool
uv tool install mcp-server-gelato
GELATO_API_KEY="your_api_key_here" mcp-server-gelato

オプション 2：GitHub からインストール

# Install directly from GitHub
uvx --from git+https://github.com/madzarmaksim/mcp-server-gelato mcp-server-gelato

# Or use uv tool install
uv tool install git+https://github.com/madzarmaksim/mcp-server-gelato

オプション 3：ローカル開発

1. このリポジトリをクローンします。

   git clone https://github.com/madzarmaksim/mcp-server-gelato.git
   cd mcp-server-gelato
   

2. 依存関係をインストールします。

   uv install
   # or
   pip install -e .
   

3. API キーを設定します。

   cp .env.example .env
   # Edit .env and add your GELATO_API_KEY
   

設定

プロジェクトのルートに .env ファイルを作成し、Gelato API キーを設定してください。

GELATO_API_KEY=your_gelato_api_key_here

# Optional configuration
# GELATO_BASE_URL=https://order.gelatoapis.com
# GELATO_PRODUCT_URL=https://product.gelatoapis.com
# TIMEOUT=30
# MAX_RETRIES=3
# DEBUG=false

使用方法

サーバーの起動

uvx でインストールした場合：

# Run the server directly
mcp-server-gelato

# Or with environment variables
GELATO_API_KEY=your_key_here mcp-server-gelato

ローカル開発の場合：

# Direct execution
python main.py

# Development mode with inspector
uv run mcp dev main.py

# Install in Claude Desktop from local directory
uv run mcp install . --name "Gelato API"

ツールとリソースの使用

注文の検索

# Search for draft orders
search_orders(order_types=["draft"])

# Search US orders from last month
search_orders(
    countries=["US"], 
    start_date="2024-01-01T00:00:00Z",
    end_date="2024-01-31T23:59:59Z"
)

# Search by customer name
search_orders(search_text="John Smith", limit=10)

注文詳細の取得

リソース URI 形式を使って注文のコンテキストを読み込みます。

orders://37365096-6628-4538-a9c2-fbf9892deb85

または、ツールを使用します。

get_order_summary(order_id="37365096-6628-4538-a9c2-fbf9892deb85")

商品カタログの確認

catalogs://list          # List all catalogs
catalogs://posters       # Get poster catalog details
catalogs://summary       # Quick overview

利用可能な検索フィルター

search_orders ツールは、幅広いフィルターに対応しています。

• order_types：["order", "draft"] - 注文タイプで絞り込み
• countries：["US", "DE", "CA"] - 配送先の国で絞り込み
• currencies：["USD", "EUR", "GBP"] - 通貨で絞り込み
• financial_statuses：支払いステータス（"draft"、"paid"、"canceled" など）
• fulfillment_statuses：フルフィルメントのステータス（"created"、"printed"、"shipped" など）
• search_text：顧客名と注文参照 ID を検索
• start_date/end_date：日付範囲で絞り込み（ISO 8601 形式）
• channels：["api", "shopify", "etsy", "ui"] - 注文チャネルで絞り込み
• limit/offset：ページネーションの制御（1 リクエストあたり最大 100 件）

主な設計上の特徴

• 型安全性：すべての API 操作に完全な Pydantic モデルを使用
• エラー処理：カスタム例外を用いた包括的なエラー処理
• 非同期処理のサポート：パフォーマンス向上のため、すべての API 呼び出しを非同期で実行
• リソースとツールの使い分け：データの公開（リソース）と操作（ツール）を明確に分離
• 拡張性：確立されたパターンに従って新しいエンドポイントを簡単に追加可能

エラー処理

このサーバーには、一般的な状況に対応する堅牢なエラー処理が含まれています。

• 認証エラー：API キーが無効または未設定
• レート制限：指数バックオフによる自動再試行
• ネットワークエラー：タイムアウトと接続エラーの処理
• API エラー：Gelato API のエラーレスポンスを適切に処理
• 検証エラー：リクエスト／レスポンスデータの検証

トラブルシューティング

「Failed to reconnect to gelato」エラー

このエラーは、有効な GELATO_API_KEY が設定されていない状態でサーバーを起動すると発生します。解決方法は次のとおりです。

Claude Desktop のインストールの場合：

# Install with API key (recommended)
claude mcp add gelato --env GELATO_API_KEY="your_actual_api_key" -- uvx mcp-server-gelato

# Or install without API key and configure later
claude mcp add gelato -- uvx mcp-server-gelato
# Then use the configure_gelato tool in Claude

ローカル開発の場合：

# Using PyPI package
GELATO_API_KEY="your_api_key_here" uvx mcp-server-gelato

# Or using local code
export GELATO_API_KEY=your_api_key_here
python main.py

# Or create .env file for local development
echo "GELATO_API_KEY=your_api_key_here" > .env
python main.py

API キーの取得

1. Gelato API Portal にアクセスします
2. アカウントを登録するか、ログインします
3. ダッシュボードで API キーを生成します
4. インストールコマンドまたは環境変数にキーを設定します

よくある問題

• 無効な API キー：API キーが正しく、有効であることを再確認してください
• ネットワークの問題：インターネットに接続できていることと、ファイアウォールでブロックされていないことを確認してください
• 権限の問題：API キーに必要な権限があることを確認してください

開発

新機能の追加

1. 新しいツール：src/tools/ に追加し、サーバーに登録します
2. 新しいリソース：src/resources/ に追加し、サーバーに登録します
3. 新しいモデル：適切な Pydantic バリデーションとともに src/models/ に追加します
4. 新しい API エンドポイント：src/client/ の GelatoClient を拡張します

テスト

# Test connection with your API key
python -c "
import asyncio
from src.config import get_settings
from src.client.gelato_client import GelatoClient

async def test():
    settings = get_settings()
    async with GelatoClient(settings.gelato_api_key, settings) as client:
        catalogs = await client.list_catalogs()
        print(f'Found {len(catalogs)} catalogs')

asyncio.run(test())
"

トラブルシューティング

よくある問題

1. API キーエラー：環境内で GELATO_API_KEY が正しく設定されていることを確認してください
2. 接続タイムアウト：ネットワーク接続を確認し、設定でタイムアウトを延長してください
3. レート制限：サーバーはバックオフを伴って自動的に再試行しますが、リクエストの頻度を下げる必要がある場合があります

デバッグモード

デバッグログを有効にします：

DEBUG=true python main.py

コントリビューション

1. 既存のコード構造とパターンに従ってください
2. 新しいエンドポイントには適切なエラー処理を追加してください
3. データ検証用の Pydantic モデルを含めてください
4. この README に新機能を記載してください

ライセンス

このプロジェクトは MIT License の下でライセンスされています。

サポート

Gelato API の問題については、Gelato Help Center をご覧ください。 MCP 関連の問題については、MCP documentation をご確認ください。