vigia-edgar

vigía EDGAR — Always-on SEC EDGAR watcher (Form 4 / 8-K alerts)

Public copy & quickstart live in mcp/README.md. This root README is the developer/architecture doc for the two-layer system (engine + skin).

An always-on engine that watches US SEC EDGAR for you and queues an alert about ~45 seconds (median, under ~2 min worst case — fast polling, not instant/real-time) after the SEC accepts an insider Form 4 or a company's 8-K. Set a ticker watchlist (AAPL, TSLA, NVDA…) and your AI agent gets insider-trading and material-event alerts on Claude, Cursor, or any MCP client — no setup on your side. Free: 1 ticker. Pro ($29): unlimited tickers.

Latency, stated honestly: about 45 seconds median from when the SEC accepts a filing, under ~2 minutes worst case (measured on the EDGAR getcurrent feed). The engine polls fast and never sleeps.

Why this needs an MCP server (the moat)

An LLM agent on its own cannot watch EDGAR 24/7. The value here is infrastructure that never sleeps: a cron-driven engine continuously polls the SEC, dedupes every filing, and keeps a per-user cursor so your agent only ever sees what's new. The agent just asks; the engine has already been watching.

Tools

watch_insider(tickers: string[])

Register US tickers to monitor (Form 4 + 8-K). Resolves each ticker to its SEC CIK and starts watching. Returns the resolved list and any tickers it couldn't find.

get_alerts()

Return new filings detected for your watched tickers since your last call (a per-user cursor advances automatically, so you never get duplicates). Each alert includes: ticker, company, formType, category (insider | material_event), accession, acceptanceTime, detectedTime, latencySeconds, and a direct filingUrl.

Architecture

Two layers:

• Engine (Cloudflare Worker + D1): a cron trigger polls EDGAR's getcurrent atom feed every minute (two polls ~30s apart per tick → ~30s effective cadence). It dedupes accession numbers, matches filings to watched companies by CIK (robust to name changes), and stores matches in D1. State: seen (dedupe), watches (per-user CIKs), alerts, cursors (per-user delivery), ticker_map (refreshed daily from company_tickers.json).
• Skin (this MCP server, hosted on MCPize): exposes the two tools and reads/writes the engine over an authenticated HTTP API (/watch, /alerts). MCPize handles auth and billing.

Per-user isolation: set WATCH_NAMESPACE (your own key) in the MCP server config to keep your watchlist and cursor private. Defaults to default.

SEC compliance

All requests to the SEC use the required identifiable User-Agent and stay well under the 10 req/s limit (the EDGAR feed is polled once per cron cycle).

Configuration (env / secrets)

• WORKER_URL — base URL of the Cloudflare engine.
• VIGIA_KEY — shared secret the skin uses to call the engine.
• WATCH_NAMESPACE — per-user watchlist namespace (optional; defaults to default).

Funnel instrumentation

The engine counts four product numbers in the D1 funnel table (one aggregate row per namespace, idempotent upserts — negligible cost):

1. installs — namespace connected the MCP (first /watch)
2. activations — actually used it (resolved a ticker, or pulled /alerts)
3. wall_hits — bounced off the Free 1-ticker cap (hunger for Pro)
4. conversions — paid → Pro active (Stripe-verified)

Read them (admin, needs X-Vigia-Key):

GET /admin/funnel            -> { funnel: { installs, activations, wall_hits, total_wall_hits, conversions } }
GET /admin/funnel?detail=1   -> also returns per-namespace rows

Or straight from D1:

SELECT COUNT(installed_utc)  installs,
       COUNT(activated_utc)  activations,
       COUNT(first_wall_utc) wall_hits,
       COUNT(converted_utc)  conversions
FROM funnel;

Repo layout

worker/   Cloudflare Worker engine (cron + D1)  — npx wrangler deploy
mcp/      MCPize MCP server (the 2 tools)        — npx mcpize deploy