Metadata-Version: 2.4
Name: ryrank-mcp
Version: 1.0.0
Summary: MCP server for RyRank — a Cohere-compatible pay-per-call reranker
License: MIT
Project-URL: Homepage, https://trigeochiral.com
Project-URL: Repository, https://github.com/trigeochiral/ryrank-mcp
Keywords: mcp,rerank,reranker,retrieval,rag,cohere-alternative,x402,agent,semantic-search
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27
Dynamic: license-file

# RyRank — MCP server

<!-- mcp-name: io.github.trigeochiral/ryrank -->

A Cohere-compatible reranker, pay-per-call in USDC on Base (x402), free tier, no signup.

Hosted API: `https://trigeochiral.com` — set it as `RYRANK_API`.

## Tool

| Tool | What |
|---|---|
| `rerank` | Rerank documents by relevance to a query. Cohere-compatible response shape (`results: [{index, relevance_score}]`), so it drops into an existing `co.rerank()` call. ~$0.001/call over x402 (roughly half Cohere Rerank's list price) or a free tier. |

## Why

A lexical+spectral hybrid reranker, not a cross-encoder: strong when the candidates already
share vocabulary with the query, which is the common case for RAG retrieval output and
document/tool shortlists. Built for high-volume, latency- and cost-sensitive reranking —
narrowing a retrieval candidate set, deduping, triage — rather than close semantic
disambiguation between near-identical phrasings. Pay-per-call and about half the price is
the trade for that.

Verified against the real `cohere.Client`, `cohere.ClientV2` and `voyageai.Client` SDKs:
point `base_url` at this API and existing rerank code runs unmodified.

## Install

```bash
pip install ryrank-mcp
claude mcp add ryrank --env RYRANK_API=https://trigeochiral.com -- ryrank-mcp
```

or with `uvx` (no install):

```bash
claude mcp add ryrank --env RYRANK_API=https://trigeochiral.com -- uvx ryrank-mcp
```

Optional: `RYRANK_XPAYMENT` = a base64 x402 `X-PAYMENT` payload, to make paid calls past the
free tier. Without it you get 25 free calls/day per IP.

## Direct HTTP (no MCP)

```bash
curl -sX POST https://trigeochiral.com/v1/rerank -H 'content-type: application/json' \
  -d '{"query":"how do I reset my password","documents":["Go to Settings > Security and click Reset Password.","Our refund policy allows returns within 30 days."],"top_n":2}'
```

Also speaks the exact Cohere v2 (`POST /v2/rerank`) and Voyage (`POST /voyage/v1/rerank`) request
and response shapes, so their official SDKs work unmodified with just a `base_url` override — see
`https://trigeochiral.com` for details.

## License

MIT
