feat: add CLI functionality to the MCP server #602

fmhall · 2026-02-03T01:56:26Z

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, and report-error 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
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 · 2026-02-03T01:56:30Z

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

Project	Deployment	Actions	Updated (UTC)
x402scan	Ready	Preview, Comment	Feb 11, 2026 10:05pm

github-actions · 2026-02-03T01:57:25Z

✅ 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
/eval unit - Unit tests

packages/external/mcp/src/cli/commands/discover.ts

packages/external/mcp/src/index.ts

fmhall · 2026-02-03T17:54:23Z

/eval full

github-actions · 2026-02-03T17:54:45Z

🚀 Eval triggered!

Parameter	Value
Suite	`full`
Branch	`mason/cli`
Commit	`8c54dc0b73f98f11605f4a1ad19ce7794960e537`

Results will be posted here when complete.

View workflow run

fmhall · 2026-02-03T18:04:11Z

❌ 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 · 2026-02-03T19:16:15Z

/eval full

github-actions · 2026-02-03T19:16:37Z

🚀 Eval triggered!

Parameter	Value
Suite	`full`
Branch	`mason/cli`
Commit	`8c54dc0b73f98f11605f4a1ad19ce7794960e537`

Results will be posted here when complete.

View workflow run

fmhall · 2026-02-03T19:35:39Z

❌ 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 · 2026-02-03T20:14:55Z

/eval full

github-actions · 2026-02-03T20:15:16Z

🚀 Eval triggered!

Parameter	Value
Suite	`full`
Branch	`mason/cli`
Commit	`8c54dc0b73f98f11605f4a1ad19ce7794960e537`

Results will be posted here when complete.

View workflow run

fmhall · 2026-02-03T20:44:16Z

❌ 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

rsproule · 2026-02-11T21:38:41Z

/eval full

github-actions · 2026-02-11T21:39:03Z

🚀 Eval triggered!

Parameter	Value
Suite	`full`
Branch	`mason/cli`
Commit	`f4da92450b4c3e7269a28c0604a3d1ae70c7411b`

Results will be posted here when complete.

View workflow run

fmhall · 2026-02-11T22:02:15Z

/eval smoke

github-actions · 2026-02-11T22:02:33Z

🚀 Eval triggered!

Parameter	Value
Suite	`smoke`
Branch	`mason/cli`
Commit	`21314546c91cda7cae1ef6aca0d96e5e6e458714`

Results will be posted here when complete.

View workflow run

fmhall · 2026-02-11T22:05:02Z

✅ Feature Branch Eval: smoke

Metric	Value
Passed	10
Failed	0
Pass Rate	100.00%
Duration	40s
Commit	`2131454`

View detailed results →

Run details

Workflow: feature-branch-eval
Filter: suite=smoke

fmhall · 2026-02-11T22:21:32Z

⚠️ Feature Branch Eval: full

Metric	Value
Passed	192
Failed	18
Pass Rate	91.42%
Duration	2437s
Commit	`f4da924`

View detailed results →

Run details

Workflow: feature-branch-eval
Filter: ``

initial work

7696a3e

vercel bot deployed to Preview February 3, 2026 01:58 View deployment

removing unused exports

83fe68b

vercel bot reviewed Feb 3, 2026

View reviewed changes

packages/external/mcp/src/cli/commands/discover.ts Show resolved Hide resolved

cli context for verbose logging

cb76494

vercel bot deployed to Preview February 3, 2026 02:16 View deployment

vercel bot reviewed Feb 3, 2026

View reviewed changes

packages/external/mcp/src/index.ts Outdated Show resolved Hide resolved

fix

b108190

vercel bot deployed to Preview February 3, 2026 02:27 View deployment

make server default

8c54dc0

vercel bot deployed to Preview February 3, 2026 17:41 View deployment

Merge branch 'main' into mason/cli

f4da924

vercel bot deployed to Preview February 11, 2026 21:41 View deployment

fixes

560edd8

vercel bot deployed to Preview February 11, 2026 22:00 View deployment

fix checks

2131454

vercel bot deployed to Preview February 11, 2026 22:05 View deployment

rsproule approved these changes Feb 11, 2026

View reviewed changes

rsproule merged commit 8f9037e into main Feb 11, 2026
4 checks passed

feat: add CLI functionality to the MCP server #602

feat: add CLI functionality to the MCP server #602

Conversation

fmhall commented Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Key Changes

Architecture

New Files

Test plan

Uh oh!

vercel bot commented Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ MCP Smoke Test

Uh oh!

Uh oh!

Uh oh!

fmhall commented Feb 3, 2026

Uh oh!

github-actions bot commented Feb 3, 2026

Uh oh!

fmhall commented Feb 3, 2026

❌ Feature Branch Eval: full

Uh oh!

fmhall commented Feb 3, 2026

Uh oh!

github-actions bot commented Feb 3, 2026

Uh oh!

fmhall commented Feb 3, 2026

❌ Feature Branch Eval: full

Uh oh!

fmhall commented Feb 3, 2026

Uh oh!

github-actions bot commented Feb 3, 2026

Uh oh!

fmhall commented Feb 3, 2026

❌ Feature Branch Eval: full

Uh oh!

rsproule commented Feb 11, 2026

Uh oh!

github-actions bot commented Feb 11, 2026

Uh oh!

fmhall commented Feb 11, 2026

Uh oh!

github-actions bot commented Feb 11, 2026

Uh oh!

fmhall commented Feb 11, 2026

✅ Feature Branch Eval: smoke

Uh oh!

fmhall commented Feb 11, 2026

⚠️ Feature Branch Eval: full

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

fmhall commented Feb 3, 2026 •

edited

Loading

vercel bot commented Feb 3, 2026 •

edited

Loading

github-actions bot commented Feb 3, 2026 •

edited

Loading