Codesys-mcp-toolkit

Implements a Model Context Protocol server that translates standardized MCP requests into CODESYS Scripting Engine operations through a layered architecture. The McpServer class from the MCP SDK handles protocol negotiation and request routing, while a Python script execution layer bridges MCP tool calls to CODESYS automation APIs. This enables AI clients (like Claude Desktop) to programmatically control CODESYS V3 environments without direct API knowledge.

Exposes MCP tools for complete project lifecycle operations: open_project, create_project, save_project, and compile_project. Each tool translates MCP parameters into Python scripts that invoke CODESYS Scripting Engine APIs to manipulate project files, manage in-memory project state, and trigger compilation with error reporting. The toolkit maintains awareness of the currently open project context across multiple tool invocations within a single MCP session.

Implements MCP tools for creating and modifying POUs (Programs, Function Blocks, Functions) with separate declaration and implementation code sections. The create_pou tool generates new POUs with specified type and initial code, while set_pou_code updates existing POU code. The toolkit reads POU code through MCP resources (codesys://project/{path}/pou/{pou_path}/code) that parse CODESYS project XML to extract declaration and implementation sections separately, enabling AI systems to understand and modify POU structure.

Exposes MCP tools create_property and create_method for adding properties and methods to Function Blocks. These tools generate Python scripts that invoke CODESYS Scripting Engine APIs to add typed properties (with getter/setter code) and methods (with parameters and return types) to existing Function Blocks. The toolkit handles the code generation for property accessors and method stubs, reducing boilerplate for AI-assisted development.

Implements MCP resource endpoints (codesys://project/{path}/structure) that parse CODESYS project XML files to expose hierarchical project structure as queryable resources. The toolkit extracts object metadata (POUs, properties, methods, variables) from the project file and returns structured JSON representations without requiring CODESYS GUI interaction. This enables AI clients to understand project topology for code generation, refactoring, or analysis tasks.

Implements MCP resource endpoint (codesys://project/status) that queries CODESYS Scripting Engine state and returns current project status, including whether a project is open, the current project file path, unsaved changes flag, and scripting engine availability. This resource is generated by executing a Python script that invokes CODESYS Scripting Engine APIs to introspect runtime state, enabling MCP clients to determine system readiness before executing project operations.

Implements a Python script templating system that generates CODESYS Scripting Engine automation scripts from MCP tool parameters. The toolkit maintains Python script templates for each operation (project management, POU creation, compilation) that are populated with parameters and executed via subprocess calls. This approach decouples MCP protocol handling from CODESYS-specific logic, enabling easy extension with new operations and version-specific script variants.

Supports configuration and management of multiple CODESYS installations through environment variables and configuration files. The toolkit can target different CODESYS versions or instances by specifying installation paths, enabling users to work with multiple CODESYS environments through a single MCP server. Configuration is managed via command-line options and environment variables that are passed to Python scripts for installation-specific scripting engine access.

Provides a command-line interface (codesys-mcp-tool binary) that launches the MCP server with configurable options for CODESYS installation path, logging level, and port binding. The CLI entry point (dist/bin.js) parses command-line arguments and initializes the McpServer with specified configuration, enabling deployment as a standalone service or integration into automation frameworks. Supports both stdio-based MCP communication (for Claude Desktop integration) and network-based communication.

Implements error handling that captures CODESYS Scripting Engine errors, compilation errors, and script execution failures, returning structured error responses through MCP protocol. Compilation errors include line numbers, column positions, and error messages extracted from CODESYS compiler output. Script execution errors are captured from Python subprocess stderr and mapped to user-friendly MCP error responses with diagnostic context.