# 慢读清单 MCP Server

把 Jun 的「慢读清单」阅读存档（Hatch web artifact `space`）开放成只读的 MCP 工具，
让 AI agent 可以搜索、浏览、引用这些收藏的文章。这是"给 agent 用的服务"的第一个实验：
agent 成为用户，来读人的精选。

## 工具（只读）

| 工具 | 说明 |
|---|---|
| `search_articles(query, limit=10)` | 大小写不敏感的子串搜索（标题/摘要/笔记/标签/主题），标题命中排前面。返回 id、标题、url、来源、主题、标签、创建时间 + 200 字摘要片段。 |
| `list_recent(limit=10, theme="", tag="")` | 按创建时间倒序，可按主题/标签过滤。 |
| `get_article(id)` | 单篇文章的完整记录（标题、url、作者、来源、摘要、笔记、标签、关键词、主题、重要度、阅读时长、创建时间）。 |
| `list_themes()` | 去重主题及各自文章数。 |

## 快速开始

```bash
cd ~/workspace/mcp-slowread
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python test_client.py   # 端到端自检
```

### stdio（Claude Code / Cursor 本地接入）

Claude Code (`~/.claude.json` 或项目 `.mcp.json`)：

```json
{
  "mcpServers": {
    "slowread": {
      "command": "/home/hatch/workspace/mcp-slowread/.venv/bin/python",
      "args": ["/home/hatch/workspace/mcp-slowread/server.py"]
    }
  }
}
```

Cursor：Settings → MCP → Add new global MCP server，填同样的 command/args。

### SSE（部署给远端 agent）

```bash
.venv/bin/python server.py --transport sse --port 8000
```

远端 agent 连 `http://<host>:8000/sse`。注意：这是只读公开元数据服务，
但仍建议只在可信网络暴露，或前面加一层反向代理做鉴权/限流。

## 数据刷新

`data/articles.json` 是静态快照（当前 44 篇，2026-09-06 抓取）。
MCP server 不直连线上 app——这是有意为之：快照简单、可审计、
不怕把线上库拖慢。刷新快照时重新从 artifact 抓取并覆盖该文件即可
（只读抓取，见 `artifact.invoke_action` 的 `listarticles` action，
`slug=space`，`args={"limit":200,"status":"all"}`）。

## 日志

每次工具调用追加一行 JSON 到 `logs/access.log`：
`{"ts": ..., "tool": ..., "args": {...}}`。只记元数据，
**不记录文章全文**。

## 隐私说明

- 只读：没有任何写入、删除、修改线上「慢读清单」的工具。
- 只暴露文章的公开元数据（标题、链接、来源、摘要、笔记、标签）——
  这些本来就是 Jun 收藏的公开网页，加上他自己的中文点评。
- 无密钥、无账号体系。`data/articles.json` 是明文快照，
  分享/部署前请确认内容可公开。