Baomihua Formatter MCP Server

一个独立的 Node.js MCP 服务器，用于检查和操作 OpenList 和 CloudDrive2 中的媒体文件，并查询 TMDB 电影和电视元数据。服务器通过 MCP stdio 进行通信，并将存储/TMDB 凭据保存在本地环境配置中，而不是放在工具描述或已提交的文档中。

要求

• Node.js 20 或更高版本（package.json 声明 engines.node >=20.0.0）。

• 使用这些后端时，需要能够访问所配置的 OpenList 和/或 CloudDrive2 端点。

• 使用 TMDB 工具时需要 TMDB 凭据。

安装

从服务器项目目录：

Set-Location C:\path\to\baomihua-formatter-mcp-server
Copy-Item .env.example .env
npm install

使用环境所需的端点和凭据编辑本地 .env 文件。.env 被 Git 忽略；切勿将其提交、将机密粘贴到本 README 中，或在已纳入源代码管理的 MCP 客户端配置中包含真实凭据。

支持的配置键由 .env.example 记录，包括：

• OPENLIST_URL、OPENLIST_USERNAME、OPENLIST_PASSWORD 以及可选的 OPENLIST_OTP_CODE；

• CLOUDDRIVE2_URL、CLOUDDRIVE2_TOKEN 和 CLOUDDRIVE2_TLS；

• TMDB_API_KEY 或 TMDB_TOKEN，以及可选的 TMDB_LANGUAGE 和 TMDB_PROXY；

• STORAGE_CONCURRENCY、UPLOAD_CONCURRENCY 和 STORAGE_MAX_CONCURRENCY；

运行 MCP 服务器

npm 脚本启动 stdio 服务器：

npm run mcp

该进程旨在由 MCP 客户端启动，因此正常的协议流量通过 stdin/stdout 发送。嵌入服务器时，请勿将诊断信息输出到 stdout。

通用 MCP 客户端条目

使用绝对路径的 Node 可执行文件和绝对路径的服务器路径。仅替换示例路径，并通过服务器的本地 .env 配置机密；此条目有意不包含任何凭据：

{
  "mcpServers": {
    "baomihua-formatter": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": [
        "C:\\path\\to\\baomihua-formatter-mcp-server\\server.js"
      ]
    }
  }
}

MCP 客户端应在服务器项目包含其 .env 文件的上下文中启动该条目。等效的 shell 命令为：

& 'C:\Program Files\nodejs\node.exe' 'C:\path\to\baomihua-formatter-mcp-server\server.js'

工具组及其语义

存储导航

两个存储后端都提供直接列表和递归扫描：

• openlist_list / clouddrive2_list 仅列出直接子项。

• openlist_scan / clouddrive2_scan 递归收集后代条目，并接受有界 concurrency 和 continue_on_error 选项。

• openlist_stat / clouddrive2_stat 检查一个精确路径。

• openlist_search / clouddrive2_search 在路径下搜索条目。

扫描和上传目录操作使用有界并发。将并发保持在服务器配置的最大值以内，除非有意接受部分完成，否则将 continue_on_error 保持为 false。

文件操作

OpenList 和 CloudDrive2 各自提供用于创建目录、重命名、删除文件/目录、移动、复制以及上传文件/目录的工具。CloudDrive2 还提供 clouddrive2_get_download_url。

每个变更工具都要求 confirm: true。Agent 或 MCP 客户端必须首先向用户展示确切的目标路径、名称、目标位置、冲突策略和破坏性影响。服务器会拒绝未经确认的变更。continue_on_error 不是确认机制；它仅控制有界批次在某个条目失败后是否继续。

TMDB

服务器提供 tmdb_search_movie、tmdb_search_tv、tmdb_get_movie_details、tmdb_get_tv_details 和 tmdb_get_season_details。这些工具返回候选结果或元数据；它们不会重命名文件。

文件名中的标题/年份/季/集/质量提取特意由 Agent 负责。对于媒体格式化工作流，请检查完整的存储路径，独立提取这些字段，查询 TMDB 候选结果，使用详细信息验证所选结果，并在提出变更之前请用户解决同名的歧义候选。

推荐工作流

1. 使用后端的 *_list 调用进行直接导航，或使用 *_scan 进行递归收集。

2. 保留原始路径，并独立解析标题、年份、季、集、质量和字幕标记。

3. 搜索 TMDB，将候选结果与解析出的证据进行比较，并获取所选 ID 的详细信息。

4. 展示完整的重命名/移动/复制/删除/上传方案，并等待明确确认。

5. 使用 confirm: true 执行已确认的变更。

6. 通过后续的 list、stat 或 scan 进行验证，并报告成功、跳过和错误。

开发

从此目录运行测试套件：

npm test

该项目是私有的，使用 ESM，并且不依赖旧版 formatter CLI 的运行时。请勿将凭据和生成的日志提交到版本库中。