Upload 10 files

.dockerignore

@@ -0,0 +1,21 @@
+# Don't ship dev artifacts into the HF Space image.
+.git
+.gitignore
+.venv
+venv
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+.pytest_cache
+.mypy_cache
+.ruff_cache
+.DS_Store
+*.egg-info
+build/
+dist/
+.env
+.env.local
+*.log
+tests/
+scripts/

Dockerfile

@@ -1,12 +1,49 @@
-FROM python:3.11-slim
+# Hugging Face Spaces Dockerfile for fabric-config-oracle MCP server.
+#
+# HF Spaces convention:
+#   - Listen on port 7860 (HF proxies public traffic here).
+#   - Run as non-root user `user` (uid 1000) — HF enforces this.
+#   - Use a slim Python base image to keep the layer small.
+#
+# After the Space is up, the public MCP endpoint is:
+#   https://<your-space-name>.hf.space/mcp
 
-WORKDIR /app
+FROM python:3.12-slim
 
-COPY requirements.txt .
+# Avoid Python writing .pyc files and forcing stdout/stderr to be unbuffered.
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    FASTMCP_HOST=0.0.0.0 \
+    FASTMCP_PORT=7860
+
+# Create the non-root user HF Spaces requires.
+RUN useradd --create-home --uid 1000 user
+
+WORKDIR /home/user/app
+
+# Install Python deps first (better Docker layer caching).
+# Copy just the requirements file, install as root, then drop privileges.
+COPY --chown=user:user requirements.txt ./
 RUN pip install --no-cache-dir -r requirements.txt
 
-COPY server.py .
+# Copy the rest of the source.
+COPY --chown=user:user . .
 
+# Switch to the non-root user.
+USER user
+
+# HF Spaces expects the container to listen on 7860.
 EXPOSE 7860
 
-CMD ["python", "server.py"]
+# Healthcheck — a 200 from the MCP endpoint means the server is up.
+# Streamable HTTP returns 406 to non-MCP requests, so we just check
+# that *something* responds (any HTTP status is OK; timeout means dead).
+HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=3 \
+    CMD python -c "import urllib.request, sys; \
+    try: urllib.request.urlopen('http://127.0.0.1:7860/mcp', timeout=3); \
+    except Exception: sys.exit(0); sys.exit(0)"
+
+# Run the HTTP entry point.
+CMD ["python", "app.py"]

README.md

@@ -1,9 +1,184 @@
 ---
-title: ACE-Step 1.5 API
-emoji: 🎵
-colorFrom: purple
-colorTo: pink
+title: Fabric Config Oracle MCP
+emoji: 🧵
+colorFrom: indigo
+colorTo: blue
 sdk: docker
 app_port: 7860
 pinned: false
----
+license: mit
+short_description: MCP server for Minecraft Fabric mod build configs
+tags:
+  - mcp
+  - minecraft
+  - fabric
+  - model-context-protocol
+  - fabricmc
+---
+
+# Fabric Config Oracle — MCP Server (Hugging Face Space)
+
+An MCP (Model Context Protocol) server that acts as a **Configuration Oracle**
+for AI assistants building or updating Minecraft Fabric mods. When an AI
+(like Claude or Cursor) is asked to scaffold a Fabric mod, it can query this
+server to instantly get the exact, correct dependency versions, mappings, and
+build configurations for any Minecraft version from `1.21` up to the latest
+`26.x` snapshot.
+
+This Space exposes the MCP server over the **streamable HTTP transport** so
+any MCP-compatible client on the internet can connect to it without installing
+anything locally.
+
+## Endpoint
+
+```
+https://<this-space-name>.hf.space/mcp
+```
+
+## How to connect from a client
+
+### Claude Desktop (`claude_desktop_config.json`)
+
+```json
+{
+  "mcpServers": {
+    "fabric-config-oracle": {
+      "url": "https://<this-space-name>.hf.space/mcp",
+      "type": "http"
+    }
+  }
+}
+```
+
+### Cursor (`.cursor/mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "fabric-config-oracle": {
+      "url": "https://<this-space-name>.hf.space/mcp"
+    }
+  }
+}
+```
+
+### Generic streamable HTTP client
+
+```bash
+curl -X POST https://<this-space-name>.hf.space/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 1,
+    "method": "initialize",
+    "params": {
+      "protocolVersion": "2025-06-18",
+      "capabilities": {},
+      "clientInfo": {"name": "demo", "version": "0.0.1"}
+    }
+  }'
+```
+
+## Why this exists
+
+Minecraft snapshots are released frequently by Mojang, but the Fabric
+ecosystem (Yarn mappings, Fabric API) often takes a few days to catch up. If
+an AI blindly writes a `gradle.properties` targeting the newest snapshot, the
+mod will fail to build because Yarn or Fabric API don't support that snapshot
+yet. This server is **intelligent**: when asked for `"latest"`, it walks the
+newest snapshots and only returns one that has full Fabric support, falling
+back to the newest stable release if no snapshots are ready.
+
+## Important: Mojang unobfuscation (MC 26.1+)
+
+Starting with Minecraft 26.1, Mojang ships the game jar **unobfuscated** with
+parameter names intact. This deprecates Yarn mappings for those versions —
+mods targeting MC 26.1+ should use `loom.officialMojangMappings()` in
+`build.gradle` instead of the Yarn `mappings "..."` declaration.
+
+This server is aware of that distinction:
+- For obfuscated versions (`1.21.x` and earlier): requires Yarn + Fabric API.
+- For unobfuscated versions (`26.1`+): requires only Fabric API; the
+  `yarn_mappings` field is returned empty and the `generate_gradle_properties`
+  tool omits that line entirely (with a comment explaining why).
+
+Source: <https://docs.fabricmc.net/develop/porting/mappings>
+
+## Tools
+
+### `get_optimal_fabric_config`
+
+Resolve the optimal Fabric build config for a Minecraft version.
+
+**Args:**
+- `minecraft_version` (str, default `"latest"`): target MC version or `"latest"`.
+- `mod_id` (str, optional): echoed in the response payload.
+
+**Returns:** JSON object with `minecraft_version`, `version_type`,
+`yarn_mappings`, `loader_version`, `fabric_api_version`, `loom_version`,
+`gradle_wrapper_version`, `message`, and (if provided) `mod_id`.
+
+### `generate_gradle_properties`
+
+Render a complete `gradle.properties` file from a resolved config.
+
+**Args:**
+- `mod_name` (str): human-readable mod name.
+- `mod_version` (str): mod version string.
+- `minecraft_version` (str, default `"latest"`): target MC version.
+
+**Returns:** plain-text content of `gradle.properties`, ready to write to disk.
+
+## Resources
+
+- `fabric://config/schema/gradle_properties` — static reference schema for
+  a Fabric mod's `gradle.properties` file. Documents both the Yarn (≤1.21.x)
+  and Mojmap (≥26.1) regimes.
+
+## Caching & rate limits
+
+The server caches:
+- The Mojang version manifest for 10 minutes (`MANIFEST_CACHE_TTL_SECONDS=600`).
+- Per-version Yarn mappings and Fabric API versions for the process lifetime.
+
+Upstream APIs queried:
+- `https://piston-meta.mojang.com/mc/game/version_manifest_v2.json` (Mojang)
+- `https://meta.fabricmc.net/v2/` (Fabric Meta — Yarn, Loader)
+- `https://api.modrinth.com/v2/` (Fabric API versions)
+
+On Modrinth `429 Too Many Requests`, the server backs off for 2 seconds and
+retries once.
+
+## Privacy & security
+
+This is a **fully open, public** MCP server. There is no authentication.
+Anyone with the Space URL can call the tools.
+
+The server only makes outbound requests to the three official upstream APIs
+listed above. It does not log, store, or forward caller-supplied data beyond
+the tool arguments needed to compute the response. The `mod_id` argument is
+echoed in the response payload and otherwise unused.
+
+## Cold starts
+
+HF Spaces on the free tier sleep after ~48 hours of inactivity. The first
+request after sleep takes ~30 seconds to wake the container; subsequent
+requests are fast. If you need always-on availability, upgrade the Space to a
+paid hardware tier.
+
+## Local development
+
+```bash
+# stdio mode (for local MCP clients like Claude Desktop)
+python main.py
+
+# HTTP mode (mirrors what this Space runs)
+pip install -r requirements.txt
+python app.py
+# → http://localhost:7860/mcp
+```
+
+## License
+
+MIT

app.py

@@ -0,0 +1,119 @@
+"""
+HTTP entry point for the fabric-config-oracle MCP server.
+
+This module exposes the same FastMCP server as `main.py`, but uses the
+**streamable HTTP** transport instead of stdio. It is designed to run
+behind a uvicorn ASGI server so the MCP can be hosted on platforms like
+Hugging Face Spaces, Fly.io, Railway, or any container host that exposes
+a public HTTP port.
+
+Run locally:
+    uvicorn app:asgi_app --host 0.0.0.0 --port 7860
+
+Or directly:
+    python app.py
+
+Hugging Face Spaces:
+    The Dockerfile in this repo starts `python app.py`. The Space's
+    public URL (e.g. `https://<space-name>.hf.space/mcp`) is the MCP
+    endpoint clients configure in their `mcp.json`.
+
+Security note:
+    The server is **fully open / public** by design. There is no bearer
+    token, no OAuth, no DNS-rebinding protection. Anyone with the URL
+    can call the tools. This is acceptable for a read-only oracle that
+    only queries public upstream APIs (Mojang / Fabric Meta / Modrinth).
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+
+# Make sibling modules importable when running as `python app.py`.
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from mcp.server.fastmcp import FastMCP  # noqa: E402
+from mcp.server.transport_security import TransportSecuritySettings  # noqa: E402
+
+from mcp_server import mcp as _configured_mcp  # noqa: E402
+from mcp_server import get_server  # noqa: E402
+
+
+logger = logging.getLogger("fabric-config-oracle.http")
+
+
+def build_http_app() -> "FastMCP":
+    """
+    Return a FastMCP instance configured for public HTTP hosting.
+
+    We rebuild the FastMCP server (rather than mutating the singleton
+    from `mcp_server.py`) so the stdio entry point in `main.py` keeps
+    its conservative localhost-only defaults. The HTTP variant:
+
+      * binds to 0.0.0.0 (required by HF Spaces, Fly.io, Docker)
+      * listens on port 7860 (HF Spaces convention)
+      * exposes the MCP endpoint at `/mcp` (FastMCP default)
+      * **disables DNS rebinding protection** — public hosts have
+        arbitrary Host headers by design.
+      * enables stateless HTTP mode so any client can POST a single
+        JSON-RPC request without first opening a long-lived session.
+        This is the friendliest mode for public MCP endpoints and
+        matches the official `streamable-http` examples.
+      * enables `json_response=True` so responses are returned as
+        Content-Type: application/json rather than text/event-stream.
+        Both are spec-compliant; JSON is simpler for clients that
+        don't want to parse SSE.
+    """
+    server = get_server()
+    # Re-apply settings that matter for public hosting. We mutate the
+    # existing Settings object so tools/resources registered on the
+    # module-level `mcp` singleton keep working.
+    server.settings.host = os.environ.get("FASTMCP_HOST", "0.0.0.0")
+    server.settings.port = int(os.environ.get("FASTMCP_PORT", "7860"))
+    server.settings.streamable_http_path = "/mcp"
+    server.settings.stateless_http = True
+    server.settings.json_response = True
+    server.settings.transport_security = TransportSecuritySettings(
+        enable_dns_rebinding_protection=False,
+        allowed_hosts=[],
+        allowed_origins=[],
+    )
+    return server
+
+
+# Module-level ASGI app for `uvicorn app:asgi_app` invocation.
+_http_server = build_http_app()
+asgi_app = _http_server.streamable_http_app()
+
+
+def main() -> None:
+    """Start the fabric-config-oracle MCP server over streamable HTTP."""
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+        stream=sys.stderr,
+    )
+    host = _http_server.settings.host
+    port = _http_server.settings.port
+    logger.info(
+        "Starting fabric-config-oracle MCP server (streamable HTTP) "
+        "on http://%s:%s/mcp",
+        host,
+        port,
+    )
+
+    import uvicorn
+
+    uvicorn.run(
+        asgi_app,
+        host=host,
+        port=port,
+        log_level="info",
+        access_log=False,  # MCP traffic is verbose; suppress per-request logs.
+    )
+
+
+if __name__ == "__main__":
+    main()

main.py

@@ -0,0 +1,35 @@
+"""
+Entry point for the fabric-config-oracle MCP server.
+
+Run via:
+    python main.py
+
+The server speaks MCP over stdio, which is the transport Claude Desktop,
+Cursor, and most other MCP-aware clients expect by default.
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+
+from mcp_server import get_server
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+    stream=sys.stderr,  # MCP uses stdout for protocol traffic; logs go to stderr.
+)
+logger = logging.getLogger("fabric-config-oracle")
+
+
+def main() -> None:
+    """Start the fabric-config-oracle MCP server over stdio transport."""
+    logger.info("Starting fabric-config-oracle MCP server (stdio transport)...")
+    server = get_server()
+    # `run()` blocks until the client disconnects or the process is killed.
+    server.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

mcp_server.py

@@ -0,0 +1,300 @@
+"""
+MCP server definition: registers tools and resources exposed by the
+fabric-config-oracle over stdio transport.
+
+Tools
+-----
+* `get_optimal_fabric_config` — resolve the optimal Fabric build config for a
+  specific or the latest Minecraft version, applying snapshot fallback logic.
+* `generate_gradle_properties` — render a complete `gradle.properties` file
+  text from a resolved config plus mod metadata.
+
+Resources
+---------
+* `fabric://config/schema/gradle_properties` — static reference schema for a
+  well-formed Fabric `gradle.properties` file.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Optional
+
+from mcp.server.fastmcp import FastMCP
+
+from models import FabricConfig
+from resolver import VersionResolver
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Server + shared state
+# ---------------------------------------------------------------------------
+
+mcp: FastMCP = FastMCP("fabric-config-oracle")
+
+# Module-level singleton resolver. The MCP stdio server runs in a single
+# process for its entire lifetime, so a single shared HTTP client + cache
+# is both safe and desirable (connection pooling, fewer upstream calls).
+_resolver: Optional[VersionResolver] = None
+
+
+def _get_resolver() -> VersionResolver:
+    """Lazily instantiate the shared VersionResolver."""
+    global _resolver
+    if _resolver is None:
+        _resolver = VersionResolver()
+    return _resolver
+
+
+# ---------------------------------------------------------------------------
+# Tool 1: get_optimal_fabric_config
+# ---------------------------------------------------------------------------
+
+
+@mcp.tool()
+async def get_optimal_fabric_config(
+    minecraft_version: str = "latest",
+    mod_id: Optional[str] = None,
+) -> dict:
+    """
+    Get the optimal Fabric mod configuration for a specific or the latest
+    Minecraft version.
+
+    When `minecraft_version` is "latest" (or omitted), the server applies
+    intelligent fallback logic: it walks the newest Minecraft snapshots and
+    returns the first one that has full Fabric ecosystem support.
+
+    **Support is defined differently depending on the MC version:**
+      - For OBFUSCATED versions (1.21.x and earlier): the snapshot must have
+        BOTH Yarn mappings AND a Fabric API build available.
+      - For UNOBFUSCATED versions (26.1+): only a Fabric API build is required.
+        Yarn mappings are deprecated and don't exist for these versions —
+        mods use Mojang's official Mojmap via Loom's
+        `loom.officialMojangMappings()` in build.gradle.
+
+    If no snapshots have full Fabric support yet, the server falls back to
+    the newest stable release that does.
+
+    Args:
+        minecraft_version: Target Minecraft version. Accepts:
+            - "latest" (default): apply fallback logic.
+            - Specific releases: "1.21", "1.21.4", "26.1", "26.2".
+            - Specific snapshots: "26.3 Snapshot 2".
+        mod_id: Optional mod identifier. Currently informational only —
+            included in the response payload for caller convenience but does
+            not affect resolution.
+
+    Returns:
+        A JSON object with the following fields:
+            minecraft_version     — the resolved MC version string
+            version_type          — "release" or "snapshot"
+            yarn_mappings         — Yarn build string (e.g. "1.21.4+build.8"),
+                                    OR empty string for MC 26.1+ (Yarn
+                                    deprecated; use Mojmap via Loom)
+            loader_version        — Fabric Loader version
+            fabric_api_version    — Fabric API mod version from Modrinth
+            loom_version          — Fabric Loom Gradle plugin version
+            gradle_wrapper_version — recommended Gradle wrapper version
+            message               — human-readable status message
+            mod_id                — echoed back if provided
+    """
+    resolver = _get_resolver()
+    config: FabricConfig = await resolver.resolve_config(minecraft_version)
+    payload = config.model_dump()
+    if mod_id:
+        payload["mod_id"] = mod_id
+    return payload
+
+
+# ---------------------------------------------------------------------------
+# Tool 2: generate_gradle_properties
+# ---------------------------------------------------------------------------
+
+
+@mcp.tool()
+async def generate_gradle_properties(
+    mod_name: str,
+    mod_version: str,
+    minecraft_version: str = "latest",
+) -> str:
+    """
+    Generate the exact text content of a `gradle.properties` file for a
+    Fabric mod, based on the resolved build configuration.
+
+    Internally calls `get_optimal_fabric_config` to resolve Yarn / Loader /
+    Fabric API versions, then renders a complete properties file with both
+    mod metadata and Fabric tooling versions.
+
+    Args:
+        mod_name: Human-readable mod name (e.g. "Example Mod").
+        mod_version: Mod version string (e.g. "1.0.0").
+        minecraft_version: Target MC version, default "latest".
+
+    Returns:
+        The full text content of a `gradle.properties` file, ready to be
+        written to disk by the AI assistant.
+    """
+    resolver = _get_resolver()
+    config: FabricConfig = await resolver.resolve_config(minecraft_version)
+
+    # Derive a safe mod_id from the mod name: lowercase, replace non-alnum
+    # with hyphens, collapse runs of hyphens, strip leading/trailing hyphens.
+    raw_id = "".join(c.lower() if c.isalnum() else "-" for c in mod_name)
+    while "--" in raw_id:
+        raw_id = raw_id.replace("--", "-")
+    mod_id = raw_id.strip("-") or "mod"
+
+    maven_group = f"com.example.{mod_id.replace('-', '.')}"
+    archives_base_name = mod_id
+
+    # For unobfuscated versions (26.1+), Yarn mappings are deprecated and
+    # not used — Loom reads Mojang's official Mojmap directly via
+    # `loom.officialMojangMappings()` in build.gradle. We omit the
+    # `yarn_mappings` line entirely and emit a comment explaining why.
+    from resolver import is_unobfuscated
+    unobf = is_unobfuscated(config.minecraft_version)
+
+    mc_fabric_section: list[str] = [
+        "# Minecraft & Fabric versions",
+        f"minecraft_version = {config.minecraft_version}",
+    ]
+    if unobf:
+        mc_fabric_section.append(
+            "# yarn_mappings: not used — MC 26.1+ is unobfuscated; mods"
+        )
+        mc_fabric_section.append(
+            "# use Mojang official Mojmap via loom.officialMojangMappings()"
+        )
+        mc_fabric_section.append(
+            "# in build.gradle. (See https://docs.fabricmc.net/develop/porting/mappings)"
+        )
+    else:
+        mc_fabric_section.append(f"yarn_mappings = {config.yarn_mappings}")
+    mc_fabric_section.append(f"loader_version = {config.loader_version}")
+    mc_fabric_section.append(f"fabric_version = {config.fabric_api_version}")
+
+    lines: list[str] = [
+        "# Gradle properties for Fabric mod",
+        "# Generated by fabric-config-oracle MCP server",
+        "",
+        "# Mod metadata",
+        f"mod_name = {mod_name}",
+        f"mod_id = {mod_id}",
+        f"mod_version = {mod_version}",
+        f"maven_group = {maven_group}",
+        f"archives_base_name = {archives_base_name}",
+        "",
+        *mc_fabric_section,
+        "",
+        "# Build tooling",
+        f"loom_version = {config.loom_version}",
+        f"gradle_wrapper_version = {config.gradle_wrapper_version}",
+        "",
+        "# Optional: Kotlin support (uncomment if needed)",
+        "# kotlin_code_style = official",
+        "# fabric_kotlin_version = 1.10.10+kotlin.1.9.10",
+    ]
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Resource: gradle_properties schema
+# ---------------------------------------------------------------------------
+
+
+_GRADLE_PROPERTIES_SCHEMA = """\
+# Fabric gradle.properties Schema Reference
+# =========================================
+# This document describes the expected structure of a Fabric mod's
+# gradle.properties file. All keys are case-sensitive.
+#
+# IMPORTANT: Mappings selection depends on the target Minecraft version:
+#
+#   * MC <= 1.21.11  (OBFUSCATED):   Yarn mappings are REQUIRED. The mod
+#                                    references obfuscated class names which
+#                                    Yarn translates to human-readable names.
+#                                    Loom is configured in build.gradle via
+#                                        mappings "net.fabricmc:yarn:${yarn_mappings}:v2"
+#
+#   * MC >= 26.1      (UNOBFUSCATED): Yarn mappings DO NOT EXIST and are
+#                                    NOT NEEDED. Mojang ships the jar
+#                                    unobfuscated with parameter names.
+#                                    Loom is configured in build.gradle via
+#                                        loom.officialMojangMappings()
+#                                    The `yarn_mappings` property line is
+#                                    OMITTED entirely.
+#
+# Source: https://docs.fabricmc.net/develop/porting/mappings
+
+# --- Common keys (always present) ---
+
+# mod_name: Human-readable mod name (string, any characters)
+mod_name = Example Mod
+
+# mod_id: Lowercase identifier, alphanumeric + hyphens only, max 64 chars.
+mod_id = example-mod
+
+# mod_version: SemVer-style version string for the mod itself.
+mod_version = 1.0.0
+
+# maven_group: Maven group ID for artifact publishing. Conventionally the
+#              reversed domain of the mod author.
+maven_group = com.example.examplemod
+
+# archives_base_name: Base name for built jar artifacts.
+archives_base_name = example-mod
+
+# minecraft_version: Exact MC version this mod targets (e.g. "1.21.4", "26.2").
+minecraft_version = 26.2
+
+# loader_version: Fabric Loader version. The mod's minimum compatible loader.
+loader_version = 0.16.0
+
+# fabric_version: Fabric API mod version from Modrinth. Required if the mod
+#                 depends on Fabric API; otherwise can be omitted.
+fabric_version = 0.155.2+26.2
+
+# --- Keys present ONLY for obfuscated versions (MC <= 1.21.11) ---
+
+# yarn_mappings: Yarn mappings version from meta.fabricmc.net.
+#                Format: "<mc_version>+build.<n>".
+#                OMITTED for MC 26.1+ (unobfuscated; use Mojmap instead).
+yarn_mappings = 1.21.4+build.8
+
+# --- Build tooling (always present) ---
+
+# loom_version: Fabric Loom Gradle plugin version (e.g. "1.7-SNAPSHOT").
+loom_version = 1.7-SNAPSHOT
+
+# gradle_wrapper_version: Recommended Gradle wrapper version.
+gradle_wrapper_version = 8.8
+
+# --- Optional: Kotlin ---
+# kotlin_code_style = official
+# fabric_kotlin_version = 1.10.10+kotlin.1.9.10
+"""
+
+
+@mcp.resource("fabric://config/schema/gradle_properties")
+def get_gradle_properties_schema() -> str:
+    """
+    Static reference schema for a Fabric mod `gradle.properties` file.
+
+    Reading this resource returns a plain-text document describing every
+    expected key, its purpose, and an example value. AI assistants can use
+    this to validate generated `gradle.properties` files or to learn the
+    expected structure before generating one.
+    """
+    return _GRADLE_PROPERTIES_SCHEMA
+
+
+# ---------------------------------------------------------------------------
+# Public entry point
+# ---------------------------------------------------------------------------
+
+
+def get_server() -> FastMCP:
+    """Return the configured FastMCP server instance."""
+    return mcp

models.py

@@ -0,0 +1,114 @@
+"""
+Pydantic data models for the Fabric Config Oracle MCP server.
+
+These models define the canonical shape of:
+  * A Minecraft version entry parsed from the Mojang version manifest.
+  * A fully-resolved Fabric mod build configuration.
+
+All MCP tool return values are validated against these models before being
+serialized to JSON, ensuring callers always receive well-formed payloads.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+# ---------------------------------------------------------------------------
+# Manifest-level model
+# ---------------------------------------------------------------------------
+
+
+class MinecraftVersion(BaseModel):
+    """
+    A single Minecraft version entry extracted from the Mojang manifest.
+
+    Mojang's manifest exposes every released version (stable releases, snapshots,
+    pre-releases, release candidates) along with an ISO-8601 `releaseTime`. We
+    use `releaseTime` for sorting because version strings alone are ambiguous
+    across the dual versioning schemes (legacy `1.21.x` vs year-based `26.x`).
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    id: str = Field(
+        ...,
+        description="The version identifier as published by Mojang, e.g. "
+        "'1.21.4', '26.2', or '26.3 Snapshot 2'.",
+    )
+    type: Literal["release", "snapshot"] = Field(
+        ...,
+        description="Mojang-declared type. Snapshots, pre-releases and "
+        "release candidates are all bucketed under 'snapshot' for our "
+        "fallback purposes.",
+    )
+    release_time: datetime = Field(
+        ...,
+        description="ISO-8601 timestamp at which Mojang published the version. "
+        "Used for newest-first sorting.",
+    )
+    url: Optional[str] = Field(
+        default=None,
+        description="Optional URL to the per-version manifest JSON. "
+        "Currently unused but kept for diagnostics.",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Resolved configuration model
+# ---------------------------------------------------------------------------
+
+
+class FabricConfig(BaseModel):
+    """
+    The fully-resolved Fabric mod build configuration for one Minecraft version.
+
+    This is the canonical return type of the `get_optimal_fabric_config` MCP
+    tool. Every field is populated by the `VersionResolver` after consulting
+    the Mojang manifest, Fabric Meta, and Modrinth APIs.
+    """
+
+    minecraft_version: str = Field(
+        ...,
+        description="The resolved Minecraft version string. May differ from "
+        "the requested version when the requested version was 'latest' and "
+        "the resolver had to fall back to a Fabric-supported version.",
+    )
+    version_type: Literal["release", "snapshot"] = Field(
+        ...,
+        description="Whether the resolved minecraft_version is a stable "
+        "release or a snapshot.",
+    )
+    yarn_mappings: str = Field(
+        default="",
+        description="Yarn mappings build string (e.g. '26.2+build.1'). "
+        "Empty string when no Yarn build exists for this MC version.",
+    )
+    loader_version: str = Field(
+        default="",
+        description="Fabric Loader version (e.g. '0.16.0').",
+    )
+    fabric_api_version: str = Field(
+        default="",
+        description="Fabric API mod version from Modrinth "
+        "(e.g. '0.100.0+1.21.4'). Empty when Modrinth has no compatible build.",
+    )
+    loom_version: str = Field(
+        default="1.7-SNAPSHOT",
+        description="Fabric Loom Gradle plugin version. Not currently fetched "
+        "from a remote source — a sensible default is provided and may be "
+        "overridden by the caller.",
+    )
+    gradle_wrapper_version: str = Field(
+        default="8.8",
+        description="Recommended Gradle wrapper version. Not currently fetched "
+        "from a remote source — a sensible default is provided.",
+    )
+    message: str = Field(
+        default="",
+        description="Human-readable status message describing the resolution "
+        "outcome, including any missing components.",
+    )

requirements.txt

@@ -1,9 +1,22 @@
-fastapi
-uvicorn
-pydantic
-numpy
-torch
-torchaudio
-transformers
-accelerate
-librosa
+# Fabric Config Oracle - MCP Server dependencies
+# Python 3.10+ required (HF Spaces uses 3.12)
+
+# Official Model Context Protocol Python SDK (includes FastMCP)
+mcp>=1.0.0
+
+# Async HTTP client for Mojang / Fabric Meta / Modrinth API calls
+httpx>=0.27.0
+
+# Data validation for config models
+pydantic>=2.0.0
+
+# Async compatibility layer used by the MCP SDK
+anyio>=4.0.0
+
+# ASGI server — needed for the streamable HTTP transport (`app.py`).
+# Not required for stdio transport (`main.py`).
+uvicorn>=0.30.0
+
+# Starlette is pulled in by the MCP SDK as a transitive dep, but we
+# pin a minimum for the `streamable_http_app()` ASGI surface.
+starlette>=0.37.0

resolver.py

@@ -0,0 +1,613 @@
+"""
+Version resolver: turns "latest" (or a specific version string) into a
+fully-resolved Fabric build configuration by consulting the Mojang manifest,
+Fabric Meta, and Modrinth APIs.
+
+The most subtle part of this module is the **snapshot fallback logic** in
+`VersionResolver.resolve_version`. See its docstring for the rationale.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import re
+from datetime import datetime
+from typing import Any, Optional
+
+import httpx
+
+from models import FabricConfig, MinecraftVersion
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+MOJANG_MANIFEST_URL = "https://piston-meta.mojang.com/mc/game/version_manifest_v2.json"
+FABRIC_YARN_URL = "https://meta.fabricmc.net/v2/versions/yarn/{mc_version}"
+FABRIC_LOADER_URL = "https://meta.fabricmc.net/v2/versions/loader"
+MODRINTH_FABRIC_API_URL = "https://api.modrinth.com/v2/project/fabric-api/version"
+
+# These defaults are not currently fetched from a remote source. They reflect
+# the toolchain versions that work across the MC 1.21 / 26.x range. Override
+# them on the returned FabricConfig if your project requires different values.
+DEFAULT_LOOM_VERSION = "1.7-SNAPSHOT"
+DEFAULT_GRADLE_VERSION = "8.8"
+
+# Lowest Minecraft version the oracle will consider for "latest" resolution.
+MINIMUM_MC_VERSION_ID = "1.21"
+
+# Cache TTLs
+MANIFEST_CACHE_TTL_SECONDS = 600  # 10 minutes — manifest doesn't change often
+
+# Safety caps so a runaway loop never hammers the upstream APIs.
+MAX_SNAPSHOTS_TO_PROBE = 20
+MAX_RELEASES_TO_PROBE = 10
+
+
+# ---------------------------------------------------------------------------
+# Version string parsing
+# ---------------------------------------------------------------------------
+
+
+# Match the space form "26.3 Snapshot 2" OR the dash form "26.3-snapshot-2"
+# (the dash form is what Mojang's manifest actually publishes).
+_SNAPSHOT_RE = re.compile(
+    r"^\s*(\d+)\.(\d+)(?:\.(\d+))?\s*[-\s]+[Ss]napshot\s*[-\s]*(\d+)\s*$"
+)
+# Pre-release and release candidate forms: "26.2-pre-6", "26.2-rc-1".
+# Treated as snapshots for sorting (below the corresponding release).
+_PRE_RE = re.compile(
+    r"^\s*(\d+)\.(\d+)(?:\.(\d+))?\s*[-\s]+(?:pre|rc)\s*[-\s]*(\d+)\s*$"
+)
+_RELEASE_RE = re.compile(r"^\s*(\d+)\.(\d+)(?:\.(\d+))?\s*$")
+
+# Legacy weekly-snapshot format like "23w13a", "25w46a". Used by Mojang for
+# older snapshots. We need to recognize these so we can correctly *exclude*
+# pre-1.21 ones from the "latest" candidate pool.
+_WEEKLY_SNAPSHOT_RE = re.compile(r"^\s*(\d{2})w(\d{1,2})[a-z]\s*$")
+
+
+def parse_mc_version(version_id: str) -> tuple[int, ...]:
+    """
+    Parse a Minecraft version string into a comparable tuple.
+
+    Minecraft recently switched from `1.21.x` style versioning to year-based
+    `26.x` versioning. A standard semver parser would treat `1.21.4` as
+    *newer* than `26.2` because semver would parse `1` and `26` as the major
+    version. We instead want `26.2` to be newer, because year 2026 follows
+    year 2024 (when `1.21` shipped).
+
+    The trick: keep the numeric components in tuple order. Python's tuple
+    comparison walks left-to-right, so `(26, 2, 0, ...)` > `(1, 21, 0, ...)`
+    because `26 > 1`. No special "year offset" is needed.
+
+    Snapshots are sorted *below* their corresponding release by appending a
+    type marker (`1` for snapshot, `2` for release) followed by the snapshot
+    number for snapshots. This means:
+        `26.3 Snapshot 2`  <  `26.3 Snapshot 10`  <  `26.3`  (release)
+
+    Supports three input forms (all observed in Mojang's manifest):
+        - "26.3 Snapshot 2"   (space form, user-facing)
+        - "26.3-snapshot-2"   (dash form, manifest id)
+        - "26.2-pre-6"        (dash form, pre-release)
+        - "26.2-rc-1"         (dash form, release candidate)
+
+    Returns a tuple of ints. Unparseable strings return (0,) so they always
+    sort below any real version — this is intentional, because the resolver's
+    `is_minimum_version` filter then excludes them from the "latest" pool.
+    """
+    snap = _SNAPSHOT_RE.match(version_id)
+    if snap:
+        major = int(snap.group(1))
+        minor = int(snap.group(2))
+        patch = int(snap.group(3)) if snap.group(3) else 0
+        snap_num = int(snap.group(4))
+        # type marker: 1 = snapshot (lower than release's 2)
+        return (major, minor, patch, 1, snap_num)
+
+    pre = _PRE_RE.match(version_id)
+    if pre:
+        major = int(pre.group(1))
+        minor = int(pre.group(2))
+        patch = int(pre.group(3)) if pre.group(3) else 0
+        pre_num = int(pre.group(4))
+        # Treat pre-releases as snapshots for ordering purposes.
+        return (major, minor, patch, 1, pre_num)
+
+    rel = _RELEASE_RE.match(version_id)
+    if rel:
+        major = int(rel.group(1))
+        minor = int(rel.group(2))
+        patch = int(rel.group(3)) if rel.group(3) else 0
+        # type marker: 2 = release
+        return (major, minor, patch, 2)
+
+    # Legacy weekly snapshots like "23w13a", "25w46a". Map them onto the
+    # (year, week) tuple. Year 23 == 2023, week 13. We use the same 4-tuple
+    # shape with a sentinel marker so they sort *above* 1.21 if year>=24 but
+    # below 1.21 otherwise. (24wXXa corresponds to MC 1.21 snapshots.)
+    weekly = _WEEKLY_SNAPSHOT_RE.match(version_id)
+    if weekly:
+        year_short = int(weekly.group(1))
+        week = int(weekly.group(2))
+        # Weekly snapshots sort *below* the corresponding release: use type
+        # marker 1. Major version = full year (e.g. 23 -> 2023) so 23w13a
+        # (2023) sorts below 1.21 (which is (1, 21, 0, 2)).
+        return (2000 + year_short, week, 0, 1)
+
+    # Truly unparseable: return (0,) so it sorts below everything.
+    return (0,)
+
+
+def is_minimum_version(version_id: str, minimum: str = MINIMUM_MC_VERSION_ID) -> bool:
+    """
+    True iff `version_id` >= `minimum` under our custom parser.
+
+    For minimum "1.21", this rejects:
+      - Legacy weekly snapshots from before 1.21's release (mid-2024).
+        Weekly snapshots live in a separate "epoch" (year + week) that
+        doesn't tuple-compare cleanly against `1.x` / `26.x` versions, so
+        we apply a separate cutoff: weekly snapshots at or after week 24
+        of 2024 (when 1.21 dropped) are considered "above 1.21".
+      - Truly unparseable strings (which return (0,)).
+    """
+    # Special case: legacy weekly snapshots (YYwNNa format). 1.21 was
+    # released on 2024-06-13 (ISO week 24). Snapshots at or after that
+    # point are experimental snapshots for 1.21.x+ content.
+    weekly = _WEEKLY_SNAPSHOT_RE.match(version_id)
+    if weekly:
+        year_short = int(weekly.group(1))
+        week = int(weekly.group(2))
+        return (year_short, week) >= (24, 24)
+
+    try:
+        return parse_mc_version(version_id) >= parse_mc_version(minimum)
+    except Exception:
+        return False
+
+
+# Minecraft 26.1 (released March 2026) is the first release where Mojang
+# shipped the Java jar *unobfuscated*, with parameter names and (limited)
+# Javadoc-style comments included. As a consequence, the Fabric Project
+# officially retired Yarn mappings — Yarn builds simply don't exist for
+# 26.1+. Mods targeting 26.1+ use Mojang's official mappings directly via
+# Loom's `loom.officialMojangMappings()` call in build.gradle, and the
+# `gradle.properties` file does NOT carry a `yarn_mappings` line.
+#
+# Source: https://docs.fabricmc.net/develop/porting/mappings
+#         "Minecraft 26.1 is unobfuscated and includes parameter names,
+#          so there is no need for any obfuscation mappings."
+UNOBFUSCATED_MINIMUM = "26.1"
+
+
+def is_unobfuscated(version_id: str) -> bool:
+    """
+    True iff `version_id` is an unobfuscated Minecraft release (>= 26.1).
+
+    For these versions:
+      - Yarn mappings do NOT exist on Fabric Meta and never will.
+      - The Fabric ecosystem (Yarn, Loader, Fabric API) still works — only
+        the mappings layer is replaced by Mojang's official Mojmap.
+      - Loom reads Mojmap via `loom.officialMojangMappings()` in build.gradle
+        instead of `mappings "net.fabricmc:yarn:..."`.
+
+    The resolver uses this to decide whether Yarn is a hard requirement
+    when probing for "latest" support.
+    """
+    # Weekly snapshots from 2025+ (25wXXa) are 1.21.x dev cycle, still
+    # obfuscated. Only year-based 26.1+ versions are unobfuscated.
+    if _WEEKLY_SNAPSHOT_RE.match(version_id):
+        return False
+    try:
+        return parse_mc_version(version_id) >= parse_mc_version(UNOBFUSCATED_MINIMUM)
+    except Exception:
+        return False
+
+
+# ---------------------------------------------------------------------------
+# Resolver
+# ---------------------------------------------------------------------------
+
+
+class VersionResolver:
+    """
+    Resolves the optimal Fabric configuration for a Minecraft version.
+
+    ## Snapshot fallback logic
+
+    When `target_version` is `"latest"` (or omitted), the resolver must be
+    *intelligent* about which version it picks. Minecraft snapshots are
+    released frequently by Mojang, but the Fabric ecosystem (Fabric API mod
+    for all versions; Yarn mappings only for *obfuscated* versions) often
+    lags by days. If we blindly returned the newest snapshot, the AI might
+    generate a `gradle.properties` that references Fabric API versions that
+    *do not exist yet*, and the user's mod would fail to build.
+
+    The resolver therefore:
+
+      1. Fetches the Mojang manifest and keeps only versions >= `1.21`.
+      2. Sorts them by `releaseTime` descending (newest first).
+      3. Iterates the newest snapshots, one by one. For each, it asks
+         `has_fabric_support(mc_version)`, which:
+            - For OBFUSCATED versions (1.21.x and earlier): requires BOTH
+              Yarn mappings AND a Fabric API build.
+            - For UNOBFUSCATED versions (26.1+, per Mojang's Oct 2025
+              announcement and Fabric's deprecation of Yarn): requires ONLY
+              a Fabric API build. Yarn doesn't exist for these versions
+              and is not needed — mods use Mojang's official Mojmap via
+              Loom's `loom.officialMojangMappings()`.
+         If support is confirmed, that snapshot is returned immediately.
+      4. If none of the probed snapshots have support, the resolver repeats
+         the same check against the newest stable releases.
+      5. If even releases have no support (extremely unlikely — would
+         indicate a Fabric ecosystem outage), it returns the newest release
+         as a last-resort so the tool can still produce a useful error.
+
+    Iteration is *sequential* not parallel. This is intentional: the typical
+    case is that the 1st or 2nd snapshot already has support, so we make at
+    most 2-3 API round-trips total. Parallel probing would always make N
+    round-trips and risk rate-limiting on Modrinth.
+
+    See: https://docs.fabricmc.net/develop/porting/mappings
+    """
+
+    def __init__(self, http_client: Optional[httpx.AsyncClient] = None) -> None:
+        # A shared client gives us connection pooling and HTTP/2 multiplexing.
+        self._client: httpx.AsyncClient = http_client or httpx.AsyncClient(
+            timeout=httpx.Timeout(30.0),
+            headers={"User-Agent": "fabric-config-oracle/1.0"},
+        )
+
+        # In-process caches. They live for the lifetime of the resolver
+        # (i.e. for the lifetime of the MCP server process). The manifest
+        # cache additionally has a TTL; the per-version caches do not, but
+        # they're small (one entry per probed MC version) and never grow
+        # unboundedly because we cap probes via MAX_*_TO_PROBE.
+        self._manifest_cache: Optional[dict[str, Any]] = None
+        self._manifest_cache_time: Optional[datetime] = None
+        self._loader_cache: Optional[list[dict[str, Any]]] = None
+        self._yarn_cache: dict[str, Optional[dict[str, Any]]] = {}
+        self._fabric_api_cache: dict[str, Optional[dict[str, Any]]] = {}
+
+    # -- lifecycle --------------------------------------------------------
+
+    async def aclose(self) -> None:
+        """Close the underlying HTTP client. Safe to call multiple times."""
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "VersionResolver":
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.aclose()
+
+    # -- low-level HTTP ---------------------------------------------------
+
+    async def _fetch_json(
+        self,
+        url: str,
+        params: Optional[dict[str, Any]] = None,
+    ) -> Any:
+        """
+        Fetch JSON from `url` with graceful error handling.
+
+        Returns:
+            - The parsed JSON value on success.
+            - `None` on 404 (treated as "no data available").
+            - `None` on any other error after logging.
+
+        429 (rate limited) responses trigger a single backoff-and-retry.
+        """
+        try:
+            response = await self._client.get(url, params=params)
+            response.raise_for_status()
+            return response.json()
+        except httpx.HTTPStatusError as exc:
+            status = exc.response.status_code
+            if status == 404:
+                return None
+            if status == 429:
+                logger.warning("Rate limited by %s; backing off 2s and retrying once.", url)
+                await asyncio.sleep(2.0)
+                try:
+                    retry = await self._client.get(url, params=params)
+                    retry.raise_for_status()
+                    return retry.json()
+                except Exception as retry_exc:  # noqa: BLE001
+                    logger.error("Retry of %s failed: %s", url, retry_exc)
+                    return None
+            logger.error("HTTP %d from %s: %s", status, url, exc)
+            return None
+        except (httpx.RequestError, ValueError) as exc:
+            logger.error("Error fetching %s: %s", url, exc)
+            return None
+
+    # -- API wrappers -----------------------------------------------------
+
+    async def fetch_mojang_manifest(self) -> list[MinecraftVersion]:
+        """Fetch and parse the Mojang manifest, filtered to versions >= 1.21."""
+        now = datetime.now()
+        if (
+            self._manifest_cache is not None
+            and self._manifest_cache_time is not None
+            and (now - self._manifest_cache_time).total_seconds() < MANIFEST_CACHE_TTL_SECONDS
+        ):
+            return self._parse_manifest(self._manifest_cache)
+
+        data = await self._fetch_json(MOJANG_MANIFEST_URL)
+        if data is None:
+            if self._manifest_cache is not None:
+                logger.warning("Mojang manifest fetch failed; using stale cache.")
+                return self._parse_manifest(self._manifest_cache)
+            logger.error("Mojang manifest unavailable and no cache to fall back on.")
+            return []
+
+        self._manifest_cache = data
+        self._manifest_cache_time = now
+        return self._parse_manifest(data)
+
+    def _parse_manifest(self, data: dict[str, Any]) -> list[MinecraftVersion]:
+        """Parse raw manifest JSON into a list of MinecraftVersion objects."""
+        out: list[MinecraftVersion] = []
+        for v in data.get("versions", []):
+            vid = v.get("id", "")
+            vtype = v.get("type", "")
+            # Only release/snapshot types are relevant to us. Mojang also
+            # exposes 'old_beta' / 'old_alpha' which we deliberately skip.
+            if vtype not in ("release", "snapshot"):
+                continue
+            if not is_minimum_version(vid):
+                continue
+            try:
+                rt_raw = v["releaseTime"]
+                rt = datetime.fromisoformat(rt_raw.replace("Z", "+00:00"))
+            except (KeyError, ValueError):
+                continue
+            out.append(
+                MinecraftVersion(
+                    id=vid,
+                    type=vtype,  # type: ignore[arg-type]
+                    release_time=rt,
+                    url=v.get("url"),
+                )
+            )
+        return out
+
+    async def fetch_yarn(self, mc_version: str) -> Optional[dict[str, Any]]:
+        """Fetch the newest Yarn mappings build for `mc_version`, or None."""
+        if mc_version in self._yarn_cache:
+            return self._yarn_cache[mc_version]
+
+        data = await self._fetch_json(FABRIC_YARN_URL.format(mc_version=mc_version))
+        if not isinstance(data, list) or len(data) == 0:
+            self._yarn_cache[mc_version] = None
+            return None
+
+        # Fabric Meta returns Yarn builds newest-first, but sort defensively.
+        data.sort(key=lambda y: y.get("build", 0), reverse=True)
+        yarn = data[0]
+        self._yarn_cache[mc_version] = yarn
+        return yarn
+
+    async def fetch_loader(self) -> Optional[dict[str, Any]]:
+        """Fetch the newest stable Fabric Loader version."""
+        if self._loader_cache is not None:
+            return self._loader_cache[0] if self._loader_cache else None
+
+        data = await self._fetch_json(FABRIC_LOADER_URL)
+        if not isinstance(data, list) or len(data) == 0:
+            return None
+
+        self._loader_cache = data
+        # First entry is the latest stable loader per Fabric Meta convention.
+        return data[0]
+
+    async def fetch_fabric_api(self, mc_version: str) -> Optional[dict[str, Any]]:
+        """Fetch the newest Fabric API mod build for `mc_version` from Modrinth."""
+        if mc_version in self._fabric_api_cache:
+            return self._fabric_api_cache[mc_version]
+
+        # Modrinth expects JSON-encoded array query params, e.g.
+        #   ?game_versions=["1.21.4"]&loaders=["fabric"]
+        params = {
+            "game_versions": f'["{mc_version}"]',
+            "loaders": '["fabric"]',
+        }
+        data = await self._fetch_json(MODRINTH_FABRIC_API_URL, params=params)
+        if not isinstance(data, list) or len(data) == 0:
+            self._fabric_api_cache[mc_version] = None
+            return None
+
+        data.sort(key=lambda v: v.get("date_published", ""), reverse=True)
+        fabric_api = data[0]
+        self._fabric_api_cache[mc_version] = fabric_api
+        return fabric_api
+
+    async def has_fabric_support(self, mc_version: str) -> bool:
+        """
+        True iff `mc_version` has the Fabric dependencies required to build
+        a working mod.
+
+        ## Unobfuscated versions (26.1+)
+
+        As of Minecraft 26.1 (March 2026), Mojang ships Java jars
+        unobfuscated, so Yarn mappings are deprecated and no longer
+        published. Mods targeting 26.1+ use Mojang's official Mojmap
+        directly via Loom's `loom.officialMojangMappings()`. For these
+        versions, the only Fabric dependency we need to verify is Fabric
+        API on Modrinth.
+
+        ## Obfuscated versions (<= 1.21.11)
+
+        For these, BOTH Yarn AND Fabric API must exist, since a mod
+        referencing obfuscated class names cannot compile without Yarn
+        (or another mapping set) to translate them.
+
+        See: https://docs.fabricmc.net/develop/porting/mappings
+        """
+        if is_unobfuscated(mc_version):
+            # Only Fabric API required; Yarn doesn't exist for 26.1+.
+            fabric_api = await self.fetch_fabric_api(mc_version)
+            return fabric_api is not None
+
+        # Obfuscated path: Yarn + Fabric API both required.
+        yarn, fabric_api = await asyncio.gather(
+            self.fetch_yarn(mc_version),
+            self.fetch_fabric_api(mc_version),
+        )
+        return yarn is not None and fabric_api is not None
+
+    # -- resolution -------------------------------------------------------
+
+    async def resolve_version(
+        self,
+        target_version: str = "latest",
+    ) -> Optional[MinecraftVersion]:
+        """
+        Resolve a target Minecraft version, applying fallback logic for "latest".
+
+        See the `VersionResolver` class docstring for the full snapshot
+        fallback rationale.
+
+        Args:
+            target_version: Either "latest" (default) or a specific version
+                string like "1.21.4", "26.2", or "26.3 Snapshot 2".
+
+        Returns:
+            A `MinecraftVersion` if resolution succeeded, else `None`.
+
+        For specific (non-"latest") requests, the version is looked up in the
+        manifest without a support check. If it isn't in the manifest, `None`
+        is returned and the caller may still attempt to fetch dependencies for
+        it — the per-API wrappers will return empty results gracefully.
+        """
+        versions = await self.fetch_mojang_manifest()
+        if not versions:
+            return None
+
+        # Direct (specific-version) request — no fallback logic.
+        if target_version and target_version.lower() != "latest":
+            for v in versions:
+                if v.id == target_version:
+                    return v
+            # Case-insensitive fallback (some users mistype casing).
+            for v in versions:
+                if v.id.lower() == target_version.lower():
+                    return v
+            # Not in manifest. Return None so the caller can still try to
+            # fetch dependencies directly — Fabric Meta / Modrinth might
+            # know about it even if Mojang's manifest hasn't updated yet.
+            return None
+
+        # "latest" — apply snapshot-first, release-fallback resolution.
+        versions_sorted = sorted(versions, key=lambda v: v.release_time, reverse=True)
+
+        # Step 3: probe newest snapshots.
+        snapshots = [v for v in versions_sorted if v.type == "snapshot"]
+        for snap in snapshots[:MAX_SNAPSHOTS_TO_PROBE]:
+            if await self.has_fabric_support(snap.id):
+                return snap
+
+        # Step 4: fall back to newest stable releases.
+        releases = [v for v in versions_sorted if v.type == "release"]
+        for rel in releases[:MAX_RELEASES_TO_PROBE]:
+            if await self.has_fabric_support(rel.id):
+                return rel
+
+        # Step 5: last resort — return the newest release even without
+        # confirmed support, so we can surface a meaningful error message
+        # via FabricConfig.message.
+        return releases[0] if releases else (snapshots[0] if snapshots else None)
+
+    async def resolve_config(self, target_version: str = "latest") -> FabricConfig:
+        """
+        Resolve the full Fabric configuration for a target MC version.
+
+        This is the high-level entry point used by the MCP tool. It first
+        resolves the version (applying fallback logic if "latest"), then
+        fetches Yarn, Loader, and Fabric API versions concurrently.
+
+        The returned `FabricConfig.message` field always describes the
+        outcome — success, partial success, or failure — in human-readable
+        form so the AI caller can react accordingly.
+        """
+        mc_version = await self.resolve_version(target_version)
+        if mc_version is None:
+            return FabricConfig(
+                minecraft_version=target_version,
+                version_type="release",
+                yarn_mappings="",
+                loader_version="",
+                fabric_api_version="",
+                loom_version=DEFAULT_LOOM_VERSION,
+                gradle_wrapper_version=DEFAULT_GRADLE_VERSION,
+                message=(
+                    f"Could not resolve Minecraft version '{target_version}'. "
+                    "It may not exist in the Mojang manifest, or the manifest "
+                    "could not be fetched."
+                ),
+            )
+
+        # For unobfuscated versions (26.1+), Yarn does not exist and is not
+        # needed — mods use Mojang's official Mojmap directly via Loom. Skip
+        # the Yarn fetch entirely to avoid a wasted 404 round-trip.
+        unobf = is_unobfuscated(mc_version.id)
+
+        if unobf:
+            loader, fabric_api = await asyncio.gather(
+                self.fetch_loader(),
+                self.fetch_fabric_api(mc_version.id),
+            )
+            yarn = None
+        else:
+            yarn, loader, fabric_api = await asyncio.gather(
+                self.fetch_yarn(mc_version.id),
+                self.fetch_loader(),
+                self.fetch_fabric_api(mc_version.id),
+            )
+
+        yarn_version = (yarn or {}).get("version", "")
+        loader_version = (loader or {}).get("version", "")
+        # Modrinth's `version_number` is the human-facing string
+        # (e.g. "0.100.0+1.21.4"). `id` is the URL-safe UUID.
+        fabric_api_version = (fabric_api or {}).get("version_number", "")
+
+        # Build the missing-deps list. For unobfuscated versions, Yarn is
+        # intentionally absent — it's not "missing", it's deprecated.
+        missing: list[str] = []
+        if not unobf and not yarn_version:
+            missing.append("Yarn mappings")
+        if not loader_version:
+            missing.append("Fabric Loader")
+        if not fabric_api_version:
+            missing.append("Fabric API")
+
+        if missing:
+            message = (
+                f"Configuration partially resolved for MC {mc_version.id}. "
+                f"Missing: {', '.join(missing)}."
+            )
+        elif unobf:
+            message = (
+                f"Configuration resolved successfully for MC {mc_version.id}. "
+                "Yarn mappings are not required (Minecraft 26.1+ ships "
+                "unobfuscated; mods use Mojang official Mojmap via Loom's "
+                "`loom.officialMojangMappings()` in build.gradle)."
+            )
+        else:
+            message = "Configuration resolved successfully."
+
+        return FabricConfig(
+            minecraft_version=mc_version.id,
+            version_type=mc_version.type,
+            yarn_mappings=yarn_version,
+            loader_version=loader_version,
+            fabric_api_version=fabric_api_version,
+            loom_version=DEFAULT_LOOM_VERSION,
+            gradle_wrapper_version=DEFAULT_GRADLE_VERSION,
+            message=message,
+        )

smoke_test_http.py

@@ -0,0 +1,313 @@
+"""
+End-to-end smoke test for the streamable HTTP deployment of the
+fabric-config-oracle MCP server.
+
+What it does:
+  1. Starts `app.py` as a background subprocess on port 7860.
+  2. Waits for the server to come up (polls /mcp).
+  3. Issues a real JSON-RPC sequence over HTTP:
+       initialize  → tools/list → tools/call (both tools) → resources/list → resources/read
+  4. Asserts that every step returns the expected shape.
+  5. Tears down the subprocess.
+
+This proves the HF Space deployment will actually work when clients
+connect to https://<space>.hf.space/mcp.
+
+Run:
+    python scripts/smoke_test_http.py
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import signal
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+import httpx
+
+# --- Configuration -------------------------------------------------------
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+APP_DIR = PROJECT_ROOT / "fabric_config_mcp"
+HOST = "127.0.0.1"
+PORT = 7860
+BASE_URL = f"http://{HOST}:{PORT}"
+MCP_URL = f"{BASE_URL}/mcp"
+VENV_PYTHON = PROJECT_ROOT / ".venv" / "bin" / "python"
+
+# --- Helpers -------------------------------------------------------------
+
+
+def wait_for_server(timeout: float = 30.0) -> bool:
+    """Poll the MCP endpoint until it responds (any HTTP status counts)."""
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        try:
+            r = httpx.post(
+                MCP_URL,
+                json={
+                    "jsonrpc": "2.0",
+                    "id": 0,
+                    "method": "initialize",
+                    "params": {
+                        "protocolVersion": "2025-06-18",
+                        "capabilities": {},
+                        "clientInfo": {"name": "smoke-test", "version": "0.0.1"},
+                    },
+                },
+                headers={
+                    "Content-Type": "application/json",
+                    "Accept": "application/json, text/event-stream",
+                },
+                timeout=3.0,
+            )
+            # Any HTTP response means the server is up.
+            return r.status_code in (200, 406, 400)
+        except Exception:
+            time.sleep(0.5)
+    return False
+
+
+def parse_response(r: httpx.Response) -> dict:
+    """
+    The server may return either:
+      - application/json  → the JSON-RPC envelope directly
+      - text/event-stream → a single `data: {...}` line containing the envelope
+    Parse both.
+    """
+    ct = r.headers.get("content-type", "")
+    if "application/json" in ct:
+        return r.json()
+    if "text/event-stream" in ct:
+        # Read all lines, pick the first `data:` line that parses as JSON.
+        for line in r.text.splitlines():
+            line = line.strip()
+            if line.startswith("data:"):
+                payload = line[len("data:"):].strip()
+                try:
+                    return json.loads(payload)
+                except json.JSONDecodeError:
+                    continue
+        raise RuntimeError(f"SSE response had no parseable data: line. Body: {r.text!r}")
+    raise RuntimeError(f"Unexpected content-type {ct!r}. Body: {r.text!r}")
+
+
+def mcp_call(client: httpx.Client, method: str, params: dict | None = None, req_id: int = 1) -> dict:
+    """Send a single JSON-RPC request and return the parsed result envelope."""
+    payload: dict = {"jsonrpc": "2.0", "id": req_id, "method": method}
+    if params is not None:
+        payload["params"] = params
+    r = client.post(
+        MCP_URL,
+        json=payload,
+        headers={
+            "Content-Type": "application/json",
+            "Accept": "application/json, text/event-stream",
+        },
+        timeout=60.0,  # first call hits upstream APIs; give it room
+    )
+    assert r.status_code == 200, f"HTTP {r.status_code} for {method}: {r.text}"
+    return parse_response(r)
+
+
+def ok(env: dict, label: str) -> dict:
+    """Assert JSON-RPC success and return the `result` object."""
+    assert "error" not in env, f"{label} returned JSON-RPC error: {env.get('error')}"
+    assert "result" in env, f"{label} missing `result`: {env}"
+    print(f"  [OK] {label}")
+    return env["result"]
+
+
+# --- Main test -----------------------------------------------------------
+
+
+def main() -> int:
+    print("=" * 70)
+    print("fabric-config-oracle — streamable HTTP smoke test")
+    print("=" * 70)
+
+    # 1. Start server
+    print(f"\n[1/6] Starting app.py on {BASE_URL} ...")
+    env = os.environ.copy()
+    env["FASTMCP_HOST"] = HOST
+    env["FASTMCP_PORT"] = str(PORT)
+    env["PYTHONPATH"] = str(APP_DIR)
+    proc = subprocess.Popen(
+        [str(VENV_PYTHON), "app.py"],
+        cwd=str(APP_DIR),
+        env=env,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+    )
+    try:
+        if not wait_for_server():
+            # Server didn't come up — dump its output for debugging.
+            out = proc.stdout.read().decode(errors="replace") if proc.stdout else ""
+            print("ERROR: server did not start. Output:")
+            print(out)
+            return 1
+        print("  [OK] server is up")
+
+        with httpx.Client(base_url=BASE_URL) as client:
+            # 2. initialize
+            print("\n[2/6] Sending initialize ...")
+            init_result = ok(
+                mcp_call(
+                    client,
+                    "initialize",
+                    {
+                        "protocolVersion": "2025-06-18",
+                        "capabilities": {},
+                        "clientInfo": {"name": "smoke-test", "version": "0.0.1"},
+                    },
+                    req_id=1,
+                ),
+                "initialize",
+            )
+            server_info = init_result.get("serverInfo", {})
+            print(f"        server name: {server_info.get('name')!r}")
+            print(f"        protocol:    {init_result.get('protocolVersion')}")
+
+            # Send initialized notification (no response expected, but spec requires it)
+            client.post(
+                MCP_URL,
+                json={"jsonrpc": "2.0", "method": "notifications/initialized"},
+                headers={
+                    "Content-Type": "application/json",
+                    "Accept": "application/json, text/event-stream",
+                },
+                timeout=10.0,
+            )
+
+            # 3. tools/list
+            print("\n[3/6] Listing tools ...")
+            tools_result = ok(mcp_call(client, "tools/list", {}, req_id=2), "tools/list")
+            tool_names = sorted(t["name"] for t in tools_result.get("tools", []))
+            print(f"        tools: {tool_names}")
+            assert "get_optimal_fabric_config" in tool_names, "missing tool: get_optimal_fabric_config"
+            assert "generate_gradle_properties" in tool_names, "missing tool: generate_gradle_properties"
+
+            # 4. tools/call — get_optimal_fabric_config (latest)
+            print("\n[4/6] Calling get_optimal_fabric_config(version='latest') ...")
+            cfg_result = ok(
+                mcp_call(
+                    client,
+                    "tools/call",
+                    {
+                        "name": "get_optimal_fabric_config",
+                        "arguments": {"minecraft_version": "latest", "mod_id": "smoke-test"},
+                    },
+                    req_id=3,
+                ),
+                "tools/call(get_optimal_fabric_config, latest)",
+            )
+            # The result.content is a list of content blocks; the JSON payload
+            # is in the first text block.
+            text_blocks = [c for c in cfg_result.get("content", []) if c.get("type") == "text"]
+            assert text_blocks, f"no text content in result: {cfg_result}"
+            cfg_payload = json.loads(text_blocks[0]["text"])
+            print(f"        minecraft_version:   {cfg_payload.get('minecraft_version')}")
+            print(f"        version_type:         {cfg_payload.get('version_type')}")
+            print(f"        yarn_mappings:        {cfg_payload.get('yarn_mappings')!r}")
+            print(f"        loader_version:       {cfg_payload.get('loader_version')}")
+            print(f"        fabric_api_version:   {cfg_payload.get('fabric_api_version')}")
+            print(f"        loom_version:         {cfg_payload.get('loom_version')}")
+            print(f"        message:              {cfg_payload.get('message')[:80]}...")
+            assert cfg_payload.get("minecraft_version"), "minecraft_version missing"
+            assert cfg_payload.get("loader_version"), "loader_version missing"
+            assert cfg_payload.get("fabric_api_version"), "fabric_api_version missing"
+            assert cfg_payload.get("mod_id") == "smoke-test", "mod_id not echoed"
+
+            # 5. tools/call — get_optimal_fabric_config (1.21.4, obfuscated)
+            print("\n[5/6] Calling get_optimal_fabric_config(version='1.21.4') (obfuscated) ...")
+            cfg2_result = ok(
+                mcp_call(
+                    client,
+                    "tools/call",
+                    {
+                        "name": "get_optimal_fabric_config",
+                        "arguments": {"minecraft_version": "1.21.4"},
+                    },
+                    req_id=4,
+                ),
+                "tools/call(get_optimal_fabric_config, 1.21.4)",
+            )
+            text_blocks = [c for c in cfg2_result.get("content", []) if c.get("type") == "text"]
+            cfg2 = json.loads(text_blocks[0]["text"])
+            print(f"        minecraft_version:   {cfg2.get('minecraft_version')}")
+            print(f"        yarn_mappings:        {cfg2.get('yarn_mappings')}")
+            assert cfg2.get("yarn_mappings"), "1.21.4 should have Yarn mappings!"
+
+            # 6. tools/call — generate_gradle_properties
+            print("\n[6/6] Calling generate_gradle_properties(mod_name='Demo Mod', mod_version='1.0.0', minecraft_version='latest') ...")
+            grad_result = ok(
+                mcp_call(
+                    client,
+                    "tools/call",
+                    {
+                        "name": "generate_gradle_properties",
+                        "arguments": {
+                            "mod_name": "Demo Mod",
+                            "mod_version": "1.0.0",
+                            "minecraft_version": "latest",
+                        },
+                    },
+                    req_id=5,
+                ),
+                "tools/call(generate_gradle_properties)",
+            )
+            text_blocks = [c for c in grad_result.get("content", []) if c.get("type") == "text"]
+            grad_text = text_blocks[0]["text"]
+            print("        --- gradle.properties (first 30 lines) ---")
+            for line in grad_text.splitlines()[:30]:
+                print(f"        | {line}")
+            print("        ---")
+            assert "minecraft_version" in grad_text
+            assert "loader_version" in grad_text
+            assert "fabric_version" in grad_text
+            assert "loom_version" in grad_text
+
+            # 7. resources/list + resources/read (bonus)
+            print("\n[bonus] Reading fabric://config/schema/gradle_properties resource ...")
+            list_result = ok(mcp_call(client, "resources/list", {}, req_id=6), "resources/list")
+            uris = [r.get("uri") for r in list_result.get("resources", [])]
+            print(f"        resource URIs: {uris}")
+            assert "fabric://config/schema/gradle_properties" in uris
+
+            read_result = ok(
+                mcp_call(
+                    client,
+                    "resources/read",
+                    {"uri": "fabric://config/schema/gradle_properties"},
+                    req_id=7,
+                ),
+                "resources/read",
+            )
+            text_blocks = [c for c in read_result.get("contents", []) if "text" in c]
+            schema_text = text_blocks[0]["text"] if text_blocks else ""
+            print(f"        schema length: {len(schema_text)} chars")
+            assert "yarn_mappings" in schema_text
+            assert "Mojmap" in schema_text or "Mojang" in schema_text
+
+        print("\n" + "=" * 70)
+        print("ALL SMOKE TESTS PASSED")
+        print("=" * 70)
+        return 0
+    finally:
+        # Tear down: send SIGTERM, then SIGKILL if it doesn't die in 5s.
+        print("\n[cleanup] shutting down server subprocess ...")
+        proc.send_signal(signal.SIGTERM)
+        try:
+            proc.wait(timeout=5.0)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+            proc.wait()
+        print("  [OK] server stopped")
+
+
+if __name__ == "__main__":
+    sys.exit(main())