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

  • list_bounty_attempts accepts an alternate internal id field (id) as an alternative to bounty_id.
  • Selection enforces mutual exclusivity: you cannot 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 for id alias acceptance and rejection of ambiguous/mixed selectors; error messages now name the provided conflicting fields.

[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: 83cca9eb-6d7f-4f3a-82a8-f732c291724d

📥 Commits

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

📒 Files selected for processing (6)

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

---

📝 Walkthrough

Walkthrough

Adds id as an internal-ID alias to MCP list_bounty_attempts; updates selected_bounty validation messages to name provided internal-ID fields; updates tool metadata and docs; and adds tests verifying alias acceptance and mixed-selector rejection.

Changes

id alias support for bounty selection

Layer / File(s)	Summary
Bounty selector logic with alias support app/mcp_tools.py	selected_bounty error formatting now references the provided internal-ID field(s); list_bounty_attempts is invoked with internal_id_aliases=("id",), enabling id as an alias for bounty_id.
Tool metadata and examples app/mcp.py, docs/agent-guide.md, docs/api-examples.md	MCP_TOOLS description updated to mention the id alias; agent guide and API examples include curl invocations showing both bounty_id and id selectors (with include_expired:false).
Validation tests for alias behavior tests/test_api_mcp.py, tests/test_mcp_tools.py	New tests assert list_bounty_attempts accepts arguments.id, rejects ambiguous input when both bounty_id and id are provided, and raises an 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 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 names the primary change: accepting an id alias for the list_bounty_attempts MCP tool.
Description check	✅ Passed	The description covers all required template sections with concrete detail: summary of changes, explicit scope clarification and distinction from related work, validation steps with commands and results, and proper bounty reference.
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 MCP tool. No investment, price, cash-out, or payout claims added. MRWK properly described as native coin with future bridges/snapshots.
Bounty Pr Focus	✅ Passed	Six files modified match scope: app/mcp.py metadata, app/mcp_tools.py core logic, docs updated, 3 tests added. Implementation verified; no unrelated changes to wallet, ledger, or treasury.

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

[catcherintheroad-hub]

Current-head readiness note after the rebase repair.

Head 72b21ade4dd4d393498c4e95d8936462ac2bd744 is now clean against current main.

Hosted status checked:

• CI Quality, readiness, docs, and image checks: success.
• CodeRabbit: success, no actionable comments on the rebased head.
• Merge state: CLEAN.
• Current-head human review is approved.

Local validation on the rebased head:

• focused alias/error tests: 7 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 -> 156 passed, 1 existing Starlette/httpx warning.
• uv run --python 3.12 --extra dev ruff check app/mcp_tools.py app/mcp.py tests/test_api_mcp.py tests/test_mcp_tools.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 tests/test_mcp_tools.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.

Scope remains limited to read-only MCP list_bounty_attempts selector ergonomics and docs/tests. No wallet, ledger, treasury, payout, admin-token, private data, exchange, bridge, cash-out, MRWK price, or investment behavior is changed.