feat(mcp): add diagnostics tools

Author: philderks

backend/auth/buckets.py

@@ -22,6 +22,7 @@
     ("GET", "/api/servers/<server_id>/logs"),
     ("GET", "/api/servers/<server_id>/mods"),
     ("GET", "/api/servers/<server_id>/install/progress"),
+    ("GET", "/api/servers/<server_id>/java-status"),
     ("GET", "/api/servers/<server_id>/metrics"),
     ("GET", "/api/metrics/system"),
     ("GET", "/api/java/status"),

backend/server/routes.py

@@ -498,6 +498,13 @@ def get_server_details(server_id, server):
     return jsonify(_augment_with_runtime(server))
 
 
+@server_bp.route('/servers/<server_id>/java-status', methods=['GET'])
+@require_server
+def get_server_java_status(server_id, server):
+    """Report the effective runtime and Java compatibility for one server."""
+    return jsonify(_server_java_check_payload(server))
+
+
 @server_bp.route('/servers/<server_id>/logs', methods=['GET'])
 def get_server_logs(server_id):
     # type=int yields None on unparseable input, so fall back explicitly rather

mcp/README.md

@@ -62,7 +62,7 @@ The token's scope decides this, and the **panel** enforces it — not this packa
 
 | Scope | What it reaches |
 |---|---|
-| `read` | List servers and their status · read console output and crash logs · list installed mods and identify them against Modrinth by file hash · CPU and memory use · Java version checks · loader and Minecraft-version discovery · install progress and failure reasons · backup coverage and snapshot metadata · search Modrinth and check whether a mod has a build for your Minecraft version and loader |
+| `read` | List servers and their status · read console output and crash logs · list/identify installed mods and audit their compatible updates · batch-check Modrinth project compatibility · inspect exact Modrinth versions and search modpacks (catalog only) · CPU and memory use · server-specific Java/runtime and install diagnostics · loader and Minecraft-version discovery · backup coverage, schedules, and snapshot metadata · search Modrinth |
 | `manage` | Everything above, plus: start / stop / restart a server · start or retry server installation using its saved configuration · install or update one mod by Modrinth project id · delete installed mod jars |
 
 **`read` is the documented default.** It answers every diagnostic question and cannot change

mcp/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fabricator-mcp"
-version = "0.2.0"
+version = "0.3.0"
 description = "MCP server for the Fabricator Minecraft panel"
 readme = "README.md"
 requires-python = ">=3.11"

mcp/src/fabricator_mcp/__init__.py

@@ -8,4 +8,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"

mcp/src/fabricator_mcp/_panel_routes.py

@@ -17,7 +17,7 @@
 from __future__ import annotations
 
 #: Date of the last human re-audit of this snapshot.
-PANEL_TABLE_REVISION = "2026-08-06"
+PANEL_TABLE_REVISION = "2026-08-19"
 
 PANEL_READ: frozenset[tuple[str, str]] = frozenset({
     ("GET", "/api/auth/status"),
@@ -48,6 +48,7 @@
     ("GET", "/api/servers/<server_id>/backup-configs"),
     ("GET", "/api/servers/<server_id>/backup-summary"),
     ("GET", "/api/servers/<server_id>/install/progress"),
+    ("GET", "/api/servers/<server_id>/java-status"),
     ("GET", "/api/servers/<server_id>/logs"),
     ("GET", "/api/servers/<server_id>/metrics"),
     ("GET", "/api/servers/<server_id>/mods"),

mcp/src/fabricator_mcp/routes.py

@@ -56,6 +56,20 @@
     "get_install_progress": (
         ("GET", "/api/servers/<server_id>/install/progress"),
     ),
+    "search_modpacks": (("GET", "/api/modrinth/modpacks/search"),),
+    "get_mod_version": (("GET", "/api/modrinth/version/<version_id>"),),
+    "check_installed_mod_updates": (
+        ("GET", "/api/servers/<server_id>"),
+        ("GET", "/api/servers/<server_id>/mods"),
+        ("GET", "/api/modrinth/servers/<server_id>/resolve-installed"),
+        ("GET", "/api/modrinth/project/<project_id>/resolve-version"),
+    ),
+    "check_mods_compatibility": (("GET", "/api/modrinth/project/<project_id>/resolve-version"),),
+    "get_server_runtime_diagnostics": (
+        ("GET", "/api/servers/<server_id>/java-status"),
+        ("GET", "/api/servers/<server_id>/install/progress"),
+    ),
+    "list_backup_configs": (("GET", "/api/servers/<server_id>/backup-configs"),),
     "check_panel": (
         ("GET", "/api/health"),
         ("GET", "/api/auth/status"),
@@ -101,6 +115,12 @@
     "get_backup_status": READ,
     "list_snapshots": READ,
     "get_install_progress": READ,
+    "search_modpacks": READ,
+    "get_mod_version": READ,
+    "check_installed_mod_updates": READ,
+    "check_mods_compatibility": READ,
+    "get_server_runtime_diagnostics": READ,
+    "list_backup_configs": READ,
     "check_panel": READ,
     "search_modrinth": READ,
     "get_mod_info": READ,

mcp/src/fabricator_mcp/server.py

@@ -134,6 +134,36 @@ async def check_mod_compatibility(
         server as configured.
         """
         return await read_tools.check_mod_compatibility(client, project_id, mc_version, loader)
+    @server.tool()
+    async def search_modpacks(query: str, mc_version: str | None = None, loader: str | None = None, limit: int = 10) -> dict[str, Any]:
+        """Search Modrinth modpacks. Installing a modpack remains panel-UI only."""
+        return await read_tools.search_modpacks(client, query, mc_version, loader, limit)
+
+    @server.tool()
+    async def get_mod_version(version_id: str) -> dict[str, Any]:
+        """Inspect one exact Modrinth version before choosing an update."""
+        return await read_tools.get_mod_version(client, version_id)
+
+    @server.tool()
+    async def check_installed_mod_updates(server_id: str) -> dict[str, Any]:
+        """Find compatible updates for identified installed mods; reports at most 25."""
+        return await read_tools.check_installed_mod_updates(client, server_id)
+
+    @server.tool()
+    async def check_mods_compatibility(project_ids: list[str], mc_version: str, loader: str | None = None) -> dict[str, Any]:
+        """Batch-check up to 25 Modrinth projects for a target loader and Minecraft version."""
+        return await read_tools.check_mods_compatibility(client, project_ids, mc_version, loader)
+
+    @server.tool()
+    async def get_server_runtime_diagnostics(server_id: str) -> dict[str, Any]:
+        """Show this server's effective Java compatibility and current install progress."""
+        return await read_tools.get_server_runtime_diagnostics(client, server_id)
+
+    @server.tool()
+    async def list_backup_configs(server_id: str) -> dict[str, Any]:
+        """List backup schedules and retention without exposing storage paths or mutation."""
+        return await read_tools.list_backup_configs(client, server_id)
+
 
 
 def register_manage_tools(server, client: PanelClient) -> None:

mcp/src/fabricator_mcp/tools/read.py

@@ -214,6 +214,67 @@ async def get_install_progress(client: PanelClient, server_id: str) -> dict[str,
     })
 
 
+async def search_modpacks(client: PanelClient, query: str, mc_version: str | None = None, loader: str | None = None, limit: int = DEFAULT_SEARCH_LIMIT) -> dict[str, Any]:
+    """Search the catalog only; installing modpacks remains intentionally unavailable."""
+    if not isinstance(query, str) or not query.strip():
+        raise ValueError("query is required")
+    payload = await client.get("/api/modrinth/modpacks/search", params={"query": query.strip()[:128], "mc_version": mc_version, "loader": loader, "limit": clamp(limit, 1, 50, DEFAULT_SEARCH_LIMIT)})
+    hits = payload.get("hits") if isinstance(payload, dict) else []
+    hits = hits if isinstance(hits, list) else []
+    return {"results": [drop_empty({"projectId": h.get("project_id"), "slug": h.get("slug"), "title": h.get("title"), "description": h.get("description"), "downloads": h.get("downloads")}) for h in hits if isinstance(h, dict)]}
+
+
+async def get_mod_version(client: PanelClient, version_id: str) -> dict[str, Any]:
+    version_id = _require(version_id, "version_id")
+    payload = await client.get(f"/api/modrinth/version/{version_id}")
+    payload = payload if isinstance(payload, dict) else {}
+    return drop_empty({"versionId": payload.get("id"), "projectId": payload.get("project_id"), "versionNumber": payload.get("version_number"), "gameVersions": payload.get("game_versions"), "loaders": payload.get("loaders"), "name": payload.get("name")})
+
+
+async def check_mods_compatibility(client: PanelClient, project_ids: list[str], mc_version: str, loader: str | None = None) -> dict[str, Any]:
+    if not isinstance(project_ids, list) or not project_ids:
+        raise ValueError("project_ids is required")
+    if not isinstance(mc_version, str) or not mc_version.strip():
+        raise ValueError("mc_version is required")
+    results = []
+    for project_id in project_ids[:25]:
+        project_id = _require(project_id, "project_id")
+        result = await check_mod_compatibility(client, project_id, mc_version, loader)
+        results.append({"projectId": project_id, **result})
+    return {"minecraftVersion": mc_version.strip(), "loader": loader, "results": results, "truncated": len(project_ids) > 25}
+
+
+async def check_installed_mod_updates(client: PanelClient, server_id: str) -> dict[str, Any]:
+    server_id = _require(server_id, "server_id")
+    server = await client.get(f"/api/servers/{server_id}")
+    server = server if isinstance(server, dict) else {}
+    listing = await list_installed_mods(client, server_id, identify=True)
+    version, loader = server.get("version"), server.get("loader")
+    results = []
+    for mod in listing.get("mods", [])[:25]:
+        project_id = mod.get("projectId") if isinstance(mod, dict) else None
+        if not project_id or not version:
+            continue
+        compatible = await check_mod_compatibility(client, project_id, version, loader)
+        target = compatible.get("versionId")
+        results.append(drop_empty({"name": mod.get("name"), "projectId": project_id, "currentVersionId": mod.get("versionId"), "currentVersionNumber": mod.get("versionNumber"), "targetVersionId": target, "targetVersionNumber": compatible.get("versionNumber"), "updateAvailable": bool(target and target != mod.get("versionId")), "compatible": compatible.get("compatible")}))
+    return {"minecraftVersion": version, "loader": loader, "updates": results, "identified": listing.get("identified", False), "truncated": len(listing.get("mods", [])) > 25}
+
+
+async def get_server_runtime_diagnostics(client: PanelClient, server_id: str) -> dict[str, Any]:
+    server_id = _require(server_id, "server_id")
+    java, install = await client.get(f"/api/servers/{server_id}/java-status"), await client.get(f"/api/servers/{server_id}/install/progress")
+    java, install = (java if isinstance(java, dict) else {}), (install if isinstance(install, dict) else {})
+    return drop_empty({"requiredMajor": java.get("required_java"), "detectedMajor": java.get("detected_java"), "meetsRequirement": java.get("meets_requirement"), "enforcementSkipped": java.get("java_enforcement_skipped"), "install": drop_empty({"active": install.get("active"), "phase": install.get("phase"), "error": install.get("error"), "updatedAt": install.get("updated_at")})})
+
+
+async def list_backup_configs(client: PanelClient, server_id: str) -> dict[str, Any]:
+    server_id = _require(server_id, "server_id")
+    payload = await client.get(f"/api/servers/{server_id}/backup-configs")
+    configs = payload if isinstance(payload, list) else []
+    return {"configs": [drop_empty({"id": c.get("id"), "name": c.get("name"), "enabled": c.get("enabled"), "schedule": c.get("schedule"), "retention": c.get("retention"), "nextRunTime": c.get("next_run_time")}) for c in configs if isinstance(c, dict)]}
+
+
 #: What the panel reports when it has no release marker to read — a source
 #: checkout has no .fabricator_version, only a built release does.
 _UNKNOWN_VERSION = "unknown"

mcp/tests/test_tool_routes.py

@@ -72,4 +72,4 @@ def test_the_tool_set_is_narrower_than_the_ceiling():
     """Curation, stated as a fact: tools use a strict subset of the permitted routes."""
     used = {route for routes in TOOL_ROUTES.values() for route in routes}
     assert used < PANEL_TOKEN_REACHABLE
-    assert len(TOOL_ROUTES) == 19
+    assert len(TOOL_ROUTES) == 25