Advertise MCP balance output schema

[elianguitarra]

Bounty #946

Summary

• Adds an MCP outputSchema for get_balance, matching the structured balance payload already returned at runtime.
• Captures the normalized account, formatted balance_mrwk, and raw balance_microunits fields for schema-aware agents.
• Updates the agent guide so clients know to rely on the advertised output schema instead of parsing the legacy text line.

Before / after

• Before: get_balance returned structuredContent, but tools/list only advertised the input shape.
• After: tools/list advertises the exact structured output contract while preserving the existing text and structured runtime response.

Validation

• .venv\Scripts\python.exe -m pytest tests\test_api_mcp.py::test_mcp_tools_list_and_call -q -> 1 passed, 1 existing Starlette/httpx warning
• .venv\Scripts\python.exe -m pytest tests\test_api_mcp.py tests\test_mcp_tools.py -q -> 131 passed, 1 existing Starlette/httpx warning
• .venv\Scripts\ruff.exe check app\mcp.py tests\test_api_mcp.py docs\agent-guide.md -> All checks passed
• .venv\Scripts\ruff.exe format --check app\mcp.py tests\test_api_mcp.py -> 2 files already formatted
• .venv\Scripts\python.exe scripts\docs_smoke.py -> docs smoke ok
• git diff --check -> clean, Windows CRLF warning only for docs

Scope: MCP get_balance tool metadata, focused tests, and agent docs only. No ledger mutation, wallet custody, payout execution, treasury behavior, admin-token behavior, bridge/exchange/cash-out behavior, MRWK price behavior, private data, or secrets changed.

Summary by CodeRabbit

Release Notes

• Documentation

  • Updated the agent guide with detailed specifications for the get_balance tool, explicitly documenting all response fields, including account identifiers and balance values, along with their validation constraints.

• Tests

  • Enhanced the test suite for the get_balance tool to comprehensively validate the output schema structure, required field definitions, and response data format constraints.

[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: 13964924-6b22-4c02-a6e6-5b2fe15e34d5

📥 Commits

Reviewing files that changed from the base of the PR and between 2712881 and 3175cd5.

📒 Files selected for processing (3)

• app/mcp.py
• docs/agent-guide.md
• tests/test_api_mcp.py

---

📝 Walkthrough

Walkthrough

The PR adds an outputSchema to the get_balance MCP tool, documenting its response structure with three required fields: account, balance_mrwk (decimal string with up to six fractional digits), and balance_microunits (non-negative integer). Tests validate both the schema advertisement and the actual response payload; documentation clarifies the tool's structured return value.

Changes

get_balance outputSchema and validation

Layer / File(s)	Summary
get_balance outputSchema definition app/mcp.py	The get_balance tool in MCP_TOOLS now declares an outputSchema with three required fields: account (normalized), balance_mrwk (decimal string, max 6 decimal places), and balance_microunits (non-negative integer); additionalProperties is false.
Schema and response validation tests tests/test_api_mcp.py	Test assertions for tools/list now verify the get_balance outputSchema structure, required fields, and validation constraints; tools/call test now asserts the returned structuredContent contains exactly the schema-required keys.
get_balance documentation docs/agent-guide.md	Agent guide now documents that get_balance returns structured fields (account, balance_mrwk, balance_microunits) and that tools/list advertises the matching outputSchema.

Possibly related PRs

• ramimbo/mergework#990: Both PRs center on get_balance producing the same structured balance payload (account, balance_mrwk, balance_microunits): the retrieved PR adds structuredContent via MCPTextResult, while the main PR updates the MCP get_balance outputSchema and tests/docs to validate those exact structured keys/constraints.
• ramimbo/mergework#937: Both PRs modify the get_balance MCP tool definition in app/mcp.py (via MCP_TOOLS) and extend tests/test_api_mcp.py assertions against tools/list/tools/call schema details—main PR adds outputSchema validation while the retrieved PR adds inputSchema validation for the account field.
• ramimbo/mergework#731: Both PRs touch MCP get_balance expectations around structuredContent: the retrieved PR adds JSON-decoding-based structuredContent construction, while the main PR updates the get_balance outputSchema and tests to assert the returned structuredContent matches the required schema fields.

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Advertise MCP balance output schema' directly names the changed surface and accurately reflects the main change: adding an outputSchema for the MCP get_balance tool.
Description check	✅ Passed	The description follows the required template with comprehensive Summary, Evidence, Test Evidence checklist, and MRWK reference sections, clearly documenting the change and validation performed.
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 adds MCP balance outputSchema with no investment, price, cash-out, or problematic claims; maintains existing safeguards and describes MRWK appropriately as project component.
Bounty Pr Focus	✅ Passed	PR targets Bounty #946; changes confined to: app/mcp.py (outputSchema), docs/agent-guide.md (docs), tests/test_api_mcp.py (validation). No unrelated ledger, custody, payout behavior changes.

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

[NiXouuuu]

Approved current head 3175cd5b2250ff662fe56b74a9eebea645d201f6.

Files inspected: app/mcp.py, app/mcp_tools.py, app/ledger/service.py, tests/test_api_mcp.py, docs/agent-guide.md.

Verdict: approved. The new get_balance outputSchema matches the existing structured runtime payload returned by mcp_tools.py: normalized account, formatted balance_mrwk, and integer balance_microunits. The test update checks the advertised schema and verifies the returned structured content has exactly the required output fields, while docs now point agents to the advertised schema instead of text parsing.

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 tests/test_mcp_tools.py -q -> 131 passed, 1 existing Starlette/httpx warning.
• uv run --python 3.12 --extra dev ruff check app/mcp.py tests/test_api_mcp.py docs/agent-guide.md -> passed.
• uv run --python 3.12 --extra dev ruff format --check app/mcp.py tests/test_api_mcp.py -> 2 files already formatted.
• uv run --python 3.12 --extra dev mypy app/mcp.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 3f02091ecb220c9aaa0495ec0848d48e12c65179.

GitHub state checked before review: open, non-draft, no human reviews, mergeable=MERGEABLE; mergeStateStatus=UNSTABLE because CodeRabbit was still pending at review time, so maintainers should still wait for final hosted status before merging.

Scope boundaries: read-only review of MCP schema/docs/tests. No ledger mutation, wallet behavior, treasury/proposal execution, payout execution, admin-token APIs, private data, credentials, bridge/exchange/off-ramp/cash-out behavior, or MRWK price/value claim was used.

[Guciolek]

Tight, well-scoped schema work for get_balance. Three things stand out:

• The outputSchema exposes both the human-friendly decimal (balance_mrwk with the ^\d+(?:\.\d{1,6})?$ pattern) and the raw integer (balance_microunits with minimum: 0). That dual representation is the right call for an MCP consumer that wants to do arithmetic without precision loss — microunits for math, decimal string for display.
• additionalProperties: False on the output is the right choice for get_balance: the response is a closed tuple of (account, balance_mrwk, balance_microunits), and rejecting extra fields catches accidental field drift early.
• The required list is explicit and non-empty: structured outputs will reject any response that omits one of the three. Good.

The docs line in agent-guide.md is updated to point at the new outputSchema, which keeps the user-facing text in sync.

The new test assertions in test_api_mcp.py cover the schema shape (additionalProperties: False, the required list, the balance_mrwk pattern, the balance_microunits minimum) and a runtime check that the actual structuredContent returned by get_balance has the same set of keys as the required list. That last assertion is the kind of cross-check I like to see — it ties the schema to the real response.

Verified: additive change, no production logic touched, app/mcp.py is +21 lines, no new imports. ruff check and ruff format --check should pass. Approving.