Accept bounty_id alias for MCP get_bounty

[pqmfei]

Summary

Bounty #844

• let MCP get_bounty accept bounty_id as an alias for the existing internal id selector;
• reject calls that pass both id and bounty_id so agents do not get ambiguous selector behavior;
• update tools/list wording plus agent/API docs to mention the alias.

Evidence / duplicate check

• This is a focused MCP selector-usability improvement for agents reusing bounty_id fields from related bounty/attempt payloads.
• Open PR searches for get_bounty bounty_id, bounty_id alias, and get_bounty id found no same-scope open PR.
• Distinct from Accept API field aliases in MCP lookups #893 proof/ledger selector aliases, Reject unexpected MCP read tool arguments #899 unexpected read-tool argument rejection, Reject unknown MCP bounty list arguments #892 list_bounties argument guard, and Align submit_work_proof MCP contract #856 submit_work_proof contract alignment.

Validation

• .\.venv\Scripts\python.exe -m pytest tests\test_api_mcp.py tests\test_mcp_tools.py tests\test_docs_public_urls.py -q -> 149 passed, 1 existing Starlette/httpx warning
• .\.venv\Scripts\python.exe -m ruff check app\mcp.py app\mcp_tools.py tests\test_api_mcp.py docs\api-examples.md docs\agent-guide.md tests\test_docs_public_urls.py -> passed
• .\.venv\Scripts\python.exe -m ruff format --check app\mcp.py app\mcp_tools.py tests\test_api_mcp.py tests\test_docs_public_urls.py -> 4 files already formatted
• .\.venv\Scripts\python.exe -m mypy app\mcp.py app\mcp_tools.py -> success
• .\.venv\Scripts\python.exe scripts\docs_smoke.py -> docs smoke ok
• git diff --check origin/main...HEAD -> clean
• git merge-tree --write-tree origin/main HEAD -> clean tree de3fc5c4bd73b62ff49fee9ca013f9dfcb3cf65e

Scope safety

No wallet registration, wallet transfer signing, ledger mutation, bounty payout, treasury mutation, admin-token behavior, private data, credentials, secrets, exchange, bridge, cash-out, or MRWK price behavior changed.

Summary by CodeRabbit

• New Features

  • The get_bounty tool now accepts bounty_id as an alternative parameter for bounty retrieval, enabling more flexible lookup options.

• Documentation

  • Updated agent guide with instructions to inspect bounties via get_bounty before preparing evidence submissions.
  • Expanded API examples demonstrating bounty_id parameter usage alongside existing lookup methods.

[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: 01c235b6-b270-420c-a78b-09d0c629ff75

📥 Commits

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

📒 Files selected for processing (5)

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

---

📝 Walkthrough

Walkthrough

The PR extends the get_bounty MCP tool to accept bounty_id as an alias for the internal bounty id field. The core change validates that at most one internal-id field is provided and enforces exclusivity between internal-id and issue_number selectors. Documentation and tests are updated accordingly.

Changes

Bounty ID Alias Support

Layer / File(s)	Summary
Internal-id alias selector with validation app/mcp_tools.py	selected_bounty helper now accepts internal_id_aliases parameter, validates that at most one internal-id field (including aliases) is provided, enforces mutual exclusivity between internal-id fields and issue_number, and performs session.get using the provided internal-id field.
Tool integration and description app/mcp.py, app/mcp_tools.py	get_bounty tool description updated to document support for bounty_id alias, and tool call-site wired to pass internal_id_aliases=("bounty_id",) to enable the alias.
Acceptance and validation tests tests/test_api_mcp.py	Two test cases added: one verifies get_bounty resolves a bounty when called with bounty_id argument; another verifies mixed internal-id selectors (id and bounty_id both provided) are rejected with invalid tool arguments error.
Documentation and examples docs/agent-guide.md, docs/api-examples.md	Agent guide instructs agents to inspect bounty before preparing evidence using get_bounty (with bounty_id or issue_number/repo); API examples show curl call using bounty_id: 11 alongside existing id: 11 example.

Possibly related issues

• ramimbo/mergework#711: Changes to selected_bounty logic in app/mcp_tools.py and addition of aliasing/exclusivity validation directly relate to proposed issue-number selector work.

Possibly related PRs

• ramimbo/mergework#289: Both PRs modify get_bounty tool description and tests; #289 adds include_awards optional boolean while this PR adds bounty_id alias selector support.
• ramimbo/mergework#398: Both PRs modify MCP tool argument validation and dispatch logic in app/mcp_tools.py for bounty lookups.
• ramimbo/mergework#732: Both PRs extend selected_bounty bounty-selection logic in app/mcp_tools.py; #732 adds shared issue-number selectors while this PR extends support to internal bounty_id alias.

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Accept bounty_id alias for MCP get_bounty' clearly and concretely names the changed surface (the get_bounty MCP tool and its new bounty_id alias support).
Description check	✅ Passed	The PR description includes all required sections: Summary with bounty reference, Evidence with duplication check and scope safety details, and comprehensive Validation results covering tests, linting, type checking, and documentation checks.
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	All changes are technical documentation and implementation for a bounty_id API alias. No investment, price, cash-out, payout, or security claims were added.
Bounty Pr Focus	✅ Passed	PR implements bounty_id alias correctly: description updated, internal_id_aliases validation added, tests verify acceptance and rejection, docs updated with examples, no scope creep.

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

[catcherintheroad-hub]

Reviewed current head 914449c31a6bb4ee0b70de8d783854b4440bbe76 for the focused MCP get_bounty selector alias change.

What I checked:

• app/mcp_tools.py extends the existing selected_bounty() helper so get_bounty accepts bounty_id as an alias for the internal id selector.
• Mixed id + bounty_id is rejected before lookup, which avoids ambiguous internal selector input.
• Existing issue_number + optional repo behavior remains on the same helper path.
• app/mcp.py, docs/api-examples.md, and docs/agent-guide.md now document the alias in the agent-facing surface.
• tests/test_api_mcp.py covers successful bounty_id lookup, mixed internal-id rejection, and tools/list wording.

Local validation on this exact head:

• uv run --python 3.12 --extra dev python -m pytest tests/test_api_mcp.py -k 'get_bounty or tools_list or bounty_id_alias' -q -> 19 passed, 88 deselected, 1 existing Starlette/httpx 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 Starlette/httpx 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.py app/mcp_tools.py -> passed.
• uv run --python 3.12 --extra dev python scripts/docs_smoke.py -> passed.
• git diff --check origin/main...HEAD and git merge-tree --write-tree origin/main HEAD -> clean.

GitHub state checked before review: PR open and mergeable, no human reviews, no visible #838 claim for PR #908. CodeRabbit was still pending at review time, so maintainers should still consider any later bot feedback before merging. No blocker found in the reviewed code.