|
| 1 | +# Vio MCP Skill |
| 2 | + |
| 3 | +A portable skill for AI agents that provides conversational hotel search via the [Vio MCP server](https://mcp.vio.com/docs/). Search hotels, compare prices, read reviews, and explore room options through natural conversation. |
| 4 | + |
| 5 | +## What It Does |
| 6 | + |
| 7 | +The `/vio` skill teaches agents to use two MCP tools: |
| 8 | + |
| 9 | +- **`search_hotels`** — Discover hotels by location, coordinates, or name. Supports filters (star rating, amenities, property type, price range), sorting, and pagination. |
| 10 | +- **`get_hotels`** — Fetch detailed data for specific hotels: reviews, rooms, FAQ, policies, price analytics, and more. |
| 11 | + |
| 12 | +## How It Works |
| 13 | + |
| 14 | +The skill goes beyond basic search — it embeds product thinking into every interaction: |
| 15 | + |
| 16 | +- **Intent-based ranking** — Hotels are ranked by how well they match what the user is actually looking for, not just by price or popularity. The agent evaluates location, reviews, price analytics, and amenities against the user's expressed intent. |
| 17 | +- **Smart categorization** — Results are grouped into 2-3 meaningful categories (e.g., "Best Value", "Central Location", "Top Rated") with explanations of why each group stands out. |
| 18 | +- **Booking funnel** — The agent actively guides users from search → narrowing → hotel deep-dive → room selection → booking, nudging toward the next step without being pushy. |
| 19 | +- **Three modes** — Discovery (exploring options), Comparison (head-to-head evaluation), and Lookup (quick facts about a specific hotel), each with tailored behavior. |
| 20 | +- **Intent persistence** — Context accumulates across the conversation. If the user mentioned "honeymoon" early on, that signal shapes every subsequent recommendation. |
| 21 | +- **Proactive alternatives** — When criteria conflict with reality (e.g., cheap hotels in an expensive area), the agent reframes the search with context rather than just returning poor results. |
| 22 | + |
| 23 | +## Prerequisites |
| 24 | + |
| 25 | +- Access to a Vio MCP server endpoint (obtain an API key from Vio) |
| 26 | +- An AI agent that supports the skill format (OpenClaw, Claude Code, or compatible) |
| 27 | + |
| 28 | +## Download |
| 29 | + |
| 30 | +Get the latest `vio.zip` from the [Releases page](https://github.com/viodotcom/mcp-skill/releases). |
| 31 | + |
| 32 | +Or build locally: `mise run zip` |
| 33 | + |
| 34 | +## Setup |
| 35 | + |
| 36 | +### claude.ai |
| 37 | + |
| 38 | +1. Download `vio.zip` from [Releases](https://github.com/viodotcom/mcp-skill/releases) |
| 39 | +2. Go to **Customize → Skills** and upload `vio.zip` |
| 40 | +3. Enable the skill |
| 41 | +4. Add the Vio MCP server under **Customize → Integrations → MCP**: |
| 42 | + - **Type:** HTTP |
| 43 | + - **URL:** `https://mcp.vio.com/mcp?api_key=YOUR_API_KEY` |
| 44 | +5. Start a conversation and try: "Find hotels in Amsterdam for next weekend" |
| 45 | + |
| 46 | +### OpenClaw |
| 47 | + |
| 48 | +1. Copy the skill into your personal skills directory: |
| 49 | + |
| 50 | +```bash |
| 51 | +mkdir -p ~/.agents/skills/vio |
| 52 | +cp SKILL.md ~/.agents/skills/vio/ |
| 53 | +cp -r references ~/.agents/skills/vio/ |
| 54 | +``` |
| 55 | + |
| 56 | +2. Add the Vio MCP server to `~/.openclaw/openclaw.json`: |
| 57 | + |
| 58 | +```json |
| 59 | +{ |
| 60 | + "mcp": { |
| 61 | + "servers": { |
| 62 | + "vio": { |
| 63 | + "transport": "streamable-http", |
| 64 | + "url": "https://mcp.vio.com/mcp?api_key=YOUR_API_KEY" |
| 65 | + } |
| 66 | + } |
| 67 | + } |
| 68 | +} |
| 69 | +``` |
| 70 | + |
| 71 | +3. Restart the gateway and verify: |
| 72 | + |
| 73 | +```bash |
| 74 | +openclaw gateway restart |
| 75 | +openclaw skills list # Should show "vio" as ready |
| 76 | +openclaw mcp list # Should show "vio" server |
| 77 | +``` |
| 78 | + |
| 79 | +4. Launch and test: |
| 80 | + |
| 81 | +```bash |
| 82 | +openclaw tui |
| 83 | +# Then type: /vio Amsterdam for next weekend |
| 84 | +``` |
| 85 | + |
| 86 | +### Claude Code |
| 87 | + |
| 88 | +Copy or symlink the skill into a plugin directory and use `--plugin-dir`: |
| 89 | + |
| 90 | +```bash |
| 91 | +mkdir -p my-plugin/.claude-plugin my-plugin/skills/vio |
| 92 | +echo '{"name":"vio-hotels","description":"Hotel search via Vio MCP","version":"1.0.0"}' > my-plugin/.claude-plugin/plugin.json |
| 93 | +cp SKILL.md my-plugin/skills/vio/ |
| 94 | +cp -r references my-plugin/skills/vio/ |
| 95 | +``` |
| 96 | + |
| 97 | +Configure the MCP server in `.mcp.json` at the plugin root: |
| 98 | + |
| 99 | +```json |
| 100 | +{ |
| 101 | + "vio": { |
| 102 | + "type": "http", |
| 103 | + "url": "https://mcp.vio.com/mcp?api_key=${VIO_API_KEY}" |
| 104 | + } |
| 105 | +} |
| 106 | +``` |
| 107 | + |
| 108 | +Set the `VIO_API_KEY` environment variable and launch: |
| 109 | + |
| 110 | +```bash |
| 111 | +export VIO_API_KEY=your-api-key-here |
| 112 | +claude --plugin-dir ./my-plugin |
| 113 | +``` |
| 114 | + |
| 115 | +### Other Agents |
| 116 | + |
| 117 | +Install `SKILL.md` and `references/` into your agent's skill discovery path, then configure the Vio MCP server connection: |
| 118 | + |
| 119 | +``` |
| 120 | +https://mcp.vio.com/mcp?api_key=YOUR_API_KEY |
| 121 | +``` |
| 122 | + |
| 123 | +## Usage |
| 124 | + |
| 125 | +Invoke the skill directly: |
| 126 | +``` |
| 127 | +/vio Paris, 3 nights in July, budget under 150 EUR |
| 128 | +``` |
| 129 | + |
| 130 | +Or let the agent trigger it automatically when you mention hotel search: |
| 131 | +``` |
| 132 | +Find me a 4-star hotel in Amsterdam with a pool |
| 133 | +``` |
| 134 | + |
| 135 | +### Example Queries |
| 136 | + |
| 137 | +- "Search hotels in Barcelona for next weekend" |
| 138 | +- "Find family-friendly apartments in Rome with free cancellation" |
| 139 | +- "Compare the Hilton and Marriott in London" |
| 140 | +- "Show me reviews for that hotel" |
| 141 | +- "What rooms are available? I need something with a king bed" |
| 142 | +- "Sort by price, cheapest first" |
| 143 | +- "Show me more results" |
| 144 | + |
| 145 | +## File Structure |
| 146 | + |
| 147 | +``` |
| 148 | +SKILL.md # Core skill definition |
| 149 | +references/ |
| 150 | + tool-reference.md # Complete tool schemas and examples |
| 151 | +README.md # This file |
| 152 | +.mise.toml # Build commands (mise run zip) |
| 153 | +``` |
| 154 | + |
| 155 | +## License |
| 156 | + |
| 157 | +[BSD 3-Clause](LICENSE) |
0 commit comments