# Guia do servidor MCP do Nexus — passo a passo bem fácil

**O que é isto, em uma frase:** um "tradutor" que deixa uma **IA** (como o Claude
no computador) **conversar com o Nexus** — perguntar o nível da caixa d'água, listar
dispositivos, ligar/desligar e (se você deixar) abrir portões.

**Fique tranquilo:** isto é um **extra**. Se você não instalar, nada muda no Nexus.
E a IA só consegue fazer o que a **chave de API** permitir — você controla isso.

**Você vai precisar de:** o programa **Node.js**, a pasta `deploy/nexus-mcp` do
projeto, uma **chave de API** do Nexus e uns **15 minutos**.

---

## Passo 1 — Instalar o Node.js (se ainda não tiver)

1. Abra o navegador e vá em **nodejs.org**.
2. Baixe a versão **LTS** (o botão grande da esquerda) e instale clicando **Next →
   Next → Install**.
3. Para conferir: abra o **Prompt de Comando** (Menu Iniciar → digite `cmd` → Enter)
   e digite:

```
node -v
```

✅ **Deu certo se:** apareceu um número de versão, tipo `v20.11.1` (precisa ser 18 ou maior).

---

## Passo 2 — Preparar a pasta do servidor MCP

1. Copie a pasta **`deploy\nexus-mcp`** (do projeto) para um lugar fácil, por exemplo
   `C:\nexus-mcp`.
2. No Prompt de Comando, entre na pasta e instale as dependências. **Copie e cole:**

```
cd C:\nexus-mcp
npm install
```

Espere terminar (baixa uns arquivos).

✅ **Deu certo se:** apareceu uma pasta nova `node_modules` dentro de `C:\nexus-mcp`
e não houve erro em vermelho.

---

## Passo 3 — Criar uma chave de API no Nexus

A IA vai se identificar com essa chave. Você escolhe o que ela pode fazer.

1. Entre no Nexus como administrador.
2. Vá em **Configurações → API Clients** (endereço `/api-clients`).
3. Crie uma chave nova e marque os **escopos** (permissões):
   - **automation:read** — ver dispositivos e água (recomendado).
   - **automation:control** — ligar/desligar dispositivos (recomendado).
   - **doors:open** — abrir portões. **Só marque se realmente quiser** que a IA
     possa abrir portões.
4. **Copie a chave** que aparecer (uma sequência longa de letras e números) e guarde.

✅ **Deu certo se:** você tem em mãos a chave copiada.

> Onde o Nexus atende essa API? Normalmente em `http://SEU_SERVIDOR/hb` (o mesmo
> receptor do Homebridge). Anote esse endereço trocando `SEU_SERVIDOR` pelo IP do
> servidor, por exemplo `http://172.16.0.10/hb`.

---

## Passo 4 — Ligar no Claude para computador (Claude Desktop)

1. Abra a pasta de configuração do Claude Desktop e o arquivo
   **`claude_desktop_config.json`** (no Windows costuma ficar em
   `%APPDATA%\Claude\claude_desktop_config.json`). Abra com o Bloco de Notas.
2. **Cole o bloco abaixo** dentro do arquivo. Troque o **caminho**, o **endereço** e a
   **chave** pelos seus:

```json
{
  "mcpServers": {
    "nexus": {
      "command": "node",
      "args": ["C:\\nexus-mcp\\index.mjs"],
      "env": {
        "NEXUS_URL": "http://172.16.0.10/hb",
        "NEXUS_API_KEY": "cole-sua-chave-aqui"
      }
    }
  }
}
```

Atenção: no Windows, as barras do caminho ficam **duplas** (`\\`), como no exemplo.

3. Salve o arquivo e **feche e abra o Claude Desktop** de novo.

✅ **Deu certo se:** ao abrir o Claude, aparece o servidor **nexus** na lista de
ferramentas/conectores (ícone de ferramenta).

---

## Passo 5 — Testar

No Claude, peça algo como:

> Liste os dispositivos do Nexus e me diga o nível da caixa d'água.

✅ **Deu certo se:** o Claude respondeu com a lista de dispositivos e o nível da água.

---

## Deu problema?

**"node não é reconhecido…"** — o Node não foi instalado ou o computador não foi
reiniciado. Refaça o Passo 1 e reinicie.

**Deu erro `HTTP 401`** — a chave está errada ou vazia. Confira o `NEXUS_API_KEY`
no arquivo de configuração (sem espaços).

**Deu erro `HTTP 403` ao abrir portão** — a chave não tem o escopo **doors:open**.
Crie uma chave com esse escopo (Passo 3) — ou deixe assim, se não quiser que a IA
abra portões.

**Não conecta / demora** — o `NEXUS_URL` pode estar errado ou o firewall está
bloqueando. Teste abrir `http://172.16.0.10/hb/water` no navegador do servidor
(troque pelo seu IP): deve pedir a chave ou dar uma resposta.

**A IA "inventou" um dispositivo** — peça para ela usar a ferramenta `list_devices`
antes de ligar/desligar; os ids vêm de lá.

---

Pronto! Agora sua IA enxerga o Nexus com segurança e escopo. As mesmas ferramentas
funcionam em qualquer cliente compatível com MCP — basta apontar o **comando**
(`node C:\nexus-mcp\index.mjs`) e as **variáveis** `NEXUS_URL` e `NEXUS_API_KEY`.