EVIDIQ Compass

flowchart TB
    agent["<b>AI agent / dev</b><br/>MCP client"]
    request{"Tool call<br/>free or paid?"}
    agent -->|POST /compass/mcp| request

    free["Free preflight & verification<br/>capabilities · estimate · validate<br/>category_map · snapshot_status<br/>whoami · verify · get_artifact"]
    gate["x402 v2 gate<br/>EIP-3009 exact · pay per report<br/>402 unpaid · settles on X Layer"]
    xlayer[("X Layer<br/>USD₮0 · eip155:196")]
    request -->|free helper| free
    request -->|paid report| gate
    gate -. verify and settle .-> xlayer

    subgraph compass["EVIDIQ Compass trust boundary"]
        direction TB
        index["1. Snapshot history<br/>append-only sweep snapshots<br/>SQLite · mounted volume"]
        stats["2. Statistics<br/>R-7 percentiles · bands · spread<br/>pure arithmetic, no model"]
        compare["3. Placement & comparison<br/>competitor sets · percentiles · bands"]
        demand["4. Demand signals<br/>sold vs supply · gaps · trends"]
        report["5. Attestation<br/>JCS digest · EIP-191 signature"]
        index --> stats
        stats --> compare
        stats --> demand
        stats --> report
    end

    og[("0G Storage<br/>Merkle root · upload tx<br/>chain 16661")]
    free --> index
    gate --> stats
    report -. best effort .-> og
    og -. root + tx .-> response

    collector["Host collector<br/>onchainos CLI (logged-in session)<br/>systemd timer · every 6h"] -. append snapshots .-> index

    response["<b>MCP response</b><br/>distribution + placement + basis<br/>snapshotAt + coverage + stale<br/>anchoring: anchored / failed"]

    classDef client fill:#312e81,stroke:#a78bfa,color:#ffffff,stroke-width:2px;
    classDef payment fill:#052e16,stroke:#4ade80,color:#ffffff,stroke-width:2px;
    classDef core fill:#0f172a,stroke:#38bdf8,color:#ffffff,stroke-width:2px;
    classDef output fill:#4c1d95,stroke:#c4b5fd,color:#ffffff,stroke-width:2px;
    class agent,request client;
    class free,gate,xlayer,og,collector payment;
    class index,stats,compare,demand,report core;
    class response output;
    style compass fill:#0f172a,stroke:#38bdf8,color:#e0f2fe,stroke-width:2px;

npm test (vitest)               → 82 passed / 82 (6 files), tsc clean
  test/collect.test.ts  (15)    → pagination to exhaustion, retries, dedupe, cap, coverage
  test/store.test.ts    ( 6)    → schema, idempotent import, latestAgents, artifacts, pricesPerSweep
  test/stats.test.ts   (17)    → cleanPrices, R-7 percentiles, distribution, bands, spread
  test/compare.test.ts (13)    → competitor sets, placement (strictly-less pct), price bands
  test/report.test.ts  ( 6)    → JCS canonical digest, EIP-191 sign/verify round-trip
  test/server.test.ts  (25)    → all 18 tools through the x402 gate (bypass), usage on bare {},
                                 402/415/HEAD handling, unhandledRejection guards

tools/list                      → 18 tools listed ✓
Free Tools (HTTP 200)
  snapshot_status {}            → 200 ✓ (2 snapshots · 407 agents · 1231 services · coverage 1)
  category_map {}               → 200 ✓ (8 categories, 41700 sold in Software services)
Paid Tools (200 here because this run had the bypass on — see the Phase 2 block below)
  market_rate (FINANCE)         → 200 ✓ (min 0 · p25 0.005 · median 0.09 · p75 0.875 · max 50 · n=166)
  attest_market_report (FINANCE)→ 200 ✓ digest 0x9ae2b95b… · EIP-191 sig · 0G anchored
                                    root 0xa5a04eb4… · tx 0xd6737ccf…
  verify_compass_report         → 200 ✓ signatureValid: true · signer 0x8a3c…ee7D
  get_artifact                  → 200 ✓ full report + signature + signer + anchor retrieved
Public route                    → /compass/health 200 · /compass/skill.md 200 · /compass/mcp 200 ✓

empty POST (with content-type)                     → 402
POST without content-type                          → 415
HEAD /mcp                                          → 402, no hang
all 10 paid tools, bare {}                         → 402
  counterparty_history market_rate competitor_set price_my_service quote_advisor
  demand_signal listing_audit service_gap price_trend attest_market_report
all 8 free tools, bare {}                          → 200 with content
  compass_capabilities estimate_cost validate_query category_map
  snapshot_status whoami_listing verify_compass_report get_artifact
onchainos payment quote --tool counterparty_history → 0.005 USDT0, hasBalance true
onchainos payment pay                              → settled, tool executed
fleet sweep across all 18 services                 → broken_entries=0

# Read the public Skill document
curl -s https://mcp.evidiq.dev/compass/skill.md

# Inspect current x402 pricing discovery
curl -s https://mcp.evidiq.dev/compass/x402

# Connect remote MCP server (OpenClaw)
openclaw mcp add evidiq-compass --transport streamable-http --url https://mcp.evidiq.dev/compass/mcp

# Connect remote MCP server (Claude Code)
claude mcp add --transport http evidiq-compass https://mcp.evidiq.dev/compass/mcp

docker build -t evidiq-compass:latest .
docker run -d --env-file .env -p 3019:3019 evidiq-compass:latest
# Endpoint: http://localhost:3019/mcp
# The container reads snapshots from /data/snapshots; the host collector
# (systemd timer) writes them there — see deploy/run.sh for the wired-up version.