# Arena MCP Extractor

A read-only [Model Context Protocol](https://modelcontextprotocol.io) server that exposes
Rockwell Automation **Arena** simulation models to an LLM client such as Claude Code.

The server asks Arena itself to open `.doe` files through its Windows COM object model.
It **never saves, runs, or edits a model**. Extracted data is returned as a versioned,
JSON-compatible intermediate representation (IR) suitable for driving a Python
simulation translator.

## Requirements

- Windows (the server uses COM and the Windows registry)
- A licensed local install of Rockwell Automation Arena, registered under the
  `Arena.Application` ProgID
- Python 3.10+

## Install

```sh
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
```

## Run

As an MCP server over stdio (the normal mode):

```sh
python Arena_MCP_Extractor.py
```

Register it with Claude Code:

```sh
claude mcp add arena -- python C:\path\to\Arena_MCP_Extractor.py
```

### CLI mode

The same file doubles as a command-line tool, which is handy for verifying your Arena
install before wiring up an MCP client:

```sh
python Arena_MCP_Extractor.py --status
python Arena_MCP_Extractor.py --list-models
python Arena_MCP_Extractor.py --inspect  MyModel.doe
python Arena_MCP_Extractor.py --extract  MyModel.doe
python Arena_MCP_Extractor.py --audit    MyModel.doe
```

`--audit` accepts `--include-vba-source`, `--include-siman-source`, and
`--include-binary-payloads` to widen what is captured.

## Tools

All tools are annotated read-only.

| Tool | Purpose |
| --- | --- |
| `arena_status` | Report whether Arena is installed and reachable over COM |
| `list_arena_models` | Discover `.doe` models in the usual document folders |
| `inspect_arena_model` | Summarize one model: modules, counts, metadata |
| `list_arena_modules` | Enumerate modules with their operand data |
| `list_arena_connections` | Enumerate the connection graph between modules |
| `extract_arena_model` | Produce the full neutral IR for translation |
| `analyze_arena_model_compatibility` | Classify modules as automatic / assisted / unsupported |
| `audit_arena_model_data` | Pre-translation coverage gate over every data source |
| `inspect_arena_project_bar` | Read the project bar panel structure |
| `extract_arena_submodels` | Walk submodel hierarchies |
| `extract_arena_visual_model` | Extract animation and layout geometry |
| `extract_arena_material_handling` | Extract conveyors, transporters, and networks |
| `inspect_arena_compound_file` | Inspect the raw OLE compound file streams |
| `extract_arena_siman_source` | Generate SIMAN source from a temporary copy |
| `inspect_arena_results` | Inspect an Arena results database |
| `read_arena_results` | Read statistics out of a results database |

## Suggested workflow

1. `arena_status` — confirm Arena is reachable.
2. `audit_arena_model_data` — the coverage gate; shows what the model contains and what
   the extractor cannot yet represent.
3. `extract_arena_model` — obtain the neutral IR to translate.

## Schema versions

- IR schema: `0.3.0`
- Audit schema: `2.0.0`

Both are reported in every response so downstream consumers can pin behaviour.

## License

MIT — see [LICENSE](LICENSE).

## Disclaimer

Not affiliated with or endorsed by Rockwell Automation. "Arena" is their trademark.
You need your own licensed Arena installation to use this.