# reader MCP Docker 部署计划

## 1. 目标

将 reader 作为正式 MCP workflow service 以 Docker 方式部署，满足以下原则：

1. 服务运行在容器内
2. 运行态与产物必须外置挂载，不闷在容器内
3. 配置统一记录在 `.env`
4. 读写行为与当前仓库约定保持一致
5. OpenClaw 后续可将该服务作为正式上游 MCP 使用

---

## 2. 部署原则

### 2.1 容器职责

容器只负责：

- 提供 reader MCP 服务运行环境
- 加载 reader 代码与依赖
- 读取挂载进来的配置与状态目录
- 对外暴露 MCP 服务入口

### 2.2 宿主机职责

宿主机负责持久化：

- 配置文件
- 运行态
- outputs 产物
- 数据目录
- configs

### 2.3 配置收口原则

所有环境配置统一放在 `.env`，避免：

- 零散写在 compose 内
- 零散写在 shell 命令里
- 零散写在 OpenClaw skill 里

---

## 3. 建议部署目录

建议在 reader 仓库内准备标准部署结构：

```text
/home/ubuntu/zhu/github/reader/
  Dockerfile
  docker-compose.yml
  .env
  outputs/
  data/
  configs/
  knowledge-base/
```

说明：

- `Dockerfile`：构建 reader MCP 服务镜像
- `docker-compose.yml`：单服务部署编排
- `.env`：统一环境变量
- `outputs/`：产物、run-state、digest、payload 等外置持久化
- `data/`：term index 等数据外置持久化
- `configs/`：reader 运行配置外置持久化
- `knowledge-base/`：如当前 reader/skill 仍会依赖本地知识目录，可继续挂载

---

## 4. 必须挂载的目录 / 文件

### 必须挂载

- `.env`
- `outputs/`
- `data/`
- `configs/`

### 建议挂载

- `knowledge-base/`

### 通常不必挂载

- `docs/`
- `plans/`
- `.git/`

---

## 5. `.env` 统一配置建议

至少应包含以下配置：

### FreshRSS

- `FRESHRSS_API_BASE_URL`
- `FRESHRSS_USERNAME`
- `FRESHRSS_API_PASSWORD`

### 主 LLM

- `LLM_API_URL`
- `LLM_API_KEY`
- `LLM_MODEL`

### 单篇总结专用 LLM（如已使用）

- `ARTICLE_SUMMARY_API_URL`
- `ARTICLE_SUMMARY_API_KEY`
- `ARTICLE_SUMMARY_MODEL`

### IMA（如 reader / skill 仍依赖这些配置约定）

- `IMA_DAILY_KNOWLEDGE_BASE_ID`
- `IMA_DAILY_KNOWLEDGE_BASE_NAME`

### 运行控制

- `PYTHONUNBUFFERED=1`
- 视需要增加日志级别等配置

原则：

- 所有会影响服务行为的环境项，都优先进入 `.env`
- compose 文件只引用 `.env`，不在 compose 里硬编码业务参数

---

## 6. Dockerfile 设计建议

### 目标

- 使用 Python 3.11
- 安装 reader 依赖
- 默认启动 MCP 服务入口

### 建议思路

1. 基于 `python:3.11-slim`
2. 设置工作目录到 `/app`
3. 复制仓库代码
4. 安装依赖（如 `pip install -e .`）
5. 默认启动 reader MCP 服务

### 启动入口

优先使用当前正式服务入口，例如：

- `summary-mcp`

如果后续 reader 明确切换到别的稳定入口，再同步更新。

---

## 7. docker-compose 设计建议

建议先保持单服务简单结构，例如：

- service 名称：`reader-mcp`
- `env_file: .env`
- 挂载：
  - `./outputs:/app/outputs`
  - `./data:/app/data`
  - `./configs:/app/configs`
  - `./knowledge-base:/app/knowledge-base`（如需要）
  - `./.env:/app/.env:ro`（可选，若程序直接读取文件）
- `restart: unless-stopped`

如果当前 MCP 服务是 stdio 型而不是 HTTP 型，需要进一步明确：

- 它是由 OpenClaw 以本地进程方式拉起
- 还是以常驻 sidecar / gateway adapter 方式挂接

因此 compose 的最终 command 需要结合实际接入方式确认。

---

## 8. 部署前确认项

在正式执行前，需要先确认以下问题：

### 8.1 MCP 连接方式

必须确认 reader MCP 服务的正式接入方式是：

1. **stdio 型**：OpenClaw/调用方本地拉起进程
2. **HTTP/SSE 型**：服务常驻监听端口，OpenClaw 远程连接

这会直接影响：

- Docker command
- 是否需要端口映射
- OpenClaw 接入配置

### 8.2 当前 `summary-mcp` 的服务形态

需要确认：

- 现有 `summary-mcp` 是 FastMCP stdio 默认模式
- 还是已有可直接 HTTP 化的运行方式

在这点没确认前，不要盲目写死端口暴露方案。

### 8.3 OpenClaw 侧接入点

部署完成后，还需要明确 OpenClaw 将如何引用该 MCP 服务：

- 本机命令型 MCP
- Docker 内服务桥接
- 或其它现有 OpenClaw MCP 配置方式

---

## 9. 执行顺序（建议）

### Phase A：部署方案落地

1. 确认 MCP 服务连接方式（stdio / HTTP）
2. 确认最终 Dockerfile 启动命令
3. 确认 compose 结构与挂载目录
4. 整理 `.env` 字段

### Phase B：容器化实现

1. 新建/更新 `Dockerfile`
2. 新建/更新 `docker-compose.yml`
3. 检查 `.dockerignore`
4. 核对路径是否与仓库内当前代码一致

### Phase C：本地部署验证

1. `docker compose build`
2. `docker compose up -d`
3. 验证服务启动
4. 验证容器外 `outputs/`、`data/` 等是否正常落盘

### Phase D：OpenClaw 接入验证

1. 让 OpenClaw 通过正式 MCP 路径连接 reader
2. 真跑一轮：
   - run
   - status
   - payload
   - report
3. 如有需要，验证一次最小 `resume_run`

---

## 10. 当前不在本轮范围内的事

本轮部署计划不直接处理：

- `rerun_stage`
- 更复杂的后台任务系统
- 多实例部署
- 横向扩展
- 生产告警体系

本轮只做：

- 单实例
- Docker 化
- 配置收口
- 挂载持久化
- OpenClaw 可正式接入

---

## 11. 一句话结论

reader 的下一步不是继续堆内部接口，而是：

**以 Docker 正式部署成 MCP workflow service，配置进 `.env`，状态和产物目录挂载到宿主机，然后由 OpenClaw 按正式 MCP 编排路径真实接入和验证。**