ACMP MCP Server

[!NOTE] English: MCP server for Aagon ACMP's Public API, with a built-in four-eyes approval gate for write/execute/delete actions. Runs as a single Windows EXE on the ACMP server and works with any MCP client. Docs are in German because ACMP's user base is mostly DACH; issues in English are welcome.

Um servidor MCP para a ACMP Public API (Aagon Client Management Platform). Você pergunta em linguagem natural, por exemplo: "Quais computadores estão offline há 30 dias?", e a IA busca a resposta diretamente no ACMP.

De relance

• Qualquer cliente MCP: Claude, ChatGPT/Codex, GitHub Copilot, Gemini, Cursor …
• Ampla cobertura: Clientes, contêineres, jobs/client commands, chamados, ativos, inventário, vulnerabilidades e dados mestre.
• Aprovação de quatro olhos: Leitura é imediata. Tudo o que altera, executa ou exclui só acontece quando uma pessoa aprova na página de aprovação; para ações críticas, duas pessoas diferentes.
• Por operador: chave de API própria e, opcionalmente, identidade ACMP própria. O ACMP verifica então as permissões reais da pessoa.
• Um EXE, sem nuvem: roda diretamente no servidor ACMP. Sem IIS, sem .NET-SDK.
• Opcional: criar, aprovar e organizar client commands, além de manter o kiosk, diretamente no banco de dados do ACMP. Desativado por padrão.
• Modelos prontos: Na ACMP CTL (Community Template Library) há modelos de client command com cada etapa em texto claro. acmp_lib_install os cria como rascunho na sua console.

Compatibilidade

Início rápido

A) Configurar pela sua IA

No servidor ACMP, clone o repositório ou descompacte como ZIP. Inicie um agente de IA que possa executar comandos (Claude Code, Codex CLI, GitHub Copilot no modo agente, Gemini CLI, Cursor ou similar) e digite:

Richte diesen ACMP-MCP-Server auf diesem Rechner ein. Folge AGENTS.md Schritt für Schritt,
erkläre mir jeden Admin-Schritt, bevor ich ihn ausführe, und frag mich nie nach Passwörtern
oder API-Keys im Chat.

AGENTS.md contém o fluxo completo: verificação, instalação, configuração inicial, liberação na rede, conexão do cliente e solução de problemas. A maioria dos agentes lê o arquivo por conta própria. Para Claude Code (CLAUDE.md), Gemini CLI (GEMINI.md) e GitHub Copilot (.github/copilot-instructions.md) há referências incluídas.

B) Manualmente: o assistente no terminal

No servidor ACMP, abra um PowerShell, entre no repositório e inicie. Se faltarem direitos de administrador, o script se reinicia após uma confirmação do Windows (UAC):

.\install.ps1

Ao final, o assistente mostra sua chave de API e os links para a página de aprovação, o painel e o onboarding; se desejar, ele copia a chave para a área de transferência. Depois, ele pergunta sobre seu cliente de IA e mostra a configuração pronta para ele.

cd C:\ProgramData\AcmpMcp
.\add-user.ps1

Conectar cliente

Qualquer cliente MCP que suporte Streamable HTTP com cabeçalho próprio conecta-se diretamente:

Por exemplo, Claude Code:

claude mcp add --transport http acmp http://<HOST>:8765/ --header "Authorization: Bearer <KEY>" --scope user

Claude Desktop: instale acmp-mcp-<version>.mcpb dos Releases com um duplo clique e insira o endereço do servidor e a chave de API nas configurações da extensão.

Configurações prontas para todos os clientes comuns estão em docs/CLIENTS.md. Clientes que só conhecem servidores locais (stdio) podem ser conectados pela ponte mcp-remote.

Como funciona

flowchart TB
    KI["KI-Client<br/>Claude · Codex · Copilot · Gemini · Cursor"]
    subgraph SRV["ACMP-Server"]
        MCP["ACMP-MCP-Server<br/>(Windows-EXE)"]
        GATE{{"Freigabe-Seite"}}
        ACMP[("ACMP<br/>Public API über SICS/AESB")]
        DB[("ACMP-Datenbank")]
    end
    TEAM(["Freigeber im Browser"])
    KI -->|"MCP · HTTP + API-Key"| MCP
    MCP -->|"lesen: sofort"| ACMP
    MCP -->|"schreiben · ausführen · löschen"| GATE
    TEAM -->|"1 bzw. 2 Personen stimmen zu"| GATE
    GATE -->|"erst dann"| ACMP
    MCP -.->|"optional: DB-Reports, Writer"| DB

Como é a aprovação

Quando a IA solicita um comando de escrita, execução ou exclusão, ele chega como solicitação na página de aprovação. Nada é executado até que pessoas diferentes suficientes tenham aprovado. As imagens mostram uma instância de demonstração com dados fictícios.

Um exemplo do fluxo:

1. Você escreve: "O disco do PC-0815 está cheio; limpe a pasta Temp do Windows."
2. A IA procura o computador (acmp_get_client_id), verifica os discos (acmp_low_disk_space) e cria uma solicitação de PowerShell (acmp_run_powershell).
3. Na página de aprovação, dois colegas veem o script em texto claro e clicam em "Aprovar".
4. Somente então o script é executado no cliente, e a IA informa o resultado.

Ferramentas

118 ferramentas em 10 áreas. Um clique em uma área mostra todas as ferramentas com seu nível de aprovação:

🟢 executa imediatamente (somente leitura) · 🟡 aprovação por 1 pessoa · 🔴 aprovação por 2 pessoas diferentes

Os níveis são os valores padrão do código e podem ser ajustados por ferramenta em /settings. Algumas ferramentas exigem uma função opcional: (DB) a conexão com o banco de dados (db.connectionString, somente leitura), (PS) o modelo de client command (runPowershell.clientCommandId), (CW) o CC-Writer (ccWriter), (KW) o Kiosk-Writer (kioskWriter). A lista atual é fornecida por tools/list. Cada ferramenta aceita opcionalmente format: "json".

Exemplos de prompts estão em docs/USAGE.md. Novos comandos nativos são adicionados declarativamente em api-tools.json, novos relatórios SQL em db-tools.json. Ambos não exigem recompilação.

Interface web

O login usa um token próprio por aprovador e é independente da chave ACMP ou MCP: uma chave de API vazada não concede direitos de aprovação.

Configuração

config.example.json é comentado (campos _hinweis). install.ps1 gera config.local.json a partir dele.

Segurança

[!WARNING] O servidor concede acesso total ao ACMP, incluindo execução de comandos em todos os dispositivos finais. Trate cada chave de API como uma senha de administrador.

• Sem TLS integrado. O servidor escuta apenas em 127.0.0.1 por padrão e recusa operação em LAN sem chave de API. Na LAN, restrinja os subnets de origem via firewall. Através de limites de rede, coloque um proxy TLS ou VPN na frente.
• install.ps1 restringe a pasta de instalação a administradores e SYSTEM, pois é onde ficam as credenciais.
• Senhas de operadores nunca são armazenadas: acmp-token-setup.exe armazena apenas um token criptografado com DPAPI (LocalMachine).
• /regresult (canal de retorno para acmp_read_registry) está intencionalmente acessível sem chave, porque o cliente não conhece a chave. Ele aceita apenas resultados para tokens abertos e não adivinháveis.
• Por favor, não relate vulnerabilidades de segurança como issue público, mas sim conforme descrito em SECURITY.md.

Documentação

Contribuir

Issues e pull requests são bem-vindos. Por favor, não poste logs com nomes de host, IPs, nomes de usuário, chaves ou tokens em issues, mas masque-os antes.

Licença

MIT. Não é um produto oficial da Aagon GmbH. ACMP e AESB são marcas da Aagon GmbH.