factorio-ai-tools 1.1.1

A lightning-fast, hybrid-search Vector Database and Model Context Protocol (MCP) server for Factorio modding.

Factorio AI Tools (MCP Server)

A lightning-fast, hybrid-search Vector Database and Model Context Protocol (MCP) server designed to give LLMs absolute expertise over Factorio modding and Clusterio plugin development.

Architecture

This project consists of 4 main components:

1. Factorio Docs Ingestion (ingest_factorio.py): Scrapes the official Lua API documentation and Data Phase Prototypes across multiple versions (e.g. 1.1.110 and latest).
2. Clusterio Codebase Ingestion (ingest_clusterio.py): Uses AST (Abstract Syntax Tree) parsing to semantically chunk the massive Node.js/TypeScript Clusterio plugin architecture.
3. Factorio Wiki Ingestion (ingest_wiki.py): Scrapes the official Factorio Wiki via the MediaWiki API, exclusively extracting English wikitext for gameplay mechanics, ratios, and formulas.
4. GitHub Mod Ingestion (ingest_github_mod.py): A generalized pipeline that clones, AST-parses (via tree-sitter-lua), and incrementally hashes any GitHub Mod codebase (e.g., Maraxsis) into a semantic mod_lancedb index.
5. FastMCP Server (server.py): The bridge that connects the underlying LanceDB vector databases to an LLM via the standard Model Context Protocol.

Setup & Usage

There are two primary ways to install and use this MCP server locally with Claude Desktop (or any other MCP client):

Method 1: Using uvx (Recommended)

If you have uv installed, this is the cleanest way to run the server. It will automatically download the package from PyPI and fetch the necessary vector databases on the first run. Add the following to your Claude Desktop config (%APPDATA%\Claude\claude_desktop_config.json or ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "factorio-ai-tools": {
      "command": "uvx",
      "args": ["factorio-ai-tools"]
    }
  }
}

Method 2: Docker (Pre-packaged Datasets)

If you have Docker Desktop installed, you can simply pull the pre-packaged container natively. The Docker container includes the databases inside the image, so no additional downloads are required at runtime.

{
  "mcpServers": {
    "factorio-ai-tools": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/solarcloud7/factorio-ai-tools:latest"]
    }
    }
  }
}

Method 3: Global SSE Server (Save RAM/VRAM)

By default, standard stdio MCP execution spawns a completely separate Python process for every single client connection. Because this server uses PyTorch and sentence-transformers, every connection will load the embedding model again, consuming roughly ~500MB of RAM/VRAM per instance.

If you want to use the MCP server across multiple IDEs or workspaces simultaneously without duplicating memory, you can run a single global HTTP SSE server in the background:

uv run factorio-ai-tools --sse --port 8000

Then, configure your IDE or Claude client to connect to the SSE endpoint (e.g., http://localhost:8000/sse) instead of executing the CLI via stdio.

Selective Tool Loading (Optional)

By default, the server loads all available tools. If you only want to expose specific tools to your LLM, you can use the --enable-tools or --disable-tools arguments. For example, to only load the doc search and the blueprint decoder using uvx:

      "command": "uvx",
      "args": [
        "factorio-ai-tools",
        "--enable-tools", "search_factorio_docs,decode_factorio_blueprint"
      ]

---

Manual Developer Setup

If you wish to run the python scripts manually or ingest custom codebases:

1. Create a python virtual environment: python -m venv venv and activate it.
2. Run pip install -r requirements.txt.
3. (Optional) Run the ingestion scripts (python -m factorio_ai_tools.ingest.ingest_factorio, etc.) to rebuild the LanceDB tables.
4. (Optional) Ingest a specific GitHub Mod:

   python -m factorio_ai_tools.ingest.ingest_github_mod --repo-url https://github.com/notnotmelon/maraxsis
   

Maintenance (Database Hygiene)

LanceDB is append-only: every ingest run adds new immutable versions and small data fragments, and nothing is garbage-collected automatically. Re-running an ingest script grows the on-disk history (e.g. factorio_lancedb had 155 versions / 469 files before its first compaction). To keep the committed stores lean:

python maintenance/compact_lancedb.py          # compact + prune every data/*_lancedb store
python maintenance/compact_lancedb.py --check   # read-only; exits non-zero if a store is uncompacted

This runs LanceDB's Table.optimize() on each store — compacting fragments, pruning old versions, and folding new rows into existing indices. Do not run it while the server or an ingest script is writing.

Recommended workflow: let the version history accumulate on feature branches so a PR diff shows exactly what data changed, then run the compaction script before merging to main so the committed history stays collapsed.

To enforce that automatically, opt into the bundled pre-push guard (it blocks pushes to main while any store is uncompacted):

git config core.hooksPath maintenance/hooks
# or copy maintenance/hooks/pre-push into .git/hooks/

Tools Included

• search_factorio_docs: Look up Lua Runtime API methods, concepts, events, and Data Phase prototypes. Supports version filtering (1.1.110 vs latest).

• search_clusterio_code: Semantically search the Clusterio Node.js architecture.

• search_factorio_wiki: Access game mechanics, ratios, and fluid mechanics straight from the Wiki.

• search_mod_code: Semantically search through specific downloaded GitHub mods (e.g., maraxsis) to read their Lua codebase.

• decode_factorio_blueprint: Convert Factorio blueprint strings (e.g. 0eNq...) into easily readable/editable JSON.

• encode_factorio_blueprint: Compress generated JSON back into an importable Factorio blueprint string.

• factorio_mod_portal_analyzer: Scrape and summarize the Factorio Mod Portal for any given mod to retrieve dependencies and release versions.

• get_mcp_version_info: Self-diagnostics tool to verify the currently loaded database versions.