# got-cosy-mcp

An MCP server for [Got Cosy](https://gotcosy.com), the Feel Layer for hotel data: cosiness scores for about 6,300 independent hotels, computed from guest reviews and photos, with verified booking links. Free and read-only.

This package is a thin stdio proxy. Each tool call is forwarded over standard MCP JSON-RPC to Got Cosy's hosted Streamable HTTP endpoint at `https://gotcosy.com/api/mcp` and the result is returned unchanged. There are no local secrets, no API key and no local data: this server only needs outbound HTTPS.

If your client speaks Streamable HTTP directly, you can skip this package entirely and point it at `https://gotcosy.com/api/mcp` (manifest: `https://gotcosy.com/mcp.json`). Use this stdio proxy for clients that only support stdio-based MCP servers.

## Install and run

Using npx (no install step):

```bash
npx got-cosy-mcp
```

Using Docker:

```bash
docker build -t got-cosy-mcp .
docker run -i --rm got-cosy-mcp
```

Add to an MCP client config (example for a client that reads a JSON config of servers):

```json
{
  "mcpServers": {
    "got-cosy": {
      "command": "npx",
      "args": ["-y", "got-cosy-mcp"]
    }
  }
}
```

## Tools

### `find_cosy_hotels`

Find live, cosy-scored hotels. Only hotels that clear the public floor (score 5.0+) are returned. All arguments are optional.

| Argument | Type | Description |
| --- | --- | --- |
| `city` | string | City name, e.g. `"Paris"` |
| `country` | string | Country name, e.g. `"France"` |
| `min_score` | number | Minimum cosy score 0-10 (the public floor of 5.0 always applies) |
| `limit` | number | Max results, default 20, max 100 |

Example call:

```json
{
  "name": "find_cosy_hotels",
  "arguments": { "city": "Paris", "limit": 5 }
}
```

Example result (truncated):

```json
{
  "hotels": [
    {
      "slug": "les-dames-du-pantheon",
      "name": "Les Dames du Panthéon",
      "city": "Paris",
      "country": "France",
      "cosy_score": 6.7,
      "url": "https://gotcosy.com/en/hotels/les-dames-du-pantheon",
      "verified_booking": "stay22",
      "website": "https://www.hotellesdamesdupantheon.com"
    }
  ],
  "total": 81,
  "limit": 5,
  "offset": 0
}
```

### `get_hotel_feeling`

Get one hotel's cosy score, evidence signals and description by its Got Cosy slug (as returned by `find_cosy_hotels`, or from a `gotcosy.com/en/hotels/<slug>` URL).

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | string | yes | The hotel's Got Cosy slug |

Hotels below the public floor return `{"below_bar": true}` with no score exposed.

## Data and scoring

Got Cosy scores independent hotels 0-10 for warmth, intimacy and character, drawn from guest reviews and photos rather than star ratings or price. Only hotels that clear a public floor of 5.0 are exposed through these tools. See [gotcosy.com](https://gotcosy.com) for the full index and [gotcosy.com/llms-full.txt](https://gotcosy.com/llms-full.txt) for machine-readable documentation.

## Links

- Hosted endpoint: `https://gotcosy.com/api/mcp` (Streamable HTTP, stateless, no auth)
- Manifest: `https://gotcosy.com/mcp.json`
- Website: [gotcosy.com](https://gotcosy.com)
- Source repository: [github.com/perwinroth/cosyhotels](https://github.com/perwinroth/cosyhotels) (official registry entry: `io.github.perwinroth/got-cosy-graph`)
- Contact: per@gotcosy.com

## Licence

MIT, see [LICENSE](./LICENSE).