guruwalk-free-tours

# GuruWalk Free Tours

Use the GuruWalk MCP server to search free tours:

`https://guruwalk-api-44909317956.europe-southwest1.run.app/mcp`

The server currently exposes one tool:

- `search`

## Tool Contract

`search` input:

- `city` (string): lowercase slug in English with spaces replaced by `-`
- `start_date` (string): `yyyy-mm-dd`
- `end_date` (string): `yyyy-mm-dd`
- `language` (string): two-letter code, usually `es`, `en`, `de`, `it`

`search` output:

- Tool returns `content[0].text` containing a JSON string.
- Parse that string to get an array of tours.
- Each tour contains:
  - `title`, `url`, `meetpoint_address`, `average_rating`, `duration`, `guru.name`, `image_url`
  - `events[]` with `start_time` (UTC), `available_spots`, `language`

## Execution Workflow

1. Determine city, date range, and preferred language from user request.
2. Normalize `city` to slug format:
   - `new york` -> `new-york`
   - `san sebastian` -> `san-sebastian`
3. Use valid ISO dates for both fields.
4. Call `search`.
5. Parse JSON from `content[0].text`.
6. Filter and rank results for user-facing output:
   - keep only events with `available_spots > 0`
   - prioritize events matching requested language when possible
   - prefer higher `average_rating`, then earlier upcoming time
7. Return concise options with booking URL and next available slots.

## Defaults

- If user does not specify language, use:
  - `es` for Spanish conversation
  - `en` otherwise
- If user does not specify dates, ask for dates before calling the tool.
- If date intent is relative, convert to explicit dates before calling.

## Response Format to User

For each recommended tour include:

- Tour title
- Rating
- Duration
- Guide name
- Meeting point
- 1-3 next available sessions (with timezone label)
- Booking URL

If no tours are found:

- explain that no availability was returned for the given city/date range
- propose adjusting one variable at a time: city slug, dates, or language

## Observed Edge Cases (from live MCP inspection)

- `search` is the only available tool; no MCP resources/prompts/templates are exposed.
- `city` with spaces (e.g. `New York`) can return empty results.
- `start_date > end_date` can return empty results instead of validation error.
- Non-ISO dates can still be accepted by backend, but always send ISO `yyyy-mm-dd`.
- Some locale/language combinations can return tours with `title: null`; handle gracefully.

## Validation Notes

- Keep executable validation commands outside this skill file.
- Validate behavior by confirming:
  - the MCP server exposes the `search` tool
  - search results arrive as a JSON string in `content[0].text`