Reject unknown MCP bounty list arguments

[xiefuzheng713-alt]

Bounty #844

Summary

• reject undeclared list_bounties MCP arguments before applying defaults;
• prevent typoed agent calls like { statuz: paid } from silently returning the default open-bounty query;
• document the stricter list_bounties argument behavior in MCP examples.

Duplicate / Scope Check

• distinct from Document get_balance MCP account selectors #891: this does not change get_balance wording or selector guidance;
• distinct from Limit MCP bounty search query length #862: this does not change q length or search validation;
• distinct from Align submit_work_proof MCP contract #856: this does not touch submit_work_proof argument handling;
• distinct from feat: add MCP input schemas #738: this is a narrow runtime guard for list_bounties, not a broad tools/list inputSchema PR, and feat: add MCP input schemas #738 is currently dirty/needs-info;
• no ledger, wallet, treasury, payout, proposal execution, admin-token behavior, exchange, bridge, cash-out, MRWK price behavior, private data, credentials, or secrets are changed.

Validation

• uv run --python 3.12 --extra dev python -m pytest tests/test_mcp_tools.py tests/test_api_mcp.py::test_mcp_list_bounties_rejects_invalid_filters -q -> 16 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_tools.py tests/test_api_mcp.py tests/test_mcp_tools.py -> passed.
• uv run --python 3.12 --extra dev ruff format --check app/mcp_tools.py tests/test_api_mcp.py tests/test_mcp_tools.py -> 3 files already formatted.
• 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 ed74afeb10150b5eb6f0814bf1cba01cf0d541b9.

Summary by CodeRabbit

• Bug Fixes

  • The list_bounties tool now validates input arguments and rejects typos or unexpected parameters, providing clear error messages instead of silently ignoring invalid inputs.

• Documentation

  • Updated API examples to clarify that unknown argument names are rejected during validation.

[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: 83e7f934-bd3e-4d0d-9b25-f753fb279873

📥 Commits

Reviewing files that changed from the base of the PR and between d4d0e48 and d8fac66.

📒 Files selected for processing (4)

• app/mcp_tools.py
• docs/api-examples.md
• tests/test_api_mcp.py
• tests/test_mcp_tools.py

---

📝 Walkthrough

Walkthrough

The PR adds strict argument validation to the list_bounties MCP tool. A new internal helper function rejects unexpected argument keys, enforcing an explicit allowlist of five parameters. The tool now raises ValueError on typos or unknown fields instead of silently ignoring them. Documentation and tests cover the new behavior.

Changes

MCP list_bounties argument validation

Layer / File(s)	Summary
Argument validation helper and list_bounties integration app/mcp_tools.py, docs/api-examples.md	Internal reject_unexpected_args helper validates that args contain only keys in an allowed set, raising ValueError on the first unexpected key. The list_bounties branch enforces the allowlist: availability, limit, q, sort, status. Documentation clarifies the semantics of availability=effectively_open and notes that unknown argument names are rejected.
Test coverage for unknown arguments tests/test_mcp_tools.py, tests/test_api_mcp.py	New test test_call_mcp_tool_rejects_unknown_list_bounties_arguments verifies that a misspelled argument like statuz raises ValueError with the expected error message. Parametrized test case extended with the same misspelled field scenario.

Possibly related issues

• ramimbo/mergework#794: Directly implements runtime rejection of unexpected list_bounties arguments to address undeclared-argument schema mismatch.
• ramimbo/mergework#844: Implements the MCP conformance improvement requested by aligning input schemas and ensuring safer argument validation errors.

Possibly related PRs

• ramimbo/mergework#468: Both PRs modify list_bounties argument handling; #468 adds the sort argument support that is now included in this PR's explicit allowlist.
• ramimbo/mergework#286: Both PRs tighten call_mcp_tool validation for list_bounties; #286 added status, q, and limit filters that are now part of the validated allowlist.

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately names the changed surface: rejecting unknown MCP bounty list arguments, which directly reflects the core change across all modified files.
Description check	✅ Passed	The description provides clear summary, scope distinctions, validation evidence, and test results matching the template structure with all critical sections completed.
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 argument validation to list_bounties MCP tool with no investment, price, cash-out, or payout claims in new public artifacts.
Bounty Pr Focus	✅ Passed	Diff matches stated scope: 4 files modified for MCP list_bounties validation with exact line counts. Feature restricts 5 allowed arguments with proper test coverage and no unrelated 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.}

[mauricemohr88-debug]

Current-head review for #838 on d8fac662424bb23000d256c8ab2ee2065b2bb5a7.

Evidence checked:

• Inspected the list_bounties runtime guard in app/mcp_tools.py; the new unexpected-argument check runs before defaults are applied, so typoed calls like statuz fail instead of silently returning the default open-bounty list.
• Verified the allowed argument set matches the MCP list_bounties surface documented in app/mcp.py: status, q, sort, limit, and availability. Repository/issue lookup remains on get_bounty, list_bounty_attempts, and submit_work_proof.
• Inspected the API/MCP regression tests in tests/test_api_mcp.py and tests/test_mcp_tools.py; both cover the typo path.
• Ran uv run --python 3.12 --extra dev python -m pytest tests/test_mcp_tools.py tests/test_api_mcp.py::test_mcp_list_bounties_rejects_invalid_filters -q: 16 passed, 1 existing Starlette warning.
• Ran uv run --python 3.12 --extra dev ruff check app/mcp_tools.py tests/test_api_mcp.py tests/test_mcp_tools.py: passed.
• Ran uv run --python 3.12 --extra dev ruff format --check app/mcp_tools.py tests/test_api_mcp.py tests/test_mcp_tools.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 narrow, test-backed, and improves agent safety by rejecting typoed list_bounties arguments before returning misleading bounty discovery results.