storefront-guard-mcp-server

Agent-side merchant verification. A shopping agent calls verify_storefront with a domain before paying, and gets back a trust score built from free public data sources.

This is the mirror image of merchant-side agent-verification protocols like Visa's Trusted Agent Protocol: those let a merchant confirm an incoming agent is legitimate. This tool lets the agent confirm the merchant is legitimate before committing payment.

What it checks

• Domain registration age & recent changes — via free public RDAP lookups. A domain registered days ago, or one whose registration data changed in the last two weeks, is a red flag.
• SSL certificate issuance history — via free public Certificate Transparency logs (crt.sh). A cert reissued very recently on an otherwise long-established domain can indicate a takeover or hosting change, even when the domain itself looks old and trustworthy.
• HTTPS validity — does the site currently serve a valid cert at all.
• Known-scam blocklist — URLhaus and Google Safe Browsing.
• Corporate registration — US entity lookup via OpenCorporates.
• Legal name verification — GLEIF entity registry cross-check.
• Web traffic rank — Tranco top-1M ranking.
• Federal exclusions — SAM.gov debarment check.
• FDA enforcement — corroborating signal when other risks are present.

Every deduction from the trust score comes with a plain-English reason in the reasons array — this is deliberately an explainable heuristic, not a black-box model.

Setup

Requires Node.js 18+.

npm install
npm run build

Copy .env.example to .env and fill in your keys.

Running it

As a local MCP server (stdio):

npm start

As a remote MCP server (streamable HTTP) with x402 payment:

npm run start:http
# POST http://localhost:3000/mcp

As a pay-per-call x402 HTTP API:

npm run start:x402
# POST http://localhost:4021/verify   { "domain": "example-shop.com" }

As a REST API (API key auth):

npm run start:rest
# POST http://localhost:4022/verify   { "domain": "example-shop.com" }
# Header: X-API-KEY: your-key

All three servers at once:

npm run start:all
# MCP:  http://localhost:3000/mcp
# x402: http://localhost:4021/verify
# REST: http://localhost:4022/verify

Feedback endpoint

Submit outcome data after a transaction to help build training data for future ML scoring:

POST http://localhost:4022/feedback
Header: X-API-KEY: your-key
Body: { "domain": "example-shop.com", "outcome": "legit" | "scam" }

How to use the recommendation field

Every verification result includes a top-level recommendation string alongside the numeric trustScore. Agents should branch on it rather than implementing their own threshold logic against the raw score.

| Value | Suggested agent behavior | |---|---| | proceed | Complete the transaction silently. Trust score is low-risk with high confidence. | | pause_for_confirmation | Stop before paying and show recommendationReason to the user. | | do_not_proceed | Block the transaction and actively notify the user — do not fail silently. |

recommendationReason is a one-line plain-English explanation safe to show directly to users.

Pricing

$0.01/call via x402. Set your wallet address in PAY_TO_ADDRESS and network in X402_NETWORK (default: base).

Environment variables

| Variable | Required | Description | |---|---|---| | PAY_TO_ADDRESS | Yes (x402) | Your wallet address for USDC payments | | X402_NETWORK | No | Blockchain network (default: base) | | PRICE_USD | No | Per-call price (default: 0.01) | | API_KEYS | Yes (REST) | Comma-separated valid API keys | | GOOGLE_SAFE_BROWSING_API_KEY | No | Degrades gracefully if unset | | SAM_GOV_API_KEY | No | Degrades gracefully if unset | | URLHAUS_AUTH_KEY | No | Degrades gracefully if unset | | FEEDBACK_LOG | No | Path for feedback JSONL log (default: feedback.jsonl) | | MCP_PORT | No | MCP server port (default: 3000) | | X402_PORT | No | x402 server port (default: 4021) | | REST_PORT | No | REST API port (default: 4022) |