VitaminMCP

VitaminMCP

AI エージェントでプラグインをテスト — 実際に稼働しているサーバーで、実際のプレイヤーと一緒に。

ドキュメント · Modrinth · npm · 課題

VitaminMCP は、稼働中のサーバー内部から MCP（Model Context Protocol） エンドポイントを公開する Paper/Purpur プラグインです。Claude Code、Cursor、Codex、Gemini CLI など、あらゆる MCP クライアントから AI エージェントを接続すると、実際の Minecraft プロトコル経由で実際のボットクライアントが参加する中で、サーバーを操作し、実行結果を読み取ることができます。

テスト対象のプラグインには一切変更を加えません。 導入するテストフレームワークも、計測のためのソースコード変更も、モックサーバーも必要ありません。テスト対象のプラグインは、実際のライフサイクルを通じて実際のサーバー上で実行されます。そのため、自分で作成していないプラグインでもテストできます。インストールされているものなら何でもテスト可能です。

エージェントができること

• テストプレイヤーをスポーンして操作 — モックの Player オブジェクトではなく、実際のプロトコルクライアントです
• コンソールまたはプレイヤーとしてコマンドを実行
• インベントリやプラグイン GUI を開き、読み取り、クリックして検証
• ショップやクエストの依頼主で実際に行う方法で、NPC や村人を右クリック
• プレイヤーを移動させ、ブロックを壊して使用し、チャットを送信
• スリープする代わりに、イベントや条件を待機
• メニュー、チャット、アクションバー、タイトル、ボスバー、スコアボードなど、プレイヤー画面全体を読み取り
• イベント、ログ、例外、権限など、サーバーのライブ状態を読み取り
• 複数のサーバーを同時に操作 — BungeeCord ネットワークのバックエンドごとに 1 つのセッション

MCP ツール

ツール	機能
session_start	稼働中のサーバーに接続。プロキシネットワークでは複数のセッションを同時に使用可能
session_reset	すべてのボットを切断するか、セッションを閉じる
server_info	実装、バージョン、TPS、オンラインプレイヤー、インストール済みプラグイン
logs_query	重大度と正規表現でサーバーログを検索
events_summary	指定した時間範囲内に捕捉した Bukkit イベントを種類別に集計
events_query	種類とプレイヤーで絞り込み、捕捉した個々のイベントを読み取り
exceptions_recent	件数付きの重複しない例外。必要に応じて完全なスタックトレースを取得
state_query	サーバーのライブ状態 — player（権限チェックを含む）、block、inventory（プラグイン GUI の内容が存在する唯一の場所）、plugin（コマンド、権限、ライブ設定）
command_exec	権限なども含め、コンソールまたは任意のプレイヤーとしてコマンドを実行
wait_for	条件が満たされるまで待機 — ticks、block_is、block_is_not、event、player_online、player_offline、player_near、player_state、inventory_open、inventory_contains、log_matches
bot_spawn	オフラインまたは Microsoft 認証済みの Minecraft プロトコルクライアントをテストプレイヤーとして接続
bot_inspect	ボットのクライアントに送信されたすべての情報：チャット、アクションバー、タイトル、ボスバー、スコアボード、体力、エフェクト、開いているメニュー
bot_run_scenario	スクリプト化されたテスト全体を 1 回の呼び出しで実行。失敗時には、失敗したステップとその時点でのサーバーの動作を報告
bot_view	1 体のボット用の localhost ライブビューアー — ワールド、または開いているメニュー

シナリオのステップ

bot_run_scenario は次のステップを実行してテスト全体を組み立てます。失敗すると、該当するステップと、その時点でサーバーが行っていた処理が報告されます。

カテゴリ	ステップ	内容
ワールドと移動	spawn	ボットを接続し、ワールド内に立つまで待機します
	despawn	ボットを切断します
	move_to	実際の物理演算を通じて移動します。感圧板や移動リスナーが作動します。セットアップには teleport モードを使います
	look_at	ブロックまたは位置の方向を向きます
	jump	ジャンプします
	sneak	スニークを開始または停止します
	sprint	ダッシュを開始または停止します
ブロックとアイテム	break_block	実際に採掘してブロックを壊します
	place_block	手に持っているブロックを設置します
	use_block	ブロックを右クリックします。ボタン、ドア、チェストなどが対象です
	hold_item	アイテムをメインハンドに持たせます
	drop_item	持っているアイテムを落とします
インタラクション	use_entity	エンティティを右クリックします。ショップやクエストのNPCを実際に起動する方法です
	attack_entity	エンティティを攻撃します
	click_slot	開いているメニューまたはGUIのスロットをクリックします
	close_menu	開いているメニューを閉じます
	chat	ボットとしてチャットメッセージを送信します
	command	権限も含め、ボットとしてコマンドを送信します
	console	シナリオの途中でコンソールコマンドを実行します
待機	wait_for	条件が満たされるまで待機します。すべての wait_for 条件はステップとして利用できます
アサーション	assert_block	ブロックの種類を検証します
	assert_player	プレイヤーの現在の状態（位置、ゲームモード、オペレーター権限、体力）を検証します
	assert_event	サーバーでイベントが発生したことを検証します
	assert_inventory	開いているGUIまたはインベントリのスロットを検証します
	assert_message	ボットのクライアントに表示された内容（チャット、アクションバー、タイトル）を検証します
	assert_reachable	実際に歩いて到達できる位置であることを検証します

3つの要素の連携方法、各ツールとステップで指定できる内容、シナリオ例については、docs/reference.md をご覧ください。

バージョンのサポート

Minecraft のバージョン	Windows	Linux	macOS	ステータス
1.18 – 1.20.6	🟡	🟡	🟡	予定されています。現在のエージェントの下限（1.21）未満です
1.21 – 1.21.11	🟢	🟢	🟢	サポート済み、実機テスト済み
26.1 – 26.1.2	🟢	🟢	🟢	サポート済み、実機テスト済み
26.2 – 26.3, agent	🟢	🟢	🟢	エージェントをサポート：ログ、イベント、状態、コマンドに対応。Paper 26.2-134 および 26.3-200 で手動確認済み
26.2 – 26.3, bots	🔴	🔴	🔴	未対応です。mineflayer は 26.1 までです（#4）。session_start はエージェント向けに開始し、ボットが参加できない理由を表示します
以降のリリース	🟡	🟡	🟡	追加前に、バージョンごとに互換性テストが必要です

OS ごとのランナーのサポート状況

OS	Node ソースランナー	ネイティブランナーアセット	説明
Windows x64	🟢	🟢	公開済みで、マトリックスの実行対象プラットフォームです
Linux x64 / arm64	🟢	🟢	3.0.0 から公開されています
macOS Intel / Apple Silicon	🟢	🟢	3.0.0 から公開されており、アドホック署名済みです

凡例： 🟢 サポート対象 · 🟡 予定、または記載されたランタイムが必要 · 🔴 非対応。

要件、各記述の根拠、バージョンマトリックスの実行方法については、docs/reference.md をご覧ください。

セットアップ

1. プラグインをインストールする — 最新リリース（またはModrinth）から VitaminMCP.jar をダウンロードし、plugins/ に入れてサーバーを起動します。

2. MCP サーバーを AI クライアントに追加する — サーバー上ではなく、お使いのマシン上で実行されます。

Claude Code

claude mcp add vitaminmcp -- npx -y vitaminmcp

Claude Desktop、Cursor、または JSON MCP 設定に対応したクライアント：

{
  "mcpServers": {
    "vitaminmcp": {
      "command": "npx",
      "args": ["-y", "vitaminmcp"]
    }
  }
}

また、公式 MCP レジストリにも io.github.Backas03/vitaminmcp として登録されているため、レジストリカタログに対応したクライアントでは、そこから追加できます。

読み込んだプロジェクトごとに stdio プロセスを起動するクライアントでは、代わりにすべてのプロジェクトを1 つの共有ループバックサーバーに接続できます。Windows では、npx -y vitaminmcp service install を実行すると、1 つのコマンドで共有サーバーをインストールして検証できます。

3. エージェントに自動で接続設定をさせる — setup プロンプトを実行するよう依頼します（Claude Code では /mcp__vitaminmcp__setup）。実行中のサーバーを検出し、プラグインを確認して接続します。

このマシン上のサーバーであれば、これで十分です。Claude Code プラグイン（テストスキルも含みます）、その他のクライアント、jar ファイルからのインストール、config.yml のデフォルト設定、ボットのセットアップ、SSH または TLS の背後にあるサーバーへの接続については、INSTALL.md をご覧ください。

インストールと使用方法の詳細なドキュメント：backas03.github.io/VitaminMCP — 各ツール、シナリオの実行、複数サーバーのセッション、リモートサーバーのセットアップについては、docs/usage.md で説明しています。

コントリビューションとビルド

コントリビューションのルールは CONTRIBUTING.md、ソースからのビルドは docs/reference.md、リリース手順は docs/publishing.md に記載されています。

ライセンス

MIT — LICENSE をご覧ください。jar ファイルに同梱されているサードパーティコードとそのライセンスは、docs/reference.md に記載されています。