feat(cli): scripts/demo.py + mcp-curl.sh — drive MCP without Claude; README/DEMO Step 4 rewrite

[acedatacloud-dev]

Summary

User reported MCP could not be loaded on Claude Desktop. Two real
issues underneath that symptom:

1. README's Step 4 config was for the wrong product.
   {"mcpServers": {"aceguard": {"url": "..."}}} is the Claude.ai web
   Custom Connectors schema, not the Claude Desktop one. Claude
   Desktop only speaks stdio MCP. To attach an HTTP MCP endpoint to
   it you need the community-standard mcp-remote stdio↔HTTP bridge.
2. No way to test the MCP endpoint without a client. Network errors,
   bad tokens, server bugs, and client-config bugs all surfaced as the
   same opaque "could not be loaded" string, leaving the user no
   diagnostic.

This PR fixes both. Pairs with #18 — together they make
aceguard_pay_for_api actually work end-to-end and give the user a
way to prove that without depending on any specific LLM client.

What's added

scripts/demo.py — pure-Python CLI demo

httpx + stdlib, no SDK / no MCP libraries. Speaks JSON-RPC to the
endpoint and runs the full sequence:

1. tools/list                  → 4 tools registered
2. aceguard_balance            → on-chain USDC + caps
3. aceguard_pay_for_api        → 402 → on-chain spend → X-Payment retry → 200
4. aceguard_balance            → confirms vault balance ticked down
5. aceguard_history            → new spend with Solscan deep-link

Argument-parsed: --url, --body, --method, --skip-pay. Error
paths return distinct exit codes (1 = fatal; 2 = pre-flight failure
e.g. paused / empty vault / 401 token; 3 = pay_for_api isError
case — policy rejection or upstream non-200).

Smoke-tested live against
https://x402guard.acedata.cloud/mcp/<bad-token>:

$ python scripts/demo.py https://x402guard.acedata.cloud/mcp/invalid-test-token
x402guard CLI demo — driving MCP at 'https://x402guard.acedata.cloud/mcp/invalid-test-token'

━━━ 1. tools/list ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
❌ MCP endpoint returned 401 (unknown or revoked token).
   https://x402guard.acedata.cloud/mcp/invalid-test-token
   Generate a fresh token in the vault detail page → + New MCP URL → Copy.

Right answer, with remediation. Live test against a real funded vault
needs an unmerged token + USDC; reviewer with prod access can run it
manually.

scripts/mcp-curl.sh — bash + curl + jq variant

Same flow, no Python required. Useful for users on minimal containers
or for the "5-minute screen recording" we'll cut for the submission
video.

README.md — Step 4 rewrite

The old "wire the URL into Claude Desktop" section was replaced with
four sub-steps in order of "how much LLM machinery do you need?":

	What	When to use
4a	python scripts/demo.py <URL>	Verify the endpoint works at all. Always do this first.
4b	Claude Desktop via mcp-remote bridge (with the correct JSON config)	You want an LLM to use the tools.
4c	Cursor / Cline / any HTTP-MCP-aware client	Same, but client takes the URL directly without a bridge.
4d	@acedatacloud/x402-client SDK directly	You want to make a paid api.acedata.cloud call from your own wallet, without the on-chain policy enforcement that x402guard adds.

Cross-links to the @acedatacloud/x402-client SDK and its
scripts/test-solana-e2e.ts for path 4d. The framing
makes it explicit that x402guard is value-on-top of the SDK
(spending caps + allowlist enforced on-chain), not a different product.

DEMO.md — same correction in the demo script

The 1:20–1:50 segment of the recorded demo now uses the mcp-remote
bridge form. Added a B-roll suggestion: split-screen Claude Desktop
against python scripts/demo.py to make the "the boundary lives in
the program, not the client" point visually.

Added two troubleshooting rows:

• "MCP could not be loaded" with {"url": "..."} → switch to bridge form
• Suspect endpoint broken → run the demo script as a self-diagnostic

Verification

• uvx ruff check scripts/demo.py — clean
• bash -n scripts/mcp-curl.sh — clean
• python3 -c "import ast; ast.parse(open('scripts/demo.py').read())" — parses
• Live smoke test (above) against the production MCP endpoint — proper
  401 handling

Risk

Documentation + new files only. No behaviour change in the running
backend / web / Anchor program.