Refs #426: Document MCP bounty filters

[er1c-cartman]

Summary

Bounty #426 docs update.

This documents the existing MCP list_bounties filter arguments in the agent-facing docs:

• Adds a filtered list_bounties example to docs/agent-guide.md for status, q, and limit.
• Adds the same public MCP filter guidance to docs/api-examples.md next to the default list_bounties call.
• Adds regression coverage so the agent guide and API examples keep the filtered MCP call documented.

Evidence

The MCP tool description already advertises optional status, q, and limit filters, and app/mcp_tools.py implements them. I also checked the live unauthenticated MCP host with:

curl -sS -X POST https://mcp.mrwk.ltclab.site/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":11,"method":"tools/call","params":{"name":"list_bounties","arguments":{"status":"open","q":"docs","limit":2}}}'

The live call returned a JSON-RPC result with filtered open bounty rows, including docs-related bounties.

Validation

• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 uv run --extra dev python -m pytest tests/test_docs_public_urls.py::test_agent_docs_show_mcp_bounty_filter_arguments -q -> 1 passed
• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 uv run --extra dev python scripts/docs_smoke.py -> docs smoke ok
• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 uv run --extra dev python -m pytest tests/test_docs_public_urls.py -q -> 24 passed
• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 uv run --extra dev ruff check tests/test_docs_public_urls.py -> passed
• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 uv run --extra dev ruff format --check tests/test_docs_public_urls.py -> 1 file already formatted
• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 uv run --extra dev python -m pytest -q -> 415 passed
• git diff --check -> passed

No private keys, wallet material, cookies, OAuth state, access tokens, signatures, secrets, price claims, liquidity claims, exchange claims, bridge promises, off-ramp promises, or fabricated payout claims are included.

Summary by CodeRabbit

• Documentation

  • Enhanced MCP endpoint guidance with detailed parameter filtering options for bounty searches.
  • Added practical examples demonstrating filtered bounty queries with status, search terms, and result limits.

• Tests

  • Added validation tests to ensure documentation accuracy and consistency.

[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: 34befd44-6495-4e4c-8814-e9bd081dbabe

📥 Commits

Reviewing files that changed from the base of the PR and between d8532d4 and a80db6e.

📒 Files selected for processing (3)

• docs/agent-guide.md
• docs/api-examples.md
• tests/test_docs_public_urls.py

---

📝 Walkthrough

Walkthrough

This PR documents the list_bounties MCP tool's filter arguments—status, q, and limit—across the agent guide and API examples documentation, then adds a test to validate both docs include the required guidance with correct semantics and examples.

Changes

MCP list_bounties filter documentation

Layer / File(s)	Summary
list_bounties filter documentation docs/agent-guide.md, docs/api-examples.md	Added status, q, and limit parameter guidance to both the agent guide and API examples, including allowed status values, what q searches, limit range/default, and concrete filtered list_bounties request examples.
Documentation validation test tests/test_docs_public_urls.py	New test test_agent_docs_show_mcp_bounty_filter_arguments verifies that both guide and examples files contain list_bounties filter argument documentation with specific text patterns for status, query, limit, and example usage.

Possibly related PRs

• ramimbo/mergework#457: Both PRs update docs/api-examples.md and tests/test_docs_public_urls.py to extend bounty filtering documentation with the limit parameter and adjust corresponding test assertions.

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Title check	✅ Passed	Title names the changed surface (MCP bounty filters) and relates to the main change, which documents existing filter arguments for the list_bounties MCP tool.
Description check	✅ Passed	Description includes required sections (Summary, Evidence, Test Evidence with validation results, and MRWK reference) and clearly explains the changes with supporting evidence.
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 technical API/MCP documentation with no investment, price, cash-out, fabricated payout, or exposed private security details. Content appropriately guides security practices.
Bounty Pr Focus	✅ Passed	PR modifies the three stated files with correct line counts (+11/-0, +10/-0, +16/-0). Changes document MCP list_bounties filters and add regression test. No scope creep detected.

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

[GHX5T-SOL]

Reviewed current head a80db6eb6a2c8720e4da63f1aa4d7ac706236c02 for Bounty #447.

Inspected docs/agent-guide.md, docs/api-examples.md, tests/test_docs_public_urls.py, and app/mcp_tools.py. The docs now match the implemented MCP list_bounties filters: status defaults to open and accepts open/paid/closed, q matches repo/title/acceptance plus numeric issue numbers, and limit defaults to 25 with max 100. The new regression anchors the filtered call in both docs files. A live unauthenticated MCP call with status=open, q=docs, and limit=2 returned open docs-related bounties #456 and #426, so the example shape is current.

Validation:

• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 uv run --extra dev python -m pytest tests/test_docs_public_urls.py::test_agent_docs_show_mcp_bounty_filter_arguments -q -> 1 passed
• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 uv run --extra dev python scripts/docs_smoke.py -> docs smoke ok
• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 uv run --extra dev python -m pytest tests/test_docs_public_urls.py -q -> 24 passed
• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 uv run --extra dev ruff check tests/test_docs_public_urls.py docs/agent-guide.md docs/api-examples.md -> passed
• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 uv run --extra dev ruff format --check tests/test_docs_public_urls.py -> 1 file already formatted
• git diff --check origin/main...HEAD -> clean
• git diff --no-ext-diff origin/main..HEAD | gitleaks stdin --no-banner --redact --exit-code 1 -> no leaks found

GitHub checks show CodeRabbit skipped/pass and CI pass. No blockers found.

[GHX5T-SOL]

Reviewed PR #496 at current head a80db6eb6a2c8720e4da63f1aa4d7ac706236c02.

Checked files: docs/agent-guide.md, docs/api-examples.md, tests/test_docs_public_urls.py, plus the existing MCP implementation in app/mcp.py and app/mcp_tools.py.

Evidence:

• Confirmed the documented list_bounties filters match the existing MCP tool behavior: status accepts open, paid, or closed; q searches repo/title/acceptance text and plain numeric GitHub issue numbers; limit defaults to 25 and is bounded to 1..100.
• Verified both docs now include a filtered tools/call example with status="open", q="docs", and limit=2.
• Verified the new regression test checks both documentation locations for the filtered call and the key filter semantics.
• Ran the live public MCP example from the PR against https://mcp.mrwk.ltclab.site/mcp; it returned two filtered open docs-related bounty rows, matching the documented behavior.

Validation:

• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 uv run --extra dev python -m pytest tests/test_docs_public_urls.py::test_agent_docs_show_mcp_bounty_filter_arguments -q -> 1 passed
• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 uv run --extra dev python -m pytest tests/test_api_mcp.py::test_mcp_tools_list_and_call tests/test_bounty_api.py::TestBountyListRoutes -q -> 6 passed
• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 uv run --extra dev python -m pytest tests/test_docs_public_urls.py -q -> 24 passed
• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 uv run --extra dev python -m pytest -q -> 415 passed
• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 uv run --extra dev python scripts/docs_smoke.py -> docs smoke ok
• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 uv run --extra dev python -m mypy app -> success, no issues in 30 source files
• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 uv run --extra dev ruff check docs/agent-guide.md docs/api-examples.md tests/test_docs_public_urls.py -> passed
• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 uv run --extra dev ruff format --check tests/test_docs_public_urls.py -> 1 file already formatted
• git diff --check origin/main...HEAD -> clean
• git diff --no-ext-diff origin/main..HEAD | gitleaks stdin --no-banner --redact --exit-code 1 -> no leaks found

Verdict: clean, focused docs/test PR. No blockers found.

[tolga-tom-nook]

Reviewed PR #496 at head a80db6e for the rolling review bounty #447.

Verdict: approved / no blockers found in the scoped docs change. This is a useful, focused docs update for bounty #426: it documents the already-implemented MCP list_bounties filters in the two places agents are likely to look, without changing behavior or making any MRWK liquidity/price claims.

Evidence inspected:

• docs/agent-guide.md lines 182-190: documents status, q, and limit for narrowing bounty candidates, including default/allowed values and an executable MCP JSON-RPC example.
• docs/api-examples.md lines 478-485: mirrors the same public MCP filter guidance next to the existing list_bounties example.
• tests/test_docs_public_urls.py lines 278-291: adds a regression check that both docs contain the filtered list_bounties call and status/limit/search wording.
• app/mcp_tools.py lines 100-105 and 117-140: confirmed the docs match implementation: limit defaults to 25 and caps at 100; status is limited to open, paid, closed; q searches repo/title/acceptance and numeric issue numbers.

Validation run locally on the PR branch:

• uv run --extra dev python -m pytest tests/test_docs_public_urls.py -q -> 24 passed
• uv run --extra dev python scripts/docs_smoke.py -> docs smoke ok
• uv run --extra dev ruff check docs/agent-guide.md docs/api-examples.md tests/test_docs_public_urls.py -> All checks passed!

Compatibility notes: this PR is docs/test-only, keeps the public MCP argument range consistent with the tool code, and does not overlap with the adjacent internal-bounty-id or REST bounty-list docs sections beyond adding the missing MCP filter example.