MDisBetter file converter

mdisbetter MCP サーバー

エージェントがファイルを変換できるようにする MCP サーバーです。mdisbetter.com のコンバーターを stdio 経由で公開します。162 種類の入力形式で、実証済みの変換は 3649 通りです。画像、ドキュメント、電子書籍、音声、動画、オフィスファイル、フォント、アーカイブ、データ形式、字幕、書誌情報に対応しています。11 のファミリーについて、PDF への変換だけでなく、入力と出力の両方に対応します。

ツールは 2 つだけで、これがすべてです。

ツール	機能
convert_file	パスと出力形式を受け取り、変換したファイルを書き込み、そのパスを返します。
list_conversions	拡張子を指定すると、その拡張子で実証済みの出力形式を返します。指定しない場合は、受け付けるすべての入力拡張子を返します。

対応していない機能

誤って反対のことを主張しやすいため、この一覧を載せています。 このサーバーには、バッチモード、ウェブフック、ジョブのポーリング、キュー、ストリーミング、URL 入力、stdio エントリーポイント以外の CLI はありません。1 回の呼び出しにつきローカルファイルを 1 つ変換し、結果が返るまで待機します。

以前はここに「音声や動画の変換には対応していません」と記載していました。変換テーブルが再同期されたため、現在は当てはまりません。音声と動画も、ほかのすべてのファミリーと同様に変換できます。再エンコードが必要な動画は、再エンコードに実際の CPU 負荷がかかるため、元ファイルの長さが 120 秒までに制限されます。コーデックを維持したコンテナーの変更はストリームコピーとなるため、この制限はありません。

必要条件

• Node.js 20 以降。
• mdisbetter.com のアカウントと API キー。登録が必要です。キーは mdb_sk_ で始まります。

ダッシュボードの API keys から作成してください。平文のキーが表示されるのは一度だけで、その後は二度と表示されません。ハッシュのみが保存されるため、弊社を含め、誰もキーを復元できません。パネルを閉じる前に保存してください。

変換には、ウェブサイトで使用するものと同じ残高からクレジットが消費されます。プログラムからの使用に別枠の利用上限はありません。

インストール

git clone https://github.com/dresseurmonster2-oss/mdisbetter-mcp.git
cd mdisbetter-mcp
npm install

クローンせずに実行することもできます。

npx -y github:dresseurmonster2-oss/mdisbetter-mcp

MCP バンドルとして

.mcpb バンドルを開けるクライアントでは、各 リリースに添付されているファイルからサーバーをインストールできます。mdisbetter-mcp.mcpb をダウンロードして開き、求められたら API キーを入力してください。このバンドルは、依存関係を含む、このリポジトリと同じコードです。npm run bundle で自分でビルドできます。

このサーバーは、公式 MCP Registry に io.github.dresseurmonster2-oss/mdisbetter-mcp として登録されています。

設定

環境変数は 2 つで、そのうち 1 つは任意です。

変数	必須	意味
MDISBETTER_API_KEY	はい	mdb_sk_ で始まるキーです。
MDISBETTER_BASE_URL	いいえ	デフォルトは https://mdisbetter.com です。プレビュー環境を指定すると、そこでテストできます。

キーはサーバーの環境から読み取られ、ツールの引数として渡されることはありません。 サーバーがキーを出力ファイルに書き込むこともありません。クライアント設定は非公開にし、キーが漏えいした場合はダッシュボードから無効化してください。

クライアントに接続する

ほとんどの MCP クライアントは、次のような JSON ブロックを読み込みます。パスには、リポジトリをクローンした場所を指定してください。

{
  "mcpServers": {
    "mdisbetter": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/src/index.js"],
      "env": {
        "MDISBETTER_API_KEY": "mdb_sk_your_key_here"
      }
    }
  }
}

クライアントを再起動してください。ツール一覧に list_conversions と convert_file が表示されます。

ツール

list_conversions

// every input format the converter accepts
{ "name": "list_conversions", "arguments": {} }

// what a .docx can become
{ "name": "list_conversions", "arguments": { "extension": "docx" } }

拡張子は、ドットの有無や大文字・小文字を問わず指定できます。 .DOCX、docx、.docx は、いずれも同じ問い合わせです。

コンバーターが読み取れない拡張子は、空のリストを返すのではなく、拒否されます。

convert_file

{
  "name": "convert_file",
  "arguments": {
    "path": "/home/me/report.docx",
    "target": "pdf"
  }
}

引数	必須	説明
path	はい	このサーバーを実行しているマシン上で変換するファイルです。
target	はい	出力形式を拡張子のみで指定します：pdf、png、md。
output_path	いいえ	結果の書き込み先です。既存のファイルがある場合は上書きします。

output_path を指定しない場合、結果は入力ファイルと同じ場所に新しい拡張子で保存されます。たとえば、report.docx は同じディレクトリ内の report.pdf になります。その名前がすでに使われている場合、サーバーは代わりに report-1.pdf に書き込みます。指定されていないファイルを上書きすることはなく、入力ファイルに手を加えることもありません。

サーバーは、150 MB を超えるローカル入力を拒否します。アカウントのプランや変換形式の種類によって、実際の上限はさらに低くなります。Free アカウントのファイル上限は 10 MB、ドキュメント変換の形式別上限は 25 MB です。サーバーの上限が、すべての形式やアカウントで 150 MB まで利用できるという意味ではありません。

4 MB 未満の場合、ファイルはリクエスト自体に含まれるため、往復は 1 回です。それを超える場合、サーバーはまずストレージにアップロードしてからアドレスだけを送信します。これは、API をホストするプラットフォームがリクエストボディとレスポンスボディの両方を 4.5 MB に制限しているためです。2026 年 8 月 31 日に 100 KB 刻みで測定したところ、4.2 MB は通過し、4.3 MB は関数が実行される前に 413 を返しました。その日まで、この README には 25 MB と記載されていました。これはエンジンの上限から取った値であり、トランスポート経由では到達できませんでした。

表にない形式の組み合わせは、何も送信される前に拒否され、利用可能な出力形式が一覧表示されます：

.png to .docx is not a proven conversion. Proven targets for .png (28):
avif, bmp, dds, eps, gif, hdr, ico, jng, jp2, jpeg, jpg, miff, pbm, pcx,
pdf, pgm, pnm, ppm, ps, psd, ras, sgi, tga, tif, tiff, wbmp, webp, xpm.

手順：ローカル HTML から Markdown への変換

1. ダッシュボードで登録またはサインインし、API キーを作成して、表示されたら保存します。上記のとおり MCP クライアントを設定して再起動します。キーをプロンプトやソース管理に含めないでください。
2. この自作のサンプルを field-notes.html として、サーバーを実行しているマシンに保存します：

<html><body><h1>Harbor field notes</h1><p>Inspection marker: MCPCA0420261013. Tide reading: 42 centimetres.</p><h2>Actions</h2><ul><li>Check the north gate.</li><li>Record the reading.</li></ul></body></html>

3. クライアントに、次のツールを順番に呼び出すよう依頼します。入力パスを実際の絶対パスに置き換え、Windows ではドライブ名を含むパスを使用してください：

{"name":"list_conversions","arguments":{"extension":"html"}}
{"name":"convert_file","arguments":{"path":"/absolute/path/field-notes.html","target":"md"}}

最初の応答で、変換前に md が一覧にあることを確認してください。2 番目の応答には、ファイルの書き込み先が報告されます。その Markdown ファイルを開き、見出し、読み取り値、および 2 つのアクション項目を確認してください。これらは MCP ツールの引数であり、別個の公開 HTTP インターフェースや単独で実行する変換コマンドではありません。

検証済みの出力は次のとおりです：

# Harbor field notes

Inspection marker: MCPCA0420261013. Tide reading: 42 centimetres.

## Actions

-   Check the north gate.
-   Record the reading.

ソース 84b2bed および本番環境で、2026 年 10 月 13 日（シンガポール時間）に検証しました。新規の通常の Free アカウントには、最初に 50 クレジットが付与されていました。HTML の出力形式一覧の取得にはクレジットがかかりませんでした。実際の stdio 経由でこのファイルを変換すると 0.5 クレジットを消費し、151 バイトのファイルが書き込まれました。同じ変換を通常のウェブサイトセッションで認証して行った場合も、0.5 クレジットを消費し、同一のバイト列が返されました。見出し、マーカー、42 センチメートルの読み取り値、および両方のアクションが保持されました。サポート対象外の HTML から PNG への変換リクエストでは、ファイルは書き込まれず、クレジットも消費されませんでした。その後、テストキーは失効させ、合成アカウントは無効化しました。

この小さな HTML の例は、カタログ内のすべての形式の組み合わせ、大容量アップロード、有料プランの上限、お使いのクライアント設定、または複雑なドキュメントの忠実な変換を保証するものではありません。テストのためにアカウントの利用枠を増やすことはありませんでした。使用する前に各結果を確認してください。output_path を明示的に指定すると、そのパスにある既存のファイルは置き換えられます。

ファイルが返ってこない場合

サーバーは単なるステータスコードを返すのではなく、それぞれの回答を翻訳します。

状況	エージェントに伝える内容
クレジット不足	変換に必要なクレジット数、残りのクレジット数、不足しているクレジット数、およびチャージページを伝えます。これは障害ではありません。アカウントのクレジットが不足しているため、変換は行われていません。
キーが拒否された	キーがないか、無効か、または取り消されています。MDISBETTER_API_KEY を設定してください。
ファイルが拒否された	対応形式の組み合わせは実証済みなので、問題はファイル自体にあります。内容が拡張子と一致しないか、エンジンが読み取れないファイルです。
ファイルサイズ超過	ローカルサーバーの上限、アカウントプランの上限、または変換ファミリーの上限を超えました。
コンバーターが処理能力の上限に到達	サービスは性能を落とすのではなく、意図的に負荷を制限します。障害は発生しておらず、料金も発生していません。数秒後に再試行してください。
サービスを利用できない、またはタイムアウト	状況を明確に伝え、ファイルは書き込まれません。

変換後のファイルが実際にバイトデータを伴って返されない限り、ディスクに書き込まれることはありません。

変換テーブルの生成元

src/formats.js は、ウェブサイト自体が使用しているテーブルのコピーです。手作業で作成するのではなく、実際にプローブで変換し、出力が宣言された形式であることを確認するために読み戻した組み合わせだけを含めて生成します。エンジンが対応形式として提示しているだけの形式は含まれません。

編集しないでください。メインリポジトリで再生成してください。

python scripts/generer-formats.py

これにより、プローブ結果から site/content/formats.js が書き換えられ、そのファイルが元のヘッダーを保ったまま変更されずにここへコピーされます。

このテーブルでは、それぞれの組み合わせを、ファイルの種類ではなく、その組み合わせに最適なものに基づいて4つのエンドポイントのいずれかに割り当てています。

エンドポイント	組み合わせ数	主な用途
/api/convert-image	1189	画像から画像への変換
/api/convert-media	1117	音声と動画
/api/convert-document	895	マークアップおよびドキュメント形式
/api/convert-ebook	298	電子書籍およびリーダー形式
/api/convert-office	41	オフィス文書、スプレッドシート、スライド
/api/convert-archive	30	アーカイブ：ZIP、TAR とその圧縮形式、7z
/api/convert-subtitle	25	字幕：SRT、VTT、ASS、SSA、LRC、TTML
/api/convert-data	24	データ形式：JSON、YAML、TOML、CSV、TSV、NDJSON
/api/convert-font	18	フォント：TrueType、OpenType、WOFF、WOFF2
/api/convert-bibliography	12	参考文献：BibTeX、BibLaTeX、CSL JSON、RIS、EndNote XML

これらの件数は test/readme.test.mjs によってテーブルと照合されます。テーブル自体は実際のエンジンへのプローブ結果から生成されるため、ここに記載された数値が古い場合は README が更新されていないことを意味し、テーブルが間違っているという意味ではありません。

複数のエンドポイントで処理できる拡張子もあります。.docx から PDF への変換ではレイアウトを保つためオフィスエンドポイントを使用し、.docx から Markdown への変換ではテキストの忠実性を保つためドキュメントエンドポイントを使用します。呼び出し元が把握する必要はありません。ファイルと変換先の形式を指定するだけです。

テスト

npm test

テストスイートはオフラインで実行されます。サーバーを実際のプロセスとして起動し、標準入出力経由で MCP を使って通信します。3649 件すべての組み合わせのルーティングを確認し、実証されていない組み合わせがリクエスト送信前に拒否されることを確認します。また、クレジット不足を失敗と表現しないことを含め、各回答の文面を確認します。

テストでは実際の変換は行いません。そのためにはキーとクレジット残高が必要ですが、どちらもテストスイートに含めるべきではありません。

ライセンス

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

コンバーター自体はホスト型サービスです。このリポジトリは、そのサービスに接続するためのコネクターです。変換には mdisbetter.com の残高からクレジットが消費されます。