Accept id alias for MCP attempt lookup

[catcherintheroad-hub]

Bounty #844

Summary

• lets list_bounty_attempts accept id as an alias for the existing internal bounty_id selector;
• rejects mixed bounty_id + id selectors to keep internal bounty lookup unambiguous;
• updates tools/list wording and agent/API docs so agents can reuse the id field returned by list_bounties or get_bounty before opening overlapping work.

Duplicate / Scope Check

• distinct from Accept bounty_id alias for MCP get_bounty #908: this does not change get_bounty; it covers list_bounty_attempts selector usability.
• distinct from Accept API field aliases in MCP lookups #893: no proof or ledger selector alias changes.
• distinct from Reject unexpected MCP read tool arguments #899/Reject unknown MCP bounty list arguments #892: this does not add broad unexpected-argument guards; it defines one valid alias for an existing read-only selector.
• distinct from feat: add MCP input schemas #738: no broad tools/list input schema work.
• no wallet registration, wallet transfer signing, ledger mutation, bounty payout, treasury mutation, 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_api_mcp.py::test_mcp_tools_list_and_call tests/test_api_mcp.py::test_mcp_list_bounty_attempts_reports_active_and_expired tests/test_api_mcp.py::test_mcp_list_bounty_attempts_accepts_issue_number_selector tests/test_api_mcp.py::test_mcp_list_bounty_attempts_accepts_id_alias tests/test_api_mcp.py::test_mcp_list_bounty_attempts_rejects_invalid_arguments tests/test_api_mcp.py::test_mcp_list_bounty_attempts_rejects_mixed_id_aliases -q -> 6 passed, 1 existing warning.
• uv run --python 3.12 --extra dev python -m pytest tests/test_api_mcp.py tests/test_mcp_tools.py tests/test_docs_public_urls.py -q -> 149 passed, 1 existing warning.
• uv run --python 3.12 --extra dev ruff check app/mcp_tools.py app/mcp.py tests/test_api_mcp.py docs/api-examples.md docs/agent-guide.md -> passed.
• uv run --python 3.12 --extra dev ruff format --check app/mcp_tools.py app/mcp.py tests/test_api_mcp.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 abda6f4c7b8cc6d19c1ef4bc0fd2711b121cfce1.

Summary by CodeRabbit

• New Features

  • The list_bounty_attempts tool now accepts an alternate internal id field (id) as an alternative to bounty_id for selecting a bounty.
  • Selection enforces mutual exclusivity: requests may not mix internal-id selectors with each other or with an issue_number.

• Documentation

  • Guidance and examples updated to show using either bounty_id or id when listing bounty attempts.

• Tests

  • Added tests covering the id alias acceptance and rejection of ambiguous/mixed selectors.

[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: 82a7202e-e701-4879-a63a-6e946464843a

📥 Commits

Reviewing files that changed from the base of the PR and between c981b88 and 4c7c691.

📒 Files selected for processing (2)

• app/mcp_tools.py
• tests/test_mcp_tools.py

---

📝 Walkthrough

Walkthrough

The PR extends the list_bounty_attempts MCP tool to accept id as an internal-ID alias alongside bounty_id for bounty selection. The core selected_bounty helper validates that only one internal-ID field is supplied, maintains mutual exclusivity with issue_number, and resolves the bounty using the selected field. Tool metadata, documentation, and tests are updated accordingly.

Changes

id alias support for bounty selection

Layer / File(s)	Summary
Bounty selector logic with alias support app/mcp_tools.py	The selected_bounty helper now accepts internal_id_aliases, builds the primary+alias internal-ID set, rejects multiple internal-ID fields, enforces mutual exclusivity with issue_number (and repo-only-with-issue_number), and resolves the bounty via the selected internal-ID field. list_bounty_attempts calls selected_bounty("bounty_id", internal_id_aliases=("id",)).
Tool documentation and examples app/mcp.py, docs/agent-guide.md, docs/api-examples.md	Tool description, agent guide, and API examples updated to document that list_bounty_attempts accepts either bounty_id or the id field returned by list_bounties, with curl examples demonstrating both selectors.
Validation tests for alias behavior tests/test_api_mcp.py, tests/test_mcp_tools.py	Tests verify list_bounty_attempts accepts the id alias and rejects ambiguous/mixed selectors (both bounty_id and id together), and a unit test verifies error when id is mixed with issue_number.

Possibly related issues

• Proposed work: add issue-number selectors to MCP bounty lookup tools #711: Both touch MCP bounty-selection logic; this PR adds the id alias support referenced in that discussion.

Possibly related PRs

• ramimbo/mergework#732: Also modifies bounty-selection logic in call_mcp_tool for list_bounty_attempts; related at the selector validation level.
• ramimbo/mergework#398: Introduced the call_mcp_tool dispatcher/argument normalization that this PR extends.
• ramimbo/mergework#334: Originally introduced list_bounty_attempts; this PR extends its argument selection to accept the id alias.

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concretely identifies the main change: adding an id alias for the list_bounty_attempts tool's bounty selector.
Description check	✅ Passed	The description covers the summary, scope validation, test evidence with specific commands and results, and includes the bounty reference. All required sections are present and substantive.
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 id alias for list_bounty_attempts (technical change only). No investment, price, cash-out, off-ramp, or payout claims introduced. Existing disclaimers properly describe MRWK constraints.
Bounty Pr Focus	✅ Passed	PR changes match stated scope: only list_bounty_attempts accepts id alias, get_bounty/list_bounties unchanged, wallet/ledger untouched, test coverage verifies alias and rejection of mixed selectors.

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

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

app/mcp_tools.py (1)

140-163: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Inconsistent error message when alias is rejected alongside issue_number.

The error on line 155 always references internal_id_field ("bounty_id"), even when the user provided the "id" alias. For example, if the user sends {"id": 11, "issue_number": 404}, the error says "use bounty_id or issue_number, not both" even though they never used "bounty_id".

For consistency with the mixed-alias error on line 152, consider using the actual field name the user provided:

 if has_internal_id and has_issue_number:
-    raise ValueError(f"use {internal_id_field} or issue_number, not both")
+    raise ValueError(f"use {provided_internal_id_fields[0]} or issue_number, not both")

This matches the pattern on line 152 and makes the error message directly actionable.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 971df2e7-a75c-4146-963c-dc541361fc62

📥 Commits

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

📒 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

[catcherintheroad-hub]

Follow-up for CodeRabbit's selector-message note.

Updated head: 4c7c691 Clarify MCP attempt alias selector errors.

Change since initial claim:

• list_bounty_attempts now reports the actual provided internal selector when it is mixed with issue_number; for example id + issue_number reports use id or issue_number, not both rather than naming bounty_id.
• Added direct dispatcher coverage for the id + issue_number error message.

Updated validation:

• focused alias/error tests: 3 passed, 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 tests/test_docs_public_urls.py -q -> 150 passed, 1 existing Starlette/httpx warning.
• uv run --python 3.12 --extra dev ruff check app/mcp_tools.py tests/test_mcp_tools.py -> passed.
• uv run --python 3.12 --extra dev ruff format --check app/mcp_tools.py tests/test_mcp_tools.py -> 2 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 d97d9b7a1ca201506174573b3b71a1f9403496eb.

Scope remains read-only MCP list_bounty_attempts selector behavior and docs only; no wallet, ledger, treasury, payout, admin-token, private data, exchange, bridge, cash-out, or MRWK price behavior changed.

[szx19970521]

Reviewed current head $head for #838.

The change is narrowly scoped to MCP bounty-attempt lookup ergonomics: list_bounty_attempts now accepts id as an alias for �ounty_id, rejects mixed �ounty_id/id selectors, and keeps the existing issue_number path separate. I checked the follow-up commit as well: CodeRabbit's earlier error-message consistency note is addressed by reporting the actual provided selector when id is combined with issue_number.

Validation performed locally on this exact head:

` ext
python -m pytest tests/test_api_mcp.py::test_mcp_tools_list_and_call tests/test_api_mcp.py::test_mcp_list_bounty_attempts_reports_active_and_expired tests/test_api_mcp.py::test_mcp_list_bounty_attempts_accepts_issue_number_selector tests/test_api_mcp.py::test_mcp_list_bounty_attempts_accepts_id_alias tests/test_api_mcp.py::test_mcp_list_bounty_attempts_rejects_invalid_arguments tests/test_api_mcp.py::test_mcp_list_bounty_attempts_rejects_mixed_id_aliases -q

6 passed, 1 existing warning

python -m pytest tests/test_api_mcp.py tests/test_mcp_tools.py tests/test_docs_public_urls.py -q

150 passed, 1 existing warning

python -m ruff check app/mcp_tools.py app/mcp.py tests/test_api_mcp.py docs/api-examples.md docs/agent-guide.md

All checks passed

python -m ruff format --check app/mcp_tools.py app/mcp.py tests/test_api_mcp.py

3 files already formatted

python -m mypy app/mcp_tools.py app/mcp.py

Success: no issues found in 2 source files

python scripts/docs_smoke.py

docs smoke ok

`

I also rechecked hosted status before approval: mergeable clean, Quality/readiness/docs/image check success, and CodeRabbit success. No blocker found.