0.5.7 • Published 1 week agoCLI

twzrd-mcp-server

Licence

MIT

Version

0.5.7

Deps

Size

40 kB

Vulns

Weekly

Summary Dependency Versions

twzrd-mcp-server / twzrd-mcp — pre-spend seller reputation for Solana x402

Check a seller wallet and requested resource before you pay over Solana x402. Free tools return allow / warn / block. Paid clearance is $0.001 quick_trust / twzrd.payment_decision.v1. Optional $0.05 full_trust is Path A intel, not the primary SKU. TWZRD scores observed wallet and payment behavior. It does not prove a person, company, or autonomous agent identity.

Prefer the zero-install hosted Agent Intelligence MCP. Use this package only when you want local auto-pay for paid intel.

// Recommended — full hosted tool set, no wallet, nothing to install
{ "mcpServers": { "twzrd": { "url": "https://intel.twzrd.xyz/mcp" } } }

# Local auto-pay client — 6 tools; wallet only if you enable paid calls
npx -y twzrd-mcp-server        # Node
pip install twzrd-mcp          # Python

npm (Node): twzrd-mcp-server
PyPI (Python): twzrd-mcp
Agent Intelligence: https://intel.twzrd.xyz · repo: twzrd-sol/twzrd-trust

Which surface do I want?

Surface	Tool set	Wallet	Use when
`https://intel.twzrd.xyz/mcp` (hosted)	Full hosted set (live `tools/list`)	No	Default. Seller preflight, resource evaluation, reputation, receipts, watches, product-listing checks (`check_listing`), and observed-market research.
`twzrd-mcp-server` / `twzrd-mcp` (this local package)	6 local tools	Only for paid	You want `quick_trust` / `full_trust` auto-paid locally with caps.

Start with hosted twzrd_demo_gate for a zero-setup, zero-spend transcript of the block path: a recorded example, not a live run. The hosted MCP is also listed on Smithery.

The 6 local client tools

Tool	Cost	What
`preflight`	free	allow / warn / block + trust score for a seller you're about to pay
`merchant_card`	free	seller graph card — `wash_flagged: true` → don't pay (locked sequence step 2)
`wallet_lookup`	free	facilitators + counterparty breadth for a wallet
`verify_receipt`	free	offline-verify a wallet's cNFT receipt (Ed25519 vs genesis authority `2ELSDxLkb7dYrN6EUG69tNtULAq4Fo7WPvXyrZPmuFif`) — trust no server
`quick_trust`	$0.001	Clearance SKU: `twzrd.payment_decision.v1` / quick tier + score
`full_trust`	$0.05	Optional Path A intel + signed V7 receipt — not the primary SKU

quick_trust / full_trust buy intel on any wallet (you look risky ones up on purpose) — they don't refuse a target. Use preflight to vet a wallet you're about to pay elsewhere.

Happy path (seller-first)

Free preflight on the seller's receive wallet.
block → don't pay. Done, $0 spent.
Free merchant_card on the same wallet — wash_flagged: true → don't pay.
warn → $0.001 quick_trust / payment_decision.v1 clearance. Optional $0.05 full_trust is Path A intel, not the primary SKU.
allow + clean card + small spend → pay. Keep the receipt; scores decay, so re-check stale decisions.

Install & config

Paid tools are opt-in on both runtimes: they sign only when you set TWZRD_MCP_PAYMENTS_ENABLED=1 and provide a wallet key. For free tools, omit both — the server runs read-only and never signs. Spend is bounded by per-call and session caps.

Before any Solana signature the Node server runs twzrd-x402-gate@0.11.4 wash default (Python twzrd-mcp 0.2.2 does the same merchant_card check on the 402 payTo): abort iff wash_flagged===true, and fail closed if intel cannot answer (timeout, 5xx/429, unreadable body): an outage is never read as clean. That is the paying-client brake, not a Path A shop.

Python — `pip install twzrd-mcp`

{ "mcpServers": { "twzrd": {
  "command": "twzrd-mcp",
  "env": {
    "TWZRD_RPC_URL": "<your dedicated Solana RPC url>",
    "TWZRD_WALLET_KEYPAIR": "/path/to/solana-keypair.json",
    "TWZRD_MCP_PAYMENTS_ENABLED": "1",
    "TWZRD_MAX_USDC_PER_CALL": "0.05",
    "TWZRD_MAX_USDC_TOTAL": "1.00"
  }
}}}

Node — `npx -y twzrd-mcp-server`

{ "mcpServers": { "twzrd": {
  "command": "npx", "args": ["-y", "twzrd-mcp-server"],
  "env": {
    "TWZRD_RPC_URL": "<your dedicated Solana RPC url>",
    "TWZRD_WALLET_SECRET_KEY": "<base58 Solana secret>",
    "TWZRD_MCP_PAYMENTS_ENABLED": "1",
    "TWZRD_MAX_USDC_PER_CALL": "0.05",
    "TWZRD_MAX_USDC_TOTAL": "1.00"
  }
}}}

Env var	Default	Meaning
`TWZRD_MCP_PAYMENTS_ENABLED`	unset (off)	set `1` to arm paid tools — required on both runtimes
`TWZRD_WALLET_SECRET_KEY` (Node) / `TWZRD_WALLET_KEYPAIR` (Python)	—	signer for paid tools
`TWZRD_MAX_USDC_PER_CALL`	`0.05`	per-call spend cap
`TWZRD_MAX_USDC_TOTAL`	`1.00`	cumulative session spend cap
`TWZRD_RPC_URL`	none — required for paid tools	Solana RPC. Paid tools refuse to arm without it: the public RPC is rate-limited and loses x402 races (stale blockhash / sponsored feePayer between the 402 challenge and the signed retry), and a rejected settle can still move USDC. Free tools need no RPC. The Solana Foundation public endpoints (`api.mainnet-beta`, `api.devnet` and `api.testnet` `.solana.com`, trailing dots ignored) and any URL with a `/public` path segment are refused, by the Node server and by the Python client; other shared public RPCs are not detected, so choose a dedicated one. `TWZRD_ALLOW_PUBLIC_RPC` no longer enables a refused URL.

Safety

Opt-in payments — paid tools sign only with TWZRD_MCP_PAYMENTS_ENABLED=1; a wallet key alone never arms spending.
Spend caps — per-call and session caps enforced in the payment selector before any signature. Caps use the mint's true decimals, never merchant-declared extra.decimals. A mismatched declaration is refused. A malformed cap env (e.g. "$0.05") falls back to the default; it never becomes NaN and disables the cap.
Known-asset only — pay only known USD-pegged stables (USDC/USDT); unknown SPL mints are refused.
Identifiable recipient — a challenge with no payTo is refused.
Solana-only — a non-exact / non-solana: challenge is refused, never mis-signed.
Single-shot retry — at most one signed retry per tool call; a second 402 is surfaced, not silently re-paid.
Free tools never enter the payment path.

Verify receipts offline (trust no one)

full_trust returns a portable Ed25519-signed V7 receipt. Verify it without trusting any TWZRD server — new receipts use issuer key twzrd-receipt-ed25519-v2; legacy v1 keys remain verify-only during the bounded compatibility rollout. (Ak5SQwHpuQAqU7ty7ZWX7qgF39A9yi72c22KNn8sHzvS), pinned at https://intel.twzrd.xyz/.well-known/twzrd-receipt-pubkey:

npx twzrd-receipt-verifier <receipt.json> --pubkey Ak5SQwHpuQAqU7ty7ZWX7qgF39A9yi72c22KNn8sHzvS

Development

This directory in the public mirror is dist/ only. npm run build is a no-op echo. npm run demo exits 1 on purpose — the in-tree demo imports a gate export this workspace copy does not provide. Use hosted MCP https://intel.twzrd.xyz/mcp or npx -y twzrd-mcp-server from npm. Do not treat this checkout as a from-source MCP build.

Links: Agent Intelligence · hosted MCP · llms.txt · llms-full.txt · OpenAPI

License: MIT

Keywords

mcp x402 solana agent trust twzrd reputation