Add structured MCP balance result

[xiefuzheng713-alt]

Summary

• Adds an internal MCP text+structured result shape so tools can keep human-readable text while also returning structuredContent.
• Updates get_balance to keep the existing text response (account: X MRWK) and add structured {account, balance_mrwk} output for agents.
• Extends MCP coverage for treasury, wallet-address, and GitHub-account balance calls.

Bounty #844

Evidence

This is a focused MCP structured-response usability improvement:

• existing text content is preserved for current clients;
• agents no longer have to parse the balance string to read the normalized account and MRWK balance;
• distinct from feat: add MCP input schemas #738, which targets tools/list input schemas;
• distinct from Align submit_work_proof MCP contract #856, which targets submit_work_proof argument/schema behavior;
• no wallet registration, transfer signing, ledger mutation, payout execution, treasury mutation, admin, bridge, exchange, off-ramp, cash-out, or price behavior is changed.

Validation

• uv run --extra dev python -m pytest tests/test_api_mcp.py::test_mcp_tools_list_and_call tests/test_api_mcp.py::test_wallet_account_views_normalize_mixed_case_addresses tests/test_api_mcp.py::test_github_account_views_normalize_mixed_case_logins -q -> 3 passed, 1 existing Starlette/httpx warning
• uv run --extra dev python -m pytest tests/test_api_mcp.py tests/test_mcp_tools.py -q -> 112 passed, 1 existing Starlette/httpx warning
• uv run --extra dev ruff check app/mcp.py app/mcp_tools.py tests/test_api_mcp.py -> passed
• uv run --extra dev ruff format --check app/mcp.py app/mcp_tools.py tests/test_api_mcp.py -> 3 files already formatted
• uv run --extra dev mypy app/mcp.py app/mcp_tools.py -> success
• git diff --check origin/main...HEAD -> clean
• git merge-tree --write-tree origin/main HEAD -> clean tree abda6f4c7b8cc6d19c1ef4bc0fd2711b121cfce1

Scope

MCP response formatting and tests only. No private data, credentials, wallet material, payout/proof/ledger execution, exchange/bridge/cash-out, price behavior, or fabricated payout claims.

Summary by CodeRabbit

• New Features
  • Balance lookup functionality now returns structured data alongside formatted text, enabling improved integration with tools and automated systems.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 98b9069d-874a-4d82-a5e6-2ba32cb055c3

📥 Commits

Reviewing files that changed from the base of the PR and between d4d0e48 and bc3475b.

📒 Files selected for processing (3)

• app/mcp.py
• app/mcp_tools.py
• tests/test_api_mcp.py

---

📝 Walkthrough

Walkthrough

The PR adds structured result support to MCP tools. MCPTextResult type is defined alongside updated type aliases for tool results and handlers, _tool_result_response is extended to format MCPTextResult into JSON-RPC responses carrying text and structuredContent, get_balance tool is updated to return structured account and balance data, and tests are updated to validate the new structure.

Changes

Structured MCP tool results

Layer / File(s)	Summary
MCPTextResult type and type aliases app/mcp.py	MCPTextResult frozen dataclass with text and structured_content fields is introduced; MCPToolResult and MCPToolHandler type aliases extended to accept MCPTextResult alongside legacy str/dict.
Call signature and JSON-RPC response handling app/mcp_tools.py, app/mcp.py	call_mcp_tool return type updated to MCPToolResult; _tool_result_response gains new branch detecting MCPTextResult and formatting into JSON-RPC response with content from text field and separate structuredContent field.
get_balance tool structured implementation app/mcp_tools.py	get_balance tool branch returns MCPTextResult with formatted balance text and structured_content containing account identifier and balance_mrwk value.
Test assertions for structured balance results tests/test_api_mcp.py	test_mcp_tools_list_and_call and account normalization tests updated to assert presence and contents of structuredContent in get_balance responses matching normalized account identifiers and MRWK balances.

Possibly related issues

• Proposed work: return structuredContent for JSON-returning MCP tools #713: Proposes emitting parsed structuredContent alongside text for MCP tool results, directly implemented by this PR's MCPTextResult type and JSON-RPC response formatting.

Possibly related PRs

• ramimbo/mergework#329: Modifies app/mcp.py's JSON-RPC response shaping for tool results; this PR adds MCPTextResult handling while the other centralizes the same wrapping logic.
• ramimbo/mergework#398: Changes call_mcp_tool and get_balance response structure; this PR modifies the same dispatcher and tool implementation to return MCPTextResult.
• ramimbo/mergework#731: Updates app/mcp.py tool-result response and tests/test_api_mcp.py to populate and assert result["structuredContent"] for structured JSON results, overlapping with this PR's structured-content mechanism.

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Title check	✅ Passed	Title 'Add structured MCP balance result' clearly names the changed surface and accurately reflects the main change: introducing a structured result type for MCP balance responses.
Description check	✅ Passed	Description covers all required template sections with concrete evidence: summary of changes, clear evidence of scope boundaries, comprehensive validation results, and explicit scope statement. All test checklist items confirmed as passed.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Mergework Public Artifact Hygiene	✅ Passed	PR introduces technical restructuring of balance response format with no new investment, price, cash-out, or inappropriate payout claims in code, docs, or PR descriptions.
Bounty Pr Focus	✅ Passed	PR diff matches Bounty #844 scope: MCPTextResult in app/mcp.py, get_balance returning MCPTextResult in app/mcp_tools.py, and structuredContent assertions in tests. No unrelated scope creep.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[mauricemohr88-debug]

Reviewed current head bc3475bfe19048c34f146d644952117a3f8a2707.

Approved. I inspected app/mcp.py, app/mcp_tools.py, and tests/test_api_mcp.py and verified this is a focused MCP balance-response improvement:

• the new frozen MCPTextResult keeps the existing human-readable content[0].text response while allowing explicit structuredContent for tools that should not parse balance strings;
• _tool_result_response() handles MCPTextResult before the legacy dict and str paths, so existing structured JSON and text responses remain intact;
• get_balance still normalizes the requested account and still formats balances via format_mrwk(get_balance(...));
• the added structured payload contains only the normalized account and formatted MRWK balance, with coverage for treasury, wallet-address, and GitHub-login account paths;
• no wallet registration, transfer signing, ledger mutation, payout/proof execution, treasury mutation, proposal execution, admin-token API, bridge, exchange, cash-out, MRWK price, private-data, or secret-handling behavior is changed.

Validation on this exact head:

• uv run --python 3.12 --extra dev python -m pytest tests/test_api_mcp.py::test_mcp_tools_list_and_call tests/test_api_mcp.py::test_wallet_account_views_normalize_mixed_case_addresses tests/test_api_mcp.py::test_github_account_views_normalize_mixed_case_logins tests/test_api_mcp.py tests/test_mcp_tools.py -q -> 112 passed, 1 existing Starlette/httpx warning.
• uv run --python 3.12 --extra dev ruff check app/mcp.py app/mcp_tools.py tests/test_api_mcp.py tests/test_mcp_tools.py -> passed.
• uv run --python 3.12 --extra dev ruff format --check app/mcp.py app/mcp_tools.py tests/test_api_mcp.py tests/test_mcp_tools.py -> 4 files already formatted.
• uv run --python 3.12 --extra dev mypy app/mcp.py app/mcp_tools.py -> success.
• uv run --python 3.12 --extra dev python scripts/docs_smoke.py -> docs smoke ok.
• git diff --check origin/main...HEAD -> clean.
• git merge-tree --write-tree origin/main HEAD -> clean tree b5224fd2e5b933b84054aff7a5127590cbcfe5f6.

GitHub state checked before approval: mergeStateStatus=CLEAN; hosted Quality, readiness, docs, and image checks and CodeRabbit statuses are successful on this head. I found no prior human review and no existing #838 claim for PR #885 / this head before posting this review.