# 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