Xyz MCP

forkcaster — agent brief

Audience: coding agents. Prefer facts over prose. Update this file when architecture or commands change.

Intent

Micro-site that mirrors Farcaster cast URLs for sharing without the Farcaster app.

• Pattern: /{username}/{castHash} where castHash matches 0x[0-9a-fA-F]+ — short or full form
• Examples: /zoo/0x895ecc74 and /decent-artlu/0xbb54368f → SSR cast card + links
• Data: raced across a fleet of sources (worker/cast-source.ts + worker/shim.ts on the shared worker/race.ts kernel) — see "Cast source race" below. shim (https://shim.artlu.xyz/wc/{username}/{hash}, owner-run Snapchain reader with a keep-warm cron) anchors completeness and hosts the ban-signal read (/signed/{fid} — fleet-raced like every shim read); farcaster.tv is fast but quote-blind; raw nodes haatz/snap.farcaster.xyz:3381 are embed-complete but text-blind (the gateway strips the mention placeholder characters from text — shim owns the @username substitution — so mention-bearing raw wins are held until canonical text settles or is proven unavailable) and get the fid by racing the shim fleet's /f/{username} against their own /v1/userNameProofByName (first numeric answer wins, loser aborted; the shim-side winner is labeled with its fleet member id), plus a full hash requirement (castById 400s on short hashes). All upstream calls are capped at 5s.
• Missing cast: a consensus miss — every miss-authoritative source consulted and missed — ⇒ 404 page; every source errored ⇒ link-only page (200). No single source's miss is a verdict. All upstream calls are capped at 5s (AbortSignal.timeout) — shim's cold sharded lookups can otherwise hang 15s+; timeout ⇒ unreachable. Strict statuses are the JSON variant's job (see below)
• Banned accounts: embeds render for everyone — but some clients hide unsigned authors. Since Oct 15, 2026 (Network School takeover), accounts must accept the "social smart contract" (Network Code); acceptance is an on-chain access NFT. Shim exposes it: GET https://shim.artlu.xyz/signed/{fid} → {"signed":true|false}. Unsigned authors: registry clients flagged requiresSigned (e.g. farcaster) are suppressed from the action row; the check fails open — unknown state suppresses nothing
• farcaster.tv as a cast data source is quote-blind (it drops {castId} embeds) and unofficial — it races as the partial tier only (700ms HTML box, client-side quote fill-in). react-farcaster-embed's own default endpoint is farcaster.tv — always pass castData so it never fetches. The live stats row (replies/recasts/likes) is still fetched client-side from farcaster.tv — it sends access-control-allow-origin: * and answers for unsigned authors too; any failure just leaves the row absent

Architecture

The system is a waypoint layer over Farcaster: every public URL shape maps to exactly one canonical surface, and every page answers one question — *which app opens this?* There is no database, no KV, and no edge cache on this side — data is raced across a fleet of sources on every request. The product is the routing verdict, not stored content.

Cloudflare Worker (Hono; dual-domain; registration-order routing)

├─ routes: cast · profile · casts-page · aliases · mcp · /transparency · /api · /t ├─ RESOLUTION KERNEL — worker/race.ts │ staggerDelays · collectTerminals · collectiveRace │ ├─ raceShimProbe — every shim-shaped read (profiles, quotes, signed, │ │ aliases, MCP): cloud + the potato fleet │ └─ raceCast — provider roster (shim ∥ potatos ∥ haatz ∥ snap ∥ │ farcaster.tv) + completeness box + race telemetry ├─ SOURCES: shim (cloud) · potato fleet (replicas) · haatz/snap (raw │ nodes) · farcaster.tv (partial, quote-blind) ├─ RENDERERS: resolve once, render twice — SSR HTML + strict JSON twin ├─ STATEFUL LAYER: fc_client cookie → last-used badge, auto-open, pill │ order (client-side writes; the server only reads) └─ TELEMETRY: one anonymous Analytics Engine datapoint per resolve → offline snapshots → /transparency

Verdicts are collective — no single host is the source of truth. Fleet legs start staggered (tiny random steps behind the leader; a fast winner cancels the stragglers before they fire). The first affirmative answer wins; a consulted miss (asked, no data) is a vote — not-found settles only when every miss-authoritative leg has consulted and missed; errors surface only when every leg errored. Any one host — including cloud shim — can die without changing a single verdict. The price is deliberate: a true miss resolves as fast as the slowest leg, not the fastest.

Consumer-matched strictness. HTML fails open — a human always gets a page (found → card, partial → self-healing card, unreachable → link-only). JSON is the strict record (404 / 503 + Retry-After, availability-gated fields, quotes never dropped). Chat link-preview bots get HTML + OG meta unconditionally: negotiation is ?format=json / Accept, never UA sniffing, and SSR output is byte-identical for every device.

Design laws (enforced everywhere; detail in the sections below):

• Waypoint law — one surface per account; aliases redirect, never render.
• Identity law — the fname is the PRIMARY handle everywhere; ENS names are attestations.
• Echo-the-valid-input — first-party links carry the gate-validated route input; display, OG, and client targets carry the primary.
• Privacy: no identifiable tracking, only analytics. One anonymous click datapoint per client selection; the negative list (no cast IDs, no usernames, no IPs, no UA strings, no identifiers) is verbatim-checkable in worker/track.ts and declared on /transparency. Pages make no third-party requests — logos are self-hosted because a hotlinked logo would leak every visitor's IP to that client's servers. The one cookie carries a client slug, nothing else.
• Personalization is client-side on cast pages. The page shell (the client sheet's pills included, gates applied) is cookie-blind server-side; SHELL_SCRIPT reads the local fc_client cookie and applies the last-used badge, the resolution-first primary ("Open in X" — a direct anchor with the pill's exact wiring — beside a muted "More apps" sheet trigger), and the auto-open state machine after parse (the sheet's auto-open toggle syncs from the same cookie). That is what makes the full page — cookie-holders included — servable from the 12h edge shell; profiles cache 10 minutes (they are mutable) under the same client-side model. Bump SHELL_SALT in worker/edge-cache.ts to invalidate every shell (there is no global purge; v3 dropped the pre-sheet UI — bare pill row + on-page auto-open chip; v4 reached cached shells with the Safari-safe sheet CSS; v5 reached them with the kind-aware chooser copy and single-offer bare-row shape).
• Registry as the one roster — clients and their verification provenance are enumerated exactly once, in worker/client-registry.ts.

Stack

Commands

bun install

bun run dev # wrangler dev (local worker + assets) bun run build # vite build → dist/ bun run typecheck # bun check (tsc-compatible; reads tsconfig*.json) bun run deploy # build + wrangler deploy bun run lint # biome lint . bun test # worker tests (cast route + client registry) bun run cf-typegen # wrangler types → worker-configuration.d.ts

Layout

/

├── index.html # SPA shell → /src/main.tsx ├── vite.config.ts # preact + cloudflare + react→preact aliases ├── wrangler.jsonc # main=worker/index.ts; not_found_handling=none ├── public/farcaster-embed.css # linked from SSR HTML ├── public/logos/ # per-client marks for the action row ├── quilcast-router-shortcut.md # the iOS/macOS share-sheet router: mapping, build/sign, distribution ├── shortcuts/ # generated .shortcut artifact (unsigned; bun run shortcut:quilcast) ├── worker/ │ ├── index.ts # Hono app; export { app }; default { fetch } │ ├── client-registry.ts # client registry (verified templates; zero-dep, vendored-able) │ ├── clients.ts # fc_client cookie binding (last-used + auto-open prefs) │ ├── shim.ts # shim identity client (routes, ShimCast/ShimUser, /wc /h /f /u /user /casts-and-replies /signed, /refresh as the index warmer; fleetBases parses the fleet var) │ ├── race.ts # fleet-race kernel: RaceLeg, staggerDelays, collectTerminals, collectiveRace — shared by cast-source + shim │ ├── cast-source.ts # provider race: shim ∥ potato fleet ∥ haatz ∥ snap ∥ farcaster.tv (+ the /~/{hash} hash-only rescue); fleet stagger + collective miss parity │ ├── cast-page.tsx # resolve (race) → render orchestration: SSR / 404 / link fallback │ ├── cast-data.ts # pure Shim → embed-data mapping + embed helpers │ ├── cast-actions.tsx # client sheet — chooser shapes (single-offer bare row / trigger + dialog), pills byte-identical inside │ ├── cast-scripts.ts # inline client scripts (TRACK/CLIENT/DEEPLINK/AUTO/LIVE_STATS/QUOTE_FILL) │ ├── profile-page.tsx # profile landings: resolve-once/render-twice, waypoint law │ ├── warpcast.ts # Warpcast channel API client (zod contract; /v1/channel — keyless, first-party) │ ├── channel-page.tsx # channel landings: resolve-once/render-twice, waypoint law │ ├── shell.tsx # shared page frame (head/meta/CSS/footer) — cast pages + profiles + /transparency │ ├── cast-ref.ts # MCP cast-ref: zod contract + shim-direct resolution │ ├── mcp.ts # MCP SDK v2 server factory (get_cast_link) — only SDK import site │ ├── cast-route.test.ts # bun:test; mock.module + exact-URL fetch mock │ ├── clients.test.ts # registry unit tests: templates, gating, signed rule, deeplinks │ ├── cast-source.test.ts # race unit tests: eligibility, box, miss/error, abort, adapter mapping │ ├── race-stats-store.ts # lmdis snapshot read-through TTL cache (10min TTL / stale 24h / 2s cap) │ ├── fid-race-store.ts # mirror of the above for the "Author id races" snapshot (key fid-race) │ ├── vendor/lmdis-sdk.ts # vendored lmdis SDK (Upstash-shaped seam; get/set only) │ └── shims/server-only.ts # empty stub for Next.js marker package ├── scripts/ │ ├── race-stats.ts # offline stats job: AE SQL → snapshot → lmdis (dotenvx env; --dry) │ ├── race-stats-lib.ts # pure query builders (fixture-