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)