GuruWalk Affiliates

GuruWalk MCP — アフィリエイト連携ガイド

GuruWalk は、ツアーカタログの一部を Model Context Protocol（MCP）経由で公開しており、アフィリエイトはツアーの検索、閲覧、空き状況の確認を自社の AI エージェントやアシスタントに直接組み込むことができます。

ツールから返されるすべての URL には、アフィリエイト用の ?ref=<username> パラメーターが自動的に含まれます。そのため、エージェント経由の予約はご自身のアカウントに紐付けられます。

---

エンドポイント

POST https://back.guruwalk.com/mcp/affiliates

このサーバーは、ステートレスモードで Streamable HTTP を使用して MCP を実装しています。各リクエストは独立しており、呼び出し間でセッション状態は維持されません。

---

認証

以下のいずれかのヘッダーを使用して、すべてのリクエストに API キーを含めてください。

Authorization: Bearer <api_key>

または

Api-Key: <api_key>

有効なキーを含まないリクエストには、401 Unauthorized が返されます。

---

プロトコル

このサーバーは MCP specification に準拠しています。MCP 対応のクライアントライブラリを使用してください。

• Python：mcp
• TypeScript/JavaScript：@modelcontextprotocol/sdk

トランスポートは Streamable HTTP です（SSE でも stdio でもありません）。サーバーはステートレスです。クライアントのトランスポート設定で stateless: true（または同等の設定）を渡してください。

---

ツール

discover_destination

都市で利用できる無料のウォーキングツアーを検索します。目的地の情報、閲覧できるツアーカテゴリー、ページ分けされたおすすめツアーの一覧を返します。必要に応じて、日付範囲と言語で絞り込めます。

パラメーター

名前	型	必須	デフォルト	説明
destination	string	はい	—	都市または目的地の名前。例："Rome"、"Barcelona"
language	string	いいえ	"en"	ツアー名と説明の言語。次のいずれか：en、es、de、it
start_date	string	いいえ	—	この日付以降に利用できるツアーのみを表示します（YYYY-MM-DD）
end_date	string	いいえ	—	この日付までに利用できるツアーのみを表示します（YYYY-MM-DD）
page	integer	いいえ	1	おすすめツアー一覧のページ番号

レスポンス

{
  "place": {
    "id": 12,
    "name": "Rome",
    "slug": "rome",
    "country": "Italy",
    "has_free_tours": true
  },
  "pagination": {
    "page": 1,
    "per_page": 12,
    "total_count": 34
  },
  "categories": [
    {
      "id": 5,
      "name": "Ancient Rome",
      "url": "https://www.guruwalk.com/en/walks/rome/ancient-rome?ref=myaffiliate"
    }
  ],
  "featured_products": [
    {
      "id": 101,
      "name": "Classic Rome Free Tour",
      "slug": "classic-rome-free-tour",
      "rating_out_of_5": 4.9,
      "reviews_count": 312,
      "image_url": "https://cdn.guruwalk.com/tours/101.jpg",
      "url": "https://www.guruwalk.com/walks/classic-rome-free-tour?ref=myaffiliate"
    }
  ]
}

---

browse_category

カテゴリー内の無料ウォーキングツアーを一覧表示します。discover_destination の結果から category_id を指定してください。評価、画像、予約 URL を含む、ページ分けされたツアー一覧を返します。

パラメーター

名前	型	必須	デフォルト	説明
category_id	integer	はい	—	discover_destination が返すカテゴリー ID
language	string	いいえ	"en"	ツアー名とカテゴリーラベルの言語。次のいずれか：en、es、de、it
page	integer	いいえ	1	ページ分けされた結果のページ番号

レスポンス

{
  "category": {
    "id": 5,
    "name": "Ancient Rome",
    "url": "https://www.guruwalk.com/en/walks/rome/ancient-rome?ref=myaffiliate"
  },
  "place": {
    "name": "Rome",
    "slug": "rome"
  },
  "pagination": {
    "page": 1,
    "per_page": 12,
    "total_count": 8
  },
  "products": [
    {
      "id": 101,
      "name": "Classic Rome Free Tour",
      "slug": "classic-rome-free-tour",
      "rating_out_of_5": 4.9,
      "reviews_count": 312,
      "image_url": "https://cdn.guruwalk.com/tours/101.jpg",
      "url": "https://www.guruwalk.com/walks/classic-rome-free-tour?ref=myaffiliate"
    }
  ]
}

---

check_availability

無料ウォーキングツアーの今後の開催予定を確認します。discover_destination または browse_category の結果から tour_id を指定してください。日付、時刻、言語、予約 URL を含む利用可能な時間枠を返します。

パラメーター

名前	型	必須	デフォルト	説明
tour_id	integer	はい	—	discover_destination または browse_category の結果に含まれるツアー ID
from_date	string	はい	—	日付範囲の開始日（YYYY-MM-DD）
to_date	string	はい	—	日付範囲の終了日（YYYY-MM-DD）
language	string	いいえ	"en"	ツアー名と説明の言語。次のいずれか：en、es、de、it

レスポンス

dates オブジェクトには、指定した範囲内の各日付に対応するキーが含まれます。開催予定がない日の配列は空です。

{
  "tour_id": 101,
  "from_date": "2025-06-10",
  "to_date": "2025-06-12",
  "dates": {
    "2025-06-10": [
      {
        "event_id": 9901,
        "start_time": "10:00",
        "language": "en",
        "last_seats": false,
        "booking_url": "https://www.guruwalk.com/walks/classic-rome-free-tour?beginsAt=2025-06-10&endsAt=2025-06-10&ref=myaffiliate"
      }
    ],
    "2025-06-11": [],
    "2025-06-12": [
      {
        "event_id": 9902,
        "start_time": "11:00",
        "language": "en",
        "last_seats": true,
        "booking_url": "https://www.guruwalk.com/walks/classic-rome-free-tour?beginsAt=2025-06-12&endsAt=2025-06-12&ref=myaffiliate"
      }
    ]
  }
}

---

一般的なフロー

旅行アシスタントでの自然な会話フローは、次のようになります。

1. discover_destination(destination: "Barcelona", language: "en")
   → get place info, category list, and featured tours

2. browse_category(category_id: <id from step 1>, language: "en")
   → drill into a specific category to see all tours

3. check_availability(tour_id: <id from step 1 or 2>, from_date: "...", to_date: "...")
   → show the user available dates and times with direct booking links

ユーザーがすでにおすすめ一覧からツアーを選択している場合は、手順 2 を省略して、discover_destination から check_availability に直接進むこともできます。

---

アトリビューション

すべてのツールレスポンスに含まれる url フィールドと booking_url フィールドには、自動的に ?ref=<your_username> が追加されます。これにより、エージェント経由の予約が追跡され、ご自身のアカウントに計上されます。これらのパラメーターを削除したり変更したりしないでください。

---

Reference

• MCP specification: https://modelcontextprotocol.io
• Python SDK: https://pypi.org/project/mcp/
• TypeScript SDK: https://www.npmjs.com/package/@modelcontextprotocol/sdk