fabric-docs-mcp

An MCP server that exposes version-pinned Fabric modding documentation to LLM coding agents. Its goal is to stop agents from writing non-idiomatic code by giving them the actual current Fabric docs, scoped to the exact Minecraft version you develop on.

• Search + read the official Fabric docs (prose tutorials, code includes resolved into the pages).
• Version-pinned: docs are indexed per Minecraft version, so an agent pinned to 26.1.2 won't pull 26.1 or 1.21 guidance.
• Built-ins index: a curated per-category checklist of extension points and idiomatic patterns, so the model checks for the existing path (e.g. vanilla's Oxidizable interface) before reinventing it.

No decompilation, no mappings, no obfuscated-source scraping. Surface level only.

License note: the docs come from FabricMC/fabric-docs, licensed CC BY-NC-SA 4.0 (NonCommercial). This tool reads them from a local clone at runtime and does not redistribute them. See NOTICE.

Requirements

• uv
• git
• A working clone of the Fabric docs repo (see setup below)

Quick start

# 1. install/enter the project
cd fabric-docs-mcp
uv sync --extra dev

# 2. clone the docs and pick a Minecraft version (one-time)
uv run fabric-docs-mcp setup

# 3. run the server over stdio (or configure it in your MCP client)
uv run fabric-docs-mcp serve

setup is interactive: it asks where to clone the Fabric docs (default: under your user config dir), clones it if needed, and asks which Minecraft version to target. It writes a config file, so serve works with no flags afterwards.

Switching Minecraft versions

uv run fabric-docs-mcp switch --version 26.2

switch validates that the version exists in the docs clone, updates the config, and reminds you to git pull in the docs repo to fetch the latest docs.

Config precedence

Settings resolve in this order (highest wins):

1. CLI flags (serve --repo-dir X --version Y)
2. Environment variables (FABRIC_DOCS_DIR, FABRIC_DOCS_VERSION)
3. The config file written by setup
4. Built-in defaults

The config file lives in your user config directory (e.g. ~/.config/fabric-docs-mcp/config.json or %APPDATA%\fabric-docs-mcp\config.json) — never in the project, so the tool doesn't assume a fixed repo layout and nothing machine-specific is committed.

Refreshing docs

cd /path/to/your/fabric-docs-clone && git pull

Then restart the server. New pages are picked up on next start.

Tools & resources

Kind	Name	Purpose
Tool	search_docs	BM25 search over the pinned version's docs, returns ranked hits with snippets
Tool	get_doc	Full markdown of a page by slug
Tool	list_pages	List pages, optional category filter
Tool	list_categories	Doc categories with page counts
Tool	get_builtins	Curated built-ins / idiom checklist (per category)
Tool	version_info	Pinned version + versions available on disk
Resource	fabric-doc://{+slug}	Full markdown of a doc page
Resource	fabric-doc://builtins	Curated built-in extension points

The version guard keeps every answer scoped to the pinned Minecraft version.

Wiring into an MCP client

Most clients use a mcpServers config with a command. With fabric-docs-mcp installed (or run via uv), example:

{
  "mcpServers": {
    "fabric-docs": {
      "command": "uv",
      "args": ["run", "fabric-docs-mcp", "serve"],
      "cwd": "<path-to-this-project>"
    }
  }
}

Development

uv sync --extra dev
uv run pytest -v          # unit + integration tests
uv run --with mypy mypy src/fabric_docs_mcp/   # type check

The integration tests spawn the real server over stdio and talk JSON-RPC to it, exactly like a real MCP client. They skip automatically if no Fabric docs clone is found (set FABRIC_DOCS_DIR to point at one). In CI, the workflow clones the docs so the integration tests actually run.

Keeping the built-ins index honest

src/fabric_docs_mcp/builtins.py is the anti-slop surface that needs the most human care. When you notice an agent reinventing something a Fabric API hook or vanilla interface already covers, add it there. Treat it as a living checklist, not a fixed file.

License

The project code is MIT. The Fabric documentation content it reads is CC BY-NC-SA 4.0 (see NOTICE).