Add MCP schemas for proof and ledger lookups

[aosoficial]

Bounty #934

Summary

• Add tools/list input schemas for get_ledger_entry and get_proof.
• Document the required sequence and hash selectors for agent callers.
• Add MCP test coverage so the advertised schemas stay aligned with runtime lookup requirements.

Validation

• 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_mcp_get_ledger_entry_includes_payment_proof_hash tests/test_api_mcp.py::test_mcp_get_proof_returns_public_proof_details -q
• uv run --python 3.12 --extra dev ruff check app/mcp.py tests/test_api_mcp.py
• uv run --python 3.12 --extra dev ruff format --check app/mcp.py tests/test_api_mcp.py
• uv run --python 3.12 --extra dev mypy app/mcp.py
• uv run --python 3.12 --extra dev python scripts/docs_smoke.py
• git diff --check origin/main...HEAD
• git merge-tree --write-tree origin/main HEAD

Scope

This is limited to MCP tool schema/docs/tests. It does not change ledger, wallet, treasury, payout, admin, or price behavior.

Summary by CodeRabbit

• New Features

  • Enhanced input validation for MCP tools with schema-based constraints on parameters (sequence for ledger entries, hex-formatted hashes for proofs).

• Documentation

  • Updated agent guide with clarified input requirements for proof and ledger lookup operations.

• Tests

  • Added validation testing for MCP tool input schemas.

[coderabbitai]

Complex PR? Review this PR in Change Stack to move by importance, not file order.

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: 7d1d6708-9269-46d2-a1d5-7eda2508a985

📥 Commits

Reviewing files that changed from the base of the PR and between 8bdd282 and 0adcbc3.

📒 Files selected for processing (3)

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

---

📝 Walkthrough

Walkthrough

MCP tool definitions in app/mcp.py are updated with explicit JSON-schema inputSchema validation for get_ledger_entry (requiring sequence ≥ 1) and get_proof (requiring 64-character hex hash). Test assertions and documentation are updated to match the new schema constraints.

Changes

MCP Tool Schema Validation

Layer / File(s)	Summary
MCP tool schema definitions app/mcp.py	get_ledger_entry and get_proof tool entries in MCP_TOOLS now define explicit inputSchema objects with required fields, type constraints, and validation patterns: sequence (integer ≥ 1) and hash (64-character hex string).
Schema validation test assertions tests/test_api_mcp.py	Test extends test_mcp_tools_list_and_call to assert get_ledger_entry and get_proof tool inputSchema requirements and validation constraints for their respective input parameters.
Schema requirement documentation docs/agent-guide.md	Documentation clarifies that MCP tools/list advertises required selector schemas and specifies the argument requirements for get_proof (64-character hash) and get_ledger_entry (positive integer sequence).

Possibly Related PRs

• ramimbo/mergework#937: Updates MCP_TOOLS schema validation for get_balance and extends test_mcp_tools_list_and_call assertions in parallel with main PR's get_ledger_entry/get_proof changes.
• ramimbo/mergework#942: Adds stricter tools/list inputSchema validation to MCP_TOOLS and expands test_mcp_tools_list_and_call assertions in the same pattern.
• ramimbo/mergework#398: Refactors MCP tool dispatcher and argument validation for get_ledger_entry and get_proof lookups in app/mcp_tools.py.

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely names the changed surface by identifying the specific MCP schemas being added for proof and ledger lookups.
Description check	✅ Passed	The description covers all required template sections: a clear summary of changes, evidence of the problem addressed (Bounty #934), intended files/surfaces, validation commands, 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 introduces only technical MCP schema changes and documentation updates with no investment, price, cash-out, off-ramp, or fabricated payout claims added.
Bounty Pr Focus	✅ Passed	PR #974 does not reference "Bounty #N" or "Refs #N" pattern; check applicability condition not met. Files, scope isolation verified; test coverage included.

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

[elianguitarra]

Bounty #933 review packet

Reviewed head: 0adcbc3a6fea9deaaef888f57a47b6028eba93df

Files inspected:

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

Verdict: Looks useful and merge-ready from the reviewed surfaces. The PR adds missing tools/list schemas for get_ledger_entry and get_proof without changing runtime behavior, and the advertised constraints match the current dispatcher/path validation expectations: positive integer ledger sequence and 64-char hex proof hash. I did not find a blocker in this head.

Validation run locally on the PR head:

• .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_ledger_entry_rejects_non_positive_sequence tests/test_api_mcp.py::test_mcp_get_proof_returns_public_proof_details tests/test_api_mcp.py::test_mcp_get_proof_reports_unknown_hash tests/test_api_mcp.py::test_mcp_get_proof_rejects_malformed_hash -> 6 passed, 1 existing Starlette/httpx warning
• git diff --check 8bdd2823340d9704298e4829f42f53558aa83133..HEAD -> clean

Mergeability/overlap checked:

• GitHub reports PR #974 open, non-draft, mergeable.
• No human reviews were present before this review.
• CodeRabbit generated no actionable comments.