内容
# Readly MCP 服务器
<p align="center">
<a href="https://github.com/casey/just"><img src="https://img.shields.io/badge/just-ready_to_go-7c5cfc?style=flat-square&logo=just&logoColor=white" alt="Just"></a>
<a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff"></a>
<a href="https://python.org"><img src="https://img.shields.io/badge/Python-3.13+-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python"></a>
<a href="https://github.com/PrefectHQ/fastmcp"><img src="https://img.shields.io/badge/FastMCP-3.2-7c5cfc?style=flat-square" alt="FastMCP"></a>
</p>
> 📖 **[安装指南](INSTALL.md)** — 快速开始，手动设置和故障排除
一个专为 Readly 数字杂志平台（`go.readly.com`）自动阅读、抓取和内容提取而设计的 MCP 服务器。
## 功能
- **内容智能 (v0.2)**：从杂志中提取文章标题、网址和全文
- **杂志搜索 (v0.2)**：通过关键词搜索 Readly 目录中的杂志
- **类似人类的抓取**：以自然间隔翻页以避免被检测。
- **持久登录**：重用浏览器会话/cookie，因此您只需登录一次。
- **PDF 生成**：自动将抓取的杂志编译成完整的 PDF。
- **双重传输**：支持 Stdio、HTTP 流媒体和 SSE 传输。
- **REST API**：FastAPI 桥接，用于与 fleet 服务器集成（例如 `aiwatcher-mcp`）。
## 为什么选择 Readly？
我们热爱 Readly！它是终极的数字杂志和报纸订阅服务，提供一个应用中数千种杂志的无限访问权限。其“免费阅读所有内容”的模式使知识追求者能够在没有实体杂志的杂乱的情况下探索各种主题。
Readly 对于访问大量高质量的新闻报道和特定兴趣的杂志是必不可少的。无论您是关注 **NZZ** 的全球发展， **c't** 的硬件黑客，还是通过 **New Scientist** 和 **Wired** 保持领先地位，它都能满足您的需求。
它允许您通过 **船和游艇杂志** 梦想远大，或者深入研究 **建筑**、**时尚** 和 **政治**。它满足每个特定爱好者的需求，从 **狗和马** 爱好者到 **在苏格兰捕鱼** 风格的出版物。
最重要的是，它拥有令人愉悦的另类和奇怪的杂志： **Fortean Times**、**The Idler** 和 **The Lady**。这是一个在数字时代支持书面文字的优秀服务。该工具的存在是为了帮助您存档您喜欢的有偿内容，以供个人使用，庆祝 Readly 提供的巨大价值。
## 快速开始
```powershell
git clone https://github.com/sandraschi/readly-mcp
cd readly-mcp
just
```
这将打开一个交互式仪表板，显示所有可用的命令。运行 `just bootstrap` 安装依赖项，然后运行 `just serve` 或 `just dev` 启动。
### 手动设置
如果您没有安装 `just`:
## 安装
### 先决条件
- 安装 [uv](https://docs.astral.sh/uv/) （推荐）
- Python 3.12+
- 有效的 [Readly](https://www.readly.com) 账户
### 快速开始
使用 `uvx` 立即运行：
```bash
uvx readly-mcp
```
### Claude 桌面集成
将以下内容添加到您的 `claude_desktop_config.json`：
```json
"mcpServers": {
"readly-mcp": {
"command": "uv",
"args": ["--directory", "D:/Dev/repos/readly-mcp", "run", "readly-mcp"]
}
}
```
### 设置（从源代码）
```bash
git clone https://github.com/sandraschi/readly-mcp.git
cd readly-mcp
uv sync
playwright install chromium
```
关键依赖项：FastMCP、FastAPI、uvicorn、Playwright、fpdf2、Pillow（参见 `pyproject.toml`）。
## 使用
### 1. 自动登录（推荐）
将从浏览器应用程序 cookie 中获取的 Readly 身份验证令牌设置为环境变量：
```bash
set READLY_AUTH_TOKEN=eyJhbGciOiJSUzI1...
```
或通过 Web 仪表板的设置页面粘贴令牌。该令牌通过 `POST /api/auth/token` 发送到后端，并在调用 `open_readly_browser` 时自动用于设置 `readlyAuth` cookie - 无需手动登录。
### 2. 手动登录（备用）
如果没有可用的令牌，则需要手动登录（持久化 cookie）：
1. 调用 `open_readly_browser` 工具。
2. 在出现的窗口中手动登录。
3. 未来的会话将自动重用这些 cookie。
### 3. 内容智能 (v0.2)
一旦登录并在杂志问题页面上：
- **列出文章**：`list_articles` - 从当前页面提取所有文章标题和网址
- **阅读文章**：`extract_article_text` - 点击文章并提取其全文
- **搜索目录**：`search_magazines` - 按关键词查找杂志
### 4. 抓取杂志
一旦登录：
1. 导航到您要捕获的杂志问题的第一页。
2. 调用：`smart_scrape` 并输入问题名称、间隔和最大页数。
3. 服务器将在后台翻页并将 PDF 保存到 `~/Desktop/readly/`。
## MCP 工具
| 工具 | 类别 | 描述 |
|------|----------|-------------|
| `open_readly_browser` | 浏览器 | 打开浏览器，手动登录 |
| `list_articles` | 内容 (v0.2) | 从当前杂志页面提取文章标题和网址 |
| `extract_article_text` | 内容 (v0.2) | 点击文章并提取全文内容 |
| `search_magazines` | 内容 (v0.2) | 按关键词搜索 Readly 目录 |
| `smart_scrape` | 抓取 | 分页截图 + PDF 编译 |
| `get_status` | 状态 | 当前抓取作业状态 |
| `stop_scrape` | 控制 | 正常停止抓取作业 |
## REST API（端口 10863，通过 `--web` 标志）
| 方法 | 路径 | 描述 |
|--------|------|-------------|
| `GET` | `/api/health` | 健康检查 |
| `GET` | `/api/status` | 抓取作业状态 |
| `GET` | `/api/tools` | 列出已注册的 MCP 工具 |
| `GET` | `/api/articles/list` | 列出当前页面上的文章 |
| `GET` | `/api/articles/extract?index=N` | 按索引提取文章文本 |
| `GET` | `/api/magazines/search?q=QUERY` | 按关键词搜索杂志 |
| `POST` | `/api/scrape/start` | 启动抓取作业 |
| `POST` | `/api/scrape/stop` | 停止抓取作业 |
## 开发
### 结构
- `src/readly_mcp/`：源代码（服务器、浏览器管理器、PDF 生成、传输）
- `tests/`：Pytest 套件
- `docs/`：架构和 API 文档
### 运行 HTTP/SSE 服务器
对于 Web 或 SSE 传输（FastAPI + uvicorn）：
```bash
uv run readly-mcp --web
```
使用 `WEB_PORT`（默认为 10863）。需要 FastAPI 和 uvicorn（包含在依赖项中）。
### 测试
```bash
pytest
```
### 与 aiwatcher-mcp 集成
readly-mcp v0.2+ 作为 aiwatcher-mcp 的内容智能源。
在 aiwatcher-mcp 的 `.env` 中设置 `READLY_ENABLED=true` 和 `READLY_MCP_URL=http://localhost:10863`。
## 工业质量栈
该项目遵循 **SOTA 14.1** 工业标准，用于高保真代理编排：
- **Python（核心）**：[Ruff](https://astral.sh/ruff) 用于代码检查和格式化。对核心处理程序中的 `print` 语句（`T201`）采取零容忍政策。
- **Web 应用程序（UI）**：[Biome](https://biomejs.dev/) 用于毫秒级代码检查。严格执行 `noConsoleLog`。
- **协议合规性**：强化 `stdout/stderr` 隔离，以确保抗崩溃的 JSON-RPC 通信。
- **自动化**：[Justfile](./justfile) 适用于所有舰队操作（`just lint`、`just fix`、`just dev`）。
- **安全**：通过 `bandit` 和 `safety` 进行自动审计。
## 许可证
MIT
