Metadata-Version: 2.4
Name: twzrd-mcp
Version: 0.1.4
Summary: Auto-pay MCP server for the TWZRD Trust API (Solana x402). Free preflight/lookup/receipt-verify + 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/twzrd-trust
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
Requires-Dist: twzrd-receipt-verifier>=1.2.0

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

<!-- mcp-name: xyz.twzrd/twzrd-mcp -->

> Payment mechanism is mainnet-verified via the official x402 SDK (Python path,
> $0.001 moved 2026-06-26 - see Status). The Node package is published on npm as
> `twzrd-mcp-server`; v0.2.5 source adds the single-shot payment guard required
> before the next live paid proof.

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 trust calls buy intel on the target wallet by design; use the free
  `preflight` tool separately to vet a seller before paying it elsewhere.

## 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 through the official x402 SDK path.** 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
```

### TypeScript path — integrated (v0.2.5)
The TypeScript path uses the official x402 JS SDK (`@x402/core` client +
`@x402/svm` ExactSvmScheme). `@x402/svm` reads the challenge
`extra.feePayer` and builds the partially-signed sponsored transfer, and
`x402HTTPClient` encodes the `X-PAYMENT` header the server validates. Spend caps +
free/paid split are preserved — caps are enforced in the payment selector before
any signature.

Important: v0.2.5 uses a **single-shot** paid retry. The first SDK-backed E2E found
that the generic `@x402/fetch` wrapper can re-pay after a transient-looking settle
response, moving `$0.003` across two `$0.001` calls. This package now performs at
most one signed retry per logical tool call; any second 402 is surfaced instead of
silently paying again.

**Next verification step:** one operator-authorized `$0.001` `quick_trust` settle
through v0.2.5, followed by offline receipt verification.

## 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`) — x402 JS SDK
```bash
npx -y twzrd-mcp-server --help
```

```json
{ "mcpServers": { "twzrd": {
  "command": "npx", "args": ["-y", "twzrd-mcp-server"],
  "env": {
    "TWZRD_WALLET_SECRET_KEY": "<base58 Solana secret>",
    "TWZRD_RPC_URL": "<your Solana RPC url>",
    "TWZRD_MAX_USDC_PER_CALL": "0.05",
    "TWZRD_MAX_USDC_TOTAL": "1.00"
  }
}}}
```
Auto-pay is enabled whenever `TWZRD_WALLET_SECRET_KEY` is present (set
`TWZRD_MCP_PAYMENTS_ENABLED=0` to force paid tools off). Free tools need no wallet.
The package is published on npm; v0.2.5 is the next source release that includes
the single-shot double-settle guard.

## One-command Agent Demo

The packaged demo starts the MCP server over stdio, lists the tools, and runs a
live **free** preflight. It is no-spend by default, even if your shell has a
wallet secret:

```bash
npm run build
npm run demo
```

Turn the same demo into the operator-authorized `$0.001` settle proof by changing
one env var and setting tight caps:

```bash
TWZRD_DEMO_PAID=quick \
TWZRD_WALLET_SECRET_KEY="<base58 Solana secret>" \
TWZRD_RPC_URL="<mainnet RPC>" \
TWZRD_MAX_USDC_PER_CALL=0.001 \
TWZRD_MAX_USDC_TOTAL=0.001 \
node examples/agent-drop-in.mjs
```

For the full signed-receipt path, use `TWZRD_DEMO_PAID=full` and set both caps to
`0.05`; the demo verifies any returned receipt through the MCP `verify_receipt`
tool. To additionally pipe that receipt into the standalone verifier package:

```bash
TWZRD_DEMO_PAID=full \
TWZRD_DEMO_RUN_VERIFIER_SELF_TEST=1 \
TWZRD_WALLET_SECRET_KEY="<base58 Solana secret>" \
TWZRD_RPC_URL="<mainnet RPC>" \
TWZRD_MAX_USDC_PER_CALL=0.05 \
TWZRD_MAX_USDC_TOTAL=0.05 \
node examples/agent-drop-in.mjs
```

## Tools
- `preflight` (free) — allow/warn/block + trust_score before you pay a **seller** you're about to transact with
- `wallet_lookup` (free) — facilitators + counterparty breadth for a Solana wallet
- `verify_receipt` (free) — independently verify a wallet's cNFT Receipt offline (Ed25519 vs the genesis authority `2ELSDx`); no trust in any TWZRD server
- `quick_trust` ($0.001, auto-pay) — quick tier + score for any wallet
- `full_trust` ($0.05, auto-pay) — full trust intel + signed V6 receipt

> Note: `quick_trust`/`full_trust` pay TWZRD a fixed micro-fee for intel on **any** wallet — they do **not** refuse "risky" targets (you look those up on purpose). Use `preflight` to vet a counterparty you're about to *pay elsewhere*.
