l5x-toolkit 1.2.1__tar.gz

l5x_toolkit-1.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Megan Fox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

l5x_toolkit-1.2.1/MANIFEST.in

@@ -0,0 +1,4 @@
+# Vendored reference-library catalog ships in both sdist and wheel.
+recursive-include l5x_agent_toolkit/reference/data *.json
+recursive-include l5x_agent_toolkit/reference/data *.md
+include l5x_agent_toolkit/reference/data/validate.py.reference

l5x_toolkit-1.2.1/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: l5x-toolkit
+Version: 1.2.1
+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:
+
+**Claude Code:**
+```bash
+claude mcp add l5x-toolkit -- python -m l5x_agent_toolkit.mcp_server
+```
+
+**Claude Desktop:** Add to your `claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "l5x-toolkit": {
+      "command": "python",
+      "args": ["-m", "l5x_agent_toolkit.mcp_server"],
+      "env": {}
+    }
+  }
+}
+```
+
+**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 |
+| [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.

l5x_toolkit-1.2.1/README.md

@@ -0,0 +1,114 @@
+# 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:
+
+**Claude Code:**
+```bash
+claude mcp add l5x-toolkit -- python -m l5x_agent_toolkit.mcp_server
+```
+
+**Claude Desktop:** Add to your `claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "l5x-toolkit": {
+      "command": "python",
+      "args": ["-m", "l5x_agent_toolkit.mcp_server"],
+      "env": {}
+    }
+  }
+}
+```
+
+**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 |
+| [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.

l5x_toolkit-1.2.1/l5x_agent_toolkit/__init__.py

@@ -0,0 +1,99 @@
+"""
+L5X Agent Toolkit - AI-driven manipulation of Rockwell Automation L5X files.
+
+This toolkit provides validated, atomic operations for reading and modifying
+Studio 5000 Logix Designer L5X project files. It is designed to be invoked
+by an AI agent (via MCP or direct function calls) to ensure hyper-accurate
+L5X file manipulation.
+
+Core Design Principle:
+    The AI agent never touches raw XML. Instead, it invokes validated tool
+    functions that produce structurally correct XML every time.
+
+Usage:
+    from l5x_agent_toolkit import L5XProject
+
+    # Load a project
+    project = L5XProject('path/to/project.L5X')
+
+    # Query operations
+    programs = project.list_programs()
+    tags = project.list_controller_tags()
+    summary = project.get_project_summary()
+
+    # Tag operations
+    from l5x_agent_toolkit import tags
+    tags.create_tag(project, 'MyTag', 'DINT', description='A counter')
+    tags.set_tag_value(project, 'MyTag', 42)
+
+    # Program/routine operations
+    from l5x_agent_toolkit import programs
+    programs.create_program(project, 'ConveyorControl', description='Conveyor logic')
+    programs.add_rung(project, 'ConveyorControl', 'MainRoutine',
+                      'XIC(StartPB)OTE(MotorRun);', comment='Start motor')
+
+    # Rung operations
+    from l5x_agent_toolkit import rungs
+    errors = rungs.validate_rung_syntax('XIC(tag1)OTE(tag2);')
+    new_text = rungs.substitute_tags('XIC(OldTag)OTE(OldOut);',
+                                      {'OldTag': 'NewTag', 'OldOut': 'NewOut'})
+
+    # Import operations
+    from l5x_agent_toolkit import aoi, udt, modules
+    aoi.import_from_file(project, 'path/to/MyAOI.L5X')
+    udt.import_from_file(project, 'path/to/MyUDT.L5X')
+    modules.import_module(project, 'path/to/module_template.L5X',
+                          name='VFD01', address='192.168.1.100')
+
+    # Validation
+    from l5x_agent_toolkit import validator
+    result = validator.validate_project(project)
+    if not result.is_valid:
+        print(result)
+
+    # Write the modified project
+    project.write('path/to/output.L5X')
+"""
+
+__version__ = "1.2.1"
+
+
+def __getattr__(name):
+    """Lazy import to avoid circular/missing module errors during development."""
+    if name == "L5XProject":
+        from .project import L5XProject
+
+        return L5XProject
+    if name in ("L5XPlugin", "PluginContext"):
+        from .plugin import L5XPlugin, PluginContext
+
+        return L5XPlugin if name == "L5XPlugin" else PluginContext
+    if name in ("core", "model", "query", "ops", "validate"):
+        import importlib
+
+        return importlib.import_module(f"{__name__}.{name}")
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+from l5x_agent_toolkit.refactor import aoi_ops, udt_ops  # noqa: E402
+from l5x_agent_toolkit.refactor.types import (  # noqa: E402
+    BindingRequirement,
+    RefactorAction,
+    RefactorPlan,
+)
+
+__all__ = [
+    "L5XProject",
+    "L5XPlugin",
+    "PluginContext",
+    "aoi_ops",
+    "udt_ops",
+    "RefactorAction",
+    "RefactorPlan",
+    "BindingRequirement",
+    "core",
+    "model",
+    "query",
+    "ops",
+    "validate",
+]