Metadata-Version: 2.4
Name: factorio-ai-tools
Version: 1.1.1
Summary: A lightning-fast, hybrid-search Vector Database and Model Context Protocol (MCP) server for Factorio modding.
Author: solarcloud7
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp[cli]>=1.1.2
Requires-Dist: lancedb>=0.17.0
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: pyarrow>=15.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: hf-transfer>=0.1.0
Requires-Dist: tree-sitter-lua>=0.2.0
Requires-Dist: torch>=2.12.1
Requires-Dist: sentence-transformers>=5.6.0
Dynamic: license-file

<div align="center">
  <img src="docs/assets/factorio-ai-tools.png" alt="Factorio AI Tools Icon" width="200"/>
  <br/>
  <a href="https://pypi.org/project/factorio-ai-tools/"><img src="https://img.shields.io/pypi/v/factorio-ai-tools" alt="PyPI - Version"/></a>
  <a href="https://github.com/solarcloud7/factorio-ai-tools/releases"><img src="https://img.shields.io/github/v/release/solarcloud7/factorio-ai-tools" alt="GitHub Release"/></a>
</div>

# 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`):
```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.
```json
{
  "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:

```powershell
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`:
```json
      "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:
   ```powershell
   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:

```powershell
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):

```powershell
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.
