Metadata-Version: 2.4
Name: l5x-toolkit
Version: 1.3.2
Summary: AI Agent Toolkit for Rockwell Automation L5X file manipulation
Home-page: https://github.com/Axiara/l5x-toolkit
Author: Megan Fox
License: MIT
Project-URL: Homepage, https://github.com/Axiara/l5x-toolkit
Project-URL: Repository, https://github.com/Axiara/l5x-toolkit
Project-URL: Issues, https://github.com/Axiara/l5x-toolkit/issues
Project-URL: Changelog, https://github.com/Axiara/l5x-toolkit/blob/main/CHANGELOG.md
Keywords: rockwell,studio5000,l5x,plc,mcp,automation,logix
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Manufacturing
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: lxml>=4.9.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.15.7; extra == "dev"
Requires-Dist: mypy>=1.11; extra == "dev"
Provides-Extra: mcp
Requires-Dist: mcp[cli]>=1.2.0; extra == "mcp"
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# L5X Agent Toolkit

![CI](https://github.com/Axiara/l5x-toolkit/actions/workflows/ci.yml/badge.svg)
![Python](https://img.shields.io/badge/python-3.12%2B-blue)
![License: MIT](https://img.shields.io/badge/license-MIT-green)

An MCP server that lets Claude safely read and modify Rockwell Studio 5000 L5X files — **every operation produces structurally correct output; the agent never hand-edits XML.**

You describe a PLC change in plain English; the toolkit translates it into byte-perfect L5X through validated functions that understand the schema, CDATA encoding, dual data-format synchronization, and Studio 5000's import rules.

---

## Features

- **21 tools** covering tags, programs, rungs (RLL), ST lines, SFC charts, FBD sheets, alarms, I/O modules, AOIs, UDTs, axes, trends, and cross-reference analysis.
- **Native AOI/UDT editing** — Add-On Instructions and User-Defined Types are edited in place, not round-tripped through an export shell.
- **Pre-flight validation** — catch structural errors, missing references, and naming violations before you save.
- **Firmware v30–v38** — retarget projects across the supported range.
- **Plugin support** — register custom tools via entry points (see [PLUGINS.md](PLUGINS.md)).
- **Minimal dependencies** — `lxml` and the standard library, plus `mcp[cli]` for the server.

## Quick Start

Install from PyPI:

```bash
pip install "l5x-toolkit[mcp]"
```

Or from source:

```bash
git clone https://github.com/Axiara/l5x-toolkit.git
cd l5x-toolkit
pip install -e ".[mcp]"
```

Either way this installs `lxml` and `mcp[cli]`. Requires **Python 3.12+** (install 3.13 — see Getting Started). The import package is `l5x_agent_toolkit`.

Then register the MCP server using the `l5x-mcp-server` console command (installed by the step above):

**Claude Code:**
```bash
claude mcp add l5x-toolkit -- l5x-mcp-server
```

**Claude Desktop:** Add to your `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "l5x-toolkit": {
      "command": "l5x-mcp-server",
      "args": [],
      "env": {}
    }
  }
}
```

Verify the connection in Claude Code with the `/mcp` slash command — `l5x-toolkit` should appear as connected.

**New to Python?** See [Getting Started](docs/getting-started.md) for the full from-scratch setup (installing Python, PATH, and verifying the connection).

## Example Conversation

> **You:** Load my project at C:\Projects\Line4.L5X and tell me what is in it.
>
> **Claude:** *(calls `load_project`)* Loaded: Line4_Controller (1756-L83E, FW 35.11). The project has 12 programs, 847 tags, 6 AOIs, 3 UDTs, and 24 modules.
>
> **You:** Create a new program called PalletizerControl and schedule it under MainTask.
>
> **Claude:** *(calls `manage_programs` twice — once to create, once to schedule)* Done. Created program 'PalletizerControl' with a MainRoutine and scheduled it under MainTask.
>
> **You:** Add a DINT tag called PalletizerState, then add a rung that sets it to 1 when StartPB is pressed.
>
> **Claude:** *(calls `manage_tags`, then `manage_rungs`)* Created the tag and added the rung: `XIC(StartPB)MOV(1,PalletizerState);`
>
> **You:** Validate and save to C:\Projects\Line4_updated.L5X
>
> **Claude:** *(calls `validate`, then `save_project`)* Validation passed with 0 errors. Saved to C:\Projects\Line4_updated.L5X.

## Documentation

| Document | Description |
|----------|-------------|
| [Documentation index](docs/README.md) | The docs hub — Using vs Contributing tracks |
| [Getting Started](docs/getting-started.md) | Install Python, the toolkit, and the MCP server, from zero |
| [Component Libraries](docs/library-setup.md) | Configure library directories so Claude can import components by name |
| [Cookbook](docs/cookbook.md) | Task recipes — what to ask Claude, and which tools run |
| [Tool Reference](docs/tool-reference.md) | All 21 tools with parameters and behavior |
| [Architecture](docs/architecture.md) | The layered design and the 21-tool surface |
| [Development & Roadmap](docs/development.md) | Status, supported scope, known limitations, roadmap |
| [Changelog](CHANGELOG.md) | Version history |
| [Contributing](CONTRIBUTING.md) | Setup, tests, and how to contribute |

## Project Structure

The package is layered; `lxml` is isolated to `core/`. See [Architecture](docs/architecture.md) for detail.

```
l5x_agent_toolkit/
  core/        XML tree, CDATA, reference scanner, config — the only layer that imports lxml
  model/       typed DTOs / view objects
  query/       read-only projections: inspect, inventory/list, references, resolver
  ops/         language & structural operation helpers
  validate/    typed Finding/Report checks (default + opt-in families)
  server/      MCP tool wrappers (envelope, reads, write/structural/lifecycle dispatch)
  mcp_server.py    registers the 21 tools over stdio
```

## License

MIT License. See [LICENSE](LICENSE) for details.

Created by Megan Fox. Uses [lxml](https://lxml.de/) for XML processing and the [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) for the Model Context Protocol server.

Rockwell Automation, Studio 5000, Logix Designer, and RSLogix 5000 are trademarks of Rockwell Automation, Inc. This toolkit is not affiliated with or endorsed by Rockwell Automation.
