Routescore
Read-only pre-sign evidence for onchain agents: route quality, MEV exposure, clear/caution verdict.
Open source Repository Open in the app JSON README (API)
About
Read-only pre-sign evidence for onchain agents: route quality, MEV exposure, clear/caution verdict.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- io.routescore
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 0.3.5
- Last push
- 2026-07-14T18:11:33Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:01:45
- Updated
- 2026-08-29 04:01:45
- Origin id
io.routescore/mcp
README
# @routescore/mcp
**The read-only pre-sign evidence layer — a "pre-sign journal" — for onchain agents.**
Before an agent (or you) signs a swap onchain, `check_swap` returns a modeled
read of route quality, MEV/execution exposure, and token-registry recognition as
a `clear / caution / unsupported` verdict with its caveats — and persists a
hash-verifiable record of exactly what was known before signing, re-verifiable
offline. That record is the pre-sign journal. It is read-only: it never signs,
executes, routes funds, or custodies assets.
An [MCP](https://modelcontextprotocol.io) server (and a keyed REST API) for
Claude, Codex, Cursor, and any MCP-capable agent — a thin, stateless wrapper
around the Routescore public API, storing no request or response data locally.
**`check_swap` is free.** A free API key runs 100 pre-sign checks/day (Pro
1,000/day, Power 10,000/day); the modeled premium-estimate tools,
`simulate_scenario`, and persisted-record *retrieval* are Power-tier. Generate a
key at **Account → Developer → API & MCP access** (`/account`) — free to mint on
any plan. Keys look like `rs_live_…` and are shown once.
See how these modeled reads have tracked measured on-chain outcomes on the public
[calibration surface](https://www.routescore.io/calibration) — Routescore
publishes its own accuracy (Brier score, ECE, coverage), re-derivable from a
bound source manifest.
## Setup
Add the server to your MCP client config and set your key in the env block.
**Claude Desktop** (`claude_desktop_config.json`) / **Cursor** (`.cursor/mcp.json`):
```json
{
"mcpServers": {
"routescore": {
"command": "npx",
"args": ["-y", "@routescore/mcp"],
"env": {
"ROUTESCORE_API_KEY": "rs_live_your_key_here"
}
}
}
}
```
**Claude Code** (CLI):
```bash
claude mcp add routescore --env ROUTESCORE_API_KEY=rs_live_... -- npx -y @routescore/mcp
```
Optional env:
- `ROUTESCORE_API_URL` — override the API base (default `https://www.routescore.io`).
Useful for local development: `http://localhost:3000`.
The server checks the key at startup: if `ROUTESCORE_API_KEY` is missing or
does not match the minted key shape (`rs_live_` followed by 64 lowercase hex
characters), it exits immediately with an actionable error instead of
failing on the first tool call. The configured value is never echoed. This
is a shape check only — real key verification stays server-side (run the
`whoami` tool).
## Tools
| Tool | What it does |
|---|---|
| `quote_mev_cover` | Modeled premium estimate for MEV-sandwich exposure on a swap (modeled premium, expected/CVaR loss). |
| `quote_bridge_refund` | Modeled premium estimate for cross-chain bridge execution failure vs a modeled SLA expectation. |
| `quote_lrt_slashing` | Modeled premium estimate for slashing risk on an LRT position given AVS exposure. |
| `simulate_scenario` | What-if Monte Carlo: modeled expected premium vs refund/loss over a horizon. |
| `check_swap` | Pre-trade check an agent runs before it signs: modeled route quality, price-impact / slippage band, modeled MEV/execution exposure where observable, and a token registry read (recognized vs unverified), as a `clear / caution / unsupported` verdict. Supports Ethereum (1) and Robinhood Chain (4663). Recognition is not safety, sellability, rights, redemption, liquidity, or investment-quality verification. Decision support, not execution. Every keyed call also attempts to persist a hash-verifiable evidence record and returns its `record_id`, `evidence_bundle_id`, and `record_output_hash` — null, with a `record_persistence_failed` caveat, if the record store is unavailable. |
| `get_preflight_record` | Fetch one persisted preflight evidence record by `record_id` (owner-scoped to the configured key's account). The record embeds the original check response verbatim plus a canonical-JSON SHA-256 integrity hash so the evidence can be re-verified offline. Read-only evidence: record creation rejects known execution-material keys (calldata, transaction payloads, signing material) and drops identity-shaped labels from the actor context. |
| `get_detector_manifest` | Latest public MEV-detector run manifest (version hash + universe). |
| `whoami` | Confirm the key works and report its plan tier. |
All `quote_*` tool results are **modeled, point-in-time premium estimates** —
decision support only, **not** a live cover, insurance, refund, or
premium-acceptance offer. Routescore does not underwrite risk.
## Output contract
Routescore MCP is decision support, not execution infrastructure. `check_swap`,
quote, and scenario tool results preserve the same trust envelope as the REST API, and the
wrapper marks output as degraded if the upstream API ever omits required trust
fields.
`check_swap` answers `verdict: unsupported` as an HTTP 422 with a full
evaluated body — an answer, not an error. The wrapper relays those evaluated
422 bodies as normal structured tool results (gap-state fields, caveats, and
record linkage included) so agents receive "not evaluated" as first-class
evidence; true errors (400/401/403/404/429/5xx and non-evaluated 422 error
envelopes) still surface as tool errors.
Downstream agents and dashboards should render the trust-envelope fields by
default (abbreviated example):
```json
{
"score_state": "partial",
"source_freshness": {
"state": "partial",
"checked_at": "2026-06-21T00:00:00.000Z",
"sources": [
{ "name": "routescore_backend", "freshness_state": "fresh" },
{ "name": "bridge_risk_labels", "freshness_state": "unknown" }
]
},
"methodology_version": "routescore.public_api.v1",
"confidence_band": { "low": null, "high": null, "unit": "bps" },
"caveats": [
"Modeled, point-in-time decision support. Not an execution guarantee.",
"Unsupported or stale inputs widen uncertainty instead of hiding risk."
],
"commercial_disclosure": {
"paid_placement": false,
"score_influenced_by_partner": false
}
}
```
## Local development
```bash
npm install
npm run build
ROUTESCORE_API_KEY=rs_live_... ROUTESCORE_API_URL=http://localhost:3000 node dist/index.js
```
Then point [MCP Inspector](https://github.com/modelcontextprotocol/inspector)
at the command, or wire it into a client config as above.
### Public Reddit research utility
The retail-research workflow includes a standard-library parser for a saved,
publicly rendered old Reddit thread. It extracts public handles, comment counts,
IDs, and permalinks without logging in or attempting to recover deleted authors:
```bash
python3 scripts/scrape_reddit_public_handles.py /path/to/thread.html \
--csv work/reddit-public-handles.csv \
--json work/reddit-public-handles.json
```
The input must be HTML already obtained from a public `old.reddit.com` thread.
The parser does not fetch pages or bypass Reddit access controls.
## Notes
- Scenario and quote outputs are modeled decision-support, **not investment advice**.
- MCP does not custody assets, execute transactions, route funds, or guarantee
outcomes.
- Rate limits apply per key; responses carry `X-RateLimit-*` headers.