<p align="center"><img src="https://raw.githubusercontent.com/fletch-now/fletch-mcp/main/docs/fletch-logo.png" width="160" alt="Fletch"></p>

# fletch-mcp

Fletch's Robinhood Chain registry as [MCP](https://modelcontextprotocol.io) tools: verified
Stock Token addresses, live state (multiplier, pauses, Chainlink price, holders), round
history, lookalike tokens, the issuer's control plane, chain health and the changelog.
A thin client of the public API at https://fletch.now; registry reads need no key.

```
npx -y github:fletch-now/fletch-mcp
```

This runs from GitHub. npm publication is pending. To check an installable
tarball from a checkout, run `npm ci --ignore-scripts`, `npm run test:package`
and `npm pack`. See [the release guide](https://github.com/fletch-now/fletch-mcp/blob/main/docs/RELEASING.md) for publishing.

[fletch.now/developers](https://fletch.now/developers) ·
[API reference](https://fletch.now/api/v1/docs) ·
[Registry](https://fletch.now/registry) ·
[llms.txt](https://fletch.now/llms.txt)

## Use

Configure a stdio server in your MCP client:

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

## Catalog workflow

1. Call `app_catalog` with `{ "q": "FRONG" }` for app status and source age.
2. Call `token_markets` with the same query for contracts, price, volume,
   capitalization and their observation records.
3. Call `events` with `{ "kind": "listing.", "limit": 10 }` for recent observations.
4. Check `status` for pending searches, contract checks and stale jobs.

`display_only` means a price feed without app trading. `tradable` follows the
catalog fields; per-account restrictions remain in `pairs`. No contract match
is a valid result. A ticker match does not verify identity. Follow `nextOffset`
with `offset` to read another catalog page. Source errors and ages remain visible.
The API stream supports continuous delivery; this MCP tool reads one bounded page.

## Environment

- `FLETCH_API_URL`: where the API lives. Default `https://fletch.now`.
- `FLETCH_API_KEY`: optional. Needed only by `webhooks`, which reads one account's own
  endpoints. The key is sent to `/api/v1/webhooks` and to no other route, and never over
  plain http; with an `http://` base the `webhooks` tool returns an error instead.
  Redirects are refused, including same-origin redirects. Failure messages omit
  upstream bodies and configured keys; successful text also redacts the configured
  key if an upstream happens to echo it. Configure only a trusted API base.

Rate limits are the API's: anonymous callers get 120 requests a minute per address, and
a key has its own budget of 600 requests an hour. Every tool result is cached by ETag, so
repeating a question costs a conditional request that usually answers 304. The cache
keeps at most 200 entries for at most ten minutes each.

## Tools

| Tool | Reads |
|---|---|
| `token_discoveries` | latest recorded addresses, including community tokens; first observation, metadata-check time and independent trust; 20 rows by default, at most 50 |
| `search_contracts` | recorded contracts by ticker, name, address or supported link; bounded pages retain label sources and separate trust verdicts |
| `status` | is the registry live: jobs, figures, ages, verdicts |
| `list_assets` | every asset with state; `q`, `symbols`, `fields` (lookalikes, corporateActions, multiplierHistory, feedRounds, concentration) |
| `get_asset` | one ticker with history, lookalikes and last rounds |
| `history` | one row per UTC day of every per-asset number, each row one reading rather than a close; `at`, `from`, `to`, `days`, `fields` |
| `feed_rounds` | Chainlink rounds for a ticker, `since`, `limit` |
| `holders` | how much of a token is in investors' hands: the six shares (float, pools, issuer, bridge, contracts, unchecked, which add to 100), holders with share and address labels, ledger progress. Float is a floor: the probe checks holders above a ten-thousandth of supply |
| `activity` | daily transfers, volume, DvP, off-hours |
| `get_token` | resolve one exact mainnet address, retaining trust, metadata nulls and provenance |
| `filter_catalog` | current market filter values, thresholds, labels and presets from the public API |
| `app_catalog` | Robinhood crypto-catalog status, scope, account availability, source and age; q/status filters and offset pagination |
| `stock_pairings` | all discovered stock/community pools, stable IDs, metadata status and complete filtered counts; address/limit/offset pagination |
| `token_markets` | paginated token contracts with combined filters, selected-pool readings, trust and source times; 25 or 50 rows |
| `search_pools` | one filtered pool page, 20 rows by default, ordered by volume; no automatic full-registry load |
| `pools` | pools trading one ticker on every DEX read (Uniswap v4 and v3), deepest first: venue, price, `depthUsd` (V3 quote holdings or V4 bounded 1% quote estimate), raw liquidity L, premium to feed, and how far each venue's scan has read |
| `dex_venues` | tracked venues: pools, dollar-priced pools, distinct V3 quote holdings or V4 bounded 1% estimates, swaps and volume, assets priced there, and whether each venue has been read at all |
| `bridge` | L1 escrow vs L2 supply, deposits, withdrawals |
| `issuer_documents` | prospectus, Final Terms per ticker, watched pages |
| `lookalikes` | tokens borrowing a listed ticker, with verdicts |
| `control_plane` | the issuer's registry contract and its events |
| `chain_health` | head, block time, batches, status |
| `events` | the changelog, filterable, with a cursor |
| `corporate_actions` | dividends and splits in progress |
| `webhooks` | your registered alert endpoints (needs `FLETCH_API_KEY`) |

Resources: `llms.txt` and the OpenAPI document.

Answers that read live state carry the instant the registry daemon took the reading
(`checkedAt`, `takenAt` or `stateCheckedAt`); `events` rows carry `occurredAt` and
`observedAt`; `corporate_actions` carries Robinhood's `processDate` only; `webhooks` reads
account data rather than daemon output. Amounts in raw units are strings; prices and
multipliers are numbers.

## What the server covers

The tools read Robinhood Chain mainnet (chain 4663) only, and they cover the registry
routes plus the webhook list. The API has more than this server exposes: `/chains`, the
watcher routes, the event stream at `/api/v1/chains/4663/events/stream`, and the build and project routes
are reachable over HTTPS as documented at
[fletch.now/api/v1/docs](https://fletch.now/api/v1/docs) but have no tool here.

`docs/` holds dated copies of `llms.txt` and `openapi.json` as served the day this
version was cut, which was before the package reached npm, so the `llms.txt` copy still
calls the MCP server unpublished. The live documents at https://fletch.now/llms.txt and
https://fletch.now/api/v1/openapi.json are the ones to trust.

## Development

```
npm ci
npm test
npm run test:package
```

The test starts `index.mjs` over stdio with the SDK's own client, checks the tool and
resource counts, replays the ETag and bearer rules against local http and https servers,
and calls `status` against https://fletch.now. CI runs the same test on Node 20, 22 and 24.
The https server uses the self-signed pair under `test/fixtures/`, which guards nothing
outside that test.

`test:package` installs the npm tarball in a temporary application and runs the
local stdio checks against its executable and installed dependencies. It checks
all 25 tools, the resource definitions and credential handling without making
live API requests. Dependency installation uses npm; the temporary application
is removed when the check finishes.

## Licence

MIT. Fletch is not affiliated with Robinhood Markets, Inc.

## Current data and snapshots

The tools read the deployed API; status timeliness does not mean all figures are
fresh. Inspect `metadataBacklog`, coverage and each observation timestamp.
`stateCurrent=false` means current pool price, depth, valuations and changes are
unpublished; preserve their nulls. A ticker or lookalike match does not verify an
address. Pool swap fields require a complete current rolling 24-hour window.
`volumeValuation` distinguishes nominal USDG denomination from historical WETH
oracle estimates and retains source ages and coverage reasons.

Use `get_token` for one address and `search_pools` for one bounded filtered page.
The resources remain opt-in; the server never fetches the full registry automatically.
Human-readable token pages use `/registry/markets/{address}`; JSON remains at
`/api/v1/tokens/{address}`. For public apps, link the current returned `app.slug`
at `/published/{slug}`. Owners can rename a listing while keeping its hosted URL.
Old directory URLs redirect only while the current listing passes public checks.
[The agent guide](https://fletch.now/skill.md) gives a task-to-endpoint table and
explains network, authentication and observation-age boundaries.
[Full agent reference](https://fletch.now/llms-full.txt) and
[live schema](https://fletch.now/api/v1/openapi.json) describe current behavior.
The dated 5 and 8 September documents remain historical;
`docs/openapi-2026-09-10.json` and `docs/llms-2026-09-10.txt` capture the deployed
contract for that historical update. The latest checked contract, including token discoveries, is recorded in [the 15 September snapshot](docs/SNAPSHOT-2026-09-15.md). Older snapshot notes retain their original fetch times and hashes.

All tools declare read-only, non-destructive, idempotent, open-world annotations.
These are client hints; account routes still enforce their own authentication.
Token resolution may refresh server-side metadata observations without changing
an account or sending a chain transaction. Changelog cursor reads return the full
sequence: apply kind/symbol filters locally and preserve `nextCursor` after each
processed batch. No returned events does not establish indexing health.

## Market filter contract

Call `filter_catalog` to discover the same filter options used by Markets, then
pass a combination to `token_markets`. Filters combine with AND. Numeric sorts
put unavailable observations last; a zero minimum still requires a usable
reading. V3 quote holdings and V4 bounded 1% depth remain separate measures.

The input enums in `generated/market-filters.json` are generated from the public
catalog. After the matching API release is active, run `npm run generate:filters`
and the offline tests before publishing a client update. No market observations
are bundled in that catalog.

## Structured observation contract

`token_markets` and a token's `reading` preserve each metric's `observation`:
source ID, pinned block/hash when known, upstream `sourceAt`, separate
`fetchedAt`, inclusive `expiresAt`, computation `method`, `parameters`, recursive
`inputs` and coverage. `status` describes current/stale/missing/invalid age;
`readStatus` independently describes ok/partial/failed/unread source access.
Current retained values can coexist with a failed latest refresh. Compare the
expiry with the current clock even after an ETag response, and preserve nulls.

Market cap expires with the earliest required input: supply and burn balances,
decimals and selected-pool price. Volume retains its historical quote inputs and
valuation assumptions. Economic `selection` carries its observation time,
expiry and versioned policy; it cannot establish issuer identity. A beacon
match describes a dependency, with no exception to collision checks.

Status jobs expose nullable `metricCoverage`: eligible/current/failed/unread
counts, oldest input age and measurement time. Current and failed counts can
overlap. Missing coverage has no implied completeness, and a recent job cannot
refresh older metrics. The server forwards these facts unchanged using only the
requested tool read; schema and full documentation resources remain opt-in.

The reliability release's exact public schema snapshot and source hashes are in [the snapshot record](docs/SNAPSHOT-2026-09-10-reliability.md).

### Stock Token identity and discovered pools

Call `stock_pairings` with
`{"address":"0xd0601ce157db5bdc3162bbac2a2c8af5320d9eec","limit":50,"offset":0}`
for NVDA's discovered stock/community pools. Follow `nextOffset` until null;
`token_markets` includes at most three grouped examples and full counts in
`stockPairingSummary`. Deduplicate pages using stable pairing `id`, since new
observations can reorder a live catalog. Metadata may be pending, failed or stale;
an unknown symbol or missing swap stays null.

`robinhoodApp.scope` is `crypto_currency_pairs`, which excludes the separate
Stock Token list. `not_covered` is the Stock Token result; legacy `not_in_app`
means absent from this crypto source only. Read `stockToken` for independently
verified list membership, address and source age. A ticker alone cannot verify
an app contract or establish issuer origin.

Crypto-catalog reads target 15 seconds; the separate Stock Token list sync targets
15 minutes. Six-hour `canonical` checks observe listed contracts’ beacon
dependencies and code. Preserve each source and verification time separately.

`status.lookalikes` exposes completed/pending/failed searches and beacon backlogs
at `measuredAt`. Minute-level worker passes can still have unfinished catalog coverage; inspect
completed, pending and failed counts instead of treating cadence as full coverage.
The Status `swaps` figure is the count in complete current 24-hour windows for
selected canonical pools, with that scope stated in its description and unit.

The `lookalikes` tool also accepts `kind`, `limit` and `offset`. Follow `nextOffset`
for all matching contracts. The legacy `unlisted_stock` filter maps to
`unverified`; a matching beacon is dependency evidence, not proof of issuer deployment.


### Sorting and pagination

`token_markets` supports `sort: "price" | "volume" | "market_cap" | "pools"` plus
existing sorts, and `order: "asc" | "desc"`. Numeric sorts default descending;
name defaults ascending. Sorting covers all matching tokens before pagination,
with unavailable values last and stable contract-address ties in either direction.

`list_assets` also accepts `type`, `verified`, `state`, `sort`, `order`, `limit`
(1–50) and `offset`. Supplying limit or offset enables a paginated response with
`total` and `nextOffset`; omit both for the complete collection. Follow nextOffset.

Nearby Markets requests can share raw database observations for ten seconds.
Source ages, metric expiry and numeric filters are recomputed for each response;
a repeated sort does not refresh upstream evidence. Pairing summaries retain asOf.