Advertise ledger proof MCP output schemas

[modelsbridgeaicom-ship-it]

Bounty #946 delivery summary:

• Adds MCP outputSchema metadata for get_ledger_entry, matching the ledger entry JSON already returned in result.structuredContent.
• Adds MCP outputSchema metadata for get_proof, matching the public proof wrapper already returned in result.structuredContent.
• Captures stable fields and constraints for ledger sequences, MRWK decimal strings, lowercase 64-char hashes, nullable proof/submission ids, and extensible nested public proof payloads.
• Preserves existing runtime text/structuredContent behavior; this is tools/list metadata, focused conformance coverage, and a concise agent guide note.

Validation:

• .\.venv\Scripts\python.exe -m pytest tests\test_api_mcp.py::test_mcp_tools_list_and_call tests\test_api_mcp.py::test_mcp_get_ledger_entry_includes_payment_proof_hash tests\test_api_mcp.py::test_mcp_get_proof_returns_public_proof_details -q -> 3 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\python.exe scripts\docs_smoke.py -> docs smoke ok.
• .\.venv\Scripts\python.exe -m mypy app\mcp.py -> Success: no issues found.
• .\.venv\Scripts\ruff.exe check app\mcp.py tests\test_api_mcp.py -> All checks passed.
• .\.venv\Scripts\ruff.exe format --check app\mcp.py tests\test_api_mcp.py -> 2 files already formatted.
• git diff --check -> clean, Windows CRLF warning only for docs.
• git merge-tree --write-tree origin/main HEAD -> clean tree e6b0725bcf4c3c1d0817802fbd89a1e1b1c039b9.

Touched surfaces: app/mcp.py, tests/test_api_mcp.py, docs/agent-guide.md. Scope is MCP tools/list output metadata for read-only ledger/proof lookups only; no runtime ledger mutation, proof storage behavior, wallet custody, payouts, treasury mutation, bridge/exchange/off-ramp, MRWK price behavior, private data, or secrets changed.

Summary by CodeRabbit

• New Features

  • Added structured output schemas for proof and ledger entry lookup tools with validated field formats including hash validation, timestamps, and amounts.

• Documentation

  • Clarified MCP tool capabilities and schema requirements in the agent guide for proof and ledger lookups.

• Tests

  • Expanded validation tests to verify structured output schemas and field constraints.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

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: 25d6ff25-31e8-4d61-92d6-cc8c62b69b46

📥 Commits

Reviewing files that changed from the base of the PR and between 6211b68 and 12e2018.

📒 Files selected for processing (3)

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

---

📝 Walkthrough

Walkthrough

This PR adds structured JSON output schemas for the get_ledger_entry and get_proof MCP tools. New schema constants define field types, patterns, and validation rules; tool definitions are updated to reference these schemas; test assertions validate schema structure and constraints; and agent documentation is updated to reflect the advertised output schemas.

Changes

MCP Output Schemas for Proof and Ledger Tools

Layer / File(s)	Summary
Output schema definition and tool registry wiring app/mcp.py	Two schema constants define structured outputs for get_ledger_entry (with 64-char hex hash, amount string, timestamp, sequence, and optional proof hash) and get_proof (with hash, ledger/bounty/submission IDs, timestamp, and open proof object). Tool definitions wire outputSchema properties to reference these constants.
Output schema test assertions tests/test_api_mcp.py	Test assertions validate both output schemas' structure, including field descriptions, required fields, additionalProperties constraints, and type/pattern rules for hashes, amounts, and integer identifiers.
Agent guide documentation docs/agent-guide.md	Documentation updated to clarify that tools/list advertises both selector schemas and structured output schemas for proof and ledger lookups.

Possibly related PRs

• ramimbo/mergework#329: Introduces/centralizes the MCP tool catalog and handler that serves the tools/list response updated by this PR.
• ramimbo/mergework#974: Extends MCP get_ledger_entry and get_proof tool schema definitions in app/mcp.py—focused on inputSchema while this PR focuses on outputSchema.

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly names the changed surface—adding MCP output schemas for ledger proof—and accurately describes the main change in the changeset.
Description check	✅ Passed	The description follows the template structure with Summary, Evidence, and Test Evidence sections, includes bounty tracking, validation results, and scope boundaries.
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 metadata-only MCP schemas with no investment, price, cash-out, payout, or security claims. MRWK references limited to technical decimal string patterns in ledger entry schema.
Bounty Pr Focus	✅ Passed	PR correctly touches stated files with schema additions matching line claims. Scope verified: metadata-only, no runtime mutations. Test evidence present for output schemas.

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

[modelsbridgeaicom-ship-it]

Withdrawing this PR after a post-submission duplicate check found existing open PR #1019 already targets the same get_ledger_entry / get_proof MCP output-schema scope. Closing this to avoid a duplicate #946 bounty claim under the issue's stale/duplicate work rules.

[modelsbridgeaicom-ship-it]

Closing as a duplicate of existing open PR #1019 for the same MCP ledger/proof output-schema scope.