Codesys-mcp-toolkit

@codesys/mcp-toolkit

Um servidor Model Context Protocol (MCP) para ambientes de programação CODESYS V3. Este toolkit permite interação perfeita entre clientes MCP (como Claude Desktop) e CODESYS, permitindo automação de gerenciamento de projetos, criação de POU, edição de código e tarefas de compilação via CODESYS Scripting Engine.

🌟 Recursos

• Gerenciamento de Projetos

  • Abrir projetos CODESYS existentes (open_project)
  • Criar novos projetos a partir de modelos padrão (create_project)
  • Salvar alterações do projeto (save_project)

• Gerenciamento de POU

  • Criar Programas, Blocos de Função e Funções (create_pou)
  • Definir código de declaração e implementação (set_pou_code)
  • Criar propriedades para Blocos de Função (create_property)
  • Criar métodos para Blocos de Função (create_method)
  • Compilar projetos (compile_project)

• Recursos MCP

  • codesys://project/status: Verificar o status do scripting e o estado do projeto atualmente aberto.
  • codesys://project/{+project_path}/structure: Recuperar a estrutura de objetos de um projeto especificado.
  • codesys://project/{+project_path}/pou/{+pou_path}/code: Ler o código de declaração e implementação de um POU, Método ou acessor de Propriedade especificado.

📋 Pré-requisitos

• CODESYS V3: Uma instalação funcional do CODESYS V3 (testado com 3.5 SP21) com o componente Scripting Engine habilitado durante a instalação.
• Node.js: Versão 18.0.0 ou posterior é recomendada.
• Cliente MCP: Um aplicativo habilitado para MCP (ex.: Claude Desktop).

(Nota: O CODESYS usa Python 2.7 internamente para seu mecanismo de scripting, mas este toolkit lida com a interação; você não precisa gerenciar o Python separadamente.)

🚀 Instalação

A forma recomendada de instalar é globalmente usando npm:

npm install -g @codesys/mcp-toolkit

Isso instala o pacote globalmente, tornando o comando codesys-mcp-tool disponível no PATH do terminal do seu sistema.

(Usuários avançados também podem instalar a partir do código-fonte para desenvolvimento - veja CONTRIBUTING.md se disponível).

🔧 Configuração (IMPORTANTE!)

Este toolkit precisa saber onde está sua instalação do CODESYS e qual perfil usar. A configuração é normalmente feita dentro do seu aplicativo cliente MCP (como Claude Desktop).

Método de Configuração Recomendado (Comando Direto)

Devido a possíveis problemas de variáveis de ambiente (especialmente com PATH) ao iniciar ferramentas Node.js via wrappers como npx dentro de certos aplicativos host (ex.: Claude Desktop), é fortemente recomendado configurar seu cliente MCP para executar o comando instalado codesys-mcp-tool diretamente.

Exemplo 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 ...
  }
}

Passos principais:

1. Substitua "C:\\Program Files\\Path\\To\\Your\\CODESYS\\Common\\CODESYS.exe" pelo caminho completo e correto para o seu arquivo CODESYS.exe específico.
2. Substitua "Your CODESYS Profile Name" pelo nome exato do perfil CODESYS que deseja usar (visível na interface do CODESYS).
3. Certifique-se de que o comando codesys-mcp-tool esteja acessível no PATH do sistema onde o aplicativo cliente MCP é executado. A instalação global via npm install -g geralmente cuida disso.
4. Reinicie seu aplicativo cliente MCP (ex.: Claude Desktop) para aplicar as alterações de configuração.

Configuração Alternativa (Usando npx - Não Recomendado)

Iniciar com npx foi observado causar erros imediatos ('C:\Program' is not recognized...) em alguns ambientes, provavelmente devido à forma como npx lida com o ambiente de execução. Use o método de Comando Direto acima se possível. Se você precisar 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: O separador -- após o nome do pacote às vezes pode ajudar npx, mas não é garantido que corrija o problema de ambiente.)

🛠️ Argumentos de Linha de Comando

Ao executar codesys-mcp-tool diretamente ou configurá-lo, você pode usar estes argumentos:

• -p, --codesys-path <path>: Caminho completo para CODESYS.exe. (Obrigatório, substitui a variável de ambiente CODESYS_PATH, tem um padrão, mas não é recomendado confiar nele).
• -f, --codesys-profile <profile>: Nome do perfil CODESYS. (Obrigatório, substitui a variável de ambiente CODESYS_PROFILE, tem um padrão, mas não é recomendado confiar nele).
• -w, --workspace <dir>: Diretório de trabalho para resolver caminhos de projeto relativos passados às ferramentas. Padrão é o diretório onde o comando foi iniciado (o que pode ser imprevisível quando executado por outro aplicativo). Definir isso explicitamente pode ser necessário se usar caminhos relativos.
• -h, --help: Mostrar mensagem de ajuda.
• --version: Mostrar versão do pacote.

🔍 Solução de Problemas

• Erro 'C:\Program' is not recognized... imediatamente após a conexão:

  • Causa: Isso normalmente acontece quando a ferramenta é iniciada via npx dentro de um ambiente como Claude Desktop. O ambiente de execução (variável PATH) fornecido ao processo provavelmente faz com que um comando interno do CODESYS (como executar Python) falhe.
  • Solução: Configure seu cliente MCP para executar o comando diretamente ("command": "codesys-mcp-tool") em vez de usar "command": "npx". Veja a seção Método de Configuração Recomendado acima.

• Ferramenta Falha / Erros na Saída:

  • Verifique os logs do seu aplicativo cliente MCP (ex.: logs do Claude Desktop). Procure por mensagens INTEROP: ou mensagens Python DEBUG: / ERROR: impressas no stderr da execução do script CODESYS.
  • Certifique-se de que os argumentos --codesys-path e --codesys-profile passados ao comando estão corretos e apontam para uma instalação válida do CODESYS com scripting habilitado.
  • Verifique se os caminhos de projeto e caminhos de objeto que você está passando às ferramentas estão corretos (use barras normais /).
  • Certifique-se de que nenhuma outra instância do CODESYS esteja rodando de forma conflitante (ex.: mantendo um bloqueio no perfil).

• command not found: codesys-mcp-tool:

  • Certifique-se de que o pacote foi instalado globalmente (npm install -g @codesys/mcp-toolkit).
  • Certifique-se de que o diretório bin global do npm esteja na variável de ambiente PATH do seu sistema. Encontre-o com npm config get prefix e adicione o subdiretório bin (ou o diretório principal no Windows) ao seu PATH.

• Verificar Logs:

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

🤝 Contribuindo

Contribuições, problemas e solicitações de recursos são bem-vindos! Sinta-se à vontade para verificar a página de issues. (Opcionalmente, adicione um arquivo CONTRIBUTING.md com mais detalhes).

📝 Licença

Este projeto é licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.

🙏 Agradecimentos

• A equipe da CODESYS GmbH pela poderosa plataforma CODESYS e seu mecanismo de scripting.
• O projeto Model Context Protocol por definir o padrão de interação.
• Todos os contribuidores e usuários que ajudam a melhorar este toolkit.