itglue-mcp

{"type": "text"}# itglue-mcp

Schreibgeschützter MCP-Server über den IT-Glue-Mandanten von Example Corp / examplecorp (your-company.itglue.com). Beantwortet aus dem Chat „Was wissen wir über diesen Kunden?" und beantwortet „Was sind die Anmeldedaten für X?" mit einem IT-Glue-Link statt eines Geheimnisses.

Aufgebaut auf dem hauseigenen Remote-MCP-Standard: fastmcp-Ressourcenserver + Entra-ID-Authentifizierung, hinter Nginx Proxy Manager auf Portainer. Siehe ~/.claude/context/mcp-server-playbook.md.

Erkenntnisse aus der API- und Inhaltsprüfung, die dieses Design geprägt haben, finden Sie in FEASIBILITY.md. Lesen Sie §0 und §1, bevor Sie etwas ändern.

Die zwei Garantien

1. Es wird nie etwas in IT Glue geschrieben

Der verwendete API-Schlüssel hat volle Schreib- und Löschrechte. Verifiziert, nicht angenommen:

PATCH  /configurations/999999999  -> 404 "Record not found"
PATCH  /passwords/999999999       -> 404 "Record not found"
DELETE /configurations/999999999  -> 404

Ein Schlüssel ohne Schreibberechtigung schlägt mit 401/403 fehl, bevor die Datensatzsuche stattfindet. Eine 404 bedeutet, dass die Mutation autorisiert war und lediglich nichts zu tun hatte. IT Glue gibt keine klassischen API-Schlüssel mit Lesebereich aus, daher gibt es keine serverseitige Berechtigung, auf die man sich stützen kann — die Garantie liegt vollständig in dieser Codebasis:

• client.py stellt genau eine Anforderungsmethode bereit, get(), die method="GET" fest codiert.

• Es gibt keinen post/patch/put/delete-Helfer. Einen hinzuzufügen ist eine Sicherheitsregression, kein Feature.

• Ein WriteAttemptError-Auslöser feuert, wenn jemals ein Nicht-GET konstruiert wird.

• tests/smoke_local.py prüft sowohl die fehlenden Methoden als auch die fehlenden Verben.

Wenn jemals ein Rückschreiben gebaut wird (FEASIBILITY.md Option C), erfolgt es in einem separaten Prozess mit einem separaten Schlüssel. Diese Trennung ist das gesamte Sicherheitsargument, denn IT-Glue-Dokumente sind kundenerstellter Text, den ein Modell zusammenfasst — also nicht vertrauenswürdige Eingabe.

2. Es wird nie ein Anmeldedatenwert zurückgegeben

itglue_find_credential gibt einen Zeiger zurück: den Namen der Anmeldedaten, die Kategorie, zu welchem Gerät sie gehören, wann sie zuletzt rotiert wurden, ob OTP aktiviert ist, und einen IT-Glue-Deep-Link. Der Mensch klickt auf den Link und meldet sich bei IT Glue an, um das Geheimnis zu enthüllen.

Die Schwärzung erfolgt auf dem Weg in den Spiegel (redact.py), sodass kein nachgelagertes Tool ein Feld leaken kann, indem es vergisst, es zu entfernen. Datensätze, die IT Glue als restricted markiert, werden vollständig verworfen.

Related MCP server: invgate-mcp

Warum es einen lokalen Spiegel gibt

IT Glues filter[name] ist nur exakte Übereinstimmung, und einige Filter werden stillschweigend ignoriert statt abgelehnt:

Die serverseitige Suche benötigt also entweder die exakte Zeichenfolge, die das Modell nicht hat, oder sie lügt still. Daher wird alles in den RAM gespiegelt und lokal durchsucht (search.py, index.py).

Sync-Kosten, gemessen: ~10 Anfragen für ~7.000 strukturierte Datensätze; ~400 Anfragen für 300 Dokumentkörper (95 Organisationslisten + Abrufe pro Dokument), bei einer Obergrenze von 3.000 pro 5 Minuten. Der Kern erwärmt sich in Sekunden; Dokumente erwärmen sich im Hintergrund über einige Minuten, und Dokumenttools melden status: indexing, anstatt zu hängen.

Es wird nichts auf der Festplatte gespeichert — der Korpus ist klein, sodass ein Neustart einfach neu synchronisiert und es keinen Fehlermodus für veralteten Cache gibt.

Die Suche ist bewusst nachsichtig, weil echte Abfragen wie „EF Vista Del Mar Unified Controller" aussehen: ein Akronym, ein vollständiger Name und ein Produkt, das in den Daten als Unifi geschrieben ist. Behandelt durch Akronymabgleich (EF → Example Foundation), Fuzzy-Abgleich pro Wort (unified ≈ unifi, Verhältnis 0,83), Subtraktion von Organisations-Tokens und atomare Identifikatorbehandlung, sodass 192.0.2.51 nicht in ['10','105','251'] zerlegt wird.

Werkzeuge

Alle sind mit readOnlyHint: true annotiert.

Die Abfrage, für die dies gebaut wurde

„Was sind die Anmeldedaten für den Example Foundation UniFi-Controller?"

itglue_find_credential leitet die Organisation aus dem Satz ab, subtrahiert deren Namenswörter, führt einen Fuzzy-Abgleich von unified→unifi über 460 EF-Anmeldedatensätze durch und gibt fünf Zeiger zurück — die zwei auf dem aktuellen Unifi Controller (New Staging) und die drei älteren VDM_Cloudwifi-Anmeldungen — jeweils mit einem klickbaren Link, der Geräte-URL und dem Datum der letzten Rotation. Kein Geheimnis verlässt den Server.

Lokale Entwicklung

python -m venv .venv && .venv/Scripts/activate    # Windows
pip install -r requirements.txt
cp .env.example .env      # fill in ITGLUE_API_KEY; set MCP_AUTH_ENABLED=false
python -m itglue_mcp

Setzen Sie niemals einen Server ohne Authentifizierung ein. MCP_AUTH_ENABLED=false ist nur für MCP Inspector auf localhost.

Smoke-Test (live, schreibgeschützt)

python tests/smoke_local.py

47 Assertions gegen den Live-Mandanten. Liest ~/.claude/credentials/itglue.env, wenn ITGLUE_API_KEY nicht in der Umgebung gesetzt ist, und benötigt keine fastmcp-Installation. Die Anmeldedaten-Assertions sind die wichtigen — wenn eine fehlschlägt, stoppen und beheben, bevor Sie bereitstellen.

Bereitstellung

1. Entra-App + Gruppe + Token-Lebensdauer — scripts/setup_entra_app.ps1 (standardmäßig Trockenlauf; -Apply zum Ausführen). Stellt die App, die Sicherheitsgruppe ITGlue-MCP-Users mit den fünf anfänglichen Mitgliedern, Zuweisungsdurchsetzung und eine 23h59m-Zugriffstoken-Lebensdauerrichtlinie bereit. Siehe docs/ENTRA_SETUP_CHECKLIST.md.

2. Portainer-Stack + NPM — PORTAINER_DEPLOY.md. Host-Port 8111 (am 29.07.2026 auf 10.0.0.10 als frei geprüft — 8100 und 8110 sind belegt). Öffentlicher Host itglue-mcp.example.com.

Wartung

• IT-Glue-Schlüssel rotieren — noch offen. Er liegt jetzt unter ~/.claude/credentials/itglue.env im hauseigenen KEY=VALUE-Format (migriert am 30.07.2026 von einer Klartext-Datei .itglueapicreds.txt), aber das war eine Formatänderung, keine Rotation — der Schlüsselwert ist unverändert. Er hat Schreib- und Löschrechte und lag für einen unbekannten Zeitraum in einer Klartext-.txt. Zum Rotieren: Erstellen Sie einen neuen Schlüssel in IT Glue → Konto → Einstellungen → API-Schlüssel, aktualisieren Sie itglue.env und den ITGLUE_API_KEY des Portainer-Stacks, und widerrufen Sie dann den alten.

• IT Glue widerruft automatisch API-Schlüssel, die 90+ Tage lang nicht verwendet wurden. Die Spiegelaktualisierung hält diesen warm; wenn der Server jemals geparkt wird, erwarten Sie beim Aufwachen eine 401.

• Fügen Sie Zugriff über die Gruppe ITGlue-MCP-Users hinzu und entfernen Sie ihn, nicht über den Code.