unity-manual-mcp: Instructions file for Codex

AGENTS.md

Guidance for agents (and humans) working in this repo.

What this is

A local stdio MCP server that serves a local Unity documentation install — the en folder from a Unity editor's Data\Documentation — as MCP tools. Two content trees:

• Manual/ — how-to articles, organized in chapters (~3.5k pages)
• ScriptReference/ — full scripting API reference (~42k pages)

It extracts article text (Mozilla-Readability-style: boilerplate stripped, code examples preserved) and keeps a SQLite full-text index in the OS temp dir so repeated starts are instant.

Layout

• core.py — all the logic, no MCP knowledge: docs-root resolution, HTML extraction, IndexStore (SQLite index build/cache/search), and the cache manifest (CACHE_ROOT, manifest.json, stale/orphaned helpers). Depends only on beautifulsoup4 + lxml.
• server.py — thin FastMCP stdio wrapper: the 4 read-only tools, the argparse CLI (--selftest, --rebuild, --prune), and the _selftest runner. mcp = FastMCP(...) is at module level; main() sets the global _store before mcp.run(transport="stdio").
• pyproject.toml + uv.lock — uv project ([tool.uv] package = false; no build step). Deps: fastmcp>=3,<4, beautifulsoup4, lxml; requires-python = ">=3.10".

Keep the split: anything that can run without MCP belongs in core.py. server.py should stay a thin wrapper.

Running

It's a uv project: .venv is the env, managed by uv sync / uv run.

# one-time index build + sample queries, then exit (no server); ~12 min on a fresh cache
uv run server.py --selftest "C:\Program Files\Unity\Hub\Editor\<ver>\Editor\Data\Documentation\en"

# the MCP server itself (stdio; MCP clients spawn this via `uv run --directory <repo> server.py`)
uv run server.py "C:\...\Editor\Data\Documentation\en"

# drop stale manifest entries (db file missing) and exit
uv run server.py --prune

The docs path may be the en folder, or a wrapper (Documentation or Editor\Data) — core.resolve_docs_root auto-discovers the en folder. It can also come from the UNITY_DOCS_PATH env var.