<p align="center">
  <img src="docs/banner.svg" alt="GECK MCP — Fallout 3 meets AI-assisted modding" width="100%">
</p>

<p align="center">
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-85f9af?style=flat-square" alt="MIT license"></a>
  <img src="https://img.shields.io/badge/platform-Windows-85f9af?style=flat-square" alt="Windows">
  <img src="https://img.shields.io/badge/Python-3.11%2B-85f9af?style=flat-square" alt="Python 3.11+">
  <img src="https://img.shields.io/badge/status-experimental-f2ce73?style=flat-square" alt="Experimental">
</p>

<p align="center"><b>A Codex skill and local MCP server for working with the Fallout 3 G.E.C.K.</b><br>
Inspect the editor. Find cells and objects. Plan placements. Back up and edit supported plugin records.</p>

<p align="center"><a href="#quick-setup">Quick setup</a> · <a href="docs/README.ru.md">Русский</a> · <a href="docs/tools.md">46 tools</a> · <a href="#limitations">Limitations</a></p>

## What is this?

**GECK MCP** connects an AI assistant to the local Garden of Eden Creation Kit for Fallout 3.
The **skill** teaches the assistant the workflow; the **MCP server** supplies the tools.
You need both to use the complete Codex workflow.

The server uses Windows UI Automation and bounded plugin-file operations. It runs
locally over stdio and does not include an AI model, game assets, GECK, or FOSE.
Other MCP clients can use the server; the bundled instructions are written for Codex.

```text
Your request → Codex + geck-mcp skill → local MCP server
                                        ├─ GECK windows, menus and controls
                                        └─ plugin inspection, backups and edits
```

## What you can do

| Workflow | Available capabilities |
| --- | --- |
| Diagnose | Check paths and dependencies; inspect processes, windows and logs |
| Navigate | Find cells by Editor ID; jump to exterior coordinates; inspect Cell View |
| Work with objects | Filter Object Window; find/select refs; drag objects into Render Window |
| Inspect the editor | Read controls, lists and status bar; capture screenshots |
| Manage plugins | List plugins; inspect load order; back up, restore and verify disk state |
| Correct placement | Read REFR/ACHR/ACRE; change position and rotation with GECK closed |
| Check results | Scope distance checks to a cell; verify supported file structure |

See the [complete tool reference](docs/tools.md) for all 46 tools and their boundaries.

## Quick setup

### 1. Install the server

Use **Windows**, **Git**, **Python 3.11+**, an installed copy of **Fallout 3**, and
**GECK for Fallout 3**. FOSE is optional unless you need its editor/script support.
Run UI automation in your interactive Windows desktop session.

In PowerShell:

```powershell
git clone https://github.com/maksimka2432fr23/codex-skill-mcp-fallout3.git
cd codex-skill-mcp-fallout3
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
```

If your Python installation has no `py` launcher, use `python -m venv .venv`.

### 2. Connect Codex

Merge [examples/codex-config.toml](examples/codex-config.toml) into your Codex
`~/.codex/config.toml`. Replace the repository and game paths with your own.
Do not replace the rest of your configuration.

```toml
[mcp_servers.geck]
command = 'C:\Tools\codex-skill-mcp-fallout3\.venv\Scripts\python.exe'
args = ["-m", "geck_mcp"]
cwd = 'C:\Tools\codex-skill-mcp-fallout3'

[mcp_servers.geck.env]
GECK_MCP_FALLOUT3_DIR = 'C:\Games\Fallout 3 goty'
```

This is a **stdio** server: the MCP client launches it. No port or server API key
is required. Your AI client may have its own account and billing requirements.
Configuration follows the [official Codex MCP documentation](https://learn.chatgpt.com/docs/extend/mcp?surface=cli).

### 3. Install the skill

From the cloned repository, copy the skill into your user skill directory:

```powershell
$skillRoot = Join-Path $env:USERPROFILE '.agents\skills'
New-Item -ItemType Directory -Force -Path $skillRoot | Out-Null
Copy-Item -LiteralPath '.\skills\geck-mcp' -Destination $skillRoot -Recurse
```

If `geck-mcp` already exists there, review and update that copy instead of creating
duplicates. Alternatively, ask Codex's `$skill-installer` to install
`skills/geck-mcp` from this repository. The server still needs steps 1–2.
See [official skill discovery and installation guidance](https://learn.chatgpt.com/docs/build-skills).

Restart/reconnect Codex's MCP session after setup or server updates.

### 4. Check the connection

Ask Codex:

> Use $geck-mcp to run geck_doctor and inspect whether GECK is running. Do not modify any plugins.

The diagnostic should find your GECK executable, Data folder and required Python
dependencies. A missing FOSE loader is expected if you have not installed FOSE.

## Try these prompts

> Launch GECK through FOSE and inspect its main window.

> Open MegatonMoriartysSaloon and show the references in Cell View.

> Back up MyMod.esp and list its saved placed objects.

> Plan a placement from the selected anchor with a Z offset of -8. Show the coordinates before changing anything.

> Explain the recent warnings in EditorWarnings.txt.

Object selection uses the current Object Window category. A prompt is an example
workflow, not a guarantee that the requested record exists in every installation.

## A reliable editing loop

1. **Inspect** the intended plugin, cell and reference; create a backup.
2. **Work in GECK** and inspect unsaved changes in the UI.
3. **Save** when a saved mod is requested; inspect any unverified save or warning.
4. **Capture** exact coordinates if a file-level correction is needed.
5. **Close GECK and Fallout 3**, then patch the saved reference.
6. **Verify and reopen** for visual checks; roll back if the result is wrong.

Direct edits use a verified temporary file, atomic replacement and a check for
intervening changes. Omitted rotation axes are preserved; explicit file rotations
are in radians. Distance reports require the anchor's `cell_form_id`.

## Limitations

- **Experimental UI automation.** Window layouts, localization, modal dialogs and privileges can affect control discovery. Live UI workflows need testing on your installation.
- **No native GECK API.** This does not expose the editor's internal object model or guarantee automatic quest, script, dialogue or navmesh authoring.
- **Bounded ESP support.** Direct placement editing targets REFR, ACHR and ACRE. Compressed placed records and extended XXXX subrecords are rejected. NAVM is out of scope.
- **Disk and UI are different states.** Unsaved objects are absent from file reads. Direct edits and rollback are blocked while GECK/FOSE or a process in the game directory is running.
- **Legacy status-bar patch tools only plan.** They return `applied=false` and deferred arguments; apply those after closing the editor.
- **Coordinates are not collision checks.** Object origin, bounds and floor contact still need visual/game validation. IDs from the UI may use different load-order prefixes from on-disk IDs.
- **Deletion is file-local.** Removing an override is not the same as deleting its master object. This is not a full dependency/link validator.
- **Local execution is not an offline AI guarantee.** Tool results and screenshots can be sent to your configured AI client/provider. The server itself does not call an AI API.

## Configuration

| Environment variable | Purpose |
| --- | --- |
| `GECK_MCP_FALLOUT3_DIR` | Your game installation; set explicitly |
| `FALLOUT3_DIR` | Fallback game-directory variable |
| `GECK_MCP_GECK_EXE` | Override the GECK executable path |
| `GECK_MCP_DATA_DIR` | Override the Data directory |
| `GECK_MCP_LOAD_ORDER_FILE` | Override plugins.txt, e.g. for a mod-manager profile |
| `GECK_MCP_BACKUP_DIR` | Backup location; defaults to `backups/` under server cwd |
| `GECK_MCP_SCREENSHOT_DIR` | Screenshot location; defaults to `screenshots/` under server cwd |

Without an explicit game path the server tries the conventional Steam directory
under Program Files (x86). Without a load-order override it uses
`%LOCALAPPDATA%\Fallout3\plugins.txt`. Mod-manager virtual filesystems are not
automatically detected; configure the visible paths and inspect them with doctor.

## Development and verification

```powershell
.\.venv\Scripts\python.exe -m unittest discover -s tests -v
```

The initial editing suite covers 19 cases, including malformed containers,
rotation preservation, failed writes, concurrent file changes, cell scoping,
rollback and mocked save dialogs. Tests create synthetic plugins in temporary
directories; GECK and Fallout 3 are not required. CI runs these checks on Windows.

On the development machine, structural traversal was also checked against nine
installed ESP files without changing them. This is not evidence of compatibility
with every plugin or a full end-to-end GECK UI test.

```text
skills/geck-mcp/   Codex workflow instructions
src/geck_mcp/      Local stdio MCP server and bounded ESP parser
tests/            Synthetic plugin and configuration tests
examples/         Portable Codex configuration
docs/             Russian guide, banner and tool reference
```

## Contributing

Bug reports and focused pull requests are welcome. Include the tool name, error,
Windows/Python/GECK versions and a minimal reproduction. For parser changes,
add a synthetic regression test. For UI changes, describe the editor state and
how you verified it. Do not attach copyrighted game files or personal logs.

Potential next steps: broader parser coverage, stronger UI identification,
more placement checks, and dedicated quest/script workflows.

## License and credits

[MIT](LICENSE). Community project by [maksimka2432fr23](https://github.com/maksimka2432fr23).
Not affiliated with or endorsed by Bethesda or OpenAI. Fallout and GECK belong to
their respective owners; no game files are distributed here.

Built with [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk),
[pywinauto](https://github.com/pywinauto/pywinauto), psutil and Pillow.
Format reference: [xEdit's Fallout 3 record documentation](https://tes5edit.github.io/fopdoc/Fallout3/Records.html).