vigia-edgar

vigía EDGAR — 全天候 SEC EDGAR 监控器（Form 4 / 8-K 警报）

公开说明和快速入门见 mcp/README.md。 此根目录 README 是两层系统（引擎 + 外壳）的 开发者/架构文档。

全天候运行的引擎，为你监控美国 SEC EDGAR，并在 SEC 接受内部人士提交的 Form 4 或公司提交的 8-K 后约 45 秒（中位数， 最慢不到约 2 分钟——快速轮询，并非即时/实时）排队发送警报。设置股票代码观察列表（AAPL、TSLA、NVDA……），你的 AI Agent 就能在 Claude、Cursor 或任何 MCP 客户端上收到 内部交易和重大事件警报——你无需进行任何设置。免费版：1 个股票代码。Pro（$29）：不限股票代码。

延迟，如实说明： 从 SEC 接受申报文件起，中位数约为 45 秒， 最慢不到约 2 分钟（基于 EDGAR getcurrent 信息流测量）。引擎会快速轮询， 从不休眠。

为什么这需要 MCP 服务（护城河）

LLM Agent 本身无法全天候监控 EDGAR。这里的价值在于永不休眠的基础设施：由 cron 驱动的引擎持续轮询 SEC，对每份申报文件去重，并为每位用户维护游标，因此你的 Agent 只会看到新内容。Agent 只需提出请求；引擎早已在持续监控。

工具

watch_insider(tickers: string[])

注册要监控的美国股票代码（Form 4 + 8-K）。将每个股票代码解析为对应的 SEC CIK 并开始监控。返回解析后的列表以及无法找到的股票代码。

get_alerts()

返回自上次调用以来检测到的、与你观察的股票代码相关的新申报文件（每位用户的游标会自动前进，因此不会收到重复内容）。每条警报包含：ticker、company、 formType、category（insider | material_event）、accession、acceptanceTime、 detectedTime、latencySeconds 和直接的 filingUrl。

架构

两层：

• 引擎（Cloudflare Worker + D1）： cron 触发器每分钟轮询一次 EDGAR 的 getcurrent Atom 信息流（每次触发轮询两次，间隔约 30 秒 → 实际轮询频率约为 30 秒）。它对 accession 编号去重，按 CIK 将申报文件与观察的公司匹配（可稳健应对名称变更），并将匹配结果存储在 D1 中。状态：seen（去重）、watches（每位用户的 CIK）、alerts、cursors（每位用户的投递记录）、 ticker_map（每日从 company_tickers.json 刷新）。
• 外壳（此 MCP 服务，托管于 MCPize）： 提供这两个工具，并通过经过身份验证的 HTTP API（/watch、/alerts）读写引擎。 MCPize 负责处理身份验证和计费。

按用户隔离：在 MCP 服务配置中设置 WATCH_NAMESPACE（你自己的密钥），以保护观察列表和游标的私密性。默认值为 default。

SEC 合规性

所有发往 SEC 的请求都使用规定的可识别 User-Agent，且远低于每秒 10 次请求的限制（每个 cron 周期只轮询一次 EDGAR 信息流）。

配置（环境变量 / 密钥）

• WORKER_URL — Cloudflare 引擎的基础 URL。
• VIGIA_KEY — 外壳用于调用引擎的共享密钥。
• WATCH_NAMESPACE — 按用户区分的观察列表命名空间（可选；默认值为 default）。

漏斗指标

引擎在 D1 的 funnel 表中统计四项产品指标（每个命名空间一条聚合记录，通过幂等 upsert 写入——成本可忽略不计）：

1. installs — 命名空间已连接 MCP（首次调用 /watch）
2. activations — 实际使用了它（解析了股票代码，或拉取了 /alerts）
3. wall_hits — 因超过免费版 1 个股票代码的上限而受阻（对 Pro 的需求）
4. conversions — 已付费 → Pro 已激活（经 Stripe 验证）

读取这些指标（管理员权限，需要 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

也可以直接从 D1 读取：

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

仓库布局

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