Advertise submit_work_proof MCP input schema

[s0584273828-ctrl]

Summary

• Advertise an explicit MCP inputSchema for submit_work_proof in tools/list.
• Include bounty_id, issue_number, and format with the text/json enum so agents can discover structured guidance without hard-coded arguments.
• Update the agent guide and MCP regression coverage while preserving existing submit_work_proof call behavior.

Why this is distinct

PR #317 and PR #339 added structured guidance output and availability state. This PR makes that contract discoverable through MCP tool metadata, so clients can learn the selector and format fields from tools/list before calling the tool.

Test Evidence

• 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_submit_work_proof_returns_structured_bounty_guidance tests/test_api_mcp.py::test_mcp_submit_work_proof_returns_structured_generic_guidance tests/test_api_mcp.py::test_mcp_submit_work_proof_rejects_invalid_bounty_selectors -q -> 10 passed.
• uv run --extra dev python -m pytest -q -> 332 passed.
• uv run --extra dev ruff check . -> passed.
• uv run --extra dev ruff format --check . -> 46 files already formatted.
• uv run --extra dev python -m mypy app -> success.
• uv run --extra dev python scripts/docs_smoke.py -> docs smoke ok.
• git diff --check -> clean.

MRWK

Bounty #315

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

Summary by CodeRabbit

• Improvements

  • Stricter validation for the work submission tool: format limited to text or JSON (default text), IDs must be positive, extra fields disallowed, and at least one of bounty ID or issue number is required.

• Documentation

  • Agent guide clarified: JSON format returns structured content and tool listing exposes selector and format schema.

[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: 35af9fba-4654-4ccc-a078-ac6e1d6efffa

📥 Commits

Reviewing files that changed from the base of the PR and between 847d046 and ada0259.

📒 Files selected for processing (3)

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

---

📝 Walkthrough

Walkthrough

Widen MCP_TOOLS typing to allow non-string metadata and add explicit input validation to the submit_work_proof MCP tool (numeric selectors, format enum/default, no extra properties, and a mutual-selector constraint). Tests and docs updated to reflect the schema.

Changes

MCP Tool Schema and Validation

Layer / File(s)	Summary
MCP tool type expansion and submit_work_proof schema definition app/mcp.py	MCP_TOOLS type changed from list[dict[str, str]] to list[dict[str, Any]]. submit_work_proof inputSchema now defines bounty_id and issue_number as positive integers, format with enum: ["text","json"] and default "text", sets additionalProperties: False, and requires at least one selector via a not/required constraint.
Schema validation tests and documentation tests/test_api_mcp.py, docs/agent-guide.md	Tests extended to assert inputSchema.additionalProperties is False, format enum/default, minimum 1 for selectors, and the mutual-selector prohibition. Docs updated to note format: "json" returns structuredContent and to point to tools/list for schema discovery.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related issues

• MRWK bounty: structured MCP work-proof guidance #315: Implements the requested submit_work_proof schema additions (format argument, selector validation, non-string metadata).

Possibly related PRs

• ramimbo/mergework#287: Related updates to submit_work_proof's advertised interface and selector handling that align with this PR's schema tightening.
• Add structured MCP work proof guidance #317: Related work on format-specific return behavior for submit_work_proof (json structured output).
• Extract MCP transport handler #329: Earlier changes to the MCP_TOOLS catalog typing and entries related to this PR.

Suggested reviewers

• TateLyman
• 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 accurately and concisely summarizes the main change: advertising an explicit MCP input schema for the submit_work_proof tool.
Description check	✅ Passed	The description includes a clear summary of changes, explanation of distinctiveness, comprehensive test evidence covering all required checks, and MRWK reference with security confirmation.
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: 2

🤖 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 `@app/mcp.py`:
- Around line 42-66: The inputSchema currently allows both bounty_id and
issue_number simultaneously though submit_work_proof rejects that; update the
JSON Schema for inputSchema to enforce mutual exclusion (e.g., use oneOf/anyOf
with required sets or a not+required combination) so only one of "bounty_id" or
"issue_number" is allowed; specifically modify the schema object containing
"properties" and "additionalProperties" (the inputSchema definition) to include
a top-level constraint (oneOf/anyOf or a not with required) that references the
"bounty_id" and "issue_number" property names to align runtime behavior with
validation.

In `@tests/test_api_mcp.py`:
- Around line 433-438: Add an assertion to the existing test that verifies the
advertised input schema disallows providing both selectors at once: after the
current assertions on submit_schema, assert that submit_schema["not"] ==
{"required": ["bounty_id", "issue_number"]} (i.e., check the submit_schema
variable in tests/test_api_mcp.py to enforce selector exclusivity).

🪄 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: 5af98161-35c8-4ab2-8bd6-68525fa6bb6e

📥 Commits

Reviewing files that changed from the base of the PR and between ac99d79 and 847d046.

📒 Files selected for processing (3)

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

[tolga-tom-nook]

No blockers found.

Evidence checked:

• Inspected app/mcp.py, tests/test_api_mcp.py, and docs/agent-guide.md against current origin/main.
• Verified the new submit_work_proof inputSchema advertises bounty_id, issue_number, and format with text/json enum plus additionalProperties: false without changing the tool-call response path.
• Verified docs mention the structured JSON path and schema discovery.
• Ran: ./.venv/bin/python -m pytest tests/test_api_mcp.py::test_mcp_tools_list_and_call tests/test_api_mcp.py::test_mcp_submit_work_proof_returns_structured_bounty_guidance tests/test_api_mcp.py::test_mcp_submit_work_proof_returns_structured_generic_guidance tests/test_api_mcp.py::test_mcp_submit_work_proof_rejects_invalid_bounty_selectors -q -> 10 passed.
• Ran: ./.venv/bin/python -m ruff check app/mcp.py tests/test_api_mcp.py docs/agent-guide.md -> passed.
• Ran: ./.venv/bin/python -m mypy app -> passed.
• Ran: ./.venv/bin/python scripts/docs_smoke.py -> docs smoke ok.
• Ran: git diff --check origin/main...HEAD -> clean.

[TateLyman]

Requested changes: the advertised MCP schema still permits an argument object with both bounty_id and issue_number, while the actual submit_work_proof runtime rejects that same combination as ambiguous. That makes tools/list discovery over-advertise a call shape agents cannot successfully use.

Evidence checked:

• Inspected app/mcp.py, tests/test_api_mcp.py, and docs/agent-guide.md on this PR.
• submit_work_proof now advertises bounty_id, issue_number, and format, with additionalProperties: false, but the schema has no top-level not / oneOf / equivalent selector-exclusivity constraint.
• Existing runtime regression still rejects {"bounty_id": 1, "issue_number": 1} in test_mcp_submit_work_proof_rejects_invalid_bounty_selectors, so the published schema and runtime contract disagree.

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_submit_work_proof_rejects_invalid_bounty_selectors -q -> 8 passed.
• uv run --extra dev ruff check app/mcp.py tests/test_api_mcp.py docs/agent-guide.md -> passed.
• uv run --extra dev ruff format --check app/mcp.py tests/test_api_mcp.py -> passed. Note: including docs/agent-guide.md in ruff format --check fails locally because Markdown formatting is experimental without preview mode, not because of this PR's content.
• uv run --extra dev python -m mypy app/mcp.py -> passed.
• uv run --extra dev python scripts/docs_smoke.py -> docs smoke ok.
• git diff --check origin/main...HEAD -> clean.

Patch order: add a top-level selector exclusivity constraint to the submit_work_proof inputSchema, then assert it in test_mcp_tools_list_and_call so tools/list matches runtime behavior.

[s0584273828-ctrl]

Updated PR #345 for the requested schema/runtime mismatch.

Changed:

• Added top-level not: {"required": ["bounty_id", "issue_number"]} to the submit_work_proof inputSchema.
• Added a matching assertion in test_mcp_tools_list_and_call.

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_submit_work_proof_rejects_invalid_bounty_selectors -q -> 8 passed.
• uv run --extra dev python -m pytest -q -> 332 passed.
• uv run --extra dev ruff check app/mcp.py tests/test_api_mcp.py docs/agent-guide.md -> passed.
• uv run --extra dev ruff format --check app/mcp.py tests/test_api_mcp.py -> 2 files already formatted.
• uv run --extra dev python -m mypy app/mcp.py -> success.
• uv run --extra dev python scripts/docs_smoke.py -> docs smoke ok.
• git diff --check -> clean.

[TateLyman]

Rechecked the follow-up commit and the schema/runtime mismatch I flagged is fixed.

What changed:

• submit_work_proof inputSchema now includes not: {"required": ["bounty_id", "issue_number"]}.
• test_mcp_tools_list_and_call now asserts that selector-exclusivity constraint.
• Runtime behavior still rejects ambiguous selector calls, so the advertised MCP schema now matches the route behavior.

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_submit_work_proof_rejects_invalid_bounty_selectors -q -> 8 passed.
• uv run --extra dev ruff check app/mcp.py tests/test_api_mcp.py docs/agent-guide.md -> passed.
• uv run --extra dev ruff format --check app/mcp.py tests/test_api_mcp.py -> passed.
• uv run --extra dev python -m mypy app/mcp.py -> passed.
• uv run --extra dev python scripts/docs_smoke.py -> docs smoke ok.
• git diff --check origin/main...HEAD -> clean.
• GitHub mergeState CLEAN; hosted quality check and CodeRabbit are green.

[TUPM96]

No blockers from my pass on current head ada02590f78df1f3ec46b8a1f86ad1c78aeb52d3.

Evidence checked:

• Inspected app/mcp.py, tests/test_api_mcp.py, and docs/agent-guide.md.
• Rechecked the earlier schema/runtime mismatch: submit_work_proof now advertises bounty_id, issue_number, and format, rejects additional properties, and includes not: {required: [bounty_id, issue_number]} so the MCP tools/list schema matches the runtime selector exclusivity test.
• Verified docs mention structured JSON guidance and schema discovery without changing existing tool-call behavior.
• GitHub reports mergeState CLEAN; hosted quality check and CodeRabbit are green.

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_submit_work_proof_rejects_invalid_bounty_selectors tests/test_api_mcp.py::test_mcp_submit_work_proof_returns_structured_bounty_guidance tests/test_api_mcp.py::test_mcp_submit_work_proof_returns_structured_generic_guidance -q -> 10 passed.
• uv run --extra dev python -m pytest tests/test_api_mcp.py -q -> 76 passed.
• uv run --extra dev ruff check app/mcp.py tests/test_api_mcp.py docs/agent-guide.md -> passed.
• uv run --extra dev ruff format --check app/mcp.py tests/test_api_mcp.py -> passed.
• uv run --extra dev python -m mypy app/mcp.py -> passed.
• uv run --extra dev python scripts/docs_smoke.py -> docs smoke ok.
• git diff --check origin/main...HEAD -> clean.