{
  "markdown": "# veris\n\n[![npm version](https://img.shields.io/npm/v/veris-mcp.svg)](https://www.npmjs.com/package/veris-mcp) [![license](https://img.shields.io/npm/l/veris-mcp.svg)](./LICENSE) · `npx -y veris-mcp`\n\n**Provenance-first web access for AI agents.** Clean content *plus* verifiable source metadata, in one call.\n\nToday an AI agent reading the web gets a wall of text. It does **not** get: when the page was published, whether the content changed since last time, who wrote it, the canonical source, or the license terms. veris attaches all of that to every read.\n\n```\nweb_read(\"https://example.com/article\")\n  → clean markdown\n  + { publishedAt, modifiedAt, author, canonicalUrl, contentHash, license, fetchedAt }\n```\n\nThat metadata is not a nice-to-have. It is the foundation the rest of the AI-web economy needs: freshness, change-detection, citation, and — eventually — paying the people who wrote the content.\n\n---\n\n## Why this exists\n\nThe web is being scraped by AI with no attribution and no payment. Publishers are responding by blocking bots and locking content. AI gets worse; publishers lose. The fix is a layer between agents and publishers that reads cleanly, tracks provenance, and (later) settles payment.\n\nveris is the **agent-side** of that layer — the SDK every agent imports to consume the web responsibly. Think \"Plaid for the AI web\": you don't own the publishers, you own the integration developers reach for.\n\n## Roadmap (one codebase, three stages)\n\n| Stage | What | Status |\n|-------|------|--------|\n| **1. Clean + provenance** | search / read / research with verifiable source metadata | ✅ |\n| **2. Finance vertical** | SEC EDGAR filings with authoritative, official provenance | ✅ |\n| **3. Settlement** | license-aware access + micropayment + attribution | 🔜 seams in `policy.ts` + `cache.ts` |\n\nThe Stage 3 seams already exist in the code (`policy.ts`, `cache.ts`) so growth is additive, not a rewrite.\n\n## Tools\n\n**Web**\n\n| Tool | Does |\n|------|------|\n| `web_search(query, n?)` | Ranked results as structured JSON. Brave (with key) or keyless DuckDuckGo. |\n| `web_read(url, fresh?)` | URL → clean markdown + provenance block. 24h cache. |\n| `web_research(query, n?)` | Search + read top N + bundle with per-source citations. |\n\n**Finance — SEC EDGAR** (free, official, no API key)\n\n| Tool | Does |\n|------|------|\n| `finance_filings(query, formType?, limit?)` | Ticker / name / CIK → recent SEC filings: form, official filing & report dates, accession, direct document URL. |\n| `finance_filing_read(url or query, formType?)` | Read a filing by URL, or auto-read the latest matching form for a company. Clean text + provenance. |\n| `finance_financials(query)` | Revenue, net income, total assets, cash, diluted EPS from SEC XBRL — each figure stamped with the exact filing it came from. |\n\n> **Why EDGAR first?** Filings carry *authoritative* dates and identifiers straight from the SEC — provenance isn't guessed, it's official. Free, structured, no auth. One call gets an agent the latest 10-K with a verifiable source:\n>\n> ```\n> finance_filing_read({ query: \"NVDA\", formType: \"10-K\" })\n>   → NVIDIA CORP — 10-K (filed 2026-02-25)\n>     clean text + { source, filed date, contentHash, wordCount }\n> ```\n\n**Watch — change detection & alerts**\n\n| Tool | Does |\n|------|------|\n| `watch_manage(action, target?, formType?)` | Add/remove/list watches: a company's SEC filings (ticker + optional form like `8-K`) or any URL (content-hash watch). |\n| `watch_check()` | Check all watches; returns only what's NEW (new filings / changed pages) and rolls baselines forward. Run it on a schedule → alert feed. |\n\n## Install\n\n```bash\nnpx -y veris-mcp        # zero-install, always latest\n```\n\nOr from source:\n\n```bash\ngit clone https://github.com/jakeyoung1/veris && cd veris\nnpm install && npm run build\n```\n\nOptional env:\n\n```bash\nexport BRAVE_API_KEY=your_key                      # better search; https://search.brave.com/app/keys\nexport SEC_USER_AGENT=\"Your Name you@email.com\"    # SEC fair-access policy (recommended)\n```\n\nWithout a Brave key, search falls back to keyless DuckDuckGo automatically. SEC requires a\n`Name email@domain` style User-Agent — veris ships a default, but set your own contact.\n\n## Use in Claude Code\n\nAdd to your MCP config (`.mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"veris\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"veris-mcp\"],\n      \"env\": { \"BRAVE_API_KEY\": \"optional\", \"SEC_USER_AGENT\": \"Your Name you@email.com\" }\n    }\n  }\n}\n```\n\nRestart Claude Code, then ask it to `web_research` something.\n\n## Remote server (HTTP)\n\nRun veris as a remote MCP server (Streamable HTTP) and connect from any MCP client by URL:\n\n```bash\nnpx -y veris-mcp http                            # http://127.0.0.1:8787/mcp\nVERIS_HTTP_HOST=0.0.0.0 npx -y veris-mcp http    # expose it (put TLS in front)\n```\n\n| Env | Does |\n|-----|------|\n| `VERIS_PORT` / `PORT` | Port (default `8787`) |\n| `VERIS_HTTP_HOST` | Bind host (default `127.0.0.1`) |\n| `VERIS_API_KEYS` | Comma-separated keys. If set, `/mcp` requires `Authorization: Bearer <key>` (or `x-api-key`). Unset = open. |\n| `VERIS_RATE_LIMIT` | Requests/min/IP (default `60`) |\n\nSelf-hosting is free, forever. `VERIS_API_KEYS` exists so a hosted instance can be metered.\n\n### Docker\n\n```bash\ndocker build -t veris .\ndocker run -p 8787:8787 veris\n```\n\nWorks as-is on Fly.io / Render / Railway — anything that runs a Dockerfile.\n\n## Design notes\n\n- **Provenance from raw HTML.** We fetch the page ourselves and pull dates/author/canonical from `<meta>`, JSON-LD, and Open Graph *before* readability strips them.\n- **Content hash.** sha256 of extracted text — detects whether a page changed and enables dedupe across agents (the basis for a shared web index).\n- **Provider interface.** Swap search backends without touching tool code.\n- **Cache → ledger.** The same keyed store that caches reads today records read events for settlement tomorrow.\n\n## License\n\nMIT\n",
  "bytes": 5956,
  "sha": "68a2422846da3c3537114f5c5378d555aaf69eecf789f1f3535799356969867a",
  "repo_slug": "jakeyoung1/veris",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_jakeyoung1_veris_2f654b7e/readme"
}