Proposed work: add issue-number selectors to MCP bounty lookup tools

[xyjk0511]

Problem

Agent workflows often start from a GitHub bounty issue number or issue URL, such as #649, not from the internal MRWK bounty id. REST bounty rows expose both the internal id and GitHub issue_number, and submit_work_proof already supports issue_number with optional repo scoping.

MCP get_bounty currently accepts only the internal bounty id, and list_bounty_attempts currently accepts only internal bounty_id. That forces agents to list/search bounties first before they can inspect a known bounty or its active attempts through MCP, even when they already know the GitHub issue number.

Evidence

• Live MCP call get_bounty with arguments { "issue_number": 649, "repo": "ramimbo/mergework" } returned JSON-RPC error invalid tool arguments.
• Current app/mcp_tools.py handles get_bounty with session.get(Bounty, positive_int_arg("id")) only.
• Current app/mcp_tools.py handles list_bounty_attempts with positive_int_arg("bounty_id") only.
• submit_work_proof already supports either bounty_id or issue_number, with optional repo scoping when using issue number, and returns a clear ambiguity error if issue-number lookup matches more than one bounty.
• Public docs repeatedly warn that internal bounty id is not the same as GitHub issue number. For example MRWK bounty: 50 MRWK - accepted proposed-work requests, round 1 #649 is GitHub issue 649, while its public MRWK bounty row is internal bounty id 96.

Proposed work

Extend MCP bounty lookup selectors so agents can use the identifier they already have.

Suggested scope:

• Extend get_bounty to accept either:
  • internal id, or
  • GitHub issue_number with optional repo.
• Use the same ambiguity/error behavior as submit_work_proof for issue-number lookups.
• Optionally extend list_bounty_attempts with the same selector parity, so active attempts can be queried by known bounty issue number.
• Update MCP docs/examples to show internal id lookup and issue-number lookup.

Expected value

• Agents can inspect known bounty issues through MCP without an extra list/search step.
• The MCP selector model becomes consistent with submit_work_proof.
• The change reduces confusion between GitHub issue numbers and internal MRWK bounty ids without changing MRWK state.
• Maintainers get clearer tests for ambiguous issue-number behavior and selector exclusivity.

Relationship to related proposals

• Proposed work: expose structured submission mode for non-PR bounties #676 helps agents understand what artifact a bounty expects. This issue helps agents select the bounty row when they already know the GitHub issue number.
• Proposed work: add typed OpenAPI response schemas for public MRWK read APIs #688 covers OpenAPI REST schemas, not MCP selector behavior.
• Proposed work: add review-bounty candidate selection report #693 covers review-bounty candidate selection, not MCP bounty lookup.
• Proposed work: add a related bounty/source field to the proposed-work template #708 and Proposed work: add bounty lifecycle and treasury discovery links to public docs #709 cover proposed-work source fields and public docs navigation, not MCP lookup selectors.
• Proposed work: add input schemas for all MCP tools #710 covers MCP input schema metadata. This issue is a behavioral selector-parity change; Proposed work: add input schemas for all MCP tools #710 could document the schema for the new selectors if both are implemented.

Possible acceptance criteria

• MCP get_bounty can look up a bounty by internal id or by GitHub issue_number plus optional repo.
• Supplying both id and issue_number returns a clear invalid-argument error instead of guessing.
• Ambiguous issue-number lookups return a clear error instead of guessing.
• Existing internal-id behavior remains unchanged.
• If list_bounty_attempts is included, it supports the same selector parity while preserving existing bounty_id behavior.
• Docs show when to use internal id versus issue number.
• No payout, proof, treasury, wallet, claim, or bounty acceptance behavior changes.

Evidence or tests required

• Add focused MCP tool tests for get_bounty by internal id and by issue number plus repo.
• Add tests for invalid combinations and ambiguous issue-number lookups.
• Add or update tests for list_bounty_attempts if selector parity is included there.
• Run existing MCP and bounty API tests to confirm current id-based behavior remains intact.

Duplicate search

I searched for existing issues using phrases including:

• MCP issue_number get_bounty
• get_bounty issue_number
• internal bounty id issue number
• MCP bounty issue number selector

I did not find an existing proposed-work item for MCP bounty lookup selector parity. Related but distinct work is #676, #688, #693, #708, #709, and #710 as described above.

Out of scope

• No change to REST endpoint paths or public bounty ids.
• No automatic guessing across multiple repos when issue numbers are ambiguous.
• No changes to payout execution, proof creation, treasury proposals, wallet signatures, balances, ledger mutation, exchange, bridge, cash-out, private security handling, or fabricated paid-work status.
• No private contact or private payment-channel behavior.