Add MCP bounty attempt inspection

[TateLyman]

Bounty #321
/claim #321

Summary

• Adds a read-only MCP list_bounty_attempts tool so agents can inspect active advisory attempts for a bounty before opening overlapping work.
• Returns structured content with bounty id, issue number, bounty status, warning strings, and active attempt rows; include_expired and limit support audit views without changing REST registration/release behavior.
• Documents the MCP flow in the agent guide and API examples.

Validation

• uv run --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_rejects_invalid_arguments tests/test_bounty_attempts.py -q -> 6 passed
• uv run --extra dev python -m pytest tests/test_api_mcp.py tests/test_bounty_attempts.py -q -> 78 passed
• uv run --extra dev ruff check app/main.py app/mcp.py tests/test_api_mcp.py -> passed
• uv run --extra dev ruff format --check app/main.py app/mcp.py tests/test_api_mcp.py -> passed
• uv run --extra dev python -m mypy app/main.py app/mcp.py -> success
• uv run --extra dev python scripts/docs_smoke.py -> docs smoke ok
• git diff --check -> clean

No private keys, seed material, secrets, private vulnerability details, deployment credentials, or price claims are included.

Summary by CodeRabbit

• New Features

  • Added a tool to list and inspect bounty attempt reservations with filters for active/expired attempts and result limits, plus structured warnings and ordering.

• Documentation

  • Updated agent and API examples to demonstrate the new bounty-attempts listing call and adjusted example sequencing.

• Tests

  • Added tests covering listing behavior, ordering, warnings, limits, and invalid-parameter handling.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: c4345a2f-89bf-40c2-8cbd-5d13fcef8325

📥 Commits

Reviewing files that changed from the base of the PR and between 0314b79 and 65bcceb.

📒 Files selected for processing (1)

• docs/api-examples.md

---

📝 Walkthrough

Walkthrough

This PR adds a new MCP tool list_bounty_attempts that queries and returns bounty attempt reservations from the database. The tool validates the bounty ID, optionally filters active attempts, orders results, applies limits, computes warnings, and returns a structured response. Implementation, registration, documentation, and tests are included.

Changes

MCP list_bounty_attempts tool

Layer / File(s)	Summary
Tool implementation and registration app/main.py, app/mcp.py	_call_mcp_tool now implements the list_bounty_attempts handler with bounty existence lookup, optional active/expired filtering via include_expired, ordered and limited results, computed warnings, and serialization. The tool is added to MCP_TOOLS for discovery.
User documentation and API examples docs/agent-guide.md, docs/api-examples.md	Added instruction and example showing how to call list_bounty_attempts before starting overlapping work. Extended MCP tools lists and adjusted JSON-RPC example ids to reflect the new example.
Test imports and validation tests/test_api_mcp.py	Updated imports for timezone-aware datetime usage. Extended tool-list discovery test and added tests verifying list_bounty_attempts returns active/expired filtering, ordering, limits, warnings, and proper error responses for invalid arguments.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• ramimbo/mergework#323: Modifies MCP integer argument validation in _call_mcp_tool which is related to bounty_id handling used by this tool.
• ramimbo/mergework#326: Introduces bounty-attempt reservation model and warning computation logic that this MCP tool surfaces.
• ramimbo/mergework#329: Adds the MCP dispatcher and MCP_TOOLS catalog that this PR extends with an additional tool entry.

Suggested reviewers

• weilixiong
• Karry2019web

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: adding an MCP tool for bounty attempt inspection.
Description check	✅ Passed	The description includes a clear summary, covers evidence with detailed validation steps, and references the related bounty. All key sections from the template are 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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/api-examples.md`:
- Around line 450-457: The example JSON-RPC request for the "tools/call" method
invoking "list_bounty_attempts" uses a specific "id" value (e.g., 5) but the
later sample responses show different JSON-RPC "id" values (e.g., 6 or 5
mismatched after renumbering); update the response examples so their top-level
"id" fields exactly match the corresponding request "id" values for each sample
request (ensure the responses for the "list_bounty_attempts" request and the
other renamed calls use the same numeric id as their request entries).

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 08e734e7-2316-4154-a78e-3e00e5281ed5

📥 Commits

Reviewing files that changed from the base of the PR and between f4fa763 and 0314b79.

📒 Files selected for processing (5)

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

[TateLyman]

Fixed the CodeRabbit docs id mismatch in commit 65bcceb.

Changed the MCP example responses so:

• submit_wallet_transfer response id matches request id 7
• get_proof response id matches request id 6

Validation:

• uv run --extra dev python scripts/docs_smoke.py -> docs smoke ok
• uv run --extra dev python -m pytest tests/test_docs_public_urls.py tests/test_api_mcp.py::test_mcp_tools_list_and_call -q -> 18 passed
• uv run --extra dev ruff check docs/api-examples.md -> passed with no Python files warning
• git diff --check -> clean

Note: ruff format --check docs/api-examples.md is not applicable here because Ruff markdown formatting is still preview/experimental; no whitespace issues were present.

[artylobos]

Reviewed Add MCP bounty attempt inspection.

What I checked:

• Inspected app/main.py, app/mcp.py, docs/agent-guide.md, docs/api-examples.md, and tests/test_api_mcp.py.
• Verified the new list_bounty_attempts MCP tool is wired into _call_mcp_tool, exposed in MCP_TOOLS, and documented in both guides.
• Verified the endpoint behavior is consistent with the existing REST /api/v1/bounties/{bounty_id}/attempts path for active vs expired filtering, warnings, and argument rejection.

Validation:

• uv run --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_rejects_invalid_arguments tests/test_bounty_attempts.py -q -> 6 passed.
• uv run --extra dev python -m pytest tests/test_api_mcp.py tests/test_bounty_attempts.py -q -> 78 passed.
• uv run --extra dev ruff check app/main.py app/mcp.py tests/test_api_mcp.py -> passed.
• uv run --extra dev ruff format --check app/main.py app/mcp.py tests/test_api_mcp.py -> passed.
• uv run --extra dev python -m mypy app/main.py app/mcp.py -> success.
• uv run --extra dev python scripts/docs_smoke.py -> docs smoke ok.
• git diff --check origin/main...HEAD -> clean.

No blockers found.