Codesys-mcp-toolkit

@codesys/mcp-toolkit

Un servidor de Model Context Protocol (MCP) para entornos de programación CODESYS V3. Este kit de herramientas permite una interacción fluida entre clientes MCP (como Claude Desktop) y CODESYS, permitiendo la automatización de la gestión de proyectos, creación de POU, edición de código y tareas de compilación a través del Motor de Scripting de CODESYS.

🌟 Características

• Gestión de Proyectos

  • Abrir proyectos CODESYS existentes (open_project)
  • Crear nuevos proyectos a partir de plantillas estándar (create_project)
  • Guardar cambios del proyecto (save_project)

• Gestión de POU

  • Crear Programas, Bloques de Función y Funciones (create_pou)
  • Establecer código de declaración e implementación (set_pou_code)
  • Crear propiedades para Bloques de Función (create_property)
  • Crear métodos para Bloques de Función (create_method)
  • Compilar proyectos (compile_project)

• Recursos MCP

  • codesys://project/status: Verificar el estado de scripting y el estado del proyecto actualmente abierto.
  • codesys://project/{+project_path}/structure: Obtener la estructura de objetos de un proyecto especificado.
  • codesys://project/{+project_path}/pou/{+pou_path}/code: Leer el código de declaración e implementación de un POU, Método o accessor de Propiedad especificado.

📋 Requisitos previos

• CODESYS V3: Una instalación funcional de CODESYS V3 (probado con 3.5 SP21) con el componente Scripting Engine habilitado durante la instalación.
• Node.js: Se recomienda la versión 18.0.0 o posterior.
• Cliente MCP: Una aplicación compatible con MCP (por ejemplo, Claude Desktop).

(Nota: CODESYS utiliza Python 2.7 internamente para su motor de scripting, pero este kit de herramientas maneja la interacción; no necesita gestionar Python por separado).

🚀 Instalación

La forma recomendada de instalar es globalmente usando npm:

npm install -g @codesys/mcp-toolkit

Esto instala el paquete globalmente, haciendo que el comando codesys-mcp-tool esté disponible en el PATH del terminal de su sistema.

(Los usuarios avanzados también pueden instalar desde el código fuente para desarrollo - ver CONTRIBUTING.md si está disponible).

🔧 Configuración (¡IMPORTANTE!)

Este kit de herramientas necesita saber dónde está su instalación de CODESYS y qué perfil utilizar. La configuración se realiza típicamente dentro de su aplicación cliente MCP (como Claude Desktop).

Método de configuración recomendado (Comando directo)

Debido a posibles problemas con variables de entorno (especialmente con PATH) al lanzar herramientas de Node.js mediante envoltorios como npx dentro de ciertas aplicaciones host (por ejemplo, Claude Desktop), se recomienda encarecidamente configurar su cliente MCP para ejecutar el comando instalado codesys-mcp-tool directamente.

Ejemplo para Claude Desktop (settings.json -> mcpServers):

{
  "mcpServers": {
    // ... other servers ...
    "codesys_local": {
      "command": "codesys-mcp-tool", // <<< Use the direct command name
      "args": [
        // Pass arguments directly to the tool using flags
        "--codesys-path", "C:\\Program Files\\Path\\To\\Your\\CODESYS\\Common\\CODESYS.exe",
        "--codesys-profile", "Your CODESYS Profile Name"
        // Optional: Add --workspace "/path/to/your/projects" if needed
      ]
    }
    // ... other servers ...
  }
}

Pasos clave:

1. Reemplace "C:\\Program Files\\Path\\To\\Your\\CODESYS\\Common\\CODESYS.exe" con la ruta completa y correcta a su archivo CODESYS.exe específico.
2. Reemplace "Your CODESYS Profile Name" con el nombre exacto del perfil de CODESYS que desea usar (visible en la interfaz de CODESYS).
3. Asegúrese de que el comando codesys-mcp-tool sea accesible en el PATH del sistema donde se ejecuta la aplicación cliente MCP. La instalación global mediante npm install -g usualmente maneja esto.
4. Reinicie su aplicación cliente MCP (por ejemplo, Claude Desktop) para aplicar los cambios de configuración.

Configuración alternativa (usando npx - No recomendada)

Lanzar con npx ha mostrado causar errores inmediatos ('C:\Program' is not recognized...) en algunos entornos, probablemente debido a cómo npx maneja el entorno de ejecución. Use el método de comando directo si es posible. Si debe usar npx:

// Example using npx (POTENTIALLY PROBLEMATIC - USE WITH CAUTION):
{
  "mcpServers": {
    "codesys_local": {
      "command": "npx",
      "args": [
        "-y", // Tells npx to install temporarily if not found globally
        "@codesys/mcp-toolkit",
        // Arguments for the tool MUST come AFTER the package name
        "--codesys-path", "C:\\Program Files\\Path\\To\\Your\\CODESYS\\Common\\CODESYS.exe",
        "--codesys-profile", "Your CODESYS Profile Name"
      ]
    }
  }
}

(Nota: El separador -- después del nombre del paquete a veces puede ayudar a npx, pero no se garantiza que solucione el problema de entorno).

🛠️ Argumentos de línea de comandos

Al ejecutar codesys-mcp-tool directamente o configurarlo, puede usar estos argumentos:

• -p, --codesys-path <path>: Ruta completa a CODESYS.exe. (Requerido, anula la variable de entorno CODESYS_PATH, tiene un valor predeterminado pero no se recomienda confiar en él).
• -f, --codesys-profile <profile>: Nombre del perfil de CODESYS. (Requerido, anula la variable de entorno CODESYS_PROFILE, tiene un valor predeterminado pero no se recomienda confiar en él).
• -w, --workspace <dir>: Directorio de trabajo para resolver rutas de proyecto relativas pasadas a las herramientas. Por defecto es el directorio donde se lanzó el comando (lo que puede ser impredecible cuando lo ejecuta otra aplicación). Establecer esto explícitamente podría ser necesario si se usan rutas relativas.
• -h, --help: Mostrar mensaje de ayuda.
• --version: Mostrar versión del paquete.

🔍 Solución de problemas

• Error 'C:\Program' is not recognized... inmediatamente después de conectarse:

  • Causa: Esto generalmente ocurre cuando la herramienta se lanza mediante npx dentro de un entorno como Claude Desktop. El entorno de ejecución (variable PATH) proporcionado al proceso probablemente provoca que un comando interno de CODESYS (como ejecutar Python) falle.
  • Solución: Configure su cliente MCP para ejecutar el comando directamente ("command": "codesys-mcp-tool") en lugar de usar "command": "npx". Vea la sección Método de configuración recomendado arriba.

• La herramienta falla / errores en la salida:

  • Revise los registros de su aplicación cliente MCP (por ejemplo, registros de Claude Desktop). Busque mensajes INTEROP: o mensajes de Python DEBUG: / ERROR: impresos en stderr desde la ejecución del script de CODESYS.
  • Asegúrese de que los argumentos --codesys-path y --codesys-profile pasados al comando sean correctos y apunten a una instalación válida de CODESYS con scripting habilitado.
  • Verifique que las rutas de proyecto y las rutas de objetos que pasa a las herramientas sean correctas (use barras diagonales /).
  • Asegúrese de que no haya otras instancias de CODESYS ejecutándose de maneras conflictivas (por ejemplo, manteniendo un bloqueo sobre el perfil).

• command not found: codesys-mcp-tool:

  • Asegúrese de que el paquete se haya instalado globalmente (npm install -g @codesys/mcp-toolkit).
  • Asegúrese de que el directorio bin global de npm esté en la variable de entorno PATH de su sistema. Encuéntrelo con npm config get prefix y agregue el subdirectorio bin (o el directorio principal mismo en Windows) a su PATH.

• Verificar registros:

  • Registros de Claude Desktop: C:\Users\<YourUsername>\AppData\Roaming\Claude\logs\ (Windows)

🤝 Contribuciones

¡Las contribuciones, problemas y solicitudes de características son bienvenidos! Siéntase libre de consultar la página de problemas. (Opcionalmente, agregue un archivo CONTRIBUTING.md con más detalles).

📝 Licencia

Este proyecto está licenciado bajo la Licencia MIT - vea el archivo LICENSE para más detalles.

🙏 Agradecimientos

• El equipo de CODESYS GmbH por la potente plataforma CODESYS y su motor de scripting.
• El proyecto Model Context Protocol por definir el estándar de interacción.
• Todos los contribuyentes y usuarios que ayudan a mejorar este kit de herramientas.