MCP Stark Brain (Payments)

Lokaler MCP-Server, der das Payments-Team bei der täglichen Arbeit unterstützt:

• Architekturmuster der Python-Mikroservices abfragen.

• Mikroservice-Spezifikationen nachschlagen (Ziel und Verantwortung jedes Dienstes).

• Zahlungsabwicklungsabläufe verstehen.

• Tickets des Customer Success (CS) sichten und untersuchen, indem Dokumentationssuche mit GCP-Analyse (Datastore + Cloud Logging / Log Explorer) kombiniert wird.

• Stark Bank APIs in development (Standard) oder sandbox (nur auf ausdrückliche Anfrage) mit deinen ECDSA-Projektanmeldedaten aufrufen.

Er führt RAG über die Dokumentation in starkbank/alexandria durch, signiert Stark Bank API-Anfragen mit deinem privaten Schlüssel und führt GCP-Abfragen mit deiner eigenen gcloud-Identität (ADC) aus.

1. So funktioniert es

IDE / LLM  --stdio-->  MCP server
                         |-- Docs (RAG): fetch alexandria via GitHub PAT -> local vector index
                         |-- Stark Bank API: ECDSA-signed HTTP to development (default) / sandbox
                         |-- GCP: Datastore + Cloud Logging via your gcloud ADC (project per call)

• Die Dokumentation ist remote-first (es wird kein Git-Clone gespeichert). Der Server lädt das Repo-Tarball über die GitHub-API herunter (eine Anfrage für den gesamten Inhalt), um einen lokalen Embedding-Index aufzubauen. Nur der Vektorindex wird lokal zwischengespeichert.

• Rate-Limit-bewusst. Wenn das GitHub-Budget zur Neige geht, schlägt der Server vor, das Repo zu klonen und in den local-Modus zu wechseln (siehe Abschnitt 10).

• Die Stark Bank API ist standardmäßig auf development eingestellt (https://development.api.starkbank.com). Sandbox wird nur verwendet, wenn ein Tool mit environment="sandbox" nach einer ausdrücklichen Benutzeranfrage aufgerufen wird. Production ist niemals erlaubt.

• Das GCP-Projekt wird pro Aufruf übergeben. Es gibt keine feste Projekt-Env-Variable: Jede Abfrage nimmt ein explizites project entgegen, sodass du in derselben Sitzung zwischen Mikroservice-Projekten wechseln kannst, ohne deine globale gcloud config anzufassen.

• Keine Service-Account-Schlüssel für GCP. Der GCP-Zugriff verwendet deine persönlichen ADC-Anmeldedaten, wodurch benutzerspezifische Berechtigungen und Audit-Trails erhalten bleiben.

2. Voraussetzungen

• Python 3.12 (erforderlich zum Erstellen/Installieren des Bundles). chromadb und fastembed (über onnxruntime) liefern noch nicht zuverlässig vorgebaute Wheels für neuere Interpreter, daher pinnt das Projekt requires-python = ">=3.11,<3.13" und jeder Befehl unten zielt explizit auf 3.12 — ersetze nicht das standardmäßige python3 deines Systems, ohne vorher dessen Version zu prüfen.

• uv (empfohlen) oder pipx zum Installieren des Bundles.

• Google Cloud SDK (gcloud).

Überprüfe/installiere die gepinnte Python-Version mit uv (das hat keinen Einfluss auf dein System-Python):

uv python install 3.12

3. Erstelle dein GitHub-PAT

Jeder Entwickler erstellt sein eigenes PAT (niemals geteilt, niemals eingecheckt). alexandria ist privat und gehört zur starkbank-Organisation. Welcher Token-Typ funktioniert, hängt also von der Token-Richtlinie der Organisation ab — lies dir beide Optionen unten durch, bevor du eine wählst.

Option A: Feingranulares PAT (zuerst ausprobieren)

1. GitHub -> Settings -> Developer settings -> Fine-grained tokens -> Neues Token generieren.

2. Resource Owner: starkbank.

3. Repository-Zugriff: Nur ausgewählte Repositories -> starkbank/alexandria.

4. Berechtigungen: Repository-Berechtigungen -> Contents: Schreibgeschützt.

5. Generiere und kopiere das Token (du wirst es als Umgebungsvariable in deiner mcp.json setzen).

6. Überprüfe seinen Status unter https://github.com/settings/personal-access-tokens. Wenn die Organisation eine Genehmigung verlangt, wird es als Pending angezeigt und liefert bei jeder Anfrage einen 404, bis es genehmigt wurde. Bitte einen starkbank-Organisationsbesitzer, es unter Settings -> Personal access tokens -> Pending requests der Organisation zu genehmigen, oder fahre mit Option B fort.

Option B: Klassisches PAT (Fallback, wenn die Organisation keine feingranularen Tokens genehmigt)

Klassische PATs unterliegen nicht dem obigen Organisationsgenehmigungsschritt, sind also der schnellere Weg, wenn deine Organisation feingranulare Tokens einschränkt:

1. GitHub -> Settings -> Developer settings -> Tokens (classic) -> Neues Token generieren.

2. Umfang: repo (klassische Tokens haben keinen Nur-Inhalts-Umfang für private Repos).

3. Wenn die starkbank-Organisation SSO erzwingt, klicke neben dem neu erstellten Token auf Configure SSO und autorisiere es für starkbank — ein nicht autorisiertes Token wird bei starkbank-Ressourcen genau wie ein nicht genehmigtes feingranulares Token einen 404 liefern.

Führe nach der Installation in jedem Fall das Tool diagnose_github_access aus (siehe Abschnitt 8), um zu bestätigen, dass das Token wirklich funktioniert, bevor du dich darauf verlässt.

4. Bei GCP authentifizieren (ADC)

gcloud auth login
gcloud auth application-default login

Du musst hier kein Projekt festlegen — der MCP empfängt das project bei jedem GCP-Toolaufruf. Verwende analyze_ticket / resolve_project, um Projektvorschläge zu erhalten.

5. Anmeldedaten für die Stark Bank API (ECDSA)

API-Aufrufe werden mit ECDSA (secp256k1) authentifiziert, nicht mit statischen API-Schlüsseln. Siehe die offizielle Dokumentation: Authentication.

1. Generiere ein Schlüsselpaar (falls du es noch nicht hast) und registriere nur den öffentlichen Schlüssel in Web Banking (Integrations → Project) für die Entwicklungsumgebung.

2. Bewahre das PEM des privaten Schlüssels auf deinem Rechner auf — committe es niemals und lege den öffentlichen Schlüssel niemals in dieses Repo (der MCP benötigt den öffentlichen Schlüssel nicht, um Anfragen zu signieren).

3. Notiere dir die Project ID, die in Web Banking angezeigt wird, nachdem du das Projekt erstellt/registriert hast.

4. Weise den MCP über Umgebungsvariablen auf das PEM und die Project ID hin (siehe Schritt 6 / Abschnitt 11).

Empfohlener Speicherort für den privaten Schlüssel (außerhalb des Repos):

mkdir -p ~/.config/mcp-stark-brain
chmod 700 ~/.config/mcp-stark-brain
# copy your privateKey.pem there, then:
chmod 600 ~/.config/mcp-stark-brain/privateKey.pem

Standard-Basis-URLs:

6. Das Bundle (Wheel) erstellen

Führe vom Repo-Root aus den Interpreter immer explizit auf Python 3.12 fest — führe kein nacktes uv build aus und verlasse dich nicht darauf, welches Python zufällig als erstes auf deinem PATH liegt:

rm -rf dist  # avoid mixing wheels from a previous version/build
uv build --python 3.12 -o dist

Das erzeugt die installierbaren Artefakte in dist/ (die genaue Version im Dateinamen stammt aus version in pyproject.toml, aktuell 0.2.0):

dist/
  mcp_stark_brain-0.2.0-py3-none-any.whl
  mcp_stark_brain-0.2.0.tar.gz

Verteile die .whl an die Entwickler (oder an einen gemeinsamen Speicherort).

Ohne uv: Erstelle ein venv mit python3.12 -m venv .venv312, aktiviere es und führe dann pip install build && python -m build -o dist aus. Überprüfe zuerst mit python3.12 --version — wenn dieser Befehl nicht gefunden wird, installiere Python 3.12, bevor du fortfährst; baue nicht mit einer anderen Haupt-/Nebenversion.

7. Den MCP in der IDE installieren

Installiere das Wheel als isoliertes Tool und pinne erneut explizit Python 3.12, damit die Umgebung des Tools der entspricht, gegen die es gebaut/getestet wurde. Verwende einen Glob, damit du nie eine Versionsnummer von Hand bearbeiten musst (und riskierst, ein veraltetes Wheel aus einem früheren Build zu installieren):

# with uv (recommended)
uv tool install --python 3.12 ./dist/mcp_stark_brain-*-py3-none-any.whl

# or with pipx
pipx install --python python3.12 ./dist/mcp_stark_brain-*-py3-none-any.whl

Dadurch wird der Befehl mcp-stark-brain auf deinem PATH verfügbar.

Füge dann den Server zur MCP-Konfiguration deiner IDE hinzu (z. B. Cursor ~/.cursor/mcp.json oder die Projektdatei .cursor/mcp.json):

{
  "mcpServers": {
    "stark-brain": {
      "command": "mcp-stark-brain",
      "env": {
        "ALEXANDRIA_GITHUB_PAT": "<your-personal-fine-grained-PAT>",
        "STARKBANK_PRIVATE_KEY_PATH": "/Users/you/.config/mcp-stark-brain/privateKey.pem",
        "STARKBANK_PROJECT_ID": "<your-project-id>",
        "STARKBANK_DEV_BASE_URL": "https://development.api.starkbank.com",
        "STARKBANK_SANDBOX_BASE_URL": "https://sandbox.api.starkbank.com"
      }
    }
  }
}

Starte die IDE neu bzw. lade sie neu, damit sie den neuen MCP-Server übernimmt.

Du möchtest ein benutzerdefiniertes Symbol neben stark-brain in der Tools-&-MCP-Liste (so wie der offizielle github-MCP sein Logo zeigt)? Siehe cursor-plugin/README.md für einen optionalen Wrapper, der genau diese Konfiguration als lokales Cursor-Plugin mit einem logo bündelt. Rein kosmetisch — überspringe es, wenn es dir nichts ausmacht.

8. Aktualisieren eines bereits installierten MCP

Wann immer sich dieses Repo ändert (neue Tools, Bugfixes, Korrekturen an Standardkonfigurationen usw.), benötigst du ein neues Bundle. Der Befehl hängt davon ab, wie du es ursprünglich installiert hast — die Verwendung des falschen ist die häufigste Ursache für die Verwirrung „Warum wird mein Fix nicht angezeigt?“, wähle also den, der zu Schritt 6 passt:

# 1. Pull the latest source and rebuild the bundle (repo maintainer, or you if you
#    build it yourself). Always clean dist/ first to avoid mixing old/new wheels.
git pull
rm -rf dist
uv build --python 3.12 -o dist

# 2a. If you installed with `uv tool install`, use --reinstall (uv tool upgrade
#     does NOT work for local wheel paths, only for PyPI-published packages):
uv tool install --python 3.12 --reinstall ./dist/mcp_stark_brain-*-py3-none-any.whl

# 2b. If you installed with pipx, uninstall + reinstall (pipx has no local-wheel
#     upgrade command either):
pipx uninstall mcp-stark-brain
pipx install --python python3.12 ./dist/mcp_stark_brain-*-py3-none-any.whl

Sorge dann dafür, dass Cursor den Serverprozess tatsächlich neu startet — die Tool-Liste, die du siehst, ist das, was dieser spezifische stdio-Subprozess beim Start angekündigt hat. Eine alleinige Neuinstallation auf der Festplatte aktualisiert sie also nicht:

1. Überprüfe zuerst, ob die Neuinstallation tatsächlich angekommen ist (außerhalb von Cursor, in einem einfachen Terminal):

   uv tool list | grep -A2 mcp-stark-brain   # confirm the version bumped
   which mcp-stark-brain

2. Schalte den Server in Cursor aus/an — das ist der offiziell unterstützte Weg, einen einzelnen MCP-Server neu zu starten, ohne die gesamte App zu beenden: Cmd+Shift+J -> Tools & MCP -> finde stark-brain -> schalte ihn aus, warte ein paar Sekunden, schalte ihn ein.

3. Öffne einen brandneuen Chat. Ein Chat, der bereits vor dem Umschalten geöffnet war, kann nach dem Neustart des Servers weiterhin die alte Tool-Liste anzeigen.

4. Wenn die Tools immer noch veraltet aussehen, bedeutet das, dass Cursors Shared Process — ein einzelner Hintergrundprozess pro App-Instanz, der alle MCP-Subprozesse hostet (nicht pro Fenster, daher startet Developer: Reload Window ihn nicht neu) — den alten Subprozess noch im Speicher hat. Beende die App vollständig (Cmd+Q, nicht nur das Fenster schließen) und öffne sie erneut; das beendet den Shared Process und mit ihm jeden MCP-Subprozess.

5. Um es auf Protokollebene zu bestätigen, statt zu raten: Cmd+Shift+U -> Dropdown MCP Logs -> stark-brain -> prüfe, ob die tools/list-Antwort den neuen Toolnamen tatsächlich enthält. Wenn er auch dort fehlt, liegt das Problem am installierten Bundle, nicht am Cursor-Cache — gehe zurück zu Schritt 1.

6. Sobald die neuen Tools sichtbar sind, führe das status-Tool aus, um zu bestätigen, dass das Update übernommen wurde (prüfe, ob docs_mode, repo, ref, embed_model deinen Erwartungen entsprechen).

7. Wenn sich nur der Inhalt der Doku geändert hat (nicht der Code), musst du nichts neu installieren — rufe einfach refresh_docs() aus der IDE auf.

Du musst beim Aktualisieren dein PAT nicht neu generieren oder gcloud auth erneut ausführen; diese Anmeldedaten sind unabhängig von der installierten Version.

9. Erster Start und Verwendung

• Beim ersten Aufruf eines Doku-Tools lädt der Server den Inhalt von alexandria herunter und erstellt den lokalen Index (das kann etwas dauern, während das Embedding-Modell einmal heruntergeladen wird).

• Verwende refresh_docs, um nach Dokumentationsänderungen erneut zu synchronisieren (inkrementell: nur geänderte Dateien werden neu eingebettet).

• status meldet den Doku-Modus, die Anzahl der indizierten Dateien, das Rate-Limit und ob Stark Bank API-Anmeldedaten konfiguriert sind (starkbank_api_configured).

• Stark Bank API-Tools verwenden standardmäßig development. Übergib environment="sandbox" nur, wenn der Benutzer ausdrücklich Sandbox anfordert.

Verfügbare Tools:

10. Remote- vs. lokaler Modus

• remote (Standard): Die Doku wird über dein PAT von GitHub abgerufen. Effizient (Tarball = 1 Anfrage pro Aktualisierung), verbraucht aber dein GitHub-API-Kontingent.

• local: Die Doku wird aus einem Verzeichnis gelesen, das du selbst geklont hast; keinerlei API-Nutzung.

Wenn das GitHub-Rate-Limit fast erschöpft ist, warnt dich der Server und schlägt vor zu wechseln. So wechselst du:

# clone the repo once (your own credentials)
git clone git@github.com:starkbank/alexandria.git ~/repos/alexandria

Du kannst es dann entweder in mcp.json setzen:

"env": {
  "ALEXANDRIA_GITHUB_PAT": "<pat>",
  "STARK_BRAIN_DOCS_MODE": "local",
  "STARK_BRAIN_DOCS_PATH": "/Users/you/repos/alexandria"
}

oder zur Laufzeit über das Tool wechseln:

set_docs_source(mode="local", path="/Users/you/repos/alexandria")
refresh_docs()

11. Konfigurationsreferenz (Umgebungsvariablen)

Siehe .env.example.

12. Fehlerbehebung

• configuration error: ALEXANDRIA_GITHUB_PAT is required — setze das PAT in deiner mcp.json-Umgebung oder wechsle in den local-Modus.

• GitHub 401 — PAT ungültig/abgelaufen. Generiere es neu.

• GitHub 404 ("Repo or ref not found") obwohl das Repo existiert — bei privaten Repos gibt GitHub 404 sowohl zurück, wenn eine Ressource wirklich nicht existiert, als auch wenn dein Token sie nicht sehen kann. Daher ist dies fast immer ein Token-/Zugriffsproblem, keine falsche ALEXANDRIA_REPO/ALEXANDRIA_REF-Angabe. Häufigste Ursache: ein feingranulares PAT, das noch auf die Genehmigung durch den Organisations-Administrator wartet (prüfe https://github.com/settings/personal-access-tokens — wenn es "Pending" zeigt, siehe Abschnitt 3 für den Genehmigungsschritt oder den Fallback mit klassischem PAT). Führe diagnose_github_access() für eine Live-Prüfung aus, die das Problem genau eingrenzt.

• GitHub 403 / Rate-Limit erreicht — PAT-Berechtigungen prüfen oder klonen und den local-Modus verwenden.

• GCP credentials not found — führe gcloud auth application-default login aus.

• Datastore-/Logging-Berechtigungsfehler — du hast ein Projekt abgefragt, für das du keine Zugriffsrechte hast; wähle ein anderes project oder fordere Zugriff an.

• Langsamer Modell-Download beim ersten Start — das Einbettungsmodell wird nach der ersten Verwendung unter STARK_BRAIN_CACHE_DIR zwischengespeichert.

• Ein neu hinzugefügtes Tool erscheint nach der Neuinstallation nicht — das ist ein veralteter Cursor-seitiger Prozess, keine fehlerhafte Installation (siehe Abschnitt 8 Schritt für Schritt): Der laufende MCP-Subprozess nimmt eine Neuinstallation auf der Festplatte nicht von selbst auf. Schalte den Server in Tools & MCP aus und wieder ein, öffne einen neuen Chat, und falls das immer noch nicht reicht, beende Cursor vollständig (Cmd+Q) und öffne es erneut.

• STARKBANK_PRIVATE_KEY_PATH is not set / API-Tools schlagen fehl — setze den absoluten Pfad zu deinem PEM und STARKBANK_PROJECT_ID in mcp.json (siehe Abschnitt 5). Stelle sicher, dass status().starkbank_api_configured true ist.

• Stark-Bank-API 401 / ungültige Signatur — falsche Projekt-ID, PEM nicht für diese Umgebung registriert oder Uhrenabweichung. Stelle sicher, dass der öffentliche Schlüssel in der passenden Web-Banking-Umgebung (Development vs. Sandbox) registriert ist.

13. Sicherheitshinweise

• Dein PAT wird nur im Authorization-Header gesendet und niemals protokolliert.

• Der Stark-Bank-Private-Key wird bei jeder Anfrage von der Festplatte gelesen und niemals protokolliert.

• Es werden keine Servicekontoschlüssel verteilt; der GCP-Zugriff erfolgt über deine persönliche ADC-Identität.

• Das GCP-project wird pro Aufruf übergeben — kein gemeinsames/fest codiertes Projekt.

• Produktions-Hosts der Stark-Bank-API werden vom Client abgelehnt.

• .env, *.pem, keys/ und der lokale Cache sind git-ignoriert.

14. Entwicklung

Die Quelldateien liegen flach unter src/ (keine zusätzliche src/mcp_stark_brain/-Verschachtelung). Die Build-Konfiguration in pyproject.toml liefert sie als Importpaket mcp_stark_brain im Wheel aus (packages = ["src"] + sources = {"src" = "mcp_stark_brain"}), sodass Einstiegspunkte und interne Importe unabhängig von der Verzeichnisstruktur unverändert bleiben.

Diese Umbenennung ist nicht mit editable-/Dev-Modus-Installationen kompatibel (eine Einschränkung von hatchling/pip). Daher ist uv sync mit tool.uv.package = false konfiguriert: Es installiert nur Abhängigkeiten, nicht das Projekt selbst. conftest.py und scripts/smoke_test.py verwenden devtools/bootstrap.py, damit import mcp_stark_brain direkt gegen src/ für Tests und lokale Skripte funktioniert, ohne dass ein Installationsschritt erforderlich ist.

uv python install 3.12
uv sync --extra dev --python 3.12
uv run ruff check .
uv run pytest
uv run python scripts/smoke_test.py

Um den Server tatsächlich lokal auszuprobieren (kein Wheel-Build erforderlich):

uv run --python 3.12 python -c "from devtools.bootstrap import ensure_importable; ensure_importable(); from mcp_stark_brain.server import main; main()"