fix: harden MCP write tool errors

workplans/STATE-WP-0059-mcp-write-layer-reliability.md

@@ -4,7 +4,7 @@ type: workplan
 title: "State Hub MCP write-layer reliability"
 domain: custodian
 repo: state-hub
-status: ready
+status: finished
 owner: codex
 topic_slug: custodian
 created: "2026-06-07"
@@ -67,7 +67,7 @@ record status/progress, leaving file↔hub drift unreconciled.
 
 ```task
 id: STATE-WP-0059-T01
-status: todo
+status: done
 priority: high
 state_hub_task_id: "7fc04b00-2493-4310-ae76-101660621da6"
 ```
@@ -90,7 +90,7 @@ tool wrapper, not only the FastAPI endpoint, and records:
 
 ```task
 id: STATE-WP-0059-T02
-status: todo
+status: done
 priority: high
 state_hub_task_id: "2636e1d5-142e-463f-875e-4dc1edf12853"
 ```
@@ -117,7 +117,7 @@ Implementation notes:
 
 ```task
 id: STATE-WP-0059-T03
-status: todo
+status: done
 priority: medium
 state_hub_task_id: "af137d6b-07ca-4110-abb0-45a96b84b7a3"
 ```
@@ -143,3 +143,26 @@ After workplan updates, run from `~/state-hub`:
 ```bash
 make fix-consistency REPO=state-hub
 ```
+
+## Verification Notes
+
+Completed 2026-06-07:
+
+- Added shared MCP response/error helpers in `mcp_server/server.py` so API error
+  payloads and malformed REST responses return clear MCP-visible errors instead
+  of triggering response-field KeyErrors or false success.
+- Kept successful MCP write responses in the same JSON shape as their REST
+  equivalents, while preserving automatic progress events only after successful
+  primary writes.
+- Added `tests/test_mcp_write_tools.py`, which invokes the registered FastMCP
+  tools in-process and covers success/error behavior for `create_workstream`,
+  `create_task`, `update_task_status`, `add_progress_event`, and
+  `record_decision`.
+- Documented MCP/REST write parity and fallback expectations in
+  `mcp_server/TOOLS.md`.
+
+Verification:
+
+- `.venv/bin/python -m pytest tests/test_mcp_write_tools.py -q` -> 8 passed
+- `.venv/bin/python -m pytest tests/test_mcp_write_tools.py tests/test_mcp_smoke.py -q` -> 21 passed
+- `git diff --check` -> clean