# Publicação da MAIDOT em cPanel

Este pacote está preparado para `mcp.maidot.pt`, Node.js `20.20.2` e as caixas `pedro.lima@maidot.pt` e `geral@maidot.pt` no servidor `mail.maidot.pt`.

## 1. Confirmar suporte do alojamento

O alojamento já disponibiliza **Setup Node.js App** e Node.js `20.20.2`, que cumprem o requisito do projecto. Antes da publicação, confirmar ainda:

- aplicações Node.js 20+ em execução permanente;
- uma variável `PORT` fornecida pelo gestor da aplicação ou uma porta interna fixa;
- HTTPS num subdomínio próprio;
- pedidos POST para `/mcp` sem cache;
- ligações TCP de saída para IMAP e SMTP.

O servidor usa MCP Streamable HTTP sem sessões e não depende de uma ligação SSE persistente. Ainda assim, alguns planos cPanel não permitem aplicações Node ou bloqueiam portas de saída; nesses casos será necessário um VPS ou outro alojamento Node.

## 2. Criar o subdomínio

```text
mcp.maidot.pt
```

Activar AutoSSL e confirmar que o certificado inclui o subdomínio. O endpoint público final será:

```text
https://mcp.maidot.pt/mcp
```

Não apontar directamente o document root para os ficheiros da aplicação. O gestor Node/Passenger deve servir como proxy para o processo.

## 3. Criar a aplicação em Setup Node.js App

Usar estes valores:

| Campo | Valor |
| --- | --- |
| Node.js version | `20.20.2` |
| Application mode | `Production` |
| Application root | `apps/cpanel-mail-mcp` |
| Application URL | `mcp.maidot.pt` |
| Application startup file | `dist/src/index.js` |

O **Application root** deve ficar fora de `public_html`. Se a conta exigir um caminho absoluto, usar `/home/CONTA/apps/cpanel-mail-mcp`, substituindo `CONTA` pelo utilizador cPanel.

Carregar o ZIP para `/home/CONTA/apps` e extraí-lo aí. O próprio pacote cria a pasta `cpanel-mail-mcp`, ficando `package.json` directamente em `/home/CONTA/apps/cpanel-mail-mcp/package.json`. Depois, criar ou actualizar a aplicação com os valores acima.

Se o ZIP for extraído dentro de uma pasta `cpanel-mail-mcp` já existente, mover o conteúdo da pasta interior um nível acima. Não pode existir uma pasta adicional entre o **Application root** e `package.json`.

## 4. Instalar as dependências

Colocar o projecto numa pasta privada da conta, por exemplo:

```text
/home/CONTA/apps/cpanel-mail-mcp
```

Se o pacote já incluir `dist/`:

```bash
npm ci --omit=dev
```

Se for carregado apenas o código-fonte:

```bash
npm ci
npm run check
npm run build
npm prune --omit=dev
```

O ficheiro de arranque é:

```text
dist/src/index.js
```

O processo respeita `process.env.PORT`. Se o painel também pedir o comando de arranque, usar:

```text
npm start
```

## 5. Criar a configuração privada

```bash
cp .env.example .env
mkdir -m 700 data
chmod 600 .env config/mailboxes.json
```

Gerar os segredos e o hash da palavra-passe:

```bash
npm run auth:secrets
npm run auth:hash -- "uma-palavra-passe-longa-e-exclusiva"
```

Configuração mínima:

```dotenv
NODE_ENV=production
HOST=127.0.0.1
BASE_URL=https://mcp.maidot.pt
STATE_DIR=data
MAILBOXES_CONFIG=config/mailboxes.json

MCP_PROFILE_ID=prf_valor_gerado
MCP_PROFILE_NAME=Pedro Lima
MCP_ADMIN_PASSWORD_HASH=scrypt$...
MCP_TOKEN_SECRET=valor_gerado

OAUTH_ALLOW_DYNAMIC_REGISTRATION=true
OAUTH_ALLOWED_REDIRECT_HOSTS=chatgpt.com,openai.com

ENABLE_DRAFTS=true
ENABLE_SEND=false

MAILBOX_MAIDOT_PEDRO_LIMA_PASSWORD=palavra-passe-de-pedro.lima@maidot.pt
MAILBOX_MAIDOT_GERAL_PASSWORD=palavra-passe-de-geral@maidot.pt
```

Em **Setup Node.js App → Environment variables**, inserir os valores sensíveis directamente no cPanel: `MCP_ADMIN_PASSWORD_HASH`, `MCP_TOKEN_SECRET`, `MAILBOX_MAIDOT_PEDRO_LIMA_PASSWORD` e `MAILBOX_MAIDOT_GERAL_PASSWORD`. Não enviar estas palavras-passe por email ou chat. `dotenv` não substitui variáveis já injectadas pelo processo.

O ficheiro `config/mailboxes.json` já está incluído e contém apenas endereços, servidor, portas e nomes das variáveis — não contém palavras-passe.

As portas assumidas são IMAP `993` com TLS e SMTP `465` com TLS. Se **Email Accounts → Connect Devices** indicar SMTP `587`, mudar cada bloco `smtp` para porta `587` e `"secure": false`.

## 6. Validar antes de ligar o ChatGPT

```bash
npm run doctor
```

O resultado esperado para cada uma das duas caixas é:

```json
{
  "mailbox_id": "maidot-pedro-lima",
  "imap": "ok",
  "smtp": "ok"
}
```

SMTP pode surgir como `not_configured` numa caixa apenas de leitura.

Depois de iniciar/reiniciar a aplicação:

```bash
curl -i https://mcp.maidot.pt/health
curl -i https://mcp.maidot.pt/.well-known/oauth-protected-resource/mcp
curl -i https://mcp.maidot.pt/.well-known/oauth-authorization-server
```

O primeiro pedido deve devolver `200`; os dois documentos OAuth devem devolver JSON.

Um POST sem autenticação para `/mcp` deve devolver `401` e um cabeçalho `WWW-Authenticate` com `resource_metadata`.

## 7. Ligar e testar por fases

1. Manter `ENABLE_SEND=false`.
2. Criar a ligação MCP no ChatGPT com `https://mcp.maidot.pt/mcp`.
3. Autorizar no ecrã OAuth.
4. Testar listagem, pesquisa, leitura e um anexo pequeno.
5. Criar um rascunho de teste e confirmar no Outlook/Webmail.
6. Só depois, se pretendido, activar `ENABLE_SEND=true`.
7. Actualizar e voltar a autorizar a ligação para conceder `mail.send`.
8. Enviar primeiro para um endereço controlado pelo próprio titular.

## 8. Cópias de segurança e rotação

Guardar cópia privada de:

- `.env` ou das variáveis mantidas no painel;
- `config/mailboxes.json`;
- `data/oauth-clients.json`.

Rodar `MCP_TOKEN_SECRET` invalida todas as ligações, referências e autorizações pendentes. Rodar `MCP_ADMIN_PASSWORD_HASH` não invalida tokens já emitidos; para uma revogação total, rodar ambos e voltar a ligar o ChatGPT.

Não copiar `data/` para uma pasta publicamente acessível.

## 9. Actualizações

```bash
npm ci
npm run check
npm run build
npm prune --omit=dev
```

Reiniciar depois a aplicação no cPanel. Se nomes, esquemas ou permissões de ferramentas mudarem, actualizar os metadados da ligação no ChatGPT e repetir os testes.