# Content Extract MCP MVP 归档记录

## 1. 归档目的

本文档用于记录当前 MVP 阶段已经完成的能力、实现边界、验证结果和已知限制。

当前结论：MCP 这一层不再负责生成摘要，而是只负责将网页或标准化 `item` 提取为结构化文章内容，再把结果交给上层 LLM 做摘要、分类和知识判断。

---

## 2. 当前 MVP 的目标与边界

当前 MVP 实现的是阅读流中的第 2 步前半段：

`RSS / 页面来源 -> Content Extract MCP -> 结构化文章 JSON -> LLM 摘要`

### 2.1 当前 MCP 负责的事情

- 接收单个 URL
- 接收标准化 `item`
- 抓取网页 HTML
- 抽取标题
- 抽取正文纯文本
- 返回结构化文章对象
- 返回质量标记和结构化错误

### 2.2 当前 MCP 不负责的事情

- RSS 聚合
- 摘要生成
- 主题分类
- 价值判断
- 规则过滤
- 知识库入库
- 推送通知

这意味着：

当前实现已经把“内容提取”这一层从整条流水线中独立出来，成为一个可被 LLM 或自动化编排系统复用的能力模块。

---

## 3. 当前实现的服务定位

当前项目虽然目录名仍然沿用了 `summary_mcp`，但实际职责已经调整为：

`Content Extraction MCP`

也就是：

- MCP 负责内容提取
- LLM 负责总结摘要
- 规则引擎负责过滤
- sink 负责入库与推送

这比早期“让 MCP 直接产出摘要”的思路更合理，因为职责边界更清楚，也更利于后续替换模型和 prompt。

---

## 4. 当前工具接口

当前 MCP 暴露两个 tool：

- `extract_url_content`
- `extract_item_content`

### 4.1 `extract_url_content`

用途：

- 直接输入 URL
- 适合单条文章调试
- 适合上层 Agent 在没有标准化 `item` 时直接调用

### 4.2 `extract_item_content`

用途：

- 输入标准化 `item`
- 适合与上游 RSS 聚合层对接
- 保留 `item_id`、`source_id` 等追踪信息

---

## 5. 当前输出结构

当前 MCP 输出的核心对象是结构化文章，而不是摘要结果。

关键字段包括：

- `extract_id`
- `item_id`
- `source_id`
- `url`
- `title`
- `author`
- `published_at`
- `language`
- `content_kind`
- `plain_text`
- `quality_flags`
- `metadata`
- `pipeline_state`

其中：

- `plain_text` 是给上层 LLM 的核心输入
- `quality_flags` 用于后续过滤参考
- `metadata` 里包含当前提取来源和抽取器信息

---

## 6. 当前代码结构

当前目录结构如下：

```text
src/summary_mcp/
  server.py
  core/
    content_loader.py
    errors.py
    extractor.py
    mapper.py
    normalizer.py
    pipeline.py
    quality_checker.py
    summarizer.py
  models/
    document.py
    item.py
    summary_io.py
```

### 6.1 当前核心模块职责

- `server.py`
  - MCP 服务入口
  - 注册 `extract_url_content` / `extract_item_content`

- `normalizer.py`
  - 统一 `url` 输入和 `item` 输入

- `content_loader.py`
  - 负责正文来源选择和回源抓取

- `extractor.py`
  - 负责标题提取和正文抽取

- `quality_checker.py`
  - 负责生成质量标记

- `mapper.py`
  - 负责将结果映射为结构化文章对象

- `pipeline.py`
  - 负责串联整条提取流程

### 6.2 当前遗留项

- `core/summarizer.py` 仍保留在仓库中，但已经不再属于当前 MCP 的主流程
- 包名 `summary_mcp` 和项目名 `summary-mcp` 仍然沿用了早期命名，后续建议重命名为更符合职责的名称

---

## 7. 当前技术选型

当前 MVP 使用：

- Python
- MCP Python SDK (`FastMCP`)
- `httpx` 进行网络抓取
- `trafilatura` 进行正文抽取
- `beautifulsoup4` 作为 HTML 解析和兜底手段
- `pydantic` 定义输入输出模型

设计原则是：

- 外层 MCP
- 内层 extraction core
- 上层 LLM 单独负责总结和判断

---

## 8. 当前验证结果

### 8.1 语法与结构验证

已执行：

- `python -m compileall src`

结果：

- 当前 Python 源码可以通过语法编译检查

### 8.2 真实 URL 提取验证

已使用以下参考文章进行了真实提取测试：

- <https://shawnxie.top/blogs/tools/read-flow-2026.html>

验证结果：

- URL 抓取成功
- 标题提取成功
- 正文抽取成功
- 输出返回结构化 JSON
- `quality_flags` 正常生成
- `metadata` 中记录了 `content_source=fetched_html` 和 `extractor=trafilatura`

输出文件：

- `outputs/read-flow-2026.extracted.json`

### 8.3 LLM 摘要链路验证

已基于提取结果生成：

- `outputs/llm-summary-prompt.txt`
- `outputs/result.json`

验证结果：

- LLM 可基于提取结果生成结构化摘要 JSON
- 在 prompt 收紧后，`summary` 长度和 `keywords/topics` 区分已达到预期

---

## 9. 当前 MVP 已经达成的结论

当前 MVP 已经证明以下链路是成立的：

1. 参考文章 URL 可以被 MCP 成功提取为结构化内容
2. 提取结果可以独立保存为 JSON 文件
3. JSON 文件可以被上层 LLM 消费
4. LLM 可以输出稳定的摘要结构
5. “MCP 负责提取，LLM 负责摘要” 这一职责拆分是可行的

这意味着：

当前 MVP 的核心目标已经完成。

---

## 10. 已知限制

当前实现仍存在以下限制：

- 还没有正式的 JSON Schema 校验器去验证 LLM 输出
- 还没有批量处理能力
- 还没有与 RSS 聚合层正式对接
- 还没有接规则过滤器
- 还没有接知识库 sink
- 还没有移除遗留的 `summarizer.py`
- 项目命名和职责命名仍存在历史包袱

---

## 11. 下一阶段建议

后续建议按以下顺序推进：

1. 为 LLM 输出增加 schema 校验
2. 将提取结果与摘要结果串成标准化流水线
3. 接入 RSS 聚合层
4. 引入规则过滤
5. 接入知识库 sink 或 webhook
6. 最后再考虑与 OpenClaw 的进一步编排整合

---

## 12. 当前阶段一句话归档结论

当前 MVP 已经完成“内容提取 MCP”这一独立能力层：能够将文章 URL 或标准化 item 提取为结构化 JSON，并稳定交给上层 LLM 做摘要与后续处理。