fabricator-panel-mcp

fabricator-panel-mcp

**Beta 版。**仍处于早期阶段，客户端的配置方式可能会随版本发布而变化。

适用于 Fabricator Minecraft 面板的 MCP 服务。它 运行在你自己的机器上，与 MCP 客户端并列，并使用你在面板的设置中的 Model Context Protocol 下生成的 API 令牌，通过 HTTP API 与面板通信。

它专为一项任务打造：查明整合包服务器崩溃的原因。读取日志、查看已安装内容、在 Modrinth 上检查模组、 移除或更新模组，然后重启。

**此软件包不构成安全边界。**令牌能够执行哪些操作，由面板在服务器端针对该令牌决定并强制执行。 此处的工具集是一层筛选：它的范围比令牌可访问的范围更窄，并且会如实说明两者的区别。

连接 MCP 客户端

将以下内容粘贴到 MCP 客户端配置中。在 Fabricator 的设置 → Model Context Protocol 中 创建令牌。

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

要求

• 可从此机器访问的面板，并且已在设置 → Model Context Protocol 中启用 MCP 访问。
• 一个 API 令牌。建议默认使用 read——它无法更改任何内容。只有在希望助手能够执行操作时，才使用 manage。
• 已安装 uv，且位于 PATH 中。这是唯一的硬性前置条件，并非任何 MCP 客户端自带。 如果缺少 uv，客户端会报告 Fabricator 服务启动失败或在启动时断开连接——看起来像是服务损坏，而不是面板或令牌有问题，因为进程根本没有启动。 安装 uv 即可解决此问题。

助手可以做什么

具体能力由令牌的作用范围决定，并由面板强制执行——而非此软件包。

作用范围	可访问内容
read	列出服务器及其状态 · 读取控制台输出和崩溃日志 · 列出／识别已安装的模组并检查其兼容更新 · 批量检查 Modrinth 项目的兼容性 · 查看确切的 Modrinth 版本并搜索整合包（仅目录） · 查看 CPU 和内存使用情况 · 查看特定服务器的 Java／运行时和安装诊断信息 · 查找加载器和 Minecraft 版本 · 查看备份覆盖范围、计划和快照元数据 · 搜索 Modrinth
manage	包含以上所有内容，另可：启动／停止／重启服务器 · 使用已保存的配置启动或重试服务器安装 · 按 Modrinth 项目 ID 安装或更新单个模组 · 删除已安装的模组 JAR 文件

**文档中建议默认使用 read。**它可以回答所有诊断问题，并且无法更改服务器上的任何内容。

无论作用范围如何，面板都会拒绝所有令牌访问很大一部分功能：控制台、文件读写、服务器设置、创建或删除服务器、安装 Java、更新程序、创建备份和恢复快照、导入世界，以及包括玩家列表在内的所有玩家管理功能。只读的备份和快照元数据工具不会公开存档路径或文件。这些拒绝由面板执行，此软件包会如实呈现相关信息，而不会隐藏这些工具。

已知限制：子文件夹中的模组

只会列出直接位于服务器 mods 文件夹中的 JAR 文件，也只能移除这些文件。子文件夹中的 JAR 文件不会显示在列表中，且无法通过 remove_mods 删除——请改用面板 UI 管理。工具会明确说明这一点，而不会含糊地失败。

安全说明

• 服务器日志包含模组和玩家写入的文本。 任何可以向服务器控制台输出内容的来源——模组、玩家的聊天消息、昵称、MOTD——都会出现在助手读取的内容中。manage 令牌允许助手根据读取到的内容采取行动。除非你明确希望它能够更改内容，否则请优先使用 read 令牌。
• 令牌以纯文本形式保存在 MCP 客户端的配置文件中。 请像对待密码一样保护该文件：任何能读取它的人都能使用令牌。
• 令牌不会过期。请在同一 Settings 面板中撤销不再使用的令牌。
• 在面板中关闭 MCP 访问权限后，现有令牌会立即停止工作，但不会被删除。

配置

由 MCP 客户端为其启动的进程设置的两个环境变量：

变量	必填	默认值	含义
FABRICATOR_URL	否	http://127.0.0.1:5000	面板的基础 URL
FABRICATOR_TOKEN	是	—	面板 Settings 中的 API 令牌

绝不会从命令行读取令牌。机器上的每个进程都能看到 argv，且它会被写入 shell 历史记录；而被启动进程的环境变量则不会。

开发

该软件包是一个依赖隔离区：它有自己的 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

只有更改依赖项才会改变配置方案，且这两个文件会一并提交：

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

已提交的配置方案由 pyproject.toml + uv.lock + .python-version 组成。 没有已提交配置方案的工作目录只是临时草稿；不要因无关的工作而重新生成锁文件。

与面板测试套件隔离

以下四种独立机制确保此测试套件与面板的测试套件互不干扰：

1. 独立的依赖解析 — 使用此处的 pyproject.toml + uv.lock；面板使用 requirements.txt。两者互不引用。
2. 独立的环境 — mcp/.venv。面板的环境中没有 mcp/httpx；此环境中没有 Flask。
3. 独立的 pytest 根目录 — 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]。 工作区会合并两个锁文件和环境，从而破坏隔离区。

测试规则

• 测试不得访问网络。 tests/conftest.py 会安装一个自动使用的保护机制，将未经模拟的请求变成失败的测试。请使用 httpx.MockTransport 驱动客户端。
• 工具到路由的映射是一个数据表，测试会断言该表是面板允许令牌访问的路由集合的子集。如果面板的分类发生变化，该测试会按预期失败。

许可证

AGPL-3.0-only，继承自 Fabricator 仓库。