feat: add CLI functionality to the MCP server

[fmhall]

Summary

This PR extends the @x402scan/mcp package to support CLI-first invocation alongside the existing MCP server functionality. Users can now run commands directly via npx @x402scan/mcp <command> without needing to install and configure an MCP server first.

Key Changes

• CLI commands: Added fetch, check, discover, wallet, report-error, and schema commands that mirror MCP tool functionality
• Structured JSON output: All CLI commands output agent-readable JSON with consistent success/error response formats
• Exit codes: Standardized exit codes (0-5) for programmatic error handling by invoking agents
• Schema introspection: npx @x402scan/mcp schema <command> returns JSON schemas for any command
• DRY architecture: Extracted shared business logic into src/shared/operations/ consumed by both MCP tools and CLI commands

Architecture

┌─────────────────────────┐     ┌─────────────────────────┐
│   MCP Server Tools      │     │   CLI Commands          │
└───────────┬─────────────┘     └───────────┬─────────────┘
            │                               │
            └───────────┬───────────────────┘
                        ▼
            ┌───────────────────────┐
            │   Shared Operations   │
            │  (Result<T, E> types) │
            └───────────────────────┘

New Files

Path	Purpose
src/cli/commands/*.ts	CLI command implementations
src/cli/commands/lib/	Shared CLI utilities (wallet, input parsing)
src/cli/output/	Response formatting, exit codes, TTY detection
src/shared/operations/	Business logic shared between MCP and CLI

Test plan

• npx @x402scan/mcp wallet info returns wallet address and balance
• npx @x402scan/mcp discover https://enrichx402.com finds x402 resources
• npx @x402scan/mcp check https://enrichx402.com/api/apollo/people-enrich returns pricing info
• npx @x402scan/mcp fetch <url> makes paid requests successfully
• npx @x402scan/mcp schema fetch returns JSON schema
• npx @x402scan/mcp server starts the MCP server (existing functionality preserved)
• JSON output is valid and parseable by agents
• Exit codes match documented behavior

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
x402scan	Ready	Preview, Comment	Feb 3, 2026 5:41pm

[github-actions]

✅ MCP Smoke Test

Check	Status
Server Starts	✅ Pass
Tools Registered	8 tools

Run full evaluation suite

Comment /eval on this PR to trigger the full evaluation suite in x402-evals.

Available suites:

• /eval smoke - Quick validation (~2-3 min)
• /eval full - Comprehensive testing (~10 min)
• /eval regression - Known edge cases

[fmhall]

/eval full

[github-actions]

🚀 Eval triggered!

Parameter	Value
Suite	full
Branch	mason/cli
Commit	8c54dc0b73f98f11605f4a1ad19ce7794960e537

Results will be posted here when complete.

View workflow run

[fmhall]

❌ Feature Branch Eval: full

Metric	Value
Passed	9
Failed	27
Pass Rate	25.00%
Duration	454s
Commit	8c54dc0

View detailed results →

Run details

• Workflow: feature-branch-eval
• Filter: suite=full

[fmhall]

/eval full

[github-actions]

🚀 Eval triggered!

Parameter	Value
Suite	full
Branch	mason/cli
Commit	8c54dc0b73f98f11605f4a1ad19ce7794960e537

Results will be posted here when complete.

View workflow run

[fmhall]

❌ Feature Branch Eval: full

Metric	Value
Passed	16
Failed	32
Pass Rate	33.33%
Duration	1027s
Commit	8c54dc0

View detailed results →

Run details

• Workflow: feature-branch-eval
• Filter: suite=full

[fmhall]

/eval full

[github-actions]

🚀 Eval triggered!

Parameter	Value
Suite	full
Branch	mason/cli
Commit	8c54dc0b73f98f11605f4a1ad19ce7794960e537

Results will be posted here when complete.

View workflow run

[fmhall]

❌ Feature Branch Eval: full

Metric	Value
Passed	20
Failed	16
Pass Rate	55.55%
Duration	1624s
Commit	8c54dc0

View detailed results →

Run details

• Workflow: feature-branch-eval
• Filter: suite=full