filemorph

filemorph

filemorph は、ドキュメント、スプレッドシート、画像、電子書籍、字幕にまたがる 44 種類の形式間でファイルを変換する、ホスト型の FileTypeConverters MCP サーバーへの小規模なローカルブリッジです。base64 コンテンツまたは公開 https URL としてファイルを渡し、変換先の形式を選ぶと、変換後の出力が返されます。小さなテキスト出力はインラインで、大きな出力やバイナリ出力は base64 とダウンロード URL で返されます。

このブリッジ自体は変換を行わず、ファイルも保持しません。ライブエンドポイントから取得したとおりの上流サーバーのツール一覧をローカルで提供し、各ツール呼び出しを上流に転送して、結果を変更せずに返します。ツールのうち 2 つは参照データを読み取り、1 つは変換の組み合わせがサポートされているかを確認し、1 つは変換を送信し、もう 1 つは以前に送信した変換結果を取得します。

ツール

• list_formats — コンバーターが読み取りまたは書き込み可能なすべての形式を、ID、名前、拡張子、ファミリーとともに返します。ID は、ほかのツールで from と to として指定します。引数はありません。
• check_conversion — ファイルを送信する前に、ある形式から別の形式へ変換できるかどうかを確認します。エンジン、AI Deep Read が必要かどうか、その組み合わせで受け付けるオプション、組み合わせがサポートされていない場合の代替形式を報告します。形式は ID（docx）、拡張子（jpeg）、一般的な名前（word、excel）で指定できます。必須：from、to。
• list_conversions — ソース形式に対してサポートされている変換先形式、または指定した変換先を生成できるすべてのソース形式を、コンパクトな {from,to,slug,engine,mode} の行として返します。任意：from、to。
• convert_file — ファイルを送信して変換します。コンテンツは base64 または公開 url として渡します。ファイル名または URL に拡張子が含まれている場合、from は省略可能です。200 KB 以下のテキスト出力（Markdown、CSV、JSON、HTML など）は text としてインラインで返されます。それ以外の出力は base64 と、同じベアラートークンを受け付ける downloadUrl として返されます。ファイルサイズの上限は 10 MB です。deepRead: true を設定すると、AI Deep Read でスキャン画像、写真、手書き文字を読み取ります（1 ページあたり 1 クレジット）。必須：to。任意：filename、base64、url、from、options、deepRead。
• get_conversion — ID を指定して以前に送信した変換を取得します。保持されている間は、ステータス、警告（あれば）、出力（インラインテキストまたは base64）が返されます。必須：id。

設定

• FILETYPECONVERTERS_MCP_URL（任意）— 上流のエンドポイントを上書きします。デフォルトは https://filetypeconverters.com/api/mcp です。（この上書き用フックは、この再構築独自のものであることを明記しています。）
• FILETYPECONVERTERS_API_KEY（任意）— 設定すると、すべての上流リクエストに Authorization: Bearer <key> ヘッダーが付加されます。設定されていない場合、認証ヘッダーは送信されません。（この転送も、この再構築独自のものであることを明記しています。元のインターフェースはキーなしで取得されましたが、レジストリの記録では Authorization ヘッダーが必須とされています。）

転送の仕組み

最初のツール呼び出し時に、クライアントは上流とのストリーム可能な HTTP セッションを開始します。まず JSON-RPC の initialize リクエスト（protocolVersion 2025-03-26、clientInfo name filemorph）を送り、続いて notifications/initialized 通知を送り、その後、呼び出し元の引数を変更せずに含めた tools/call リクエストを送信します。上流が initialize に Mcp-Session-Id ヘッダーを付けて応答した場合、その値はセッションの後続リクエストすべてに引き継がれ、プロセスが終了するまでセッションが再利用されます。応答は通常の JSON またはサーバー送信イベントとして届く場合があり、どちらも読み取ります。

上流からの成功結果は、上流が設定した isError フラグも含め、そのまま転送されます。JSON-RPC エラー、2xx 以外のステータス、読み取り不能な応答、完了できないリクエストなどの失敗は、テキストが filemorph error: で始まる isError 結果として返されます（このエラー表示は、この再構築独自のものであることを明記しています）。

CLI

各ツールは、JSON 引数を 1 つ取るサブコマンドでもあります （引数を必要としないツールでは省略します）。

npx @reneturcios/filemorph list_formats
npx @reneturcios/filemorph check_conversion '{"from":"pdf","to":"docx"}'
npx @reneturcios/filemorph convert_file '{"to":"md","filename":"report.pdf","base64":"..."}'
npx @reneturcios/filemorph get_conversion '{"id":"conv-42"}'
npx @reneturcios/filemorph --version

終了コード：成功時は 0、isError の結果時は 1、使用方法の誤り時は 2 です。

MCP サーバー

npx -y @reneturcios/filemorph mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "filemorph": {
      "command": "npx",
      "args": ["-y", "@reneturcios/filemorph", "mcp"]
    }
  }
}

Docker

docker run -i ghcr.io/cloudcorprecords/filemorph
docker run --rm ghcr.io/cloudcorprecords/filemorph --version

コンテナのデフォルトコマンドは mcp なので、最初の形式は stdio MCP サーバーとして動作します。それ以外の引数は通常どおり CLI に渡されます。

開発

npm install
npm run build
npm test
npm run dev

テストスイートはすべて、スタブ化された JSON-RPC アップストリームに対して実行されます。実際のネットワーク呼び出しはありません。

ライセンス

MIT — LICENSE を参照してください。