# Cove Douban MCP

一个独立、可开源、默认只读的豆瓣 MCP 服务。它把本地 Chrome
中已经可见的豆瓣信息，通过标准 Model Context Protocol 提供给
Claude Code、Codex、桌面客户端、编辑器插件，以及开发者自己的前端或后端。

项目支持 macOS 与 Windows，提供 stdio 和仅限本机回环地址的
Streamable HTTP。它不依赖 Cove 主程序，也不会读取或修改任何 Cove 数据。

> 本项目与豆瓣无隶属、合作或官方授权关系。请遵守豆瓣条款、当地法律和账号
> 权限边界，仅访问你本来就有权在浏览器中查看的内容。

## 核心边界

- 豆瓣侧永久只读：不标记、不评分、不发影评、不改豆列、不改账号。
- 不索取、不导出、不持久化 Cookie；不复制 Chrome profile。
- 默认只写自己的缓存目录。
- Markdown 导出功能存在，但默认关闭。
- `confirm_each` 模式下，模型只能发起一次性提案，不能批准自己的提案。
- 本地 HTTP 只能绑定 `127.0.0.1`、`localhost` 或 `::1`，并强制 Bearer
  鉴权和浏览器 Origin 检查。
- 安装前检测同名 OpenCLI adapter；默认绝不覆盖。
- 卸载时仅删除哈希仍与安装包一致的 adapter，用户后来改过的文件会保留。

## 能做什么

当前版本提供以下只读能力：

| MCP 工具 | 能力 |
|---|---|
| `douban_status` | 本地连接、权限、缓存和同步状态 |
| `douban_search` | 搜索电影、图书、音乐 |
| `douban_chart` | 查询电影、图书、音乐的六类固定公开榜单 |
| `douban_subject` | 查询电影或图书详情 |
| `douban_movie_marks` | 查询、筛选、分页“看过 / 想看 / 在看” |
| `douban_reviews` | 查询个人影评，可选完整正文 |
| `douban_movie_profile` | 汇总多个观影状态 |
| `douban_doulists` | 查询豆列、片单、书单 |
| `douban_doulist_items` | 查询一个列表里的条目 |
| `douban_sync` | 刷新本地只读缓存 |
| `douban_working_cache_read` | 分页读取完整服务端结果 |
| `douban_export_markdown` | 按本地权限策略导出 Markdown |

`douban_chart` 支持电影一周口碑榜、北美票房榜、新片榜、Top 250、热门图书榜
和热门音乐榜。它只接受固定榜单键与数量，不接受任意网址或浏览器脚本；原有
11 个 v0.1.x 工具合同保持不变。

## 架构

```mermaid
flowchart LR
    Client["任意标准 MCP 客户端"] --> Transport["stdio / 本机 Streamable HTTP"]
    Transport --> Tools["12 个薄 MCP 工具"]
    Tools --> Services["查询、筛选、同步、导出服务"]
    Services --> Cache["四层私有本地缓存"]
    Services --> Gateway["命令白名单 + 无 shell 子进程"]
    Gateway --> OpenCLI["8 个只读 OpenCLI adapter"]
    OpenCLI --> Chrome["用户当前 Chrome 会话"]
    Chrome --> Douban["浏览器中本来可见的豆瓣页面"]
```

领域层负责标准化、筛选、分页、非缩水合并和不透明结果引用；MCP 层不直接
解析网页。两种传输共用同一个服务容器，因此结果合同一致。

## 系统要求

- macOS 13 或更新版本，或受支持的 Windows 10/11；
- Python 3.11、3.12 或 3.13；
- [uv](https://docs.astral.sh/uv/)（推荐）或能安装 Python wheel 的工具；
- Node.js 22；
- OpenCLI 1.8.x；
- Chrome，以及可用的 OpenCLI Browser Bridge；
- 已在该 Chrome 会话中正常登录豆瓣。

本项目不会自动升级全局 OpenCLI。`doctor` 会报告版本不匹配并给出处理建议。

## 安装

### 方法一：从 GitHub Release 安装（推荐）

打开
[Releases](../../releases/latest)，
下载 `cove_douban_mcp-0.2.0-py3-none-any.whl`，然后在下载目录运行：

```bash
uv tool install ./cove_douban_mcp-0.2.0-py3-none-any.whl
```

没有使用 `uv` 时，也可以安装到当前 Python 环境：

```bash
python -m pip install ./cove_douban_mcp-0.2.0-py3-none-any.whl
```

Windows 如果使用 Python Launcher，可以运行：

```powershell
py -m pip install .\cove_douban_mcp-0.2.0-py3-none-any.whl
```

从 `v0.1.x` 升级时，安装器会刻意拒绝覆盖已有 adapter。请先使用仍在
运行的旧版卸载未修改的托管文件，再替换工具并安装新版只读 adapter：

```bash
cove-douban-mcp uninstall
uv tool install --force ./cove_douban_mcp-0.2.0-py3-none-any.whl
cove-douban-mcp setup --yes
cove-douban-mcp doctor --json
```

`uninstall` 只删除内容仍与当时安装包一致的 adapter；用户修改过的
adapter 会保留。如果 `setup` 报告冲突，请先备份并显式移除它报告的文件，
然后重试。升级过程不会修改 MCP 客户端配置或豆瓣数据。

### 方法二：从源码安装

```bash
git clone <repository-url>
cd cove-douban-mcp
uv tool install .
```

先看安装计划，不改任何文件：

```bash
cove-douban-mcp setup --dry-run
```

确认后安装默认配置和八个只读 adapter：

```bash
cove-douban-mcp setup --yes
```

`setup` 不会修改任何 MCP 客户端配置。它会输出一份通用配置，用户自行决定
放进哪个客户端。

## 连接任意 MCP 客户端

### stdio（推荐）

完整示例见 [examples/generic-stdio.json](examples/generic-stdio.json)：

```json
{
  "mcpServers": {
    "douban": {
      "command": "cove-douban-mcp",
      "args": ["serve", "--transport", "stdio"]
    }
  }
}
```

这是一份标准 MCP stdio 配置，不绑定某个厂商。若客户端使用不同字段名，请
把同一条 command/args 映射进去即可。

### 本机 Streamable HTTP

启动：

```bash
cove-douban-mcp serve --transport streamable-http
```

默认端点是 `http://127.0.0.1:8765/mcp`。首次启动会在应用数据目录生成
至少 256 位的本地 token；服务不会把 token 打到日志或 MCP 结果中。
macOS 使用仅限文件所有者的权限，Windows 使用 `icacls` 移除继承权限并
只授权当前用户；如果无法建立这层保护，本地 HTTP 会拒绝启动并清理新令牌。

完整结构见
[examples/generic-streamable-http.json](examples/generic-streamable-http.json)。
浏览器前端不应把 token 写进源码；请由同机后端代持，或使用 stdio。

随时生成通用配置：

```bash
cove-douban-mcp print-config --transport stdio
cove-douban-mcp print-config --transport streamable-http
```

## 首次使用

1. 在 Chrome 中正常打开豆瓣并完成登录。
2. 确认 OpenCLI Browser Bridge 可用。
3. 运行 `cove-douban-mcp doctor --json`。
4. 在 MCP 客户端调用 `douban_status`。
5. 用 `douban_search`、`douban_chart` 或 `douban_movie_marks` 做第一条只读查询。

`doctor` 不执行私有账号数据抓取，只检查本地文件、插件和 OpenCLI 可执行文件。

## 缓存与同步

应用使用四层缓存：

- 六小时、有上限的普通查询缓存；
- “看过 / 想看 / 在看”的非缩水持久基线；
- 同步状态；
- 24 小时、按客户端隔离的不透明完整结果引用。

筛选发生在分页之前。普通增量更新只会补充或丰富旧条目，不会因为一次网页
只返回部分内容而把历史基线截短。

默认同步状态为启用，每日目标时间为本地 `05:10`，默认同步 `wish`、
`collect` 和豆列。手动调用 `douban_sync` 始终只写内部缓存，不写豆瓣。
观影标记同步使用有界的轻量列表分块，不会逐条打开影片详情页；已有的类型、
国家、导演和演员等丰富字段会由非缩水合并保留。多个本地 MCP 进程会串行使用
同一个 Browser Bridge，避免互相抢占浏览器页面。

## 可选 Markdown 导出

默认：

```toml
[export]
enabled = false
policy = "off"
```

允许每次人工确认：

```bash
cove-douban-mcp permissions export \
  --policy confirm_each \
  --root "/path/selected/by/user"
```

允许在一个固定根目录内直接写：

```bash
cove-douban-mcp permissions export \
  --policy allow_in_root \
  --root "/path/selected/by/user"
```

Windows PowerShell 同样使用用户自己选择的绝对路径：

```powershell
cove-douban-mcp permissions export `
  --policy confirm_each `
  --root "D:\Documents\DoubanExports"
```

人工提案命令：

```bash
cove-douban-mcp export list
cove-douban-mcp export show <proposal-id>
cove-douban-mcp export approve <proposal-id>
cove-douban-mcp export reject <proposal-id>
```

导出只接受 `.md` 和 `.markdown`，会拒绝 `..`、根目录外绝对路径、符号链接
逃逸和 Windows junction/reparse-point 逃逸。`replace` 只替换本项目标记的
生成区块，并先创建可恢复备份。

## 数据位置

macOS：

```text
~/Library/Application Support/cove-douban-mcp/
```

Windows：

```text
%LOCALAPPDATA%\cove-douban-mcp\
```

其中只有配置、缓存、同步状态、提案、脱敏诊断信息和本地 HTTP
凭据；没有 Cookie、密码、Chrome profile 或 MCP 对话历史。

## 卸载

移除 OpenCLI 集成、保留缓存和配置：

```bash
cove-douban-mcp uninstall --yes
```

连应用数据一起清除需要第二次明确确认：

```bash
cove-douban-mcp uninstall --yes --purge-data --confirm-purge
```

无论哪种方式，都不会删除已经导出的 Markdown。

## 开发

```bash
uv sync --all-groups
uv run ruff check .
uv run mypy src
uv run pytest -q
npm --prefix opencli-plugin ci
npm --prefix opencli-plugin test
```

默认测试完全使用合成数据，不连接豆瓣。参见
[CONTRIBUTING.md](CONTRIBUTING.md)。

## 安全、隐私与排障

- [安全设计](docs/security.md)
- [隐私说明](docs/privacy.md)
- [故障排查](docs/troubleshooting.md)
- [漏洞报告政策](SECURITY.md)

## 许可证

Apache License 2.0。第三方归属见 [NOTICE](NOTICE)。