veris

veris

· npx -y veris-mcp

以来源溯源为先的 AI Agent 网络访问。 一次调用即可获得干净的内容 以及 可验证的来源元数据。

如今，AI Agent 阅读网页时，只能看到一大段文本。它无法获知：网页的发布时间、内容自上次查看后是否发生变化、作者是谁、规范来源是什么，或适用哪些许可条款。veris 会为每次读取附加所有这些信息。

web_read("https://example.com/article")
  → clean markdown
  + { publishedAt, modifiedAt, author, canonicalUrl, contentHash, license, fetchedAt }

这些元数据不是锦上添花，而是 AI 网络经济其余部分所需的基础：内容新鲜度、变更检测、引用，以及——最终——向内容创作者付费。

---

为什么要做这个项目

AI 正在抓取网络内容，却不注明来源，也不支付费用。出版商的应对方式是屏蔽机器人并锁定内容。AI 的表现变差，出版商也蒙受损失。解决办法是在 Agent 与出版商之间加入一层，干净地读取内容、追踪来源溯源，并在之后结算付款。

veris 是这一层的Agent 侧——每个 Agent 用来负责任地获取网络内容的 SDK。可以把它想成“面向 AI 网络的 Plaid”：你不拥有出版商，但你拥有开发者会优先选择的集成方案。

路线图（一个代码库，三个阶段）

阶段	内容	状态
1. 清理 + 来源溯源	搜索 / 读取 / 研究，并提供可验证的来源元数据	✅
2. 金融垂直领域	SEC EDGAR 文件，具有权威的官方来源溯源信息	✅
3. 结算	感知许可的访问 + 归属记录账本 + 付款意向	✅ v0.3.0（付款功能为存根，不会发生资金转移）
3b. 实时付款	将支付服务商（RSL 许可服务端 / x402 / Stripe）接入 settlement.ts	🔜

阶段 3：v0.3.0 的功能

每次读取内容前都会先通过策略门控：web_read、web_research、finance_filing_read、URL 监控（watch_manage 会拒绝添加可能无法读取的 URL；watch_check 会将其报告为 withheld 并保留旧基线），以及 veris-mcp digest 中的文件读取。EDGAR 索引查询使用 SEC JSON API，不属于页面读取。

1. robots.txt。 按 RFC 9309，按源获取并针对 VerisBot 标记进行匹配（若无则回退到 *）：最长匹配优先，支持 * 和 $ 通配符；文件缺失时允许，5xx 时禁止。被禁止的 URL 会返回 status: "blocked"，并给出确切规则（例如 Disallow: /cgi-bin），且不会请求该页面。
2. RSL 许可。 从 robots.txt 的 License: 行、<link rel="license" type="application/rsl+xml"> 或内联的 <script type="application/rsl+xml"> 中发现许可。门控会选择覆盖该 URL 的 <content> 范围，以及允许 ai-input 使用的许可。
3. 价格。 如果许可收费（purchase、subscription、crawl、use），工具会返回 status: "payment_required"，并提供条款、价格和 RSL 文档 URL，而非内容。当许可在 robots.txt 中声明时，不会获取页面。priceHint 仅会根据已声明的 <amount> 填充，并原样复制。已付费许可若未提供金额，则报告 price: null；veris 不会估算金额。
4. 账本。 每次读取、拦截和付款要求都会追加到 ~/.veris/ledger.jsonl（可通过 VERIS_LEDGER_FILE 覆盖），记录 URL、内容哈希、时间戳、工具和完整的许可记录。条目采用哈希链，因此可以检测编辑或删除：veris-mcp ledger --verify。使用 veris-mcp ledger [--kind read|blocked|payment_required|payment_intent] [--url U] [--since ISO] [--limit N] 列出条目。
5. 结算占位实现。 对于付费许可，也会记录一条 payment_intent 条目（已声明的价格、条款、许可服务器）。默认提供方为 none：状态为 recorded，不会扣款，内容也会被隐藏。真实提供方可在 src/settlement.ts 中实现 PaymentProvider.authorize() 并通过 setPaymentProvider() 注册。

每个许可字段都会注明其来源（robotsUrl + robotsRule、rslUrl、price.source），因此可以重新获取并核验任何判定。工具输入架构与 v0.2 保持不变。

工具

Web

工具	功能
web_search(query, n?)	按相关性排序的结构化 JSON 结果。Brave（需密钥）或无需密钥的 DuckDuckGo。
web_read(url, fresh?)	URL → 清理后的 Markdown + 来源信息块。缓存 24 小时。
web_research(query, n?)	搜索 + 阅读排名前 N 的结果 + 整合并附上各来源引用。

金融 — SEC EDGAR（免费、官方、无需 API 密钥）

工具	功能
finance_filings(query, formType?, limit?)	股票代码 / 名称 / CIK → SEC 近期申报文件：表格类型、官方申报日期和报告日期、受理编号、文档直达 URL。
finance_filing_read(url or query, formType?)	按 URL 阅读申报文件，或自动阅读公司最新的匹配表格类型文件。清理后的文本 + 来源信息。
finance_financials(query)	来自 SEC XBRL 的营收、净利润、总资产、现金、摊薄后每股收益 — 每项数据均标明其所依据的确切申报文件。

为什么优先使用 EDGAR？ 申报文件直接来自 SEC，包含权威日期和标识符 — 来源信息并非猜测，而是官方数据。免费、结构化、无需身份验证。只需调用一次，Agent 就能获取最新的 10-K 及可验证来源：

finance_filing_read({ query: "NVDA", formType: "10-K" })
  → NVIDIA CORP — 10-K (申报于 2026-02-25)
    清理后的文本 + { source, filed date, contentHash, wordCount }

监控 — 变更检测与提醒

工具	功能
watch_manage(action, target?, formType?)	添加 / 移除 / 列出监控项：公司的 SEC 申报文件（股票代码 + 可选表格类型，如 8-K）或任意 URL（内容哈希监控）。
watch_check()	检查所有监控项；仅返回新增内容（新申报文件 / 已更改页面），并更新基准。按计划运行 → 提醒流。

申报文件监控默认仅关注重大表格类型 — 8-K、10-K、10-Q、20-F、SC 13D/G、 合并代理文件、发行文件、逾期申报通知。由于无人阅读的提醒流比没有提醒流更糟，因此会抑制常规的 Form 4 / 13F-HR 通知。传入 formType: "ALL" 可查看所有内容， 或指定某个表格类型以仅监控该类型。

通过电子邮件发送提醒（veris-mcp digest）

watch_check 会向 MCP 客户端返回 JSON。digest 会将相同数据整理成人们真正会阅读的电子邮件：检查每个监控项，阅读每份新增的重要申报文件，概述变更内容，并发送邮件。

veris-mcp digest --dry-run          # print the digest, send nothing
veris-mcp digest                    # check, summarize, email
veris-mcp digest --to [email protected]      # override recipients
veris-mcp mailtest                  # verify SMTP without sending

每份摘要都包含申报文件中的逐字引文，且发送前会逐条对照来源文本核验 — 无法匹配的引文会在邮件中标记，而不会被当作事实呈现。超过字符预算的申报文件会标记为仅部分阅读；绝不会在不作说明的情况下截断。

环境变量	功能
ANTHROPIC_API_KEY	启用申报文件摘要。未设置时，仍会发送包含原始申报文件通知的摘要邮件。
VERIS_SUMMARY_MODEL	摘要使用的模型（默认值为 claude-opus-5）。
VERIS_SUMMARY_CHAR_BUDGET	摘要所用的申报文件文本字符数（默认值为 250,000）。
VERIS_SMTP_URL	例如：smtps://user:[email protected]:465
VERIS_MAIL_FROM	例如："Veris Alerts <alerts@yourdomain>"
VERIS_MAIL_TO	以逗号分隔的默认收件人。

按计划运行，即可获得实时提醒流：

*/15 * * * * ANTHROPIC_API_KEY=... VERIS_SMTP_URL=... veris-mcp digest

安装

npx -y veris-mcp        # zero-install, always latest

或从源代码安装：

git clone https://github.com/jakeyoung1/veris && cd veris
npm install && npm run build

可选环境变量：

export BRAVE_API_KEY=your_key                      # better search; https://search.brave.com/app/keys
export SEC_USER_AGENT="Your Name [email protected]"    # SEC fair-access policy (recommended)

没有 Brave 密钥时，搜索会自动回退到无需密钥的 DuckDuckGo。SEC 要求 User-Agent 使用 Name email@domain 格式 — veris 提供了默认值，但请设置你自己的联系方式。

在 Claude Code 中使用

将其添加到 MCP 配置（.mcp.json）：

{
  "mcpServers": {
    "veris": {
      "command": "npx",
      "args": ["-y", "veris-mcp"],
      "env": { "BRAVE_API_KEY": "optional", "SEC_USER_AGENT": "Your Name [email protected]" }
    }
  }
}

重启 Claude Code，然后让它执行 web_research 搜索内容。

远程服务（HTTP）

将 veris 作为远程 MCP 服务（Streamable HTTP）运行，并通过 URL 从任意 MCP 客户端连接：

npx -y veris-mcp http                            # http://127.0.0.1:8787/mcp
VERIS_HTTP_HOST=0.0.0.0 npx -y veris-mcp http    # expose it (put TLS in front)

环境变量	作用
VERIS_PORT / PORT	端口（默认值为 8787）
VERIS_HTTP_HOST	绑定主机（默认值为 127.0.0.1）
VERIS_API_KEYS	以逗号分隔的密钥。设置后，/mcp 需要 Authorization: Bearer <key>（或 x-api-key）。未设置则不设限制。
VERIS_RATE_LIMIT	每个 IP 每分钟的请求数（默认值为 60）

可免费、自托管地永久使用。设置 VERIS_API_KEYS 是为了让托管实例能够计量用量。

Docker

docker build -t veris .
docker run -p 8787:8787 veris

无需修改即可在 Fly.io / Render / Railway 上运行——任何支持 Dockerfile 的平台都可以。

设计说明

• 原始 HTML 来源信息。 我们自行获取页面，并在可读性处理移除信息之前，从 <meta>、JSON-LD 和 Open Graph 中提取日期、作者和规范 URL。
• 内容哈希。 对提取的文本计算 sha256，以检测页面是否发生变化，并支持跨 Agent 去重（这是构建共享网页索引的基础）。
• 提供商接口。 无需修改工具代码即可切换搜索后端。
• 缓存 + 账本。 cache.ts 将键控读取缓存与仅追加、哈希链式归属账本并列维护。

许可证

MIT