Wangsu Terraform Knowledge Base MCP Server

Wangsu Terraform Provider Wissensdatenbank für Suchabrufendienst, der über MCP (Model Context Protocol) Clients wie Claude Code eine Tool-Aufrufschnittstelle bereitstellt.

Was ist das?

Dies ist ein reiner Retrieval-MCP-Server: Er ruft lediglich die relevanten Dokumentfragmente zum Wangsu Terraform Provider aus der Vektordatenbank ab und ruft serverseitig kein LLM zur Antwortgenerierung auf. Das eigentliche „Lesen der Fragmente und Zusammenstellen einer Antwort“ übernimmt der eigene Claude-Client des Aufrufers; verbraucht wird dabei das Kontingent des Kontos des Aufrufers.

Diese Aufteilung hat zwei Vorteile:

• Auf dem Server muss keine ANTHROPIC_API_KEY konfiguriert werden; die Aufrufkosten des gesamten Teams werden nicht auf dem Konto einer einzelnen Person gesammelt.

• Die Angriffsfläche ist kleiner – die einzige vertrauliche Information, die der Server schützen muss, ist ein Authentifizierungstoken.

Related MCP server: NetApp AIDE MCP Server

Architektur

团队成员的 Claude Code 客户端（用自己的账号做推理）
        │
        │ MCP over HTTP，携带 Bearer Token
        ▼
网宿 CDN（HTTPS，证书由网宿托管）
        │
        │ 回源 HTTPS，源站证书校验已关闭
        ▼
Caddy（反向代理，tls internal 自签证书，监听 443）
        │
        │ 转发到本地 8000 端口
        ▼
FastMCP + uvicorn（mcp_server.py）
        │
        │ 向量检索
        ▼
Chroma 向量数据库（本地持久化）

Kernkomponenten

Werkzeuge

search_wangsu_terraform(question: str) -> str

Ruft die Wangsu-Terraform-Wissensdatenbank ab und liefert:

1. Eine feste Erläuterung der Antwortregeln (ANSWER_GUIDANCE) – sie schränkt das Verhalten des aufrufenden Claude ein und verhindert Halluzinationen bei wangsu-spezifischen Parameter-/Ressourcennamen.

2. Die relevantesten abgerufenen Dokumentfragmente (standardmäßig Top 8), jeweils mit Quelldateinamen und Relevanzscore.

Der aufrufende Claude setzt daraus selbst die endgültige Antwort zusammen und unterscheidet dabei drei Fragentypen:

• Kategorie A: Wangsu-Provider-spezifische Details – stets auf den abgerufenen Inhalt stützen; nicht wörtlich abgerufene Feldnamen dürfen nicht erfunden werden.

• Kategorie B: Allgemeines Terraform/HCL-Wissen – kann aus eigenem Wissen beantwortet werden, wenn der abgerufene Inhalt es nicht abdeckt.

• Kategorie C: Fragen zu anderen Cloud-Anbietern – Wangsu-spezifische Inhalte dürfen nicht auf andere Anbieter übertragen werden.

Anbindung

Nach dem Erhalt des von den Administratoren verteilten MCP_AUTH_TOKEN führst du lokal Folgendes aus (ersetze <token> durch den tatsächlichen Wert):

claude mcp add --transport http wangsu-kb https://<你的加速域名>/mcp \
  --header "Authorization: Bearer <token>" -s user

Hinweis für Windows-PowerShell-Benutzer: Das Zeilenfortsetzungszeichen ist ein Backtick (`), nicht \. Es wird empfohlen, den Befehl als eine einzige Zeile zu schreiben, um zu vermeiden, dass durch Zeilenfortsetzungs-Interpretation der Authentifizierungs-Header verloren geht.

Verifiziere, ob die Verbindung erfolgreich ist:

claude mcp list

Es sollte wangsu-kb: ... (HTTP) — Connected angezeigt werden. Danach kannst du im Chat direkt Fragen zu Wangsu Terraform stellen, und Claude ruft das Tool bei Bedarf automatisch auf.

Server-Bereitstellung

Die vollständigen Bereitstellungsschritte findest du in deploy/DEPLOY.md, hier ein Überblick:

1. EC2-Instanz erstellen (Ubuntu 24.04 LTS, t3.small, 8-20 GB GP3), Elastic IP zuweisen.

2. Sicherheitsgruppe öffnet ausschließlich 22 (Administrator-IP) und 443 (IP-Bereiche von Wangsu für Quellenabrufe).

3. Wangsu CDN konfigurieren: Ursprungsquelle zeigt auf die Elastic IP, Quellabruf über HTTPS, Zertifikatsprüfung der Ursprungsstation deaktivieren (die Ursprungsstation verwendet ein selbstsigniertes Zertifikat).

4. Projektdateien nach /opt/wangsu-kb hochladen, virtuelle Umgebung erstellen und Abhängigkeiten installieren.

5. Einen eigenen Systembenutzer wangsu-mcp zum Ausführen des Dienstes anlegen (minimale Rechte, nicht root).

6. /etc/wangsu-mcp/env speichert MCP_AUTH_TOKEN und PORT, Berechtigung 600.

7. systemd verwaltet den Lebenszyklus des Dienstes (Autostart beim Booten, automatischer Neustart bei Absturz).

8. Caddy verwendet für den Reverse-Proxy ein selbstsigniertes Zertifikat (tls internal), stattdessen von Let's Encrypt.

Betrieb

Servicestatus / -logs ansehen

sudo systemctl status wangsu-mcp
sudo systemctl status caddy
sudo journalctl -u wangsu-mcp -f
sudo journalctl -u caddy -f

Wissensdatenbank-Inhalt aktualisieren

Lokal Quelldokumente im data/-Verzeichnis bearbeiten, ingest.py erneut ausführen, um ein neues chroma_db/ zu erzeugen, auf den Server synchronisieren und Dienst neu starten:

rsync -avz --exclude '.git' -e "ssh -i your-key.pem" \
  ./chroma_db/ ubuntu@<Elastic IP>:/tmp/chroma_db_new/

# 登录服务器
sudo systemctl stop wangsu-mcp
sudo rm -rf /opt/wangsu-kb/chroma_db
sudo mv /tmp/chroma_db_new /opt/wangsu-kb/chroma_db
sudo chown -R wangsu-mcp:wangsu-mcp /opt/wangsu-kb/chroma_db
sudo systemctl start wangsu-mcp

Token rotieren / entziehen

openssl rand -hex 32                          # 生成新token
sudo nano /etc/wangsu-mcp/env                  # 替换 MCP_AUTH_TOKEN
sudo systemctl restart wangsu-mcp

Das neue Token muss über einen Passwortmanager oder im privaten Gespräch erneut an die Teammitglieder verteilt werden. Die Teammitglieder müssen danach erneut claude mcp add ausführen (zuerst claude mcp remove wangsu-kb, dann das Tool mit dem neuen Token erneut hinzufügen).

Hinweis: Der Token ist der eindeutige Zugangsschlüssel. Gib ihn an keiner Stelle ein, die in Git committet wird, und vermeide nach Möglichkeit die Speicherung im Klartext in der Shell-History (verwende am besten Umgebungsvariablen oder einen Passwortmanager zur Übergabe).

Elastic-IP-Änderung

Wenn sich die Elastic IP ändert, müssen die folgenden drei Punkte synchron aktualisiert werden, keiner darf fehlen:

1. Die Quell-IP in der Wangsu-Konsole.

2. Die IP in /etc/caddy/Caddyfile (sofern die IP in der Caddyfile explizit eingetragen ist).

3. Die eingehende Regel für Port 443 in der Sicherheitsgruppe (falls sie bereits auf bestimmte IP-Bereiche beschränkt wurde).

Bekanntes Problem: Erstmaliges Laden des Embedding-Modells dauert lange

Beim Start lädt mcp_server.py das Embedding-Modell BAAI/bge-small-en-v1.5. Wenn der lokale Cache (/home/wangsu-mcp/.cache/huggingface) nicht vorhanden ist, lädt der Dienst es zuerst aus dem Netz herunter (ca. 67 MB). Schlägt der Download fehl, wird dreimal wiederholt (Backoff 3s/9s/27s). Wenn alle Versuche fehlschlagen, wird der Prozess beendet und systemd startet ihn automatisch neu und versucht es erneut.

Wenn der Dienst jedoch wiederholt neu startet, kann man die Laufzeitumgebung des Benutzers wangsu-mcp manuell simulieren, um zu prüfen:

sudo -u wangsu-mcp bash -c '
cd /opt/wangsu-kb
set -a; source /etc/wangsu-mcp/env; set +a
./venv/bin/python -c "
from llama_index.embeddings.fastembed import FastEmbedEmbedding
FastEmbedEmbedding(model_name=\"BAAI/bge-small-en-v1.5\")
print(\"加载成功\")
"'

Häufige Ursachen: Das Home-Verzeichnis des Benutzers wangsu-mcp existiert nicht oder ist nicht beschreibbar, nicht genügend Speicherplatz oder Netzwerkverbindungsprobleme.

Sicherheitsdesign

• Der Server gehört keinen Anthropic API Key; die Inferenzkosten und -kontingente trägt vollständig der Aufrufer.

• MCP_AUTH_TOKEN wird per openssl rand -hex 32 erzeugt, mit der Berechtigung 600, die nur wangsu-mcp erhält.

• Das Systemkonto wangsu-mcp für den Dienst ist ein speziell eingerichtetes Konto mit nicht interaktiver Shell (/usr/sbin/nologin) und folgt dem Prinzip der geringsten Berechtigungen.

• Der Caddy an der Ursprungsstation nutzt ein selbstsigniertes Zertifikat mit tls internal, das nur für das Wangsu-CDN zum Vertrauen beim Quellenabruf ausgelegt ist und ist nicht für öffentliche Browser ausgelegt.

• Der DNS-Rebinding-Schutz des MCP SDK (TransportSecuritySettings) wurde mit zulässiger Host-/Origin-Whitelist konfiguriert.

License

"Internal use only"