ahreas-mcp

Servidor MCP para o ERP Ahreas (Ahreas / Superlógica), o sistema de gestão de condomínios. Ele lê o catálogo de métodos direto do WSDL da sua própria instalação, descreve o que cada um faz e executa consultas e operações via SOAP com a credencial de web service da administradora. É o primeiro MCP de Ahreas — não existe hoje nenhum outro, oficial ou de comunidade.

A ideia é a mesma de manter a verdade na fonte: em vez de uma lista de métodos escrita à mão dentro do projeto, o servidor pergunta ao próprio Ahreas o que ele publica. Uma instalação real expõe cerca de 139 métodos entre os dois web services, e os módulos que a sua administradora não contratou aparecem como "sem acesso" — a mesma resposta que o ERP dá, não um erro.

O que ele consegue

Listar o catálogo de métodos lido dos WSDL de administracaoweb e Condominioweb, com busca por texto.
Descrever um método: parâmetros, formato esperado, se lê ou escreve.
Executar um método com a credencial de web service, devolvendo o conteúdo normalizado.
Diagnosticar a instalação: se os dois serviços respondem e se a credencial é aceita.

O que ele não consegue

Módulo não contratado não executa. Se a licença não cobre um método, o Ahreas recusa com "não possui acesso" e o servidor repassa isso como resposta.
Ele não emula regra de negócio. Nunca reproduz um método por conta própria; se o Ahreas não expõe, o servidor diz que não expõe.

Como cada pessoa se conecta

Há dois modos, e a autenticação do Ahreas é a mesma dos dois: cada chamada leva usuario + senha da pessoa e a chave da administradora. O Ahreas valida o usuário e a senha individualmente, então as permissões aplicadas são as daquela pessoa.

Remoto (HTTP + OAuth), multiusuário. É o modo do produto. A pessoa conecta o MCP no cliente dela (Claude, GPT, Cursor) pela URL pública; ao autorizar, abre uma tela pedindo o usuário e a senha do Ahreas dela. A chave fica no servidor. Cada sessão executa com a credencial de quem logou.
Local (stdio), pessoal. Uma pessoa só, com AHREAS_USUARIO/AHREAS_SENHA no ambiente.

As sessões vivem na memória do processo. O deploy do modo remoto tem de rodar um processo só — não subir réplicas sem um armazenamento de sessão compartilhado.

Segurança

A credencial nunca é parâmetro de ferramenta. A chave entra por variável de ambiente; o usuário e a senha vêm do login (remoto) ou do ambiente (stdio). Nenhuma tool as recebe, então o modelo não as vê e elas não aparecem no histórico da conversa.
A senha da sessão fica só na memória. O Ahreas autentica por chamada, sem token de sessão do lado dele; então a senha de quem logou fica na memória do processo enquanto a sessão vive, some no logout e na expiração, e nunca é registrada em log.
Escrita vem desligada. AHREAS_PERMITIR_ESCRITA é false por padrão. Toda operação com efeito exige, além disso, uma confirmação explícita.
Não versione o .env. Ele já está no .gitignore.

Configuração

Todas as variáveis usam o prefixo AHREAS_. Copie o .env.example como ponto de partida.

Variável	Obrigatória	Padrão	Para que serve
`AHREAS_BASE_URL`	sim	—	Endereço do Ahreas, ex. `https://sistema.suaadm.com.br`.
`AHREAS_CHAVE`	sim	—	Chave de acesso da integração (da administradora).
`AHREAS_USUARIO`	só no stdio	—	Usuário do Ahreas, no modo local.
`AHREAS_SENHA`	só no stdio	—	Senha desse usuário, no modo local.
`AHREAS_PUBLIC_URL`	só no remoto	—	URL pública do servidor; âncora do OAuth.
`AHREAS_SESSAO_HORAS`	não	`12`	Validade da sessão antes de novo login.
`AHREAS_TIMEOUT_SEGUNDOS`	não	`30`	Tempo máximo por chamada SOAP.
`AHREAS_TENTATIVAS`	não	`2`	Tentativas num soluço de rede.
`AHREAS_CACHE_WSDL_SEGUNDOS`	não	`3600`	Validade do catálogo lido do WSDL.
`AHREAS_PERMITIR_ESCRITA`	não	`false`	Libera operações que gravam no ERP.

Licença

MIT.

Aviso

Projeto independente, sem qualquer vínculo com a Ahreas ou a Superlógica. Ahreas é marca de seus detentores, citada aqui apenas para identificar o sistema com o qual este servidor se comunica.