Free Web MCP — Verifiable Web Evidence Network

Give AI agents free web access, verify the evidence behind web-derived claims, and anchor evidence fingerprints on BNB Smart Chain (Testnet).

AI Agent → MCP → Web Search → Web Fetch → Claim Extraction → Evidence Collection
  → Cross Verification → Counter Evidence → Evidence Package → SHA-256
  → BSC Testnet (EvidenceRegistry) → Dashboard

Live demo (local): pnpm dev → http://localhost:3000

Don't trust this README? Every on-chain claim has a credential-free public proof — see docs/VERIFICATION.md.

What this project is

A monorepo with two halves:

All evidence packages are persisted in SQLite (apps/web/data/evidence.db) and can be anchored on-chain — the on-chain record stores only the SHA-256 hash

• URI + version + submitter + timestamp, never the full content.

Related MCP server: qsearch

Milestones (computed live on the dashboard)

MCP Server · Web Search · Web Fetch · Evidence Engine · First Evidence · Blockchain Registry · First On-chain Record · Dashboard · Validator · VERI Test Token

Quick start

1. Install

# Node side
pnpm install

# Python side (MCP server)
cd apps/mcp-server && uv sync && cd ../..

2. Run everything (3 terminals)

# Terminal 1 — Python MCP server (port 8765)
cd apps/mcp-server && uv run --no-sync free-web-mcp --transport http --host 127.0.0.1 --port 8765

# Terminal 2 — Next.js dashboard (port 3000)
pnpm dev

# Terminal 3 — local blockchain (Anvil, port 8545) — optional for anchoring
anvil --port 8545

3. See it work

• Dashboard: http://localhost:3000 — System Online, live status probes, evidence statistics, Run Demo button (search → fetch → extract → verify → hash).

• CLI demo: pnpm demo prints the same pipeline.

• Evidence records: http://localhost:3000/evidence and /evidence/EV-XXXXXX.

• Anchor on-chain (needs a contract): click Anchor Evidence on a detail page, confirm, and the hash is registered on the EvidenceRegistry.

Environment

Copy .env.example → .env.local (web) / .env (mcp-server). Key vars:

Private keys must never be committed, logged, or sent to the frontend. See SECURITY.md.

Smart contract (Phase 5)

cd contracts
forge build
forge test          # 6 tests
# local Anvil
anvil --port 8545 &
forge script script/Deploy.s.sol:DeployEvidenceRegistry \
  --rpc-url http://127.0.0.1:8545 --broadcast
# BSC Testnet (needs tBNB — never use a real key)
forge script script/Deploy.s.sol:DeployEvidenceRegistry \
  --rpc-url https://data-seed-prebsc-1-s1.binance.org:8545 \
  --private-key $PRIVATE_KEY --broadcast

The deployed address goes into .env.local as EVIDENCE_REGISTRY_ADDRESS. The dashboard then flips Blockchain → CONNECTED and the Anchor button works.

Live deployment (BSC Testnet)

MCP tools (Python server)

All errors return {success:false, error:{type, message}} with a stable type (INVALID_URL, FETCH_FAILED, TIMEOUT, HTTP_ERROR, PARSER_ERROR, SEARCH_FAILED, RATE_LIMITED, CONTENT_TOO_LARGE, RENDER_FAILED, RENDER_TIMEOUT, INTERNAL_ERROR).

Architecture

┌─────────────┐   ┌───────────────────────────────┐
│ MCP Clients │──▶│ apps/mcp-server (Python)      │
│ Cursor /    │   │ 8 tools, error-wrapped        │
│ Claude /    │   └───────────────┬───────────────┘
│ ChatGPT     │                   │ MCP_SERVER_URL
└─────────────┘                   ▼
┌─────────────────────────────────────────────────┐
│ apps/web (Next.js dashboard + API)              │
│  /api/evidence  create/list/stats               │
│  /api/evidence/[id]  detail                     │
│  /api/demo/run   one-click demo pipeline        │
│  /api/anchor/[id]  on-chain write (confirm req) │
│  SQLite: apps/web/data/evidence.db              │
└──────────────┬────────────────┬─────────────────┘
               │                │
               ▼                ▼
┌──────────────────────┐  ┌─────────────────────────┐
│ packages/evidence    │  │ packages/blockchain     │
│ claims / engine /    │  │ viem client for         │
│ canonical SHA-256    │  │ EvidenceRegistry        │
└──────────────────────┘  └────────────┬────────────┘
                                       ▼
                        EvidenceRegistry.sol (contracts/)
                        BSC Testnet (97) or Anvil (31337)

Layering rule: MCP tools never touch storage or chain directly — they call the dashboard API; the dashboard owns SQLite + the on-chain signer.

Testing

# Python (44 + SSRF tests)
cd apps/mcp-server && uv run pytest -q

# Node (evidence engine 15, blockchain, web db 6)
pnpm -r test

# Type checks
pnpm -r typecheck
cd apps/mcp-server && uv run mypy

CI runs all of the above on every push — see .github/workflows/ci.yml.

Security

See SECURITY.md — SSRF protection, private-key handling, threat model, what is and isn't logged. Key points:

• WebClient rejects private/local/link-local addresses (SSRF, spec §30).

• Rate limits on /api/demo/run and /api/anchor.

• On-chain writes require explicit {confirm: true} and are signed only by the server-side wallet from WALLET_PRIVATE_KEY.

• No real funds, no mainnet, no promises of exchange listing. Testnet only.

Roadmap

• v0.3 (done): dashboard + evidence engine + SQLite + 8 MCP tools + EvidenceRegistry contract (BSC Testnet: 0xD4F1…85D7) + demo mode + SSRF/rate limits.

• v0.4 (done): VERI Test Token (BEP-20, testnet: 0x4FF8…50Da) + validator votes & rewards + multi-provider search aggregation + BNB Greenfield evidence publishing (§27, content-addressed) + ERC-8004 agent identity (§28, registered on the official BSC Testnet registry, agentId 2006) + Playwright e2e.

• Next (watchlist): ERC-8004 reputation feedback writing (needs a second non-owner wallet — the registry blocks self-feedback); agent payments (§29) gated on B402/x402 BSC facilitator self-service; BNB Greenfield mainnet when ready.

License

MIT — see LICENSE.