Normalize MCP proof timestamps

[Floofy6]

Related bounty

Refs #798

Summary

• serialize MCP get_proof proof metadata created_at with the existing public UTC timestamp helper
• keep the MCP proof response consistent with the related ledger entry timestamp shape
• update the public MCP example and add a regression assertion

Evidence

Live read-only checks still show MCP get_proof returning 2026-06-01T11:42:20.646161 while get_ledger_entry for the same proof-backed ledger item returns 2026-06-01T11:42:20.644787Z.

Final preflight before publication: mergework-798-mcp-final-preflight-20260604T035708Z.md.

Tests

• focused MCP/docs tests: 140 passed, 1 warning
• full pytest: 790 passed, 1 warning
• Ruff check and format check passed
• docs smoke passed
• mypy app passed
• diff whitespace check clean

Out of scope

• No wallet, payout, transfer, bridge, exchange, cash-out, price, or investment behavior changes.
• No private data, secrets, credentials, account creation, or live mutation.

Summary by CodeRabbit

• Bug Fixes

  • Corrected timestamp format in the get_proof API response to use proper UTC notation (ISO 8601 standard)

• Documentation

  • Updated API example payload to reflect the corrected timestamp format

[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: 0cd2a29b-d68f-43f5-8501-82a8344c7622

📥 Commits

Reviewing files that changed from the base of the PR and between d4d0e48 and e737d84.

📒 Files selected for processing (3)

• app/mcp_tools.py
• docs/api-examples.md
• tests/test_api_mcp.py

---

📝 Walkthrough

Walkthrough

This PR standardizes timestamp serialization for the MCP get_proof tool. The implementation now uses public_utc_timestamp instead of isoformat() to ensure consistent UTC formatting with a trailing Z. Test assertions and API documentation are updated to match the new format.

Changes

MCP get_proof Timestamp Serialization

Layer / File(s)	Summary
Timestamp serialization implementation app/mcp_tools.py	public_utc_timestamp is imported and used in get_proof tool output to replace isoformat() for the created_at field.
Test assertion and documentation tests/test_api_mcp.py, docs/api-examples.md	Test assertion verifies created_at matches the standardized UTC format. API example is updated to show the trailing Z in the timestamp string.

Possibly Related PRs

• ramimbo/mergework#755: Adjusted created_at serialization for proof-related API responses to use public_utc_timestamp(...), with similar UTC timestamp standardization now extended to the MCP get_proof payload.

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Normalize MCP proof timestamps' clearly and concretely names the changed surface (MCP proof timestamp serialization).
Description check	✅ Passed	The description covers the main change, provides evidence of the issue, includes test results, and identifies out-of-scope items. All critical sections are addressed.
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 contains only technical timestamp normalization changes with no investment, price, cash-out, payout fabrication claims or private security details.
Bounty Pr Focus	✅ Passed	PR diff matches stated changes: mcp_tools.py imports/uses public_utc_timestamp for created_at; docs example updated with Z suffix; test assertion validates output. No unrelated changes.

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

[xiefuzheng713-alt]

Bounty #654 current-head review for PR #850.

Reviewed head e737d847b4e5d3c9e33132192a44549c72dfdfb1 against base d4d0e4860cfa3e9c338b1349001277c148afaf6d as a non-author.

Files inspected: app/mcp_tools.py, app/serializers.py, tests/test_api_mcp.py, and docs/api-examples.md.

What I verified:

• get_proof now uses the existing public_utc_timestamp() helper instead of raw datetime.isoformat(), so naive stored UTC values and aware datetimes serialize with an explicit Z marker consistently with public API timestamp behavior.
• The focused regression assertion covers the exact get_proof.created_at field from the created proof object.
• The docs example was updated to show the same explicit UTC marker.
• The change is limited to timestamp serialization for this MCP tool and does not touch proof hashing, ledger mutation, payout/proposal execution, wallet material, or private state.

Validation run locally on this head:

• uv run --extra dev pytest tests/test_api_mcp.py::test_mcp_get_proof_returns_public_proof_details -q -> 1 passed, 1 existing Starlette/httpx warning.
• uv run --extra dev pytest tests/test_api_mcp.py -q -> 105 passed, 1 existing Starlette/httpx warning.
• uv run --extra dev pytest -q -> 790 passed, 1 existing Starlette/httpx warning.
• uv run --extra dev ruff check app/mcp_tools.py tests/test_api_mcp.py docs/api-examples.md -> passed.
• uv run --extra dev ruff format --check app/mcp_tools.py tests/test_api_mcp.py -> passed.
• uv run --extra dev mypy app -> success for 42 source files.
• uv run --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 e6fb6b528aad46aac4adb0e4fcdaa202345945af.

GitHub state checked before review: PR #850 head still matches e737d847b4e5d3c9e33132192a44549c72dfdfb1, mergeable, hosted Quality/readiness/docs/image check successful, CodeRabbit had no actionable comments, and there were no prior human reviews.

[laughlife]

Bounty #838 current-head review for PR #850.

Reviewed head e737d847b4e5d3c9e33132192a44549c72dfdfb1 as a non-author after #838 claims opened.

No blocker found.

What I verified:

• get_proof now serializes created_at through the existing public_utc_timestamp() helper, matching the UTC Z timestamp shape already used by public serializers.
• The focused regression assertion checks the actual MCP get_proof response payload against public_utc_timestamp(proof.created_at).
• The docs example was updated to show the same explicit UTC marker.
• Scope stays limited to MCP proof timestamp serialization and documentation; I did not see changes to proof hashing, ledger mutation, wallet material, payout/proposal execution, bridge/exchange/cash-out, or price behavior.

Validation on current head:

• uv run --extra dev pytest tests/test_api_mcp.py::test_mcp_get_proof_returns_public_proof_details -q -> 1 passed, 1 existing Starlette/httpx warning.
• uv run --extra dev ruff check app/mcp_tools.py tests/test_api_mcp.py docs/api-examples.md -> passed.
• uv run --extra dev ruff format --check app/mcp_tools.py tests/test_api_mcp.py -> 2 files already formatted.
• uv run --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 e6fb6b528aad46aac4adb0e4fcdaa202345945af.

GitHub state checked before review: PR #850 head still matches e737d847b4e5d3c9e33132192a44549c72dfdfb1, merge state is CLEAN, hosted Quality/readiness/docs/image check is successful, and CodeRabbit is successful. I saw one prior human approval on this head; this review is an independent current-window verification for #838 rather than a claim that no prior review existed.

[aglichandrap]

Review evidence (head SHA: e737d847b4e5):

• ✅ Scope: Replaces proof.created_at.isoformat() with public_utc_timestamp(proof.created_at) — ensures UTC suffix.
• ✅ Consistency: Imports public_utc_timestamp from app/serializers.py, reusing existing utility.
• ✅ Docs: api-examples.md updated to show Z suffix in example output.
• ✅ Tests: test_api_mcp.py updated to assert normalized timestamp format.
• ✅ Files: 3 files, +4/-2 — minimal, focused.
• ✅ Mergeable: state=clean.

No blockers. Approve.