WinCC Unified MCP Server

Um servidor MCP para interfacear com sistemas SCADA SIEMENS WinCC Unified através de sua API GraphQL.

Documentação

Servidor MCP Unificado WinCC

Um servidor Model Context Protocol (MCP) projetado para interfacear com sistemas SCADA SIEMENS WinCC Unified por meio de sua API GraphQL. Este servidor expõe várias funcionalidades do WinCC Unified como ferramentas MCP, permitindo que assistentes de IA e outros clientes compatíveis com MCP interajam com o sistema SCADA.

Recursos

Conecta-se a um endpoint GraphQL do WinCC Unified.
Fornece ferramentas MCP para:
- Autenticação de usuário (login-user).
- Navegação por objetos SCADA (browse-objects).
- Leitura de valores atuais de tags (get-tag-values).
- Consulta de dados históricos/registrados de tags (get-logged-tag-values).
- Busca de alarmes ativos (get-active-alarms).
- Busca de alarmes registrados (get-logged-alarms).
- Escrita de valores em tags (write-tag-values).
- Reconhecimento de alarmes (acknowledge-alarms).
- Reset de alarmes (reset-alarms).
Suporta um mecanismo opcional de login automático com conta de serviço e renovação de token.

Pré-requisitos

Node.js (v18.x ou posterior recomendado).
npm (que normalmente acompanha o Node.js).
Acesso a um endpoint de servidor GraphQL WinCC Unified em execução.

Configuração

O servidor é configurado usando variáveis de ambiente:

GRAPHQL_URL: Obrigatório. A URL completa do seu servidor GraphQL WinCC Unified. Exemplo: https://your-wincc-server.example.com/graphql
GRAPHQL_USR: (Opcional) Nome de usuário para uma conta de serviço. Se fornecido junto com GRAPHQL_PWD, o servidor tentará fazer login com essas credenciais na inicialização e periodicamente (a cada minuto) para manter uma sessão. Este token é armazenado globalmente e usado pelas ferramentas se um login específico do usuário não tiver ocorrido.
GRAPHQL_PWD: (Opcional) Senha para a conta de serviço.

Exemplo de configuração de variáveis de ambiente (Linux/macOS):

export GRAPHQL_URL="http://localhost:4000/graphql"
export GRAPHQL_USR="username1"
export GRAPHQL_PWD="password1"
export NODE_TLS_REJECT_UNAUTHORIZED=0 # Set to 0 to disable TLS certificate validation (development only)

Como Iniciar

Navegue até o diretório do projeto.
Instale as dependências: Se ainda não o fez, instale os pacotes Node.js necessários:
```
npm install
```
Defina as Variáveis de Ambiente: Certifique-se de que as variáveis de ambiente GRAPHQL_URL (e opcionalmente GRAPHQL_USR, GRAPHQL_PWD) estejam definidas conforme descrito na seção "Configuração".
Execute o servidor: Você pode usar o script run.sh fornecido (no Linux/macOS):
```
./run.sh
```
O script run.sh executa export NODE_TLS_REJECT_UNAUTHORIZED=0 antes de iniciar o servidor com node index.js. A configuração NODE_TLS_REJECT_UNAUTHORIZED=0 desativa a validação de certificado TLS, o que pode ser necessário se o seu servidor GraphQL WinCC Unified usar HTTPS com um certificado autoassinado ou emitido internamente. Aviso: Desativar a validação de certificado (NODE_TLS_REJECT_UNAUTHORIZED=0) só deve ser feito em ambientes de desenvolvimento confiáveis ou redes internas, pois ignora verificações de segurança importantes.

Alternativamente, você pode executar o servidor diretamente:
```
# On Linux/macOS, if your GraphQL server uses HTTPS with a self-signed certificate:
# export NODE_TLS_REJECT_UNAUTHORIZED=0
# On Windows (PowerShell), if needed:
# $env:NODE_TLS_REJECT_UNAUTHORIZED = "0"

node index.js
```

O servidor MCP iniciará e escutará na porta 3000 por padrão. Você pode configurar a porta usando a variável de ambiente MCP_PORT:

MCP_PORT=8080 node index.js

As solicitações MCP são esperadas no endpoint /mcp (por exemplo, http://localhost:3000/mcp).

Aviso Legal

Aviso de Segurança: Este servidor não foi endurecido ou protegido para uso em produção. É responsabilidade do usuário implementar medidas de segurança apropriadas (como autenticação, autorização, restrições de rede e HTTPS) antes de implantar ou expor este servidor em qualquer ambiente.

Conectando com um Cliente Claude Desktop

Para usar este servidor MCP com o aplicativo de desktop Claude AI (ou outros clientes que suportam mcp-remote), você precisa configurar o cliente para se conectar a este servidor. Para o aplicativo Claude Desktop, isso normalmente é feito editando um arquivo claude_desktop_config.json. A localização deste arquivo varia de acordo com o sistema operacional, mas geralmente está dentro do diretório de suporte ou configuração do aplicativo Claude.

Adicione ou atualize a seção mcpServers no seu arquivo claude_desktop_config.json assim:

{
  "mcpServers": {
    "WinCC Unified": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:3000/mcp"]
    }
  }
}

Explicação:

"WinCC Unified": Este é um nome definido pelo usuário para esta conexão de servidor que aparecerá no aplicativo Claude. Você pode alterá-lo para algo significativo para você (por exemplo, "WinCC_Unified_Plant_A").
"command": "npx": Isso informa ao cliente para usar npx (Node Package Execute) para executar a ferramenta mcp-remote.
"args": ["mcp-remote", "http://localhost:3000/mcp"]:
- mcp-remote: Este é o cliente MCP de linha de comando. Certifique-se de que npx possa encontrá-lo. Você pode precisar instalar @modelcontextprotocol/tools globalmente (npm install -g @modelcontextprotocol/tools) ou tê-lo disponível em um contexto de projeto acessível por npx.
- http://localhost:3000/mcp: Esta é a URL onde seu servidor MCP Unificado WinCC está escutando. Ajuste o hostname e a porta se o seu servidor estiver em outro lugar ou em uma porta diferente.

Após salvar esta configuração, reinicie seu aplicativo Claude Desktop. Ele agora deve listar "WinCC Unified" (ou o nome escolhido) como um servidor MCP disponível, permitindo que você use suas ferramentas.

Ferramentas Disponíveis

O servidor expõe as seguintes ferramentas para interagir com o WinCC Unified:

login-user: Registra um usuário no WinCC Unified usando nome de usuário e senha. Armazena o token de sessão para solicitações subsequentes. É opcional, porque o servidor MCP pode ser iniciado de forma que faça automaticamente um login com a conta de serviço.
browse-objects: Consulta tags, elementos, tipos, alarmes, tags de registro e basicamente qualquer coisa que tenha um nome configurado, com base nos critérios de filtro fornecidos.
get-tag-values: Consulta valores de tags do WinCC Unified. Com base na lista de nomes fornecida. Se directRead for verdadeiro, os valores são obtidos diretamente do PLC.
get-logged-tag-values: Consulta valores de tags registrados no banco de dados.
get-active-alarms: Consulta alarmes ativos dos sistemas fornecidos.
get-logged-alarms: Consulta alarmes registrados do sistema de armazenamento.
write-tag-values: Atualiza tags, com base na lista TagValueInput fornecida.
acknowledge-alarms: Reconhece um ou mais alarmes. Cada identificador de alarme deve ter o nome do alarme configurado e, opcionalmente, um instanceID. Se o instanceID for 0 ou não for fornecido, todas as instâncias do alarme fornecido serão reconhecidas.
reset-alarms: Reseta um ou mais alarmes. Cada identificador de alarme deve ter o nome do alarme configurado e, opcionalmente, um instanceID. Se o instanceID for 0 ou não for fornecido, todas as instâncias do alarme fornecido serão resetadas.