MCP server for TIA Portal (Totally Integrated Automation Portal) integration with Claude, providing tools for PLC programming, project management, and industrial automation tasks
This MCP server exhibits severe structural and documentation deficiencies across nearly all quality dimensions. While the naming convention is generally acceptable (verb-first), the tool definitions are critically incomplete. All 34 tools share identical, minimalist parameter schemas with only two fields (confirm: boolean, safetyToken: string) that do not meaningfully document what parameters actually control the underlying operations. Descriptions are extremely generic, almost all are single-line statements like 'Update block logic in TIA Portal' with no explanation of when to use the tool, what it modifies, or what consequences follow. No tool documents its output schema, making it impossible for LLMs to reason about result structure or plan downstream chains. The schema uniformity across all write tools suggests tool definitions are inferred or auto-generated rather than carefully designed. The preview tools (17 READ_ONLY variants) have empty input schemas {}, which technically satisfy the presence requirement but provide zero constraint or guidance. Error handling is entirely absent from visible tool definitions, no recovery guidance, no actionable error messages, no categorization of retryable vs. fatal failures. There is no evidence of security annotations, audit logging, or permission gates despite numerous DESTRUCTIVE and WRITE operations. The write-guard hook in hooks/tia-write-guard.ps1 enforces a safety token pattern, but this is an external control mechanism, not part of the tool definitions themselves. No parameter descriptions explain what 'confirm' or 'safetyToken' actually do beyond brief one-word hints. The tool composition is reasonable (each tool has a single responsibility), but the lack of schema documentation makes it impossible to verify proper chaining. Per-tool scores average 28 across all 34 tools.
All write tool descriptions are identical single-line generic statements ('Update block logic in TIA Portal', 'Create a tag in TIA Portal', etc.). No description explains WHAT the tool modifies, WHY an agent would choose it, or WHAT the consequences are. This violates the fundamental requirement that descriptions guide tool selection and inform agents of side effects.
All write tool input schemas contain only generic 'confirm' and 'safetyToken' fields. There are NO parameters documenting what actual operation-specific inputs are needed (e.g., block_name, tag_name, project_name, network_device_id). This makes it impossible for an LLM to know what data to provide to each tool or to verify it has the necessary information before calling the tool.
Recommendations
Expand every tool description from single lines to 50 - 150 characters, following this template: 'ACTION: [verb] [resource]. WHEN: [use case]. RETURNS: [result type]. CONSEQUENCE: [side effect if write operation].' Example: 'Create a new tag in TIA Portal with specified properties. Use this to add a tag before writing block logic. Returns the tag ID. This modifies the project, changes are not immediately saved to disk.'
Add domain-specific input parameters to every write tool. For example, update_block_logic should include parameters like block_name (string, required), block_logic (string, required, multiline code), and language (enum: 'STL', 'SCL', 'GRAPH'). Each parameter must have a description explaining its purpose and constraints.
Document output schemas for all tools. Example for create_tag: 'Returns {tag_id: string, tag_name: string, tag_type: enum, created_at: ISO8601_string, project_id: string}'. This enables downstream tool chaining and LLM planning.
Add parameter descriptions for confirm and safetyToken. Example: 'confirm (boolean, required): Set to true to confirm the operation after running the corresponding preview_* tool. safetyToken (string, required): The safety token returned by preview_* operation, proving the operation was previewed and is intentional. Prevents accidental modifications.'
Add a 'WORKFLOW' note to all write tool descriptions explaining the mandatory preview→confirm pattern. Example: '⚠️ WORKFLOW: Always call preview_update_block_logic first (no params required) to see what will change. It returns a safetyToken. Then call this tool with confirm=true and the safetyToken to execute. This two-step process prevents accidental destructive actions.'
All 17 preview tools have completely empty input schemas ({}), providing zero guidance on constraints or validation. Additionally, none of the tools (preview or write) document their OUTPUT schema, making it impossible for LLMs to understand what data structure is returned or plan subsequent tool calls.
No tool provides error handling guidance. The visible code (hooks/tia-write-guard.ps1) shows a write-guard enforcement mechanism that can deny operations with messages like 'confirm=true is required' or 'safetyToken is required', but tool definitions themselves contain no error recovery guidance, no categorization of retryable vs. fatal failures, and no actionable error messages that an LLM could use to self-correct.
Destructive tools (delete_tag_table, delete_tag, delete_user_constant) have minimal descriptions and no explicit confirmation or dry-run documentation in their tool definitions themselves. While hooks/tia-write-guard.ps1 enforces a multi-step safety token pattern, this control is external to the tool schema and not visible to an LLM consulting the tool definition alone.
No tool annotations are present in any tool definition. The MCP spec supports readOnlyHint, destructiveHint, and idempotentHint to signal tool properties. The server lists several DESTRUCTIVE operations but provides no annotations to flag them to clients, forcing clients to infer risk from tool names alone.
No description or schema clarifies the relationship between preview_* and write_* tools, what a safetyToken is, how to obtain it, or what confirm=true signifies. An LLM encountering these tools for the first time has no guidance on the intended workflow.
Implement tool annotations. Add readOnlyHint: true to all preview_* tools. Add destructiveHint: true to delete_tag_table, delete_tag, delete_user_constant. Add idempotentHint: true if repeated calls with same parameters produce identical results (likely true for create_project with overwrite, but verify implementation).
Add error handling guidance to write tool descriptions. Example: 'Possible errors: INVALID_TOKEN (re-run preview_* to get fresh token), CONFIRM_REQUIRED (set confirm=true), PROJECT_NOT_FOUND (project name does not exist, call list_projects to verify), PERMISSION_DENIED (user lacks write access).'
Create separate tool registrations documenting the preview/write relationship. Consider renaming to make the workflow explicit: preview_tag_creation, execute_tag_creation. Or add a parameter to control behavior: create_tag(tag_name, preview_only: bool, confirm: bool, safetyToken: string).
Audit tool composition. Verify that the same parameters (especially resource identifiers like project_name, tag_name, block_name) are used consistently across related tools. If create_project returns project_id, ensure open_project accepts project_id as a parameter.
Document which operations are idempotent and which are not. If calling open_project twice with the same project_id is safe, state it. If calling create_tag with the same name twice creates a duplicate, document that, so agents know whether retry is safe.