PA MCP Server

MCP-Server, der die Portfolio Advisor (PA)-Engine als Tool für KI-Agenten bereitstellt. Die quantitative Engine ist in pa_engine/src enthalten, sodass das Projekt eigenständig ist und nicht von Ordnern oder Daten außerhalb der Distribution abhängt.

Produktdokumentation und Einschränkungen: PRODUCT_OVERVIEW.md. Datenschutzvorlage, die einer professionellen Prüfung unterzogen werden muss: PRIVACY_NOTICE_TEMPLATE.md. Ergebnis des Pre-Release-Audits: AUDIT_REPORT.md.

Was es bereitstellt

Der Agent ruft zunächst schema_input_pa auf, erfasst die Daten und übergibt die Konfiguration an valida_input_pa. Wenn valid=true ist, ruft er prepara_simulazione auf: Der Client zeigt ein Panel mit den ausgefüllten Parametern, und die Simulation bleibt angehalten. Der Benutzer kann die Werte ändern und muss explizit bestätigen. Das Widget friert die Konfiguration ein und sendet dem Agenten eine interne Genehmigungskennung; der Agent ruft dann direkt analisi_completa auf, das Optimierung, erwartete Renditen, Monte Carlo, Stresstests und Benchmark-Vergleich umfasst. Die Genehmigung läuft nach 2 Stunden ab und wird verbraucht, sobald der vollständige Bericht erfolgreich abgeschlossen wird.

Wenn der Benutzer eine Liste von Instrumenten bereitstellt, übergibt der Agent sie an verifica_strumenti und erklärt jede Ablehnung im Einzelnen. Wenn er keine Liste hat und Vorschläge anfragt, verwendet der Agent proponi_strumenti, präsentiert Ticker, Name, Börse, geschätzte Kosten und Kommentar und wartet dann auf eine explizite Bestätigung, bevor er die Prüfung und Konfiguration durchführt. Es findet kein automatischer Ersatz statt.

cost_annual_pct wird in Prozentpunkten ausgedrückt: 0.50 bedeutet 0,50% pro Jahr. Clients ohne MCP-Apps-Unterstützung können den Entwurf validieren und anzeigen, aber den interaktiven Genehmigungsablauf nicht abschließen.

Einrichtung

python3.13 -m venv .venv
./.venv/bin/python -m pip install .

Zum Ändern und Neuerstellen der Widgets werden außerdem Node.js 20+ und npm ci benötigt.

Die Engine Portfolio Advisor ist im Projekt unter pa_engine/src enthalten, daher ist der Server eigenständig. Für die Entwicklung kann auf eine alternative Engine verwiesen werden:

export PA_ENGINE_DIR="/percorso/del/motore"   # opzionale, solo sviluppo

Start

Lokal (stdio):

./.venv/bin/python -m pa_mcp.server

Streamable HTTP, für Remote-Connector und MCP-Apps-Tests:

PA_MCP_TRANSPORT=http PA_MCP_PORT=3000 \
  ./.venv/bin/python -m pa_mcp.server

MCP-Endpunkt: http://127.0.0.1:3000/mcp. Für Web-Clients muss er vorübergehend über HTTPS bereitgestellt oder auf einem Remote-Host gehostet werden. Der lokale HTTP-Start aktiviert keine Authentifizierung und darf nicht direkt in Produktion veröffentlicht werden.

Genehmigungen, Überprüfungen und Cache sind persistent und teilbar (sie überleben einen Neustart), wenn ein beschreibbarer Statuspfad aktiviert wird:

PA_STATE_PATH=/var/lib/pa_mcp/state.db PA_MCP_TRANSPORT=http PA_MCP_PORT=3000 \
  ./.venv/bin/python -m pa_mcp.server

Ohne PA_STATE_PATH bleibt der Status im Speicher (übliches Verhalten für lokale Entwicklung und Tests).

OAuth (HTTP, vor dem Freigeben des Endpunkts)

OAuth 2.1 (Scope pa.read) ist über FastMCP OAuthProvider verfügbar:

PA_OAUTH=1 PA_PUBLIC_BASE_URL=https://pa.example.com \
  PA_MCP_TRANSPORT=http PA_MCP_PORT=3000 ./.venv/bin/python -m pa_mcp.server

Wenn PA_OAUTH nicht gesetzt ist, bleibt der HTTP-Server ohne Authentifizierung (geeignet für Entwicklung und Test). In Produktion sollten die OAuth-Tokens im gemeinsamen Store persistiert und eine mandantenbezogene Autorisierung konfiguriert werden.

Schutz der Infrastruktur (HTTP)

• PA_RATE_LIMIT_PER_MIN — Token-Bucket pro IP (HTTP 429).

• PA_MAX_BODY_BYTES — Begrenzung des Anfrage-Bodys (HTTP 413).

• PA_ANALYSIS_TIMEOUT_SECONDS — Harte Deadline für Analysen (Standard: 60 s; gibt Slot und Genehmigung frei).

• PA_ANALYSIS_QUOTA_PER_HOUR — Stündliches Analyse-Kontingent pro Mandant (0 = unbegrenzt); Mandantenschlüssel über PA_TENANT (Standard: anonymous).

Observability (HTTP)

• GET /health/live — Liveness.

• GET /health/ready — Readiness (503, wenn nicht bereit; Status des Stores).

• GET /metrics — Betriebskennzahlen (ohne personenbezogene Daten).

Deployment und Dokumente

Zum Veröffentlichen des Connectors wird ein stabiler Endpunkt benötigt (nicht der Tunnel): folge DEPLOY_GUIDE.md (enthält Dockerfile). Entwürfe der Datenschutzerklärung und der Nutzungsbedingungen in PRIVACY_NOTICE_DRAFT.md und TERMS_OF_USE_DRAFT.md (zu prüfen).

Für Clients sind die neuen Module pa_mcp/auth.py, pa_mcp/limits.py, pa_mcp/state.py, pa_mcp/oauth_provider.py, pa_mcp/quotas.py in der Wheel enthalten.

Der Server kommuniziert über stdio: Jeder MCP-Client kann ihn anbinden. Beispielkonfiguration für einen generischen Client:

{
  "mcpServers": {
    "pa-engine": {
      "command": "/percorso/pa-mcp-server/.venv/bin/python",
      "args": ["/percorso/pa-mcp-server/server_script.py"],
      "cwd": "/percorso/pa-mcp-server"
    }
  }
}

Test der Tools

Offline-Test des Vertrags und des Genehmigungsablaufs:

./.venv/bin/python -m unittest discover -s tests -p 'test_*.py'
node scripts/test_config_widget_render.js
node scripts/test_widget_render.js

Vollständiger Selbsttest mit Marktdaten:

./.venv/bin/python -m pa_mcp.selfcheck

Führt alle Tools gegen eine Testkonfiguration mit echten Daten aus (erfordert Netzwerkzugriff auf Yahoo Finance) und gibt die Schlüssel jeder Ausgabe aus.

Hinweis zur Engine

Der Wrapper verwendet pa/src der PA-Engine wieder. Er berechnet nichts neu: Er delegiert die gesamte Pipeline an die Engine und serialisiert den von export_report_json erzeugten JSON-Bericht. Wenn die Engine ihre Schnittstelle ändert, pa_mcp/engine.py aktualisieren.

Auf die Engine angewandter Bugfix (numpy 2.x)

pa/src/core/stress_test.py: weights.to_numpy(dtype=float) liefert mit numpy 2.x ein schreibgeschütztes Array zurück, und target /= target.sum() schlug mit ValueError: output array is read-only fehl. Behoben mit np.array(weights.to_numpy(dtype=float)). Der Fix wird in der Engine in den Upstream übernommen.

Roadmap

1. Professionelle Prüfung von Finanzen, Steuern, Datenschutz und Datenlizenzen.

2. Remote-Deployment mit OAuth 2.1, Mandantenisolierung, Kontingenten und Observability.

3. Veröffentlichung in den unterstützten Registries nach unabhängiger Security-Review.

Die blockierende Checkliste befindet sich in GO_LIVE_CHECKLIST.md.