@renanlido/tia-openness-mcp 1.1.0 → 1.2.0

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`.