ACMP MCP Server

[!NOTE] English: MCP server for Aagon ACMP's Public API, with an activity log of every write/execute/delete action and an emergency brake that blocks them all (the four-eyes approval of version 1 is gone). 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.

Ein MCP-Server für die ACMP Public API (Aagon Client Management Platform). Ihr fragt in normaler Sprache, zum Beispiel „Welche Rechner waren seit 30 Tagen offline?“, und die KI holt sich die Antwort direkt aus ACMP.

Auf einen Blick

• Jeder MCP-Client: Claude, ChatGPT/Codex, GitHub Copilot, Gemini, Cursor …
• Breite Abdeckung: Clients, Container, Jobs/Client Commands, Tickets, Assets, Inventar, Schwachstellen und Stammdaten.
• Aktivitätsprotokoll und Notbremse: Alles wirkt sofort, vorher zeigt dryRun eine Vorschau. Jede Schreib-, Ausführ- und Löschaktion steht mit Bediener, Ziel, Absicht und Ergebnis im Protokoll, und die Notbremse auf der Weboberfläche sperrt sie alle auf einen Klick. Die Vier-Augen-Freigabe von Version 1 gibt es nicht mehr (warum).
• Pro Bediener: eigener API-Key und optional eigene ACMP-Identität. ACMP prüft dann die echten Rechte der Person.
• Eine EXE, keine Cloud: läuft direkt auf dem ACMP-Server. Kein IIS, kein .NET-SDK.
• Optional: Client Commands anlegen, freigeben, einsortieren und mit Parametern versehen, den Kiosk pflegen, Windows-Updates ablehnen, Unix Scripts schreiben, individuelle Felder anlegen und Jobs schalten, direkt in der ACMP-Datenbank. Standardmäßig aus.
• Fertige Vorlagen: In der ACMP CTL (Community Template Library) liegen Client-Command-Vorlagen mit jedem Schritt im Klartext. acmp_lib_install legt sie als Entwurf in eurer Console an.

Kompatibilität

Schnellstart

A) Von eurer KI einrichten lassen

Auf dem ACMP-Server das Repo klonen oder als ZIP entpacken. Dort einen KI-Agenten starten, der Befehle ausführen kann (Claude Code, Codex CLI, GitHub Copilot im Agent-Modus, Gemini CLI, Cursor o. Ä.), und eingeben:

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 enthält den kompletten Ablauf: Prüfung, Installation, Ersteinrichtung, LAN-Freigabe, Client-Anbindung und Fehlersuche. Die meisten Agenten lesen die Datei von selbst. Für Claude Code (CLAUDE.md), Gemini CLI (GEMINI.md) und GitHub Copilot (.github/copilot-instructions.md) liegen Verweise bei.

B) Von Hand: der Assistent im Terminal

Auf dem ACMP-Server eine PowerShell öffnen, ins Repo wechseln und starten. Fehlen Admin-Rechte, startet sich das Skript nach einer Windows-Abfrage (UAC) selbst neu:

.\install.ps1

Zum Schluss zeigt der Assistent euren API-Key und euren Web-Login (Kurzname + Web-Token für Übersicht, Aktivität, Notbremse und Onboarding), auf Wunsch kopiert er den Key in die Zwischenablage. Danach fragt er nach eurem KI-Client und zeigt die fertige Konfiguration dafür.

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

Client anbinden

Jeder MCP-Client, der Streamable HTTP mit eigenem Header kann, verbindet sich direkt:

Zum Beispiel Claude Code:

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

Claude Desktop: acmp-mcp-<version>.mcpb aus den Releases per Doppelklick installieren, dann Server-Adresse und API-Key in den Einstellungen der Erweiterung eintragen.

Fertige Konfigurationen für alle gängigen Clients stehen in docs/CLIENTS.md. Clients, die nur lokale (stdio) Server kennen, binden ihr über die Brücke mcp-remote an.

Funktionsweise

flowchart TB
    KI["KI-Client<br/>Claude · Codex · Copilot · Gemini · Cursor"]
    subgraph SRV["ACMP-Server"]
        MCP["ACMP-MCP-Server<br/>(Windows-EXE)"]
        LOG[("Aktivitätsprotokoll<br/>+ Notbremse")]
        ACMP[("ACMP<br/>Public API über SICS/AESB")]
        DB[("ACMP-Datenbank")]
    end
    TEAM(["IT im Browser<br/>Weboberfläche"])
    KI -->|"MCP · HTTP + API-Key"| MCP
    MCP -->|"lesen · schreiben · ausführen"| ACMP
    MCP -->|"jede Schreibaktion"| LOG
    TEAM -->|"Aktivität ansehen · Notbremse ziehen"| LOG
    MCP -.->|"optional: DB-Reports, Writer"| DB

Version 2: ohne Vier-Augen-Freigabe

Bis Version 1 landeten Schreib-, Ausführ- und Löschbefehle als Antrag auf einer Freigabe-Seite und liefen erst nach Zustimmung. In unserer Praxis wurde nie ein Antrag aus Sicherheitsgründen abgelehnt, die Klicks bremsten nur. Seit Version 2 wirken diese Tools sofort. Dafür gibt es:

• Vorschau: Fast alle Schreib-Tools kennen dryRun: true. Die Hinweise des Servers weisen die KI an, erst die Vorschau zu zeigen und das OK des Menschen im Chat abzuwarten, bei PowerShell und Löschen immer.
• Aktivitätsprotokoll: wer wann was auf welchem Ziel getan hat, mit Absicht und Ergebnis. Kennwörter werden maskiert.
• Notbremse: ein Schalter auf der Weboberfläche, der sofort alle Schreib-Tools für alle Bediener sperrt. Lesen und dryRun laufen weiter.

Ein Beispiel im Ablauf:

1. Ihr schreibt: „Auf PC-0815 ist die Platte voll, räum den Windows-Temp-Ordner auf.“
2. Die KI sucht den Rechner (acmp_get_client_id), prüft die Laufwerke (acmp_low_disk_space) und zeigt euch das PowerShell-Skript.
3. Nach eurem OK startet sie es (acmp_run_powershell). Der Aufruf steht sofort im Aktivitätsprotokoll.
4. Die KI meldet das Ergebnis.

Update von Version 1: git pull und .\install.ps1. Der Assistent stellt die Config um (approval → web, mit Sicherung). Eure bisherigen Freigabe-Tokens sind danach die Web-Logins. Sie standen aber in den Links der Freigabe-Mails: Erneuert sie danach mit .\renew-web-tokens.ps1 (als Administrator im Installationsordner). Auch ohne erneute Installation liest der Server eine alte approval-Section weiter (nur publicUrl, requester und approvers). Offene Freigabe-Anträge werden nicht mehr ausgeführt.

[!IMPORTANT] Ohne Freigabe hängt die Sicherheit an euren Bedienern und daran, wem ihr API-Keys gebt. Behandelt jeden Key wie ein Domänen-Admin-Passwort, lasst die KI keine Anweisungen aus Tickets, Dateien oder Webseiten ausführen und zieht im Zweifel die Notbremse.

Tools

139 Tools in 11 Bereichen. Ein Klick auf einen Bereich zeigt alle Tools mit ihrer Wirkung:

🟢 liest · 🟡 schreibt (wirkt sofort, steht im Protokoll) · 🔴 führt aus oder löscht (kritisch). 🟡 und 🔴 sperrt die Notbremse.

Welche Tools etwas ändern, zeigt auch /settings. Manche Tools brauchen eine optionale Funktion: (DB) die Datenbank-Anbindung (db.connectionString, nur lesend), (PS) die Client-Command-Vorlage (runPowershell.clientCommandId), (CW) den CC-Writer (ccWriter), (KW) den Kiosk-Writer (kioskWriter), (WW) den WUM-Writer (wumWriter), (UW) den Unix-Script-Writer (unixWriter), (FW) den Feld-Writer (cfWriter), (JW) den Job-Writer (jobWriter). Die aktuelle Liste liefert tools/list. Jedes Tool akzeptiert optional format: "json".

Beispiel-Prompts stehen in docs/USAGE.md. Neue native Kommandos ergänzt ihr deklarativ in api-tools.json, neue SQL-Reports in db-tools.json. Beides braucht kein Neu-Kompilieren.

Weboberfläche

Die Anmeldung (/login) läuft über Kurzname und ein eigenes Web-Token pro Bediener, danach über ein Sitzungs-Cookie (HttpOnly, SameSite=Strict, 12 Stunden). Das Web-Token ist unabhängig vom ACMP- oder MCP-Key: Mit einem abgeflossenen API-Key lässt sich die Notbremse nicht lösen. Alte Links aus Version 1 (?approver=…&token=…) melden nicht mehr an, denn ein Token in der Adresse landet in Mails, Browserverlauf und Proxy-Logs. renew-web-tokens.ps1 erneuert die Web-Tokens.

Konfiguration

config.example.json ist kommentiert (_hinweis-Felder). install.ps1 erzeugt daraus config.local.json.

Sicherheit

[!WARNING] Der Server gewährt vollen ACMP-Zugriff bis hin zur Befehlsausführung auf allen Endgeräten. Behandelt jeden API-Key wie ein Admin-Passwort.

• Kein TLS eingebaut. Der Server lauscht standardmäßig nur auf 127.0.0.1 und verweigert LAN-Betrieb ohne API-Key. Im LAN beschränkt ihr per Firewall die Quell-Subnetze. Über Netzgrenzen hinweg gehört ein TLS-Proxy oder VPN davor.
• install.ps1 beschränkt den Installationsordner auf Administratoren und SYSTEM, denn dort liegen Zugangsdaten.
• Notbremse und Protokoll liegen im Installationsordner (notbremse.json, activity-*.jsonl). Wer dort schreiben kann, kann beides umgehen, deshalb nur Administratoren und SYSTEM. Auf dem ACMP-/MCP-Server selbst startet der MCP keine Jobs (acmp_run_powershell, acmp_enqueue_client_command, acmp_read_registry, acmp_call), denn ein Skript als SYSTEM könnte dort config.local.json mit allen Keys lesen. Weitere Rechner, etwa den SQL-Server, schützt ihr mit runPowershell.protectedClients.
• Bediener-Passwörter werden nie gespeichert: acmp-token-setup.exe speichert nur einen DPAPI-verschlüsselten Token (LocalMachine).
• /regresult (Rückkanal für acmp_read_registry) ist bewusst ohne Key erreichbar, weil der Client den Key nicht kennt. Er nimmt nur Ergebnisse zu offenen, nicht ratbaren Tokens an.
• Sicherheitslücken bitte nicht als öffentliches Issue melden, sondern wie in SECURITY.md beschrieben.

Dokumentation

Mitmachen

Issues und Pull Requests sind willkommen. Bitte in Issues keine Logs mit Hostnamen, IPs, Benutzernamen, Keys oder Tokens posten, sondern vorher schwärzen.

Lizenz

MIT. Kein offizielles Produkt der Aagon GmbH. ACMP und AESB sind Marken der Aagon GmbH.