fabricator-panel-mcp

fabricator-panel-mcp

ベータ版です。 まだ開発初期段階のため、リリース間でクライアントの設定方法が変わる場合があります。

Fabricator Minecraft パネル用の MCP サーバーです。 お使いのマシン上で MCP クライアントの隣で動作し、パネルの Settings にある Model Context Protocol で発行した API トークンを使って、HTTP API 経由でパネルと通信します。

このサーバーは、modpack サーバーがクラッシュする原因を調べるという、ひとつの目的に特化しています。ログを読み、インストール済みのものを確認し、Modrinth で mod を調べ、削除または更新して、再起動します。

このパッケージはセキュリティ境界ではありません。 トークンで可能な操作は、サーバー側でパネルがトークンに対して決定し、適用します。ここで提供するツールセットは、厳選されたものです。トークンがアクセスできる範囲より狭く、両者の違いを明確に示します。

MCP クライアントを接続する

この設定を MCP クライアントの設定に貼り付けてください。Fabricator の Settings → Model Context Protocol でトークンを作成します。

{
  "mcpServers": {
    "fabricator": {
      "command": "uvx",
      "args": ["fabricator-panel-mcp"],
      "env": {
        "FABRICATOR_URL": "http://YOUR-PANEL:5000",
        "FABRICATOR_TOKEN": "YOUR_API_TOKEN"
      }
    }
  }
}

要件

• このマシンからアクセスでき、Settings → Model Context Protocol で MCP アクセスが有効になっているパネル。
• API トークン。read が推奨されるデフォルトです。変更操作は一切できません。アシスタントが操作を実行できるようにする場合に限り、manage を使用してください。
• uv がインストールされ、PATH に設定されていること。 これが唯一の必須要件であり、どの MCP クライアントにも同梱されていません。uv がないと、クライアントには Fabricator サーバーが 起動に失敗している、または起動時に切断している と表示されます。プロセスが起動しないため、パネルやトークンの問題ではなく、サーバーが壊れているように見えます。uv をインストールすれば解決します。

アシスタントにできること

トークンのスコープによって決まり、適用するのはこのパッケージではなく パネル です。

スコープ	アクセスできる内容
read	サーバーとそのステータスの一覧表示 · コンソール出力とクラッシュログの読み取り · インストール済み mod の一覧表示・特定と互換性のある更新の監査 · Modrinth プロジェクトの互換性の一括確認 · Modrinth の正確なバージョンの確認と modpack の検索（カタログのみ） · CPU とメモリの使用状況 · サーバー固有の Java／ランタイムとインストールの診断 · ローダーと Minecraft バージョンの検出 · バックアップの対象範囲、スケジュール、スナップショットのメタデータ · Modrinth の検索
manage	上記すべてに加え、サーバーの起動／停止／再起動 · 保存済み設定を使ったサーバーインストールの開始または再試行 · Modrinth プロジェクト ID による mod のインストールまたは更新 · インストール済み mod の jar ファイルの削除

read がドキュメントで定められたデフォルトです。 あらゆる診断上の質問に答えられ、サーバー上のものを変更することはできません。

スコープにかかわらず、パネルの多くの機能はすべてのトークンで拒否されます。コンソール、ファイルの読み書き、サーバー設定、サーバーの作成や削除、Java のインストール、アップデーター、バックアップの作成とスナップショットの復元、ワールドのインポート、プレイヤーリストを含むすべてのプレイヤー管理が対象です。読み取り専用のバックアップおよびスナップショットのメタデータツールは、アーカイブのパスやファイルを公開しません。これらの拒否はパネル側で行われ、このパッケージはツールを隠さず、そのまま表示します。

既知の制限：サブフォルダー内の mod

サーバーの mods フォルダーの直下にある jar ファイルのみが一覧表示され、削除できるのもそれらに限られます。サブフォルダー内の jar ファイルは一覧に表示されず、remove_mods では削除できません。代わりにパネルの UI から管理してください。ツールは不明瞭なエラーを返すのではなく、この制限を明示します。

セキュリティに関する注意事項

• サーバーログには、MODやプレイヤーが書き込んだテキストが含まれます。 サーバーコンソールに出力できるもの（MOD、プレイヤーのチャットメッセージ、ニックネーム、MOTD）はすべて、アシスタントが読み取る内容に含まれます。manage トークンを使うと、アシスタントはそこで読み取った内容に基づいて操作できます。変更もできるようにしたい場合を除き、read トークンを優先してください。
• トークンはMCPクライアントの設定ファイルにプレーンテキストで保存されます。 このファイルはパスワードと同じように扱ってください。読み取れる人なら誰でもトークンを使用できます。
• トークンに有効期限はありません。使わなくなったトークンは、同じ設定パネルから無効にしてください。
• パネルでMCPアクセスをオフにすると、トークンを削除しなくても、既存のトークンはすぐに使えなくなります。

設定

MCPクライアントが起動するプロセスに設定する環境変数は2つです。

変数	必須	デフォルト	意味
FABRICATOR_URL	いいえ	http://127.0.0.1:5000	パネルのベースURL
FABRICATOR_TOKEN	はい	—	パネルの設定にあるAPIトークン

トークンがコマンドラインから読み取られることはありません。argv はマシン上のすべてのプロセスから参照でき、シェルの履歴にも残ります。一方、起動したプロセスの環境変数はどちらにも該当しません。

開発

このパッケージは依存関係が独立した環境です。独自の pyproject.toml、独自のロックファイル、独自のインタープリター指定を持ち、パネルとは完全に分離して解決・実行されます。パネルの requirements.txt は関与せず、変更もされません。

cd mcp
uv sync                 # create .venv from uv.lock, provisioning CPython 3.11
uv run pytest           # run this package's suite

CIや、記録された環境を正確に再現したい場合：

cd mcp
uv sync --frozen        # fails if uv.lock has drifted from pyproject.toml
uv run pytest -q

依存関係を変更したときだけ手順が変わります。2つのファイルは必ず一緒にコミットしてください。

cd mcp
uv add "mcp>=1.28"
git add pyproject.toml uv.lock

コミットする手順書は pyproject.toml + uv.lock + .python-version です。 手順書がコミットされていない環境は、使い捨ての作業場所です。無関係な作業のついでにロックファイルを再生成しないでください。

パネルのテストスイートからの分離

このテストスイートとパネルのテストスイートが互いに干渉しないよう、4つの仕組みで独立性を保っています。

1. 依存関係の解決を分離 — この pyproject.toml + uv.lock を使用し、パネルは requirements.txt を使用します。互いを参照することはありません。
2. 環境を分離 — mcp/.venv を使用します。パネルの環境には mcp/httpx がなく、こちらの環境には Flask がありません。
3. pytest の rootdir を分離 — pyproject.toml の [tool.pytest.ini_options] テーブルによって、pytest の上位ディレクトリ検索はここで止まります。そのため、mcp/ で実行してもパネルの conftest.py は読み込まれません。また、パネルの pytest.ini では testpaths = tests と norecursedirs = mcp が設定されているため、リポジトリのルートで実行してもこのディレクトリには入りません。
4. テストのワークフローを分離 — .github/workflows/mcp-tests.yml は、ロック済みとロック解除済みのジョブを mcp/ から実行します。

リポジトリのルートに [tool.uv.workspace] を追加しないでください。 ワークスペースを追加すると、2つのロックファイルと環境が統合され、独立性が失われます。

テストのルール

• ネットワークに接続するテストは禁止です。 tests/conftest.py は自動適用されるガードを設定し、モックされていないリクエストを失敗するテストにします。httpx.MockTransport を使ってクライアントを動作させてください。
• ツールとルートの対応関係はデータテーブルで管理し、テストでは、それがパネルでトークンに許可されているルートの一部であることを検証します。パネル側の分類が変わった場合、このテストは意図的に失敗します。

ライセンス

Fabricator リポジトリから継承した AGPL-3.0-only。