Baomihua Formatter MCP Server

OpenList と CloudDrive2 のメディアファイルを検査・操作し、さらに TMDB の映画・TV メタデータを照会するためのスタンドアロン Node.js MCP サーバーです。このサーバーは 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 ファイルが存在するコンテキストからエントリを起動する必要があります。同等のシェルコマンドは次のとおりです:

& '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 は正確に 1 つのパスを検査します。

• 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. フォローアップのリスト、stat、またはスキャンで検証し、成功、スキップ、エラーを報告します。

開発

このディレクトリからテストスイートを実行します:

npm test

このプロジェクトはプライベートで、ESM を使用し、旧形式の formatter CLI への実行時依存関係はありません。認証情報と生成されたログをコミットに含めないでください。