# cosmos-mcp

MCP server for searching [cosmos.so](https://www.cosmos.so). Returns direct CDN image URLs — no page scraping.

Used by [TVLR](https://github.com/vihaanshahh/tvlr) to find destination photos for `places.json`.

## Install

```bash
git clone https://github.com/vihaanshahh/cosmos-mcp.git
cd cosmos-mcp
npm install
```

## Cursor / Claude Code

```json
{
  "mcpServers": {
    "cosmos": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/cosmos-mcp/dist/index.js"]
    }
  }
}
```

## Tools

| Tool | What it does |
|------|--------------|
| `search_images` | Search by keyword. Filter by color, content type, sort order. |
| `search_collections` | Search curated boards. |
| `get_element` | Look up one element by ID or `cosmos.so/e/...` URL. |

### search_images

```json
{
  "query": "Tokyo skyline dusk",
  "limit": 10,
  "exclude_ai": true,
  "order": "RELEVANT",
  "color": "FF5500"
}
```

Returns `results[].media_id`, `thumbnail_url`, `image_url`, `caption`.

### get_element

```json
{ "element_id": 1169598936 }
```

Or pass a full share URL.

## TVLR workflow

1. `search_images({ query: "Porto azulejos tiles", exclude_ai: true })`
2. Pick a result → copy UUID from CDN URL → set as `cosmosId` in `places.json`
3. URL pattern: `https://cdn.cosmos.so/<cosmosId>?format=webp&w=800`

## Dev

```bash
npm run build
npm run dev
```

## Notes

- No API key. Uses Cosmos's public GraphQL endpoint.
- Not an official Cosmos API — same backend the website uses.
- Typical search: ~300ms.

## License

MIT