PA MCP Server

Server MCP che espone il motore Portfolio Advisor (PA) come tool per agenti AI. Il motore quantitativo è incluso in pa_engine/src, così il progetto è autonomo e non dipende da cartelle o dati esterni alla distribuzione.

Documentazione prodotto e limiti: PRODUCT_OVERVIEW.md. Template privacy da sottoporre a revisione professionale: PRIVACY_NOTICE_TEMPLATE.md. Esito audit pre-release: AUDIT_REPORT.md.

Cosa espone

L'agente chiama prima schema_input_pa, raccoglie i dati e passa la configurazione a valida_input_pa. Se valid=true, chiama prepara_simulazione: il client mostra un pannello con i parametri compilati e la simulazione resta ferma. L'utente può modificare i valori e deve confermare esplicitamente. Il widget congela la configurazione e invia all'agente un identificatore interno di approvazione; l'agente chiama quindi direttamente analisi_completa, che include ottimizzazione, rendimenti attesi, Monte Carlo, stress test e confronto benchmark. L'approvazione scade dopo 2 ore e viene consumata quando il report completo termina con successo.

Se l'utente fornisce una lista di strumenti, l'agente la passa a verifica_strumenti e spiega puntualmente ogni rifiuto. Se non ha una lista e chiede suggerimenti, l'agente usa proponi_strumenti, presenta ticker, nome, borsa, costo stimato e commento, quindi attende conferma esplicita prima della verifica e della configurazione. Nessuna sostituzione avviene automaticamente.

cost_annual_pct è espresso in punti percentuali: 0.50 significa 0,50% annuo. I client senza supporto MCP Apps possono validare e mostrare la bozza, ma non completano il percorso di approvazione interattiva.

Setup

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

Per modificare e ricostruire i widget servono inoltre Node.js 20+ e npm ci.

Il motore Portfolio Advisor è incluso nel progetto in pa_engine/src, quindi il server è autonomo. Per sviluppo è possibile puntare un motore alternativo:

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

Avvio

Locale (stdio):

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

Streamable HTTP, per connector remoti e test MCP Apps:

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

Endpoint MCP: http://127.0.0.1:3000/mcp. Per i client web va esposto temporaneamente tramite HTTPS oppure distribuito su un host remoto. L'avvio HTTP locale non abilita autenticazione e non va pubblicato direttamente in produzione.

Approvazioni, recensioni e cache sono persistenti e condivisibili (sopravvivono al riavvio) attivando un percorso di stato scrivibile:

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

Senza PA_STATE_PATH lo stato resta in memoria (comportamento usuale per sviluppo locale e test).

OAuth (HTTP, prima di esporre l'endpoint)

OAuth 2.1 (scope pa.read) è disponibile via FastMCP OAuthProvider:

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

Con PA_OAUTH non impostato il server HTTP resta senza autenticazione (adatto a sviluppo e test). In produzione i token OAuth andrebbero persistiti nello store condiviso e configurare autorizzazione per-tenant.

Protezione infrastruttura (HTTP)

• PA_RATE_LIMIT_PER_MIN — token-bucket per IP (HTTP 429).

• PA_MAX_BODY_BYTES — limite body richieste (HTTP 413).

• PA_ANALYSIS_TIMEOUT_SECONDS — deadline hard per analisi (di default 60s; rilascia slot e approvazione).

• PA_ANALYSIS_QUOTA_PER_HOUR — quota oraria di analisi per tenant (0 = illimitata); chiave tenant via PA_TENANT (default anonymous).

Osservabilità (HTTP)

• GET /health/live — liveness.

• GET /health/ready — readiness (503 se non pronto; stato dello store).

• GET /metrics — contatori operativi (senza dati personali).

Deploy e documenti

Per pubblicare il connettore servirà un endpoint stabile (non il tunnel): segli DEPLOY_GUIDE.md (include Dockerfile). Bozza di informativa e termini in PRIVACY_NOTICE_DRAFT.md e TERMS_OF_USE_DRAFT.md (da revisionare).

Per i client i nuovi moduli pa_mcp/auth.py, pa_mcp/limits.py, pa_mcp/state.py, pa_mcp/oauth_provider.py, pa_mcp/quotas.py sono inclusi nella wheel.

Il server parla su stdio: qualsiasi client MCP può collegarlo. Esempio di config per un client generico:

{
  "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 dei tool

Test offline del contratto e del flusso di approvazione:

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

Self-check completo con dati di mercato:

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

Esegue tutti i tool contro una config di test con dati reali (serve rete verso Yahoo Finance) e stampa le chiavi di ogni output.

Nota sul motore

Il wrapper riusa pa/src del motore PA. Non ricalcola nulla: delega la pipeline completa al motore e serializza il report JSON prodotto da export_report_json. Se il motore cambia interfaccia, aggiornare pa_mcp/engine.py.

Bug fix applicato al motore (numpy 2.x)

pa/src/core/stress_test.py: weights.to_numpy(dtype=float) con numpy 2.x restituisce un array read-only e target /= target.sum() falliva con ValueError: output array is read-only. Corretto con np.array(weights.to_numpy(dtype=float)). In via di upstream nel motore.

Roadmap

1. Revisione professionale finanziaria, fiscale, privacy e licenze dati.

2. Deploy remoto con OAuth 2.1, isolamento tenant, quote e osservabilità.

3. Pubblicazione sui registry supportati dopo security review indipendente.

La checklist bloccante è in GO_LIVE_CHECKLIST.md.