# Engine Atlas MCP

Research the Asphalt 8 game engine with your AI assistant. Engine Atlas MCP gives
Claude Code, Codex, Antigravity or any other MCP client the tools of the
[Engine Atlas](https://github.com/mindkeyboard/engine-atlas-mcp#how-it-fits-together)
reference: the class catalog, decompilation through Ghidra, notes, card writing and
quality checks.

[Русская версия](README.ru.md)

Everything is saved to local drafts. Nothing reaches the public reference until you
send it and it passes review.

## What you need

- Python 3.11 or newer.
- A database snapshot from the Engine Atlas maintainer. It is not distributed with this
  project, and the server cannot start without it.
- For decompilation: [Ghidra](https://github.com/NationalSecurityAgency/ghidra) with
  [Ghidra MCP](https://github.com/bethington/ghidra-mcp), and `libasphalt8.so` from the
  Engine Atlas site, opened in Ghidra.

## Install

```sh
pip install git+https://github.com/mindkeyboard/engine-atlas-mcp
engine-atlas-mcp init --snapshot atlas-snapshot.sqlite
engine-atlas-mcp doctor --elf /path/to/libasphalt8.so
```

Data goes to `~/.engine-atlas`. Use `--data`, or the `ENGINE_ATLAS_DATA` variable, to
keep it elsewhere.

Then connect it to your client: [Claude Code, Codex and Antigravity](docs/clients.md).

## Use

Ask the model to study a class:

> Study the class gin::Widget in Engine Atlas.

The model reads the full research rules from the server itself, so there is nothing
else to teach it. Strong models are strongly recommended, such as Sonnet 5.5, GPT-6 Sol
or newer. AI research is valued above manual work because its whole process stays
visible, so keep the notes.

Before you send anything, have a second session check the result as a critic:

> You are the critic. Check the cards for gin::Widget by the critic role in the guide.

When the critic has no findings left:

> Export my drafts with atlas_export_drafts.

Open **My edits** on the site, choose **Load a file**, review the edits and send them.

## What is different from the maintainer's copy

Tools work the same, on your local copy of the database. Four publication actions are
absent: `atlas_promote_class_publication`, `atlas_promote_class_contract`,
`atlas_waive_class_method` and `atlas_refresh_reference`. Two tools are added:
`atlas_list_drafts` and `atlas_export_drafts`.

The export carries articles, method descriptions, properties, examples, evidence and
notes. Method order, class contracts and executable bindings stay local for now.

## How it fits together

`src/engine_atlas` holds the parts of the research core that the server uses.
`src/engine_atlas_mcp` adds local drafts and the export. The original game file is
never changed, and no game files are part of this repository.

## License

[Apache-2.0](LICENSE). This is an independent project, not affiliated with Gameloft.
See [NOTICE](NOTICE).