GuruWalk Affiliates

GuruWalk MCP — 联盟集成指南

GuruWalk 通过 Model Context Protocol（MCP）开放了部分旅游产品目录，让联盟合作伙伴能够将旅游产品发现、浏览和可用性查询直接集成到自己的 AI Agent 和助手中。

工具返回的所有 URL 都会自动包含你的联盟参数 ?ref=<username>，因此由你的 Agent 引导完成的预订会归属到你的账户。

---

端点

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

该服务通过 Streamable HTTP 以无状态模式实现 MCP。每个请求都是独立的——调用之间不会保留会话状态。

---

身份验证

在每个请求中使用以下任一标头包含你的 API 密钥：

Authorization: Bearer <api_key>

或

Api-Key: <api_key>

没有有效密钥的请求会收到 401 Unauthorized。

---

协议

此服务遵循 MCP 规范。可使用任何兼容 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>，以便追踪来自你的 Agent 的预订并将其计入你的账户。请勿移除或修改这些参数。

---

Reference

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