Accept API field aliases in MCP lookups

[xiefuzheng713-alt]

Summary

Bounty #844 MCP usability follow-up.

This PR lets MCP lookup tools accept the same field names agents receive from public API payloads and exposes those aliases in tools/list descriptions:

• get_proof keeps hash and also accepts proof_hash.
• get_ledger_entry keeps sequence and also accepts ledger_sequence.
• Passing both names for the same selector remains invalid to avoid ambiguous calls.

Agents commonly receive proof_hash and ledger_sequence from /api/v1/activity, /api/v1/ledger, get_bounty award rows, get_proof, and get_ledger_entry. Accepting these aliases avoids predictable -32602 invalid tool arguments dead ends without changing response shapes.

Live behavior checked before the fix

Against https://mcp.mrwk.online/mcp using public proof/ledger values from /api/v1/activity:

• get_proof with arguments.hash returned the proof payload successfully.
• get_proof with the same value under arguments.proof_hash returned -32602 invalid tool arguments.
• get_ledger_entry with arguments.sequence returned the ledger-entry payload successfully.
• get_ledger_entry with the same value under arguments.ledger_sequence returned -32602 invalid tool arguments.

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_ledger_entry_rejects_mixed_sequence_selectors tests/test_api_mcp.py::test_mcp_get_proof_returns_public_proof_details tests/test_api_mcp.py::test_mcp_get_proof_rejects_mixed_hash_selectors -q -> 5 passed, 1 existing warning
• uv run --python 3.12 --extra dev python -m pytest tests/test_api_mcp.py tests/test_mcp_tools.py -q -> 114 passed, 1 existing warning
• uv run --python 3.12 --extra dev ruff check app/mcp.py app/mcp_tools.py tests/test_api_mcp.py -> passed
• uv run --python 3.12 --extra dev ruff format --check app/mcp.py app/mcp_tools.py tests/test_api_mcp.py -> passed
• uv run --python 3.12 --extra dev mypy app/mcp_tools.py 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 e89a80c362f20dcd98aaf41cfad383b6c7b44f72

Scope

Focused MCP selector usability and tool descriptions only. No proof payload shape, ledger-entry response shape, ledger mutation, payout execution, wallet behavior, treasury behavior, admin-token behavior, private data, bridge, exchange, cash-out, or MRWK price behavior is changed.

Summary by CodeRabbit

• New Features

  • Lookups now accept either hash or proof_hash for proofs, and either sequence or ledger_sequence for ledger entries; requests providing both alternatives are rejected.

• Documentation

  • API examples updated to show the alternate parameter names for proof and ledger lookups.

• Tests

  • Added tests verifying the alternate parameters and rejection of mixed selectors.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds exclusive dual-selector parsing for MCP tool inputs: get_proof accepts exactly one of hash or proof_hash (canonicalized via proof_hash_from_path); get_ledger_entry accepts sequence or ledger_sequence. Tests cover both aliases and mixed-selector rejection; docs and tool descriptions updated.

Changes

MCP selector normalization

Layer / File(s)	Summary
Proof selector validation and integration app/mcp_tools.py, tests/test_api_mcp.py, docs/api-examples.md	Add proof_hash_arg helper enforcing exactly one of hash/proof_hash, canonicalize via proof_hash_from_path, use it for Proof lookup in get_proof; extend tests to call with proof_hash and reject mixed selectors; document proof_hash usage.
Ledger sequence selector and metadata app/mcp_tools.py, app/mcp.py, tests/test_api_mcp.py, docs/api-examples.md	Use ledger_sequence_arg() in get_ledger_entry to accept sequence or ledger_sequence, update MCP_TOOLS descriptions to mention ledger_sequence, extend tests to call with ledger_sequence and reject mixed selectors.

Possibly related PRs

• ramimbo/mergework#398: Also touches MCP tool argument-validation/dispatch logic and selector normalization.
• ramimbo/mergework#526: Modifies MCP get_proof handling (related to proof row/public_json handling).
• ramimbo/mergework#329: Previously updated MCP_TOOLS definitions and handler catalog.

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concretely names the changed surface: accepting API field aliases in MCP lookup tools.
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 contains no investment, price, cash-out, payout, or security claims. Changes limited to MCP tool parameter aliases and documentation. MRWK properly described as bounty rewards.
Bounty Pr Focus	✅ Passed	PR #893 scope is focused: field-alias support for MCP tools (proof_hash/hash, ledger_sequence/sequence), with tests and documentation. No unrelated changes to payloads or payment logic.
Description check	✅ Passed	PR description comprehensively covers all required template sections with specific evidence, validation results, and scope clarification.

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

Current-head review for #838 on 49033480f40c091c7cec2ae5a2fab88d0da708a9.

Evidence checked:

• Inspected app/mcp_tools.py; get_proof now accepts hash or proof_hash, and get_ledger_entry now accepts sequence or ledger_sequence, while mixed selectors still raise before lookup.
• Verified the aliases are read through the existing validators (str_arg, proof_hash_from_path, and positive_int_arg), so malformed hashes, non-positive ledger sequences, and wrong types continue to be rejected by the same paths.
• Inspected app/mcp.py and docs/api-examples.md; the tool descriptions and MCP examples now mention the aliases without changing response shapes.
• Inspected tests/test_api_mcp.py; coverage checks tools/list descriptions, alias parity with canonical selectors, and mixed-selector rejection for both tools.
• Ran 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_ledger_entry_rejects_mixed_sequence_selectors tests/test_api_mcp.py::test_mcp_get_proof_returns_public_proof_details tests/test_api_mcp.py::test_mcp_get_proof_rejects_mixed_hash_selectors -q: 5 passed, 1 existing Starlette warning.
• Ran uv run --python 3.12 --extra dev python -m pytest tests/test_api_mcp.py tests/test_mcp_tools.py -q: 114 passed, 1 existing warning.
• Ran uv run --python 3.12 --extra dev ruff check app/mcp.py app/mcp_tools.py tests/test_api_mcp.py: passed.
• Ran uv run --python 3.12 --extra dev ruff format --check app/mcp.py app/mcp_tools.py tests/test_api_mcp.py: 3 files already formatted.
• Ran uv run --python 3.12 --extra dev mypy app/mcp_tools.py app/mcp.py: success.
• Ran uv run --python 3.12 --extra dev python scripts/docs_smoke.py: docs smoke ok.
• Ran git diff --check origin/main...HEAD and git merge-tree --write-tree origin/main HEAD: clean.

No blocker found. The change is a narrow MCP usability improvement that maps public API field names onto existing lookup validators without mutating ledger, proof, treasury, wallet, or payout behavior.