# CompareFairly MCP Server

**Model Context Protocol** server for [CompareFairly](https://comparefairly.com) -
a universal, AI-driven comparison engine. It gives AI agents real-time access to
**neutral, sourced** comparisons across any category (products, services, and more),
in multiple languages and countries.

Runs as a **stdio** server (dependency-free bridge) or can be called directly as a
**remote HTTP** endpoint.

- **Remote endpoint:** `https://comparefairly.com/mcp` (Streamable HTTP, JSON-RPC 2.0)
- **Auth:** none (public, read-only) · **CORS:** open · **Rate-limited** per IP

## Why

Comparison is one of the top things people (and now agents) use AI for, but most
comparison content is opinion or pay-to-rank. CompareFairly is built on three
principles that make it a trustworthy data source for agents:

- **Provable neutrality** - ranking is never bought; sorted on measured criteria.
- **Traceability** - every value links to a source; "sourced" vs "estimate" is explicit.
- **Freshness** - each comparison exposes its data age and TTL; stale data is flagged.

## Tools

| Tool | Description |
|------|-------------|
| `search_comparisons` | Search the catalog. Params: `query`, `lang`, `country`, `limit`. |
| `get_comparison` | One full structured comparison (scores, sub-scores, per-criterion values, badges, sources, freshness). Params: `slug`, `lang`, `country`. |
| `list_categories` | Top-level categories for a market. Params: `lang`, `country`. |

A comparison exists **per market**: always pass the same `lang` + `country` you got
from `search_comparisons`. If a slug exists only in other markets, `get_comparison`
returns `available_markets` so the agent can retry correctly.

## Install

### Option 1 - stdio via npx (no install)

```bash
npx -y github:cgdev2019/comparefairly-mcp
```

Client config:

```json
{
  "mcpServers": {
    "comparefairly": {
      "command": "npx",
      "args": ["-y", "github:cgdev2019/comparefairly-mcp"]
    }
  }
}
```

### Option 2 - Docker

```bash
docker build -t comparefairly-mcp .
docker run --rm -i comparefairly-mcp
```

```json
{
  "mcpServers": {
    "comparefairly": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "comparefairly-mcp"]
    }
  }
}
```

### Option 3 - remote HTTP (no local process)

```json
{
  "mcpServers": {
    "comparefairly": {
      "type": "streamable-http",
      "url": "https://comparefairly.com/mcp"
    }
  }
}
```

Requires Node >= 18 for the stdio options. Override the backend with
`COMPAREFAIRLY_MCP_URL` if needed.

## Raw calls

```bash
# List tools
curl -s -X POST https://comparefairly.com/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Search
curl -s -X POST https://comparefairly.com/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_comparisons","arguments":{"query":"password manager","lang":"en","country":"US","limit":5}}}'
```

## Other machine formats

Every comparison is also available without MCP, at the same URL plus a suffix:

- `…/{lang}/{country}/{slug}.json` - structured data (scores, sources, freshness)
- `…/{lang}/{country}/{slug}.md` - clean Markdown
- Discovery guide for agents: `https://comparefairly.com/llms.txt`

## License & data terms

This repository (code and docs) is provided under the MIT License. The **comparison
data** returned by the server is subject to CompareFairly's usage terms: citation
with a link is welcome; bulk extraction and redistribution of the catalog is not
permitted. For volume access, use the [contact page](https://comparefairly.com/contact).

## Links

- Website: https://comparefairly.com
- MCP endpoint: https://comparefairly.com/mcp
- Agent guide: https://comparefairly.com/llms.txt