docs: add MCP work-proof structured example

[prettyboyvic]

Summary

• Add a public MCP submit_work_proof example using format:json.
• Document the actual JSON-RPC response shape with result.content[0].text plus result.structuredContent.
• Add a docs test that keeps the structured guidance fields visible in docs/api-examples.md.

Bounty #411

Evidence

• Compared against app/mcp.py, where dict tool results are returned as both content[0].text and structuredContent.
• Compared against app/mcp_work_proof.py, which emits availability, can_submit, availability_warnings, submission_requirements.reference_formats, attempt_endpoint, and next_actions.
• Intended files or surfaces: docs/api-examples.md, tests/test_docs_public_urls.py.
• Expected PR size: focused API/MCP example update.
• Out of scope: activity examples, MCP ledger/wallet lookup examples, route behavior changes.

Test Evidence

• ./.venv/Scripts/python.exe scripts/docs_smoke.py -> docs smoke ok
• ./.venv/Scripts/python.exe -m pytest tests/test_docs_public_urls.py -q -> 19 passed
• ./.venv/Scripts/python.exe -m ruff check tests/test_docs_public_urls.py -> passed
• ./.venv/Scripts/python.exe -m ruff format --check tests/test_docs_public_urls.py -> passed
• git diff --check -> clean

MRWK

Related bounty or issue (Bounty #N or Refs #N for multi-award bounties): Bounty #411

Summary by CodeRabbit

• Documentation

  • Added new API usage example for work proof submissions, demonstrating how to handle structured responses and properly interpret availability status, submission requirements, and reference format specifications.

• Tests

  • Added automated test to validate API documentation accuracy and completeness.

[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: 212f2bf0-f7f4-48e7-9ef5-64cee4d35430

📥 Commits

Reviewing files that changed from the base of the PR and between 764e9ed and 7cf9927.

📒 Files selected for processing (2)

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

---

📝 Walkthrough

Walkthrough

This PR adds a documented MCP API example for submit_work_proof showing how to call the endpoint with issue_number and optional repo, consume the structured response via result.structuredContent, and check key fields like availability and submission requirements. A test validates the documentation contains the expected content and field names.

Changes

MCP API Example and Validation

Layer / File(s)	Summary
submit_work_proof API example and test validation docs/api-examples.md, tests/test_docs_public_urls.py	Documents submit_work_proof with format:"json", showing how to read result.content[0].text and result.structuredContent fields (availability, can_submit, availability_warnings, submission_requirements), including example structured payload. Test asserts the documented fields and JSON fragments are present in the docs.

Possibly related issues

• MRWK bounty: public API and MCP examples accuracy, round 3 #411: Addresses the bounty request to update and verify public MCP/API examples.

Possibly related PRs

• ramimbo/mergework#424: Both PRs update docs/api-examples.md with MCP tool-call examples and extend tests/test_docs_public_urls.py to assert documented result shapes for specific MCP endpoints.
• ramimbo/mergework#317: The new submit_work_proof JSON example and structured-response field assertions in the docs directly mirror the implementation and tests for format:"json" returning result.structuredContent.
• ramimbo/mergework#347: The documented submission_requirements structure in the example depends on the retrieved PR's addition of the machine-readable submission_requirements structure in the MCP JSON guidance payload.

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'docs: add MCP work-proof structured example' clearly and specifically names the changed surface—a documentation update adding an MCP example.
Description check	✅ Passed	The description includes all required sections: a clear summary, evidence comparing against source files, intended surfaces, scope boundaries, and comprehensive test evidence with all checks marked passed.
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 API examples for submit_work_proof. No investment claims, price claims, cash-out/off-ramp claims, fabricated payouts, or security details exposed.
Bounty Pr Focus	✅ Passed	PR modifies only stated files, focuses on MCP submit_work_proof structured response documentation, includes all required fields, and test validates content. Out-of-scope items correctly excluded.

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

[weilixiong]

LGTM — useful MCP work-proof structured example covering availability, can_submit, submission_requirements. Clean docs addition.