factorio-ai-tools 1.1.1__tar.gz

factorio_ai_tools-1.1.1/.agents/AGENTS.md

@@ -0,0 +1,11 @@
+## Python Windows Terminal Printing
+When writing Python scripts that scrape the web or process LLM responses, NEVER directly `print()` raw dynamic strings. Windows PowerShell default encodings will throw a fatal `UnicodeEncodeError` when encountering characters like en-dashes or emojis.
+*Fix:* Always encode/decode before printing:
+```python
+print(text.encode('ascii', 'replace').decode('ascii'))
+```
+
+## Comprehensive Git Commits
+When tasked with committing and pushing code to a repository, NEVER assume you have tracked all necessary files based on memory. 
+- Before confirming to the user that "all changes have been pushed", you MUST run `git status` to explicitly verify that no unexpectedly modified or untracked files were left behind in the working directory.
+- Ensure that you either use `git add .` (if safe) or meticulously stage every modified file related to the current task before committing.

factorio_ai_tools-1.1.1/.gitattributes

@@ -0,0 +1,32 @@
+# Make line endings deterministic across machines, editors, and CI, so the
+# repository stops drifting between CRLF and LF (and Git stops warning that
+# "LF will be replaced by CRLF"). This file is authoritative and overrides
+# each developer's personal `core.autocrlf` setting for this project.
+
+# Default: let Git auto-detect text vs binary. Text is stored as LF in the repo.
+* text=auto
+
+# Source and config: enforce LF in the working tree too (not just in the repo),
+# so the checked-out files always match what is committed. The repo is already
+# all-LF, so this introduces no content churn.
+*.py            text eol=lf
+*.md            text eol=lf
+*.txt           text eol=lf
+*.yaml          text eol=lf
+*.yml           text eol=lf
+*.cfg           text eol=lf
+*.toml          text eol=lf
+*.json          text eol=lf
+*.sh            text eol=lf
+.gitignore      text eol=lf
+.gitattributes  text eol=lf
+
+# Git hooks are run by sh and must keep LF endings (no file extension, so the
+# rules above don't catch them); CRLF would break them on Windows checkout.
+maintenance/hooks/*  text eol=lf
+
+# Pre-built LanceDB vector stores are binary data — never apply line-ending
+# (or any) conversion. These rules come last so they win over the patterns
+# above for any text-looking files (hint .json, version.txt) inside the stores.
+data/*_lancedb/**    binary
+*.lance              binary

factorio_ai_tools-1.1.1/.github/release-drafter.yml

@@ -0,0 +1,28 @@
+name-template: 'v$NEXT_PATCH_VERSION'
+tag-template: 'v$NEXT_PATCH_VERSION'
+categories:
+  - title: '🚀 Features'
+    labels:
+      - 'feature'
+      - 'enhancement'
+  - title: '🐛 Bug Fixes'
+    labels:
+      - 'fix'
+      - 'bug'
+  - title: '📊 Dataset Updates'
+    labels:
+      - 'dataset'
+      - 'data'
+  - title: '🧰 Maintenance'
+    labels:
+      - 'chore'
+      - 'refactor'
+      - 'dependencies'
+change-template: '- $TITLE @$AUTHOR (#$NUMBER)'
+template: |
+  ## Changes
+  
+  $CHANGES
+  
+  ---
+  *Automated release generated by Release Drafter.*

factorio_ai_tools-1.1.1/.github/workflows/docker-publish.yml

@@ -0,0 +1,46 @@
+name: Build and Publish Docker (GHCR)
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  build-and-push-image:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Log in to the Container registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata (tags, labels) for Docker
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=raw,value=latest,enable={{is_default_branch}}
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

factorio_ai_tools-1.1.1/.github/workflows/publish-databases.yml

@@ -0,0 +1,27 @@
+name: Publish Databases to GitHub Release
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  publish-databases:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Zip LanceDB folders
+        run: |
+          cd data
+          zip -r ../factorio_lancedb.zip factorio_lancedb/ clusterio_lancedb/ wiki_lancedb/ mod_lancedb/ forum_lancedb/
+
+      - name: Upload databases zip to Release
+        uses: softprops/action-gh-release@v2
+        if: github.event_name == 'release'
+        with:
+          files: factorio_lancedb.zip

factorio_ai_tools-1.1.1/.github/workflows/pypi-publish.yml

@@ -0,0 +1,27 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  publish-pypi:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # IMPORTANT: mandatory for trusted publishing
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install build tool
+        run: pip install build
+      - name: Build package
+        run: python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

factorio_ai_tools-1.1.1/.github/workflows/release-drafter.yml

@@ -0,0 +1,22 @@
+name: Release Drafter
+
+on:
+  push:
+    branches:
+      - main
+  # pull_request event is required only for autolabeler
+  pull_request:
+    types: [opened, reopened, synchronize]
+
+permissions:
+  contents: write
+
+jobs:
+  update_release_draft:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: release-drafter/release-drafter@v6
+        with:
+          config-name: release-drafter.yml
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

factorio_ai_tools-1.1.1/.gitignore

@@ -0,0 +1,15 @@
+venv/
+.mod_temp/
+__pycache__/
+.claude/
+*.pyc
+.env
+
+# Build Artifacts
+build/
+dist/
+*.egg-info/
+
+# Local Data
+data/
+.venv/

factorio_ai_tools-1.1.1/CLAUDE.md

@@ -0,0 +1,74 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+A hybrid-search RAG system and FastMCP server that gives LLMs expert knowledge of Factorio modding and Clusterio plugin development. Five ingestion scripts scrape/parse external sources into local LanceDB vector stores; `server.py` exposes those stores to MCP clients (Claude Desktop, etc.) as search tools.
+
+## Commands
+
+```powershell
+# One-time setup
+python -m venv venv
+.\venv\Scripts\Activate.ps1
+pip install -r requirements.txt
+
+# Build/refresh the vector databases (each is idempotent — safe to re-run).
+# Scripts live in ingest/; every store is written under data/.
+python ingest/ingest_factorio.py      # -> data/factorio_lancedb  (Lua API + prototype docs, multiple versions)
+python ingest/ingest_clusterio.py     # -> data/clusterio_lancedb (set CLUSTERIO_REPO; defaults to ./clusterio)
+python ingest/ingest_wiki.py          # -> data/wiki_lancedb      (full Factorio wiki via MediaWiki API)
+python ingest/ingest_forum.py         # -> data/forum_lancedb     (curated topics from forum_links.txt)
+python ingest/ingest_github_mod.py --repo-url https://github.com/notnotmelon/maraxsis   # -> data/mod_lancedb
+
+# Compact/prune all data/*_lancedb stores (collapses LanceDB version history).
+# Run before merging data changes to main; --check is a read-only guard.
+python maintenance/compact_lancedb.py
+python maintenance/compact_lancedb.py --check
+
+# Run the MCP server (stdio transport)
+python server.py
+```
+
+There is no test suite, linter, or build step beyond the above. `smithery.yaml` defines the Smithery deployment (build = pip install + the three core ingest scripts; run = `python server.py`).
+
+To test a tool manually, import `server.py` in a REPL — the `@mcp.tool()` functions are plain callables. Note that importing `server.py` eagerly loads the SentenceTransformer model and opens all five LanceDB connections.
+
+## Architecture
+
+**Ingestion → LanceDB → MCP server.** Every database is built offline by an ingest script and queried at runtime by the server. The two halves only share the embedding model and the on-disk store; they never call each other.
+
+**Shared embedding contract (must stay consistent across all scripts and the server):**
+- Model: `BAAI/bge-base-en-v1.5`, overridable via `EMBEDDING_MODEL` env var. Device auto-selects CUDA→CPU.
+- Vectors are **768-dim** and **L2-normalized** (`normalize_embeddings=True`). Any new ingest script or schema must match this dimension and normalization, or search breaks silently.
+
+**Incremental / idempotent ingestion.** Every script hashes source content with SHA-256 (`get_hash`/`hashlib.sha256`) and stores it as `content_hash`. On re-run it compares hashes per source unit (per URL, per file, per wiki page, per forum topic) and **skips unchanged content; deletes-then-re-adds changed content.** This is why re-running an ingest script is cheap and safe.
+
+**Schema migration guard.** Each ingest script checks whether the existing table has the current columns (e.g. `if "content_hash" not in table.schema.names`) and **drops + recreates the whole table** if the schema is stale. Changing a `LanceModel`/pyarrow schema therefore forces a full re-ingest of that store — account for that when editing schemas.
+
+**Code-aware chunking via Tree-sitter.** `ingest_clusterio.py` (TypeScript) and `ingest_github_mod.py` (Lua) parse files into AST nodes (classes, functions, methods, interfaces/tables) using a Tree-sitter `Query`, and store each node as a chunk with `node_type`/`node_name`. Non-code files fall back to fixed-size sliding-window text chunking (`extract_text_chunks`, 1500 chars / 200 overlap). The doc/wiki/forum scripts use plain text chunking only.
+
+**Per-store table names and key columns** (the server opens these by exact name; all stores live under `data/`):
+- `data/factorio_lancedb` → table `docs`: `text`, `class_name`, `version`, `url`, `node_type`. Holds **multiple Factorio versions** (`["1.1.110", "latest"]`); search filters by `version`. Writes `version.txt`.
+- `data/clusterio_lancedb` → table `codebase`: `content`, `file_path`, `node_type`, `node_name`. Writes `version.txt` from the repo's `package.json`.
+- `data/wiki_lancedb` → table `docs`: `text`, `title`, `url`.
+- `data/forum_lancedb` → table `forum`: `content`, `class_name` (= topic title), `file_path` (= URL), `version`.
+- `data/mod_lancedb` → table `codebase`: `content`, `repo_url`, `file_path`, `node_type`, `node_name`. One store holds **multiple mods**; search filters by `mod_name` via `repo_url LIKE`.
+
+**Server resilience.** `server.py` opens each table in its own try/except and sets the handle to `None` on failure, so a missing database degrades only the affected tool (which returns a "run ingest_X.py first" error) rather than crashing the server. Search tools accept a **list of queries** (batched encode) and clamp `limit` to 1–20.
+
+**Non-search tools** in `server.py` are self-contained (no DB): `decode_factorio_blueprint`/`encode_factorio_blueprint` (base64+zlib, version byte `0`, 10 MB decompress guard), `factorio_mod_portal_analyzer` (mods.factorio.com API), `factorio_log_inspector` (OS-aware path to `factorio-current.log`), `get_mcp_version_info` (reads the `version.txt` files).
+
+## Conventions (from `.agents/AGENTS.md`)
+
+- **Windows console printing:** never `print()` raw dynamic/scraped strings — PowerShell's default encoding throws `UnicodeEncodeError` on en-dashes/emojis. Wrap dynamic output: `print(text.encode('ascii', 'replace').decode('ascii'))`. The ingest scripts already do this; preserve it.
+- **Committing:** always run `git status` to verify nothing modified/untracked is left behind before telling the user changes are pushed. Stage deliberately.
+- **SQL-string safety:** LanceDB `.where()` clauses are built with f-strings, so user/dynamic values are escaped by doubling single quotes (`value.replace("'", "''")`). Keep this when adding filters.
+
+## Data files & git
+
+- The `data/*_lancedb/` stores are committed to the repo and marked `binary` in `.gitattributes` (no line-ending conversion). `.mod_temp/` (clone scratch for `ingest_github_mod.py`, at repo root), `venv/`, `__pycache__/`, `.claude/`, and `.env` are gitignored.
+- `.gitattributes` enforces LF line endings for all text/source files regardless of `core.autocrlf`.
+- `forum_links.txt` is the curated input list for `ingest_forum.py` (one URL per line, `#` comments allowed).
+- **LanceDB hygiene.** Stores are append-only and never self-prune, so each ingest run accumulates versions/fragments. Let that history grow on feature branches (a PR diff then shows what data changed), but run `python maintenance/compact_lancedb.py` before merging to `main` to collapse it (`Table.optimize()` with `cleanup_older_than=0`). `maintenance/hooks/pre-push` is an opt-in guard (`git config core.hooksPath maintenance/hooks`) that blocks pushes to `main` while any store is uncompacted, via `compact_lancedb.py --check`.

factorio_ai_tools-1.1.1/Dockerfile

@@ -0,0 +1,19 @@
+FROM python:3.11-slim
+
+# Install git for any tree-sitter or fetching dependencies
+RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Copy requirements first to leverage Docker cache
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy all python scripts and LanceDB vector databases
+COPY . .
+
+# Ensure the mcp server binds to stdio properly and PYTHONPATH is set for the src layout
+ENV PYTHONUNBUFFERED=1
+ENV PYTHONPATH=/app/src
+
+ENTRYPOINT ["python", "-m", "factorio_ai_tools.server"]

factorio_ai_tools-1.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 solarcloud7
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

factorio_ai_tools-1.1.1/Makefile

@@ -0,0 +1,19 @@
+.PHONY: help compact ingest-all mcp
+
+help:
+	@echo "Available commands:"
+	@echo "  make compact       - Compact and condense the LanceDB database"
+	@echo "  make ingest-all    - Run the ingestion script for all configured repositories"
+	@echo "  make mcp           - Start the MCP server"
+
+compact:
+	uv run --no-sync python src/factorio_ai_tools/ingest/compact_db.py
+
+ingest-all:
+	uv run --no-sync python src/factorio_ai_tools/ingest/ingest_github_repo.py --repo-url https://github.com/clusterio/clusterio-docker.git
+	uv run --no-sync python src/factorio_ai_tools/ingest/ingest_github_repo.py --repo-url https://github.com/wube/factorio-data.git
+	uv run --no-sync python src/factorio_ai_tools/ingest/ingest_github_repo.py --repo-url https://github.com/redruin1/factorio-draftsman.git
+	uv run --no-sync python src/factorio_ai_tools/ingest/ingest_github_repo.py --repo-url https://github.com/Teoxoy/factorio-blueprint-editor.git
+
+mcp:
+	.\start_mcp_server.bat

factorio_ai_tools-1.1.1/PKG-INFO

@@ -0,0 +1,137 @@
+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.

factorio_ai_tools-1.1.1/README.md

@@ -0,0 +1,118 @@
+<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.