Advertise MCP balance output schema

[modelsbridgeaicom-ship-it]

Summary

• Add an MCP outputSchema for get_balance, matching the structured balance payload already returned at runtime.
• Capture the stable account, balance_mrwk, and balance_microunits fields so schema-aware agents can rely on tools/list instead of parsing the legacy text response.
• Keep the existing get_balance text and structuredContent runtime behavior unchanged.
• Update the agent guide to note that get_balance advertises its structured output schema through tools/list.

Bounty scope

Bounty #946
Refs #946

.

This is focused MCP structured-output metadata and conformance coverage.

Duplicate / stale-work check

• Current main still returns structuredContent for get_balance but does not advertise outputSchema for the tool.
• Existing PR Advertise MCP balance output schema #1035 targets the same gap, but it is currently DIRTY and has not been accepted or paid.
• This PR is a current-main clean replacement with the minimal schema/docs/test change.

Validation

• python -m pytest tests\test_api_mcp.py::test_mcp_tools_list_and_call -q -> 1 passed, 1 existing Starlette/httpx warning.
• ruff check app\mcp.py tests\test_api_mcp.py docs\agent-guide.md -> All checks passed.
• ruff format --check app\mcp.py tests\test_api_mcp.py -> 2 files already formatted.
• python scripts\docs_smoke.py -> docs smoke ok.
• git diff --check -> clean, with the normal Windows LF-to-CRLF warning for docs/agent-guide.md.
• git merge-tree --write-tree origin/main HEAD -> clean tree 7762447113c0e738c8786f302ccb0b9ba7e09cef.

Out of scope

No MCP runtime behavior changes, no ledger mutation, no wallet custody, no transfers, no treasury/proposal execution, no payout execution, no admin-token behavior, no bridge/exchange/off-ramp/cash-out behavior, no MRWK price behavior, and no private data or secrets.

Payout boundary: this is a submitted bounty claim only. It is not confirmed or withdrawable unless maintainers accept it and record payment.

Summary by CodeRabbit

• New Features

  • The get_balance tool now advertises a structured output schema with standardized fields for account and balance information, allowing callers to consume data programmatically instead of parsing text.

• Documentation

  • Updated agent guide to document the structured output schema and available fields for the get_balance tool.

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR adds structured output schema documentation to the MCP get_balance tool by defining MCP_BALANCE_OUTPUT_SCHEMA, wiring it into the tool definition, validating it with schema assertions in existing tests, and updating agent documentation to enumerate the structured fields now available via tools/list.

Changes

MCP get_balance output schema

Layer / File(s)	Summary
Schema definition and tool wiring app/mcp.py	MCP_BALANCE_OUTPUT_SCHEMA constant defines the JSON object shape for balance results with required fields (account, balance_mrwk, balance_microunits) and additionalProperties: false; the schema is wired into the get_balance tool's outputSchema field.
Schema validation tests tests/test_api_mcp.py	Test assertions verify the advertised outputSchema enforces required properties, disallows additional properties, and validates balance_mrwk (string) and balance_microunits (minimum 0) type and constraint expectations.
Documentation update docs/agent-guide.md	Agent guide clarified to note that tools/list advertises the structured output schema and enumerates the accessible structured fields (account, balance_mrwk, balance_microunits) alongside the preserved legacy balance text.

Possibly related issues

• ramimbo/mergework#794: PR implements MCP schema conformance validation by adding an output schema definition and test assertions for the get_balance tool, aligning with the issue's proposal for schema/runtime conformance tests.

Possibly related PRs

• ramimbo/mergework#990: Directly related; introduced the structured result.structuredContent fields (account, balance_mrwk, balance_microunits) that this PR now documents and validates via outputSchema.
• ramimbo/mergework#937: Both modify the MCP get_balance tool definition in app/mcp.py and extend schema assertions in tests/test_api_mcp.py::test_mcp_tools_list_and_call; PR #937 addresses inputSchema while this PR validates outputSchema.
• ramimbo/mergework#1031: Parallel pattern; both PRs add JSON-schema constants to MCP_TOOLS entries (get_balance here, bounty tools there) with corresponding schema validation assertions in tests.

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Title check	✅ Passed	Title directly names the changed surface (MCP balance output schema) and clearly reflects the main change of adding and advertising an outputSchema for the get_balance tool.
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	Changes add only technical schema and docs without investment, price, cash-out, or security claims. MRWK properly described as supporting snapshots, bridges, and onchain claims.
Bounty Pr Focus	✅ Passed	PR diff matches stated Bounty #946 scope: only 3 files modified (app/mcp.py +23, docs/agent-guide.md ±4, tests/test_api_mcp.py +9). No unrelated scope creep detected.
Description check	✅ Passed	The pull request description is comprehensive and well-structured, covering summary, bounty scope, duplicate/stale-work check, validation steps, and clear out-of-scope boundaries.

_{✏️ 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.}

[szx19970521]

Approved at current head acb00a7aced5520b62800401f013c545d73bcb87.

Evidence checked:

• Inspected the 3-file diff: app/mcp.py, tests/test_api_mcp.py, and docs/agent-guide.md.
• MCP_BALANCE_OUTPUT_SCHEMA matches the existing get_balance structuredContent payload: account, balance_mrwk, and balance_microunits.
• The tool catalog change only advertises outputSchema; runtime balance lookup/text response/structuredContent behavior remains unchanged.
• The test pins required fields, additionalProperties: False, balance_mrwk string type, and balance_microunits minimum 0; existing runtime assertion still checks treasury structuredContent shape.
• Docs change matches the existing structuredContent guidance.

Commands run locally on this PR head:

• python -m pytest tests\test_api_mcp.py::test_mcp_tools_list_and_call -q -> 1 passed, 1 existing Starlette/httpx warning.
• ruff check app\mcp.py tests\test_api_mcp.py docs\agent-guide.md -> All checks passed.
• ruff format --check app\mcp.py tests\test_api_mcp.py -> 2 files already formatted.
• python scripts\docs_smoke.py -> docs smoke ok.

Eligibility/duplicate notes for review bounty tracking:

• PR is open, non-draft, mergeable, and CodeRabbit is green.
• Before submitting this review, I found no human reviews on this PR and no #933 issue comment referencing PR #1077.
• The PR body notes earlier PR #1035 covered the same gap but is dirty and not accepted/paid; this PR is current-main clean, so the reviewed artifact itself is distinct and current.

No blockers found.