MCP Qbit Server

MCP qBittorrent服务器

一个轻量级的模型上下文协议（MCP）服务器，通过JSON-RPC公开精心策划的qBittorrent自动化原语。该服务将qBittorrent的WebUI API与严格的验证、依赖性注入工具和Jest-based回归测试相结合，因此代理可以安全地查询torrent状态或添加新的torrent。

亮点

• JSON-RPC 2.0传输 与单一 /rpc 终点和健康探针 /health.
• 工具注册表+DI容器 (lib/mcp)在启动时连接qBittorrent感知工具。
• 严格的论证验证 通过Zod模式来防止格式错误的torrent操作。
• 可测试的组成根 (createApp)这使得嘲笑成为可能 QBitClient 在Jest测试中。
• 准备发布Node.js服务 使用基于dotenv的配置和nodemon驱动的开发循环。

建筑

client ──JSON-RPC──> Express (/rpc)
                    │
                    ▼
              JsonRpcHandler
                    │
              ToolService (tools/call)
                    │
              ToolRegistry (DI container)
             ┌──────────────┴──────────────┐
     GetTorrentsTool               AddTorrentTool
             │                             │
             └──────────────QBitClient─────┘

• lib/qbit/QBitClient 封装了qBittorrent WebUI的身份验证、cookie重用和重试。
• 工具继承自 McpTool 并宣布自己的Zod inputSchema 加 execute 逻辑。
• ToolService 验证 tools/call 有效载荷，解析工具 ToolRegistry，运行它，并将成功/错误结果标准化。

需求

• Node.js 18+（建议使用LTS）
• npm 10+
• 在启用WebUI的情况下运行qBittorrent实例

配置

创建一个 .env 启动服务器之前，请先执行以下操作：

PORT=8000
QBIT_BASE_URL=http://localhost:8080
QBIT_USERNAME=admin
QBIT_PASSWORD=secret
QBIT_TIMEOUT=10000

配置选项

• 端口 （可选）：服务器端口，默认为 8000
• QBIT_BASE_URL （必填）：qBittorrent WebUI URL（必须以http://或https://开头）
• QBIT_用户名 （必填）：qBittorrent用户名
• QBIT_PASSWORD （必填）：qBittorrent密码
• QBIT超时 （可选）：请求超时（毫秒），默认为 10000 （10秒）

安装和本地运行

npm install
npm run dev

• npm run dev 使用nodemon启动服务，因此代码编辑会触发重新加载。
• 使用 npm start 在生产环境中运行 server.js 直接。

健康和RPC端点

样品申请

curl -X POST http://localhost:8000/rpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "qbit/getTorrents",
      "arguments": { "filter": "all" }
    }
  }'

样品响应

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": false,
    "content": [
      { "name": "ubuntu.iso", "state": "seeding", "progress": 1 },
      { "name": "movie.mkv", "state": "downloading", "progress": 0.42 }
    ]
  }
}

可用工具

每个工具在接触qBittorrent之前都会强制执行自己的Zod模式，因此格式错误的有效载荷永远不会到达客户端。

测试

运行Jest套件（模拟qBittorrent，因此不需要外部依赖）：

npm test

现场测试 tests/mcp.test.js 涵盖健康检查、传输错误以及两种刀具路径。

部署说明

• 该服务是无状态的；在任何反向代理后面运行并水平缩放。
• 请确保可以从此服务器访问qBittorrent WebUI API，并且凭据的作用域正确。
• 考虑设置 NODE_ENV=production 因此Express省略了堆栈跟踪。
• 安全：参见 安全.md 安全最佳实践，包括：

- 使用TLS/SSL在反向代理后面运行 - 实施速率限制 - 使用强凭据 - 网络隔离建议

贡献

生活指南 CONTRIBUTING.md简而言之：打开一个问题，运行 npm test 在提交之前，记录新工具。

行为准则

参与受以下规定的约束 CODE_OF_CONDUCT.md，它改编了《贡献者公约》，以保持社区的欢迎。

许可证

根据MIT许可证分发。看 LICENSE 了解详情。

维护者

由创建和维护 雅克·默里 ().