reader/docs/openclaw/archive/formalization-summary-2026-04-07.md

reader MCP workflow service formalization summary (2026-04-07)

Overview

On 2026-04-07, the reader project was formally advanced from a script-first integration model into a reader-centric MCP workflow service model.

The key shift is:

• before: OpenClaw primarily relied on long CLI / exec flows and direct output-path stitching
• now: reader exposes a formal workflow-oriented MCP surface with run-state, status queries, result reads, and minimal recovery

This document records the main outcomes and commits for the first formalization phase.

---

Completed capability set

1. Run-state persistence

Commit:

• 72a6853 — Add run-state persistence for FreshRSS pipeline

Delivered:

• run-state.json
• RunState / StageState / ArtifactRecord
• stage-level state persistence for the FreshRSS pipeline

2. Architecture / implementation docs

Commit:

• 7563aa8 — docs: add reader MCP architecture and implementation plan

Delivered:

• architecture design
• implementation plan
• TODO-driven collaboration model

3. MCP run-status query tools

Commit:

• d9173fb — feat: add MCP run status query tools

Delivered:

• get_run_status
• list_runs
• list_run_artifacts

4. MCP result-read tools

Commit:

• 4a02894 — Add MCP delivery payload and run report queries

Delivered:

• get_delivery_payload
• get_run_report

5. Minimal resume design

Commit:

• d91cdbc — docs: narrow resume_run minimal recovery design

Delivered:

• narrowed design for resume_run
• explicit supported / unsupported recovery points

6. Minimal resume_run

Commit:

• c622bc6 — Implement minimal resume_run for freshrss runs

Delivered:

• minimal resume_run
• supports only freshrss runs with run-state.json
• supports only recent resumable points
• explicitly rejects fetch_feed and extract_articles

7. Formal handoff / workflow docs

Commits:

• 4f219ef — docs: formalize reader MCP workflow service handoff
• 2df0af5 — docs: add openclaw orchestration flow for reader MCP

Delivered:

• formal handoff aligned to actual implementation
• OpenClaw orchestration runbook
• explicit rule that OpenClaw should stop hand-stitching reader paths in the normal production flow

---

Current formal MCP workflow surface

The current reader MCP workflow surface now includes:

• run_freshrss_openclaw_pipeline
• get_run_status
• list_runs
• list_run_artifacts
• get_delivery_payload
• get_run_report
• resume_run (minimal version)

---

Current boundary

reader is now the upstream workflow engine for:

• FreshRSS pull
• extraction
• summary
• filter
• payload generation
• run-state persistence
• result read
• minimal recovery

OpenClaw / skill remains responsible for:

• digest markdown generation
• Hugo publishing
• chat reporting
• user confirmation
• IMA orchestration

---

Current limitations

The first formalization phase is complete, but some constraints remain:

• resume_run is still minimal and does not support arbitrary stage re-entry
• historical runs without run-state.json are not formally recoverable
• some very old runs may still require conservative artifact/path discovery
• rerun_stage is not implemented
• deeper runtime consolidation of run_freshrss_openclaw_pipeline can still be improved later

---

Practical conclusion

The reader project should now be treated as a formal MCP workflow service rather than as a long-running CLI-first integration point.

For normal production orchestration:

• start via MCP
• observe via MCP status tools
• read results via MCP result tools
• use resume_run only within the documented minimal recovery range
• keep CLI for debug / fallback only