@renanlido/tia-openness-mcp 1.0.0

package/README.md

@@ -0,0 +1,207 @@
+# 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
+complexidade (`AssemblyResolve`, worker serial MTA) vive no processo `serve`. Aqui só falamos **MCP de um
+lado** e **HTTP/JSON do outro**.
+
+**Cross-platform:** o MCP é Node puro (bundle ESM com shebang) e roda em **macOS / Linux / Windows**
+(Node ≥ 20). Só a **API `serve` é Windows-only** (net48/x64 + Openness) — por isso o arranjo canônico é
+**MCP no seu laptop (ex.: Mac) → `serve` num host/VM Windows**, apontado por env (veja abaixo).
+
+Distribuído como **pacote npm bundled** (esbuild → 1 arquivo self-contained, sem `node_modules` em runtime),
+publicado no **npm público** via **semantic-release** — rode com um one-liner, **sem auth e sem `.npmrc`**:
+
+```bash
+npx -y @renanlido/tia-openness-mcp
+```
+
+## Tools
+
+### Diagnóstico + M1 read-only (classe R, auto-aprováveis)
+| Tool | Endpoint | Descrição |
+|---|---|---|
+| `tia_ping` | `GET /health` + `GET /readiness` | Diagnostica conectividade e ATIVAÇÃO do `serve`. `{ base, reachable, activated, latencyMs, hint }`. Ideal p/ Mac→VM. |
+| `tia_readiness` | `GET /readiness` | Prontidão do ambiente **no host do serve** (x64, grupo Windows, PublicAPI, registro, instâncias). |
+
+**M1 (read-only, 1:1 com os GET da API):** `tia_instances`, `tia_status`, `tia_projects`, `tia_project_info`,
+`tia_project_languages`, `tia_plcs`, `tia_devices`, `tia_device_tree`, `tia_device_connections`,
+`tia_plc_blocks/types/tags/watchtables`, `tia_catalog`, `tia_connections_diagnose`, `tia_subnets`,
+`tia_obj_roots/get/items/info/creationinfos/services`. Nenhuma muta estado.
+
+### M2 — ciclo de vida (classe M-off) + GATE de confiança (G1)
+| Tool | Endpoint | Descrição |
+|---|---|---|
+| `tia_start` | `POST /tia/start` | Inicia/anexa o TIA **sem projeto** (`headless` opcional). |
+| `tia_show_ui` | `POST /tia/show-ui` | Relança o TIA headless como **visível** p/ renderizar o diálogo de confiança (habilita o G1). |
+| `tia_connect` | `POST /connect` | Abre/anexa um projeto. **Pode bloquear no GATE G1** → devolve um envelope `requires_human_action` (sem retry-storm) com `resumeToken`. UMAC (G6) só se um humano fornecer. |
+| `tia_disconnect` | `POST /disconnect` | Desconecta (Gd3: use `tia_project_close` p/ liberar o lock). |
+| `tia_project_create` | `POST /project/create` | Cria projeto (Gd4: diretório vazio → senão 409). |
+| `tia_project_save` / `tia_project_saveas` / `tia_project_close` / `tia_project_archive` | `POST /project/*` | Ciclo de vida do projeto. |
+
+**GATE de confiança (G1):** na 1ª conexão por processo `serve`, o TIA exige confirmação manual de um diálogo
+de segurança NO HOST. O fluxo proativo é **`tia_start` → `tia_show_ui` → (humano confirma) → `tia_connect`**.
+Se o `tia_connect` esbarra no diálogo, ele NÃO faz retry-storm: devolve `{ status:"requires_human_action",
+gate:"trust_dialog", youMustDo, resumeToken }`. Após o humano confirmar, re-chame `tia_connect` com o `resumeToken`.
+
+### M3 — criação/autoria offline (classe M-off) + guards
+Superfície de **criação compliant-by-construction** (~28 tools), todas com `dryRun` (Gd11) e validação por schema (Gd13):
+- **Hardware/rede:** `tia_device_create`/`plug`/`unplug`, `tia_device_group_create`, `tia_subnet_create`, `tia_network_connect`/`address`/`disconnect`.
+- **Tags/constantes:** `tia_tagtable_create`, `tia_tag_create`/`delete`, `tia_constant_create`.
+- **Blocos/tipos:** `tia_fb_create`, `tia_instancedb_create`, `tia_block_delete`/`set_attribute`, `tia_block_group_create`, `tia_type_group_create`/`type_delete`.
+- **Código:** `tia_source_put` (SCL textual — Gd6), `tia_import_xml`/`tia_types_import` (SimaticML gráfico — Gd6/Gd7), `tia_export_xml`.
+- **Watch tables:** `tia_watchtable_create`/`delete`.
+- **Camada genérica de escrita:** `tia_obj_set_attributes`/`invoke`/`create`.
+
+**Guards (client-side, antes de tocar o Openness):** **Gd5** — `typeIdentifier` deve usar `/V<fw>` (barra), nunca `:V`
+(rejeitado com `kind:"guard_violation"`; resolva o valor via `tia_catalog`). **Gd11** — `dryRun:true` valida os guards
+e retorna o **plano por nome SEM mutar** (`status:"plan_ok"`). **Gd6** (advisório) — linguagem textual (SCL) via
+`tia_source_put`, gráfica (LAD/FBD/GRAPH) via `tia_import_xml`; UDTs antes dos blocos. **Gd2** (advisório) — idempotência
+por nome (cheque a existência com as tools read-only do M1 antes de criar; o Openness não tem rollback).
+
+### M4 — verificação + deploy GATED (hardware)
+| Tool | Endpoint | Gate/classe |
+|---|---|---|
+| `tia_compile` | `POST /plcs/{plc}/compile` | M-off — **o verificador**. Achata a árvore de mensagens + `verification:{compiled,errors,warnings}` + `nextHints` (Gd8: só ERRO bloqueia). |
+| `tia_connection_create` | `POST /connections` | M-off — conexão S7 (G2: exige ≥2 CPUs consistentes; falha anexa diagnóstico). |
+| `tia_download` | `POST /plcs/{plc}/download` | **GATE G3** — não baixa sem aprovação humana vinculada ao `planHash`. |
+| `tia_online` / `tia_offline` / `tia_online_state` | `POST /plcs/{plc}/online`·`/offline`·`GET …/state` | **G4** (online) / R (state). |
+| `tia_accessible_devices` | `POST /plcs/{plc}/online/accessibledevices` | **GATE G7** (net scan). |
+| `tia_mastersecret_set` / `tia_mastersecret_reset` | `…/online/mastersecret` | **GATE G6** (segredo vem do humano, nunca da IA). |
+
+**GATE de download (G3):** `tia_download` NUNCA baixa sem aprovação. Fluxo: `tia_compile` (precondição Gd9: `errors=0`) →
+`tia_download dryRun:true` (devolve `plan` + `planHash`, sem baixar) → um humano aprova → `tia_download approved:true`
+com o **mesmo `planHash`**. Hash errado ou `approved` ausente → envelope `requires_human_action / download_approval`.
+**Limitação honesta:** o `serve` ainda **auto-confirma** StopAll/Overwrite (backlog C# **P0.5**); até isso ser
+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)):
+- **`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.
+
+## Configuração (env)
+
+| Var | Default | Uso |
+|---|---|---|
+| `TIA_API_BASE` | `http://localhost:5000` | Base URL da API `serve`. |
+| `TIA_API_TIMEOUT_MS` | `15000` | Timeout por request (falha rápido se o host/VM não responde). |
+
+> **O MCP não envia chave.** A API é **ativada por uma licença** configurada na GUI (aba "Licença") — quem
+> autoriza o servidor é a licença do host, não o cliente. O MCP é um cliente HTTP normal: só aponta a base.
+
+## Cenário Mac → VM Windows (apontar o servidor)
+
+1. **Na VM Windows**, ative o servidor com uma licença válida (aba "Licença" da GUI, ou `--license`) e
+   suba aceitando conexões externas (a API **recusa bind não-loopback se NÃO estiver ativada**):
+   ```powershell
+   .\bin\Debug\net48\TIAOpenness.exe serve 5000 --host 0.0.0.0 --license TIA1.xxxxx.yyyyy
+   ```
+   Libere a porta no firewall do Windows e garanta rede acessível (bridged ou NAT com port-forward).
+   Controle de **acesso** de quem chama = firewall/VPN (a licença ativa o servidor, não autentica clientes).
+2. **No Mac**, aponte o MCP para a VM:
+   ```bash
+   export TIA_API_BASE="http://<ip-da-vm>:5000"
+   ```
+3. **Diagnostique** com o tool `tia_ping`: `reachable:false` → IP/porta/firewall/VM; `activated:false` →
+   licença ausente/inválida na VM; ambos `true` → pronto.
+
+## Build / bundle
+
+```bash
+# garanta o Node (no Windows com nvm-windows: $env:Path = "C:\nvm4w\nodejs;" + $env:Path)
+cd mcp
+npm install
+npm run build         # typecheck + esbuild -> dist/index.js (self-contained)
+```
+
+## Instalação
+
+### A) Do npm público (uso normal, Mac/Windows/Linux)
+
+Pacote **público** — **sem auth, sem `.npmrc`**. Use direto via `npx` ou instale o binário global:
+
+```bash
+npx -y @renanlido/tia-openness-mcp             # roda sem instalar (recomendado p/ .mcp.json)
+# ou instale o binário `tia-openness-mcp` no PATH:
+npm install -g @renanlido/tia-openness-mcp
+```
+
+### B) Local, sem publicar (dev nesta máquina)
+
+```bash
+cd mcp
+npm install -g .                               # o prepack compila e instala o binário
+# ou: npm pack && npm install -g ./renanlido-tia-openness-mcp-*.tgz
+```
+
+## 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
+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`).
+
+Usa **dois tokens**: `NPM_TOKEN` (secret a configurar — token *Automation/Publish* do npmjs.org) para o
+**publish** via `@semantic-release/npm`, e o `GITHUB_TOKEN` nativo do Actions para criar a release/tag e
+commitar o `CHANGELOG`.
+
+**Para ligar (passos com credencial, uma vez):**
+1. Crie o repo no GitHub (`renanlido/TIAOpenness`) — ou ajuste `repository.url`/scope no `package.json` e
+   o workflow se o owner for outro.
+2. **Configure o secret `NPM_TOKEN`** no repositório (Settings → Secrets and variables → Actions): gere um
+   token de *Automation* em npmjs.org com permissão de publish no pacote `@renanlido/tia-openness-mcp`.
+3. `git add . && git commit -m "feat: initial commit"` → `git branch -M main` →
+   `git remote add origin <url>` → `git push -u origin main`.
+4. A partir daí, **commits convencionais** na `main` disparam o release automaticamente.
+
+> 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)
+
+O [../.mcp.json](../.mcp.json) na raiz já registra o servidor `tia` apontando para o binário instalado:
+
+```jsonc
+{
+  "mcpServers": {
+    "tia": {
+      "command": "tia-openness-mcp",          // binário do pacote (PATH); requer instalação (A ou B)
+      "args": [],
+      "env": {
+        "TIA_API_BASE": "${TIA_API_BASE:-http://localhost:5000}"      // IP:porta do serve (use o IP da VM se remoto)
+      }
+    }
+  }
+}
+```
+
+**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`.
+
+Como é servidor de **escopo de projeto**, o Claude Code pede **aprovação** na 1ª vez: `claude mcp list`
+(deve listar `tia`), rode `claude` no projeto e **aprove**, **recarregue** a sessão, e peça para chamar
+`tia_ping` / `tia_readiness`.
+
+## Smoke test
+
+```bash
+npm run smoke                                                   # alvo = dist/index.js local
+# apontar para o binário global:
+MCP_COMMAND=tia-openness-mcp MCP_ARGS='[]' npm run smoke        # (Windows: use o caminho do .cmd)
+```
+
+## Notas
+
+- **O MCP não envia chave/segredo.** A API é ativada por licença no host (GUI). Segredos (master secret /
+  UMAC / senha de cert) nunca vão no `.mcp.json`.
+- **Serial-only**: o backend é um worker serial; o MCP nunca deve paralelizar tool calls (Gd1).
+- **stdout é do protocolo MCP** — logs vão para **stderr**.
+- O bundle é gerado por [scripts/build.mjs](scripts/build.mjs) (esbuild, ESM, shebang + `createRequire`,
+  versão injetada). `dist/`, `node_modules/`, `*.tgz` são artefatos (gitignored).
+- Ao adicionar/alterar tools, **rebuild + reinstalar** o binário (`npm run build && npm i -g .`) para a
+  instalação local refletir; em produção, o push para `main` republica.