Metadata-Version: 2.4
Name: twzrd-mcp
Version: 0.1.0
Summary: Auto-pay MCP server for the TWZRD Trust API (Solana x402). Free preflight/lookup + auto-paid trust intel with spend caps. Payment path mainnet-proven via the official x402 SDK.
Author: TWZRD
License: MIT
Project-URL: Homepage, https://intel.twzrd.xyz
Project-URL: Repository, https://github.com/twzrd-sol/wzrd-final
Keywords: mcp,model-context-protocol,x402,solana,twzrd,trust,agent,auto-pay,reputation
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Intended Audience :: Developers
Classifier: Topic :: Security
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.0
Requires-Dist: x402>=2.10
Requires-Dist: requests>=2.31
Requires-Dist: solders>=0.21

# twzrd-mcp-server - auto-pay MCP for the TWZRD Trust API

> Payment mechanism is mainnet-verified via the official x402 SDK (Python path,
> $0.001 moved 2026-06-26 - see Status). The bundled TypeScript path stays
> fail-closed until its hand-rolled header is replaced with the x402 JS SDK.

Auto-pay MCP server for TWZRD's Trust API, matching the competitor GTM shape
(anchor-x402, Br0ski777, BitBooth all ship one). An agent adds one `mcpServers`
entry; paid tool calls auto-handle the x402 challenge. Free tools never pay.

## Why this is a corrected rebuild
A first draft signed **EIP-3009 on Base (EVM/viem)**. TWZRD settles x402 on
**Solana** (`scheme:"exact"`, USDC, sponsored `feePayer`) — the EVM scheme never
matches the challenge, so that draft could not pay TWZRD at all (it would `tsc`-pass
yet fail every real call). This version is Solana-native and **refuses** any
non-Solana challenge instead of mis-signing.

## Safety guardrails (enforced before any signature)
- Per-call cap `TWZRD_MAX_USDC_PER_CALL` (default 0.05)
- Cumulative session cap `TWZRD_MAX_USDC_TOTAL` (default 1.00)
- Free discovery tools never enter the payment path
- No cross-chain fallback — a non-`exact`/non-`solana:` challenge is rejected
- Paid calls run the free preflight first; `decision=block` aborts the pay

## Status — payment path VERIFIED on mainnet 2026-06-26

Two authorized settles from dev wallet `2pHjZLqs…`:

1. **Hand-rolled `X-Payment` (this MCP's original approach): FAILED** — HTTP 402,
   no USDC moved. The intel host validates via the official x402 lib's
   `PaymentPayload`, so a hand-built header is rejected. (Green `tsc` ≠ settles —
   fail-closed default was correct.)
2. **Official x402 SDK: SUCCEEDED** — `GET /v1/intel/quick/CqtQPaAuQ5UR…` →
   **HTTP 200, `"paid":true,"charged_amount_usdc":0.001`**, tier Silver score 53.6.
   USDC balance moved `0.057236 → 0.056236` (exactly $0.001). A second call against
   a no-data pubkey returned `422 charged:false` — the server's no-charge-on-empty
   guard works.

**Conclusion: auto-pay works ONLY via the official x402 SDK, not a hand-rolled
header.** Proven client wiring (Python):

```python
from x402.client import x402ClientSync
from x402.mechanisms.svm.signers import KeypairSigner
from x402.mechanisms.svm.exact import register_exact_svm_client
from x402.http.clients.requests import x402_requests
client = x402ClientSync()
register_exact_svm_client(client, KeypairSigner(keypair), rpc_url=RPC)
session = x402_requests(client)
session.get("https://intel.twzrd.xyz/v1/intel/quick/<wallet>")  # auto-pays $0.001
```

### Remaining work for THIS (TypeScript) MCP
Replace the hand-rolled `payAndRetry` with the **x402 JS SDK** (SVM support) so the
TS path matches the verified Python path. Note the x402 lib also ships an MCP module
(`x402.mcp`) — a thin Python MCP over the proven client is the fastest route to a
shippable auto-pay server. Keep the spend caps + preflight gate + free/paid split.
Until the TS path is re-tested with the SDK it stays **fail-closed**; the **payment
mechanism itself is now proven**.

## Install & Config

### Python (recommended — the mainnet-proven path)
```bash
pip install twzrd-mcp
```
MCP client config (`mcpServers`):
```json
{ "mcpServers": { "twzrd": {
  "command": "twzrd-mcp",
  "env": {
    "TWZRD_RPC_URL": "<your 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"
  }
}}}
```
The **free** tools (`preflight`, `wallet_lookup`) need no wallet and no flags — leave
`TWZRD_MCP_PAYMENTS_ENABLED` unset and they work read-only. Only the paid tools need
the keypair + `TWZRD_MCP_PAYMENTS_ENABLED=1`.

### Node (`npx twzrd-mcp-server`) — not yet shippable
The bundled TypeScript path is **fail-closed** until its hand-rolled `X-Payment` header
is replaced with the x402 JS SDK (see Status). Use the Python package above for working
auto-pay today.

## Tools
- `preflight` (free) — allow/warn/block + trust_score before you pay
- `wallet_lookup` (free) — facilitators + counterparty breadth for a Solana wallet
- `quick_trust` ($0.001, auto-pay) — quick tier + score
- `full_trust` ($0.05, auto-pay) — full trust intel + signed V6 receipt (verify offline with `twzrd-receipt-verifier`)
