@renanlido/tia-openness-mcp 1.0.2 → 1.1.1

package/README.md

@@ -1,7 +1,7 @@
 # TIA Openness MCP server
 
 Servidor **MCP (stdio)** que é um **cliente HTTP puro** sobre a API `serve` do TIA Openness
-(veja [../docs/API-HTTP.md](../docs/API-HTTP.md)). Não referencia Openness / net48 / x64 — toda a
+(veja `docs/API-HTTP.md` no repositório). Não referencia Openness / net48 / x64 — toda a
 complexidade (`AssemblyResolve`, worker serial MTA) vive no processo `serve`. Aqui só falamos **MCP de um
 lado** e **HTTP/JSON do outro**.
 
@@ -76,12 +76,12 @@ com o **mesmo `planHash`**. Hash errado ou `approved` ausente → envelope `requ
 re-externalizado, o "Load Preview" real não é exposto e o G3 é a salvaguarda da **camada do MCP** (não bypassável só por texto do LLM).
 
 ### M5 — ingestão de project-spec (orquestra M1–M4)
-Aceita o **project-spec** estruturado ([../docs/TIA-BEST-PRACTICES.md](../docs/TIA-BEST-PRACTICES.md) §13.2; JSON Schema em [../.claude-plugin/schemas/project-spec.schema.json](../.claude-plugin/schemas/project-spec.schema.json)):
+Aceita o **project-spec** estruturado (`docs/TIA-BEST-PRACTICES.md` §13.2; JSON Schema em `.claude-plugin/schemas/project-spec.schema.json`):
 - **`tia_spec_validate`** (R, determinístico, **sem serve**): valida forma + regras de campo cruzado — R-NAMES (nomes únicos), R-TYPEID (`OrderNumber:<MLFB>/V<fw>`), R-SUBNET (IP∈CIDR, CPU+IO na mesma subnet, 1 IO-system), R-LANGFAM (STL/GRAPH só S7-1500), R-MODLIMIT, e **G5** (`safety.required && autonomous ⇒ REJECT`).
 - **`tia_spec_plan`** (sem serve): transforma um spec válido na sequência ordenada de operações (subnets→devices→módulos→rede→tags→blocos→compile).
 - **`tia_spec_apply`**: orquestra o build OFFLINE num projeto aberto (valida → G5 → executa serial → compila), **para no 1º erro** e **nunca baixa** (download é o GATE G3, sempre humano). `dryRun:true` devolve o plano.
 
-> **MCP M0–M5 COMPLETO** (73 tools). O que falta é **runtime** (validar contra um TIA real — precisa reload + serve + hardware nos gates) e o **C# P0.5** (re-externalizar o auto-confirm do download p/ o G3 expor o Load-Preview de verdade). Detalhe em [../docs/ROADMAP.md](../docs/ROADMAP.md) §3.
+> **MCP M0–M5 COMPLETO** (~74 tools), **validado em runtime** contra um TIA Portal V21 real (incluindo **deploy em hardware** num S7-1200) e **publicado no npm**. Roadmap e marcos em `docs/ROADMAP.md` §3.
 
 ## Configuração (env)
 
@@ -149,7 +149,7 @@ npm install -g .                               # o prepack compila e instala o b
 ## Publicação (npm público + semantic-release)
 
 Versionamento **automático por commits convencionais** (`feat` → minor, `fix` → patch, `BREAKING CHANGE`
-→ major). O workflow [../.github/workflows/release-mcp.yml](../.github/workflows/release-mcp.yml) dispara
+→ major). O workflow `.github/workflows/release-mcp.yml` dispara
 no push para `main` **quando algo em `mcp/` muda** (e `semantic-release-monorepo` filtra os commits por
 esse path), builda e publica no **npm público** (`registry.npmjs.org`, `publishConfig.access: public`).
 
@@ -169,16 +169,24 @@ commitar o `CHANGELOG`.
 > Config validada localmente: versões dedupadas em `semantic-release@24`; o dry-run carregou config/plugins
 > e só parou por o repo remoto ainda não existir.
 
-## Registro no Claude Code (escopo de projeto)
+## Registro no Claude Code
 
-O [../.mcp.json](../.mcp.json) na raiz já registra o servidor `tia` apontando para o binário instalado:
+**Não precisa instalar nada** — o recomendado é o `npx`, que baixa e roda o pacote publicado. Um comando
+só (escopo de **usuário**):
+
+```bash
+claude mcp add --transport stdio --env TIA_API_BASE=http://localhost:5000 --scope user tia -- npx -y @renanlido/tia-openness-mcp
+```
+
+Confira com `claude mcp list` e `claude mcp get tia`. O equivalente por **`.mcp.json`** na raiz do projeto
+(escopo de **projeto**) — também via `npx`, sem instalar:
 
 ```jsonc
 {
   "mcpServers": {
     "tia": {
-      "command": "tia-openness-mcp",          // binário do pacote (PATH); requer instalação (A ou B)
-      "args": [],
+      "command": "npx",                              // baixa e roda o pacote do npm — NADA instalado
+      "args": ["-y", "@renanlido/tia-openness-mcp"],
       "env": {
         "TIA_API_BASE": "${TIA_API_BASE:-http://localhost:5000}"      // IP:porta do serve (use o IP da VM se remoto)
       }
@@ -187,6 +195,15 @@ O [../.mcp.json](../.mcp.json) na raiz já registra o servidor `tia` apontando p
 }
 ```
 
+> **`tia-openness-mcp` NÃO é um arquivo do repositório** — é o nome do **bin** do pacote (`package.json` →
+> `"bin": { "tia-openness-mcp": "dist/index.js" }`). Esse atalho só fica no seu PATH **se** você instalar
+> global (`npm install -g @renanlido/tia-openness-mcp`); só então faria sentido
+> `"command": "tia-openness-mcp", "args": []`. O `npx` dispensa esse passo — por isso é o recomendado.
+
+**Outros clientes** (Claude Desktop, Codex, Gemini CLI, Cursor, VS Code, Windsurf): o guia canônico de
+instalação — com os formatos exatos de cada um e a pegadinha do `cmd /c npx` no Windows — está em
+`docs/INSTALL.md` no repositório.
+
 **Envs opcionais** (default embutido no MCP — só defina para sobrescrever): `TIA_API_TIMEOUT_MS` (15000),
 `TIA_SLOW_TIMEOUT_MS` (120000), `TIA_CONNECT_TIMEOUT_MS` (30000). Ex.: `--env TIA_SLOW_TIMEOUT_MS=180000`
 no `claude mcp add`, ou a chave correspondente no `env` do `.mcp.json`.

package/dist/index.js

@@ -31539,6 +31539,14 @@ async function deviceCreateFlow(args) {
     summary: `criar device "${args.deviceName ?? args.deviceItemName ?? "?"}" (${args.typeIdentifier})`
   });
 }
+async function deviceChangeVersionFlow(args) {
+  const bad = gd5Violation(args.typeIdentifier);
+  if (bad) return guardError("Gd5", bad, { typeIdentifier: args.typeIdentifier });
+  return mutate("POST", `/plcs/${seg2(args.plc)}/device/changeversion`, jsonBody2({ typeIdentifier: args.typeIdentifier, dryRun: args.dryRun }), {
+    dryRun: args.dryRun,
+    summary: `trocar firmware da CPU "${args.plc}" para ${args.typeIdentifier}`
+  });
+}
 var dryRunField = {
   dryRun: external_exports.boolean().optional().describe("Gd11: plano-sem-aplicar \u2014 valida os guards e descreve a a\xE7\xE3o SEM mutar o projeto")
 };
@@ -31557,6 +31565,19 @@ function registerAuthoringTools(server2) {
     },
     async (args) => deviceCreateFlow(args)
   );
+  server2.registerTool(
+    "tia_device_change_version",
+    {
+      title: "TIA \u2014 trocar firmware da CPU (in-place)",
+      description: "Troca a vers\xE3o de FIRMWARE da CPU IN-PLACE (wrap do DeviceItem.ChangeType), PRESERVANDO o programa \u2014 alternativa ao delete+recreate (habilita o 'auto-FW-match'). Guard Gd5: o typeIdentifier segue 'OrderNumber:<MLFB>/V<fw>' com '/V' (barra), nunca ':V' \u2014 resolva via tia_catalog. Regra: a vers\xE3o de firmware do PROJETO deve ser \u2264 a do DEVICE f\xEDsico (project FW \u2264 device FW). dryRun (Gd11) devolve o plano sem mutar. Mapeia POST /plcs/{plc}/device/changeversion. Classe M-off.",
+      inputSchema: {
+        plc: external_exports.string().describe("nome do CLP (CPU) cujo firmware ser\xE1 trocado"),
+        typeIdentifier: external_exports.string().describe('OrderNumber:<MLFB>/V<fw> do firmware destino (Gd5; resolva via tia_catalog) \u2014 ex.: "OrderNumber:6ES7 214-1HG40-0XB0/V4.4"'),
+        ...dryRunField
+      }
+    },
+    async ({ plc, typeIdentifier, dryRun }) => deviceChangeVersionFlow({ plc, typeIdentifier, dryRun })
+  );
   server2.registerTool(
     "tia_device_plug",
     {
@@ -32441,7 +32462,7 @@ function registerSpecTools(server2) {
 }
 
 // src/index.ts
-var server = new McpServer({ name: "tia-openness", version: "1.0.2" });
+var server = new McpServer({ name: "tia-openness", version: "1.1.1" });
 server.registerTool(
   "tia_ping",
   {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@renanlido/tia-openness-mcp",
-  "version": "1.0.2",
+  "version": "1.1.1",
   "description": "MCP server (stdio) — thin HTTP client over the TIA Openness `serve` API. Zero Openness/net48 references.",
   "license": "MIT",
   "type": "module",