# fabric-docs-mcp

An [MCP](https://modelcontextprotocol.io) 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](https://github.com/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](NOTICE).

## Requirements

- [uv](https://docs.astral.sh/uv/)
- [git](https://git-scm.com/)
- A working clone of the Fabric docs repo (see `setup` below)

## Quick start

```bash
# 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

```bash
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

```bash
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:

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

## Development

```bash
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](NOTICE)).