{
  "markdown": "# GuruWalk MCP — Affiliate Integration Guide\n\nGuruWalk exposes a subset of its tour catalog through the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), allowing affiliates to embed tour discovery, browsing, and availability checking directly into their own AI agents and assistants.\n\nAll URLs returned by the tools include your affiliate `?ref=<username>` parameter automatically, so bookings driven by your agent are attributed to your account.\n\n---\n\n## Endpoint\n\n```\nPOST https://back.guruwalk.com/mcp/affiliates\n```\n\nThe server implements MCP over **Streamable HTTP**, stateless mode. Every request is independent — no session state is maintained between calls.\n\n---\n\n## Authentication\n\nInclude your API key on every request using one of these headers:\n\n```\nAuthorization: Bearer <api_key>\n```\n\nor\n\n```\nApi-Key: <api_key>\n```\n\nRequests without a valid key receive `401 Unauthorized`.\n\n---\n\n## Protocol\n\nThis server follows the [MCP specification](https://modelcontextprotocol.io). Use any MCP-compatible client library:\n\n- Python: [`mcp`](https://pypi.org/project/mcp/)\n- TypeScript/JavaScript: [`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk)\n\nThe transport is **Streamable HTTP** (not SSE, not stdio). The server is stateless — pass `stateless: true` (or equivalent) in your client transport configuration.\n\n---\n\n## Tools\n\n### `discover_destination`\n\nFind free walking tours available in a city. Returns the destination info, tour categories to browse, and a paginated list of featured tours. Optionally filter by date range and language.\n\n**Parameters**\n\n| Name | Type | Required | Default | Description |\n|---|---|---|---|---|\n| `destination` | string | yes | — | City or destination name, e.g. `\"Rome\"`, `\"Barcelona\"` |\n| `language` | string | no | `\"en\"` | Language for tour names and descriptions. One of: `en`, `es`, `de`, `it` |\n| `start_date` | string | no | — | Only show tours available from this date (`YYYY-MM-DD`) |\n| `end_date` | string | no | — | Only show tours available until this date (`YYYY-MM-DD`) |\n| `page` | integer | no | `1` | Page number for the featured tours list |\n\n**Response**\n\n```json\n{\n  \"place\": {\n    \"id\": 12,\n    \"name\": \"Rome\",\n    \"slug\": \"rome\",\n    \"country\": \"Italy\",\n    \"has_free_tours\": true\n  },\n  \"pagination\": {\n    \"page\": 1,\n    \"per_page\": 12,\n    \"total_count\": 34\n  },\n  \"categories\": [\n    {\n      \"id\": 5,\n      \"name\": \"Ancient Rome\",\n      \"url\": \"https://www.guruwalk.com/en/walks/rome/ancient-rome?ref=myaffiliate\"\n    }\n  ],\n  \"featured_products\": [\n    {\n      \"id\": 101,\n      \"name\": \"Classic Rome Free Tour\",\n      \"slug\": \"classic-rome-free-tour\",\n      \"rating_out_of_5\": 4.9,\n      \"reviews_count\": 312,\n      \"image_url\": \"https://cdn.guruwalk.com/tours/101.jpg\",\n      \"url\": \"https://www.guruwalk.com/walks/classic-rome-free-tour?ref=myaffiliate\"\n    }\n  ]\n}\n```\n\n---\n\n### `browse_category`\n\nList free walking tours within a category. Use a `category_id` from `discover_destination` results. Returns paginated tours with ratings, images, and booking URLs.\n\n**Parameters**\n\n| Name | Type | Required | Default | Description |\n|---|---|---|---|---|\n| `category_id` | integer | yes | — | Category ID returned by `discover_destination` |\n| `language` | string | no | `\"en\"` | Language for tour names and category labels. One of: `en`, `es`, `de`, `it` |\n| `page` | integer | no | `1` | Page number for paginated results |\n\n**Response**\n\n```json\n{\n  \"category\": {\n    \"id\": 5,\n    \"name\": \"Ancient Rome\",\n    \"url\": \"https://www.guruwalk.com/en/walks/rome/ancient-rome?ref=myaffiliate\"\n  },\n  \"place\": {\n    \"name\": \"Rome\",\n    \"slug\": \"rome\"\n  },\n  \"pagination\": {\n    \"page\": 1,\n    \"per_page\": 12,\n    \"total_count\": 8\n  },\n  \"products\": [\n    {\n      \"id\": 101,\n      \"name\": \"Classic Rome Free Tour\",\n      \"slug\": \"classic-rome-free-tour\",\n      \"rating_out_of_5\": 4.9,\n      \"reviews_count\": 312,\n      \"image_url\": \"https://cdn.guruwalk.com/tours/101.jpg\",\n      \"url\": \"https://www.guruwalk.com/walks/classic-rome-free-tour?ref=myaffiliate\"\n    }\n  ]\n}\n```\n\n---\n\n### `check_availability`\n\nCheck when a free walking tour has upcoming events. Use a `tour_id` from `discover_destination` or `browse_category` results. Returns available time slots with dates, times, languages, and booking URLs.\n\n**Parameters**\n\n| Name | Type | Required | Default | Description |\n|---|---|---|---|---|\n| `tour_id` | integer | yes | — | Tour ID from `discover_destination` or `browse_category` results |\n| `from_date` | string | yes | — | Start of date range (`YYYY-MM-DD`) |\n| `to_date` | string | yes | — | End of date range (`YYYY-MM-DD`) |\n| `language` | string | no | `\"en\"` | Language for tour names and descriptions. One of: `en`, `es`, `de`, `it` |\n\n**Response**\n\nThe `dates` object contains one key per day in the requested range. Days with no events have an empty array.\n\n```json\n{\n  \"tour_id\": 101,\n  \"from_date\": \"2025-06-10\",\n  \"to_date\": \"2025-06-12\",\n  \"dates\": {\n    \"2025-06-10\": [\n      {\n        \"event_id\": 9901,\n        \"start_time\": \"10:00\",\n        \"language\": \"en\",\n        \"last_seats\": false,\n        \"booking_url\": \"https://www.guruwalk.com/walks/classic-rome-free-tour?beginsAt=2025-06-10&endsAt=2025-06-10&ref=myaffiliate\"\n      }\n    ],\n    \"2025-06-11\": [],\n    \"2025-06-12\": [\n      {\n        \"event_id\": 9902,\n        \"start_time\": \"11:00\",\n        \"language\": \"en\",\n        \"last_seats\": true,\n        \"booking_url\": \"https://www.guruwalk.com/walks/classic-rome-free-tour?beginsAt=2025-06-12&endsAt=2025-06-12&ref=myaffiliate\"\n      }\n    ]\n  }\n}\n```\n\n---\n\n## Typical Flow\n\nA natural conversation flow for a travel assistant looks like this:\n\n```\n1. discover_destination(destination: \"Barcelona\", language: \"en\")\n   → get place info, category list, and featured tours\n\n2. browse_category(category_id: <id from step 1>, language: \"en\")\n   → drill into a specific category to see all tours\n\n3. check_availability(tour_id: <id from step 1 or 2>, from_date: \"...\", to_date: \"...\")\n   → show the user available dates and times with direct booking links\n```\n\nYou can also skip step 2 and go directly from `discover_destination` to `check_availability` if the user already selected a tour from the featured list.\n\n---\n\n## Attribution\n\nAll `url` and `booking_url` fields in every tool response automatically include `?ref=<your_username>` so bookings originating from your agent are tracked and credited to your account. Do not strip or modify these parameters.\n\n---\n\n## Reference\n\n- MCP specification: https://modelcontextprotocol.io\n- Python SDK: https://pypi.org/project/mcp/\n- TypeScript SDK: https://www.npmjs.com/package/@modelcontextprotocol/sdk\n",
  "bytes": 6692,
  "sha": "bfa2b457e0558d52677a7332ddc9f9c18551fbb787a347ae2bbfc49eff3fba57",
  "repo_slug": "guruwalk/affiliates-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_guruwalk_affiliates_mcp_b33af02a/readme"
}