Forkcaster MCP server

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 providers (worker/cast-source.ts, rpc-racer pattern) — see "Cast source race" below. shim (https://shim.artlu.xyz/wc/{username}/{hash}, owner-run Snapchain reader with a keep-warm cron) is the completeness anchor and the sole ban-signal dependency (/signed/{fid}); farcaster.tv is fast but quote-blind; raw nodes haatz/snap.farcaster.xyz:3381 are complete but need shim /f/{username} for the fid and a full hash. All upstream calls are capped at 5s.
• Missing cast: an authoritative miss from a complete provider (shim, haatz, snap) → 404 page; no provider resolved → link-only page (200). 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

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

Shortened. The full README is on GitHub.