# PureRank MCP server

A small [Model Context Protocol](https://modelcontextprotocol.io) server that gives your AI agent a **pre-publish QA gate** and site-level AI-content-spam scoring, backed by [PureRank](https://pure-rank.com).

If your pipeline drafts and publishes content with an LLM, wire this in so the agent **scores every draft before it publishes** — and only ships content that reads as human-edited, not scaled AI slop of the kind Google's spam updates target.

- **Free and open-source.** The connector is free; it uses PureRank's public API.
- **Free quota, no crawl needed for drafts.** A free PureRank account includes an API key with a daily allowance for the draft gate (**25 draft scores/day**) plus a few full site scans/day. That is enough to gate a real publishing cadence. Higher volume is on the paid plans.
- **No secrets in code.** Configured entirely with environment variables.

## Quick start

**1. Get an API key** — create a free account at <https://pure-rank.com>, open the dashboard, and create an API key (the free plan includes one). Keep it secret.

**2. Add the server to Claude Code** (requires Node.js ≥ 18):

```bash
claude mcp add purerank --env PURERANK_API_KEY=YOUR_KEY -- npx -y purerank-mcp-server
```

Or add it to any MCP client config (`.mcp.json` / `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "purerank": {
      "command": "npx",
      "args": ["-y", "purerank-mcp-server"],
      "env": { "PURERANK_API_KEY": "YOUR_KEY_HERE" }
    }
  }
}
```

**3. Use it.** Ask your agent things like *"score this draft with PureRank before publishing"*, or make it a standing rule: *draft → `purerank_score_draft` → publish only if `gate == "pass"`, otherwise revise and re-score.*

## Tools

| Tool | What it does |
|---|---|
| `purerank_score_draft` | Score ONE draft (text or HTML) for AI-content-spam risk **without crawling**. Returns a 0–100 score, a `pass`/`warn`/`fail` gate, a per-signal breakdown, and human-readable findings. This is the pre-publish gate. |
| `purerank_scan_site` | Crawl and score a whole site. Submits the scan, polls to completion, returns the score, top risk signals, and a shareable report link. |
| `purerank_get_report` | Fetch the latest report summary for a domain (or a report id) without re-scanning. |

### `purerank_score_draft`

The pre-publish gate. Content-only — nothing is fetched, so it is fast and cheap.

**Input:** `{ text? , html? , title? , url? , response_format? }` — provide `text` (plain/markdown) **or** `html`.

**Output (JSON):**
```json
{
  "score": 82,
  "gate": "fail",
  "verdict": "Likely AI-generated",
  "confidence": "high",
  "words": 512,
  "language": "en",
  "signals": { "lexical": 100, "burstiness": 78, "vocabulary": 40, "repetition": 5, "formatting": 12 },
  "explanations": ["39.5 AI stock phrases /1k words", "uniform sentence rhythm (CV 0.31)"],
  "embedding": { "available": true, "margin": 0.34, "adjustment": 12 }
}
```
Gate bands: **pass** (`<30`, publish-ready) · **warn** (`30–54`, review) · **fail** (`≥55`, revise).

### `purerank_scan_site`

**Input:** `{ url , max_pages? , wait_seconds? , response_format? }`

**Output (JSON):** `{ domain, score, verdict, confidence, profile, pages_analyzed, top_signals[], report_url, report_id, cached }`. Established global brands return `{ not_applicable: true, note }` and are not scored.

### `purerank_get_report`

**Input:** `{ query , response_format? }` — `query` is a domain, a report id, or a `/r/{id}` URL.

**Output:** same summary shape as `purerank_scan_site` (domain lookups return the latest **public** report).

All tools accept `response_format: "markdown"` (default, human-readable) or `"json"` (machine-readable). Machine-readable data is also always returned as `structuredContent`.

## Configuration (environment variables)

| Variable | Required | Default | Description |
|---|---|---|---|
| `PURERANK_API_KEY` | **yes** | — | Your PureRank API key. |
| `PURERANK_API_URL` | no | `https://pure-rank.com` | API base URL. Override to point at a local or self-hosted instance. |
| `PURERANK_SCAN_WAIT_S` | no | `180` | Default seconds to wait for a site scan before returning a still-running status. |
| `PURERANK_TIMEOUT_MS` | no | `30000` | Per-request network timeout. |

## Running from source

```bash
git clone https://github.com/vadimsv1/purerank-mcp-server.git
cd purerank-mcp-server
npm install
npm run build
claude mcp add purerank --env PURERANK_API_KEY=YOUR_KEY -- node /absolute/path/to/purerank-mcp-server/dist/index.js
```

Inspect it with the MCP Inspector:

```bash
npx @modelcontextprotocol/inspector node dist/index.js
```

Development: `npm run dev` (tsx watch) · `npm run build` (tsc → `dist/`) · `npm start`.

## Notes

- stdio transport: logs go to **stderr**; stdout is reserved for the MCP protocol.
- The score is an explainable heuristic from public signals — not a Google metric and not proof of authorship. Use it to prioritize human review.
- API reference: <https://pure-rank.com/api/docs>.

## License

[MIT](LICENSE) © SVS Project LLC