feat(mcp): real Model Context Protocol server over stdio

[Pattermesh]

What

Replaces the MCP stub (src/commands.rs) with a real Model Context Protocol server speaking JSON-RPC 2.0 over stdio — the transport MCP hosts (Claude Desktop, Cursor, …) use to launch tool binaries. The README headlines MCP; this makes it actually work.

How

New src/mcp.rs:

• Protocol surface — handles initialize, tools/list, tools/call, and ping. initialize advertises protocol version 2024-11-05, server info, and tool capabilities.
• Tools — exposes the existing commands as namespaced tools: arbitrum.block · arbitrum.tx · arbitrum.balance · arbitrum.token · arbitrum.call · arbitrum.gas · arbitrum.exec. Each advertises a JSON Schema for its arguments and returns its result as both a text content block and structuredContent.
• Error semantics — tool-execution failures (bad/missing args, unknown tool, RPC error) are returned as isError: true content so the model can read and react; unknown JSON-RPC methods return proper JSON-RPC errors (-32601); malformed JSON returns a parse error with a null id. Notifications (no id) get no response.
• Testable layering — an injectable RpcCaller trait abstracts node access (LiveRpc in prod, a mock in tests), so a full tools/call round-trip runs with no network. run_loop is generic over AsyncBufRead/AsyncWrite — real stdin/stdout in prod, in-memory buffers in tests.

The mcp command now runs over stdio and drops the unused --bind network flag. README updated with stdio usage and a Claude Desktop config example. Adds one dependency: async-trait.

Tests

11 new tests in src/mcp.rs (24 total pass):

• initialize reports protocol + server info
• tools/list advertises every tool with an object input schema
• tools/call round-trip executes against a mock RPC and returns content + structuredContent, verifying the dispatched RPC method/params
• block tool decorates number_decimal / timestamp_decimal and hex-encodes numeric blocks
• exec passthrough; isError paths (unknown tool, missing arg); unknown-method error; notification handling
• stdio run_loop drives requests / skips notifications / reports parse errors

Verification

cargo build --all-targets   # green (RUSTFLAGS=-D warnings)
cargo clippy --all-targets -- -D warnings   # green
cargo test --all-targets    # 24 passed; 0 failed

End-to-end stdio smoke test (arbitrum-cli mcp with piped JSON-RPC) confirms initialize → tools/list (7 tools) → ping → tools/call → parse-error all behave per spec.

🤖 Generated with Claude Code

[abhicris]

Welcome to kcolbchain, @Pattermesh — glad you're here. 🌱

Here's what happens from this PR:

1. Our automated review looks for obvious issues (tests, secrets, size) within a couple of hours.
2. If it's clean and CI passes, we merge without back-and-forth.
3. If we need changes, we'll leave a specific comment — not a generic nit. Push another commit and we re-review.

While you wait:

• Run the repo's tests locally (see the repo README.md).
• Keep the PR scoped to one concern — bigger PRs land slower.
• Don't commit tokens or .env contents.

What happens after your first merge

• You're listed on https://kcolbchain.com/contributors/ (opt-out anytime via data/contributors-optout.txt).
• At 2+ merged PRs you're a Regular; at 5+ you're a Fellow — Fellows are the pool we invite first for paid research, partner-org gigs, and grant-funded work. Details: https://kcolbchain.com/docs/org-contribution-policy.html
• Looking for what to pick up next? https://kcolbchain.com/invitations/ lists open help-wanted / good-first-issue across every kcolbchain repo.

Thanks for writing the code. We're building this to last.