# qBittorrent Read-only MCP

这是一个独立维护的 qBittorrent 只读 MCP 项目，把 qBittorrent Web API 查询包装为本机 `stdio` MCP 工具，便于 AI 客户端直接做实时诊断。

## 安全模型

- 仅支持 `stdio`，不监听任何网络端口。
- qBittorrent 地址和 API Key 只从环境或外部秘密文件读取，MCP 工具参数不能覆盖连接目标。
- 客户端只允许固定 GET endpoint；没有通用 request、URL 或 endpoint 工具。
- 不注册添加、暂停、恢复、校验、删除、移动、改 tracker、改设置等写工具。
- 完整 tracker URL、passkey、magnet、Cookie 和认证信息不会进入工具结果。
- qBittorrent API Key 本身仍有完整 Web API 权限；只读性由本服务的两层 allowlist 和测试保证。

本 MCP 不执行文件系统递归扫描，职责限定为 qBittorrent 实时查询。

## 工具

- `get_health_summary`：版本、速度、任务状态和异常摘要。
- `list_torrents`：按状态、分类、最小大小、无活动天数筛选任务。
- `get_torrent_details`：按至少 8 位 Info Hash 前缀获取安全字段、文件和 tracker hostname。
- `list_problem_torrents`：列出 `missingFiles`、error 和未完成停滞任务。
- `analyze_largest_torrents`：按逻辑大小分析 Top N 任务。

## 环境要求

- Python 3.10+
- `uv`
- 项目外部秘密文件中已有：
  - `QBIT_URL`
  - `QBIT_API_KEY`

默认从进程环境读取。也可只传递秘密文件路径：

```bash
export QBIT_MCP_ENV_FILE="/path/to/secrets/nas-audit.env"
```

不要把 Key 复制到本目录或 Codex 配置中。

## 安装与测试

```bash
cd /path/to/qbittorrent-readonly-mcp
uv sync
uv run pytest
```

真实只读 smoke test（仅输出工具名和脱敏检查结果）：

```bash
uv run python scripts/live_smoke.py \
  --env-file /path/to/secrets/nas-audit.env
```

本地启动：

```bash
QBIT_MCP_ENV_FILE="/path/to/secrets/nas-audit.env" \
  uv run qbittorrent-readonly-mcp
```

服务启动后使用 stdin/stdout 传输 MCP 协议，不会显示普通交互提示符。

## Codex 配置

Codex 支持在可信项目的 `.codex/config.toml` 中配置本地 STDIO MCP。以下是示例配置；这里只传秘密文件路径，不把 API Key 写进配置。实际路径应由使用该 MCP 的宿主项目维护：

```toml
[mcp_servers.qbittorrent_readonly]
command = "/path/to/qbittorrent-readonly-mcp/.venv/bin/qbittorrent-readonly-mcp"
args = []
cwd = "/path/to/qbittorrent-readonly-mcp"
enabled = true
required = false
startup_timeout_sec = 20
tool_timeout_sec = 60
default_tools_approval_mode = "auto"
enabled_tools = [
  "get_health_summary",
  "list_torrents",
  "get_torrent_details",
  "list_problem_torrents",
  "analyze_largest_torrents",
]

[mcp_servers.qbittorrent_readonly.env]
QBIT_MCP_ENV_FILE = "/path/to/secrets/nas-audit.env"
```

本仓库不保存 Codex 配置，也不保存任何凭据。调用方只需要引用本项目的启动命令，并传入项目外的秘密文件路径。

Codex MCP 配置方式参考 [OpenAI 官方文档](https://developers.openai.com/codex/mcp)，Python 实现使用 [Model Context Protocol 官方 Python SDK](https://github.com/modelcontextprotocol/python-sdk)。

## 开发

核心分层：

```text
MCP tools
  -> ReadOnlyQbitService（筛选、聚合、固定输出）
    -> QbitReadOnlyClient（固定 GET allowlist）
      -> qBittorrent Web API
```

任何新 endpoint 都必须先加入 `READ_ONLY_ENDPOINTS`，并为“非白名单拒绝”和“敏感字段不泄漏”增加测试。