# OpenTIA-MCP

An MCP (Model Context Protocol) server that lets AI agents interact with
**Siemens TIA Portal** via its **Openness API**.

## Requirements

- **Windows** (TIA Portal is Windows-only)
- **Python 3.11+**
- **TIA Portal V17–V20** with Openness API installed (V20 is what this repo is
  verified against)
- **pip** (Python package installer)
- For simulation and automated downloads: **S7-PLCSIM Advanced** (verified with 7.0)

## Installation

```bash
# Create a virtual environment (recommended)
python -m venv .venv
.venv\Scripts\activate

# Install the package in editable mode
pip install -e .
```

## Configuration

Copy or create an `opentia.toml` file (see `opentia.toml` for the template).
The server searches for it in this order:

1. Path specified by the `OPENTIA_CONFIG` environment variable
2. `./opentia.toml` in the current working directory
3. `%APPDATA%\opentia-mcp\opentia.toml`

## Usage

```bash
# Start the MCP server
python -m opentia_mcp
```

Or use the installed entry point:

```bash
opentia-mcp
```

## Tools

| Tool | Purpose |
| --- | --- |
| `tia_connect` / `tia_disconnect` | Attach to a running Portal (use `process_id` when several run) or spawn one |
| `tia_project_open` / `tia_project_close` / `tia_project_save` / `tia_project_info` / `tia_project_archive` | Project lifecycle (Multiuser local sessions are handled: saving goes through `LocalSessions[i].Save()`) |
| `tia_block_list` / `tia_block_read_scl` / `tia_block_write_scl` | Block inventory and SCL round-trip |
| `tia_fb_create` / `tia_fc_create` | Create blocks from SCL (optionally into a block group via `group_path`) |
| `tia_simulation_start_plcsim` / `tia_simulation_status` / `tia_simulation_stop_plcsim` | PLCSIM Advanced instance lifecycle (runtime API, not Openness) |
| `tia_download_to_plc` / `tia_download_verify` | Download to a **virtual** PLCSIM target and offline/online comparison |
| `tia_documentation_generate` | Project documentation |

## Project Structure

```
src/opentia_mcp/
├── __init__.py
├── __main__.py          # Entry point
├── server.py            # MCP server and tool registration
├── models.py            # Pydantic models
├── errors.py            # Exception hierarchy
├── config.py            # Configuration loading
├── logging.py           # Logging to stderr
└── tia/                 # Openness API abstraction layer
    ├── __init__.py
    ├── portal.py        # Connection lifecycle
    ├── project.py       # Project management
    ├── block.py         # PLC block CRUD
    ├── compilation.py   # Compilation
    ├── reference.py     # Cross-references
    ├── hmi.py           # HMI tags
    ├── watch.py         # Watch tables
    ├── diagnostic.py    # Diagnostics
    ├── simulation.py    # PLCSIM Advanced
    ├── download.py      # Download to PLC
    └── documentation.py # Documentation generation
```