feat: add RustChain MCP reference server

[createkr]

Summary

• add a reviewable RustChain MCP reference server under rustchain-bounties-mcp/
• expose seven MCP tools for health, balances, miners, epoch info, wallet verification, attestation submission, and bounty discovery
• back bounty discovery with GitHub Issues data, tighten wallet semantics, and include tests plus install/docs

Testing

• cd rustchain-bounties-mcp && pytest tests/ -v

[createkr]

Payout RTC wallet: RTC1d48d848a5aa5ecf2c5f01aa5fb64837daaf2f35

[Scottcjn]

Review — Two Deliverables, Two Tracks

@createkr — this PR ships two things:

1. MCP Reference Server (rustchain-bounties-mcp/) — READY TO MERGE

The 7-tool MCP server with health, balances, miners, epoch, wallet verification, attestation submission, and bounty discovery is exactly what we need as the official reference server. Includes tests, pyproject.toml, proper schema definitions. This is mergeable independently.

2. AgentFolio ↔ Beacon Integration (bounties/issue-2890/) — ON HOLD

Bounty #2890 has a priority claim reserved for @0xbrainkid through 2026-04-16 (6 days remaining). The bounty body explicitly states this. I cannot merge this portion until the priority window closes, regardless of contributor tier.

If 0xbrainkid does not convert the priority claim into shipped work by April 16, your AgentFolio integration becomes the leading submission and will be reviewed for the full 200 RTC staged payout.

Recommendation

Would you consider splitting this PR into two?

• PR A: Just rustchain-bounties-mcp/ — merge now
• PR B: Just bounties/issue-2890/ — merge after April 16 if priority claim lapses

This way the MCP server ships immediately (it deserves to) and the AgentFolio work is preserved for the priority window resolution.

If you'd rather keep it as one PR, I'll merge the whole thing after April 16 and attribute both bounties to you.

MCP server payment: Separate from #2890 — this work stands on its own. 25-50 RTC range depending on whether it gets published to PyPI.

Excellent work as always.

[Scottcjn]

Deep Review Complete — Changes Needed On Both Deliverables

@createkr — ran this through Codex deep verification against the live API. Found real issues that need fixing before merge. This is not a rejection — your code is the closest to correct of all MCP server submissions. But it needs work.

MCP Reference Server — Changes Required

1. Async entry point bug: pyproject.toml console script points at async main, and mcp_server.py leaves it un-awaited. Running the installed package prints a coroutine object and exits.

2. Wallet verification always returns exists=True: Live /wallet/balance returns 200 with amount_rtc: 0.0 for any wallet ID including nonsense. Your code interprets 200 as "wallet exists" but that's not what the API means — every query returns 200.

3. Attestation submission fails: client.py requires a nonce for /attest/submit but no challenge/nonce tool is exposed. Live endpoint returns MISSING_NONCE.

4. Miner pagination misread: client.py misreads the real /api/miners response structure.

5. Bounties via GitHub instead of node: Using GitHub Issues API for bounties is actually correct (since /api/bounties returns 404 on the live node), but should be documented as intentional.

Tests: 38 pass, 66% overall coverage, 41% on the real HTTP client. No hardcoded secrets found.

AgentFolio Integration (bounties/issue-2890/) — Changes Required

1. bridge.py never calls the required Beacon directory: Targets RustChain-node paths instead of https://bottube.ai/api/beacon/directory. The bounty spec explicitly requires querying the BoTTube endpoint.

2. Multiple 404 endpoints: /api/agent/<id>, /api/reputation*, /api/contracts, /api/bounties, /api/beacon/envelopes, /api/health all 404 on live.

3. Contract field mismatch: bridge.py filters on from_agent/to_agent but beacon_api.py emits from/to.

4. Spec inaccuracies: SPEC.md documents wrong method signatures (identity= vs actual signing_key_hex).

Tests: 68 pass, 88% coverage, but all are unit mocks — none validate against real endpoints.

Reminder: The AgentFolio portion is on hold until 0xbrainkid priority window expires April 16 regardless.

Payment Estimate (After Fixes)

• MCP server: ~25 RTC after the async bug, wallet verification, and attestation issues are fixed
• AgentFolio integration: 50-75 RTC (partial of 200 RTC) depending on how many endpoints are corrected + whether tests hit real API

What To Fix First

1. Fix the async entry point so pip install -e . && rustchain-bounties-mcp actually runs
2. Fix wallet verification to not report every query as "exists"
3. Add SSL context documentation (self-signed cert on 50.28.86.131)
4. For AgentFolio: switch to https://bottube.ai/api/beacon/directory as the primary data source

Your code quality is still the best of all competing submissions. These are fixable issues, not architectural problems.

[createkr]

Thanks — I addressed the MCP review items in the latest push. Changes made: switched the console script entry point to the sync wrapper so the installed package no longer exits with an un-awaited coroutine; changed wallet verification to a conservative heuristic because the live endpoint returns with zero balance for arbitrary ids; added a dedicated tool plus required handling for attestation submission; and adjusted miner parsing to match the live shape instead of assuming pagination metadata. I also kept GitHub-backed bounty discovery and documented that it is intentional because the live node returns 404 for . I spot-checked the live node for wallet balance, miner list, and attestation challenge behavior after the patch. Please take another look when convenient.

[createkr]

Thanks — I followed your suggestion to keep this PR focused on the MCP deliverable only. I pushed another MCP-only cleanup pass to this branch and left the AgentFolio work for a separate follow-up. This update tightens the live-API alignment: miner pagination now reads the nested object from , the MCP server initialization call is fixed to use the inner MCP server object, wallet verification remains conservative ( only on observed non-zero balance), attestation challenge/nonce flow is documented and enforced, and the docs now clearly state that GitHub is the authoritative bounty source because the live node returns 404 for . I also removed the unsupported assumption from the miner schema/output and corrected the Python requirement to 3.10+ to match the MCP SDK. I reran the MCP test suite and rechecked the live endpoints (, , , , , , , GitHub bounties API). Please take another look when convenient.