vigia-edgar

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

> **Public copy & quickstart live in [`mcp/README.md`](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
```