164 lines
3.6 KiB
Markdown
164 lines
3.6 KiB
Markdown
# 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
|