Baomihua Formatter MCP Server

A standalone Node.js MCP server for inspecting and operating on media files in OpenList and CloudDrive2, plus querying TMDB movie and TV metadata. The server communicates over MCP stdio and keeps storage/TMDB credentials in local environment configuration rather than in tool descriptions or checked-in documentation.

Requirements

• Node.js 20 or newer (package.json declares engines.node >=20.0.0).
• Network access to the configured OpenList and/or CloudDrive2 endpoint when those backends are used.
• TMDB credentials when using the TMDB tools.

Install

From the server project directory:

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

Edit the local .env with the endpoints and credentials needed by your environment. .env is ignored by Git; never commit it, paste secrets into this README, or include real credentials in an MCP client configuration checked into source control.

The supported configuration keys are documented by .env.example, including:

• OPENLIST_URL, OPENLIST_USERNAME, OPENLIST_PASSWORD, and optional OPENLIST_OTP_CODE;
• CLOUDDRIVE2_URL, CLOUDDRIVE2_TOKEN, and CLOUDDRIVE2_TLS;
• TMDB_API_KEY or TMDB_TOKEN, plus optional TMDB_LANGUAGE and TMDB_PROXY;
• STORAGE_CONCURRENCY, UPLOAD_CONCURRENCY, and STORAGE_MAX_CONCURRENCY;

Run the MCP server

The npm script starts the stdio server:

npm run mcp

The process is intended to be launched by an MCP client, so normal protocol traffic is sent over stdin/stdout. Keep diagnostics out of stdout when embedding the server.

Generic MCP client entry

Use an absolute Node executable and an absolute server path. Replace only the example paths and configure secrets through the server's local .env; this entry intentionally contains no credentials:

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

The MCP client should launch the entry from a context where the server project has its .env file. An equivalent shell command is:

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

Tool groups and semantics

Storage navigation

Both storage backends expose a direct listing and a recursive scan:

• openlist_list / clouddrive2_list list direct children only.
• openlist_scan / clouddrive2_scan recursively collect descendants and accept bounded concurrency and continue_on_error options.
• openlist_stat / clouddrive2_stat inspect one exact path.
• openlist_search / clouddrive2_search search entries below a path.

Scan and upload-directory operations use bounded concurrency. Keep concurrency within the server's configured maximum and leave continue_on_error false unless partial completion is intentionally accepted.

File operations

OpenList and CloudDrive2 each provide tools for creating directories, renaming, deleting files/directories, moving, copying, and uploading files/directories. CloudDrive2 also provides clouddrive2_get_download_url.

Every mutating tool requires confirm: true. The Agent or MCP client must first present the exact proposed paths, names, destinations, conflict policy, and destructive effects to the user. The server rejects unconfirmed mutations. continue_on_error is not a confirmation mechanism; it only controls whether a bounded batch continues after an item fails.

TMDB

The server exposes tmdb_search_movie, tmdb_search_tv, tmdb_get_movie_details, tmdb_get_tv_details, and tmdb_get_season_details. These tools return candidates or metadata; they do not rename files.

Filename title/year/season/episode/quality extraction is deliberately an Agent responsibility. For media formatting workflows, inspect the complete storage path, extract those fields independently, query TMDB candidates, validate the selected result with details, and ask the user to resolve ambiguous same-name candidates before proposing a mutation.

Recommended workflow

1. Use a backend *_list call for direct navigation or *_scan for recursive collection.
2. Keep original paths and parse title, year, season, episode, quality, and subtitle markers independently.
3. Search TMDB, compare candidates with the parsed evidence, and fetch details for the chosen ID.
4. Show a complete rename/move/copy/delete/upload proposal and wait for explicit confirmation.
5. Execute the confirmed mutation with confirm: true.
6. Verify with a follow-up list, stat, or scan and report successes, skips, and errors.

Development

Run the test suite from this directory:

npm test

The project is private, uses ESM, and has no runtime dependency on the older formatter CLI. Keep credentials and generated logs out of commits.