PA MCP Server

Servidor MCP que expone el motor Portfolio Advisor (PA) como herramienta para agentes de IA. El motor cuantitativo está incluido en pa_engine/src, por lo que el proyecto es autónomo y no depende de carpetas ni datos externos a la distribución.

Documentación del producto y límites: PRODUCT_OVERVIEW.md. Plantilla de privacidad sujeta a revisión profesional: PRIVACY_NOTICE_TEMPLATE.md. Resultado de la auditoría previa al lanzamiento: AUDIT_REPORT.md.

Qué expone

El agente llama primero a schema_input_pa, recopila los datos y pasa la configuración a valida_input_pa. Si valid=true, llama a prepara_simulazione: el cliente muestra un panel con los parámetros rellenados y la simulación permanece detenida. El usuario puede modificar los valores y debe confirmar explícitamente. El widget congela la configuración y envía al agente un identificador interno de aprobación; el agente llama entonces directamente a analisi_completa, que incluye optimización, rendimientos esperados, Monte Carlo, pruebas de estrés y comparación con el benchmark. La aprobación expira después de 2 horas y se consume cuando el informe completo finaliza correctamente.

Si el usuario proporciona una lista de instrumentos, el agente se la pasa a verifica_strumenti y explica detalladamente cada rechazo. Si no tiene lista y pide sugerencias, el agente usa proponi_strumenti, presenta ticker, nombre, bolsa, coste estimado y comentario, y espera confirmación explícita antes de la verificación y la configuración. Ninguna sustitución se produce automáticamente.

cost_annual_pct se expresa en puntos porcentuales: 0.50 significa 0,50% anual. Los clientes sin soporte de MCP Apps pueden validar y mostrar el borrador, pero no completan el flujo de aprobación interactiva.

Setup

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

Para modificar y reconstruir los widgets se necesitan además Node.js 20+ y npm ci.

El motor Portfolio Advisor está incluido en el proyecto en pa_engine/src, por lo que el servidor es autónomo. Para desarrollo es posible apuntar a un motor alternativo:

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

Inicio

Local (stdio):

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

Streamable HTTP, para conectores remotos y pruebas de 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. Para los clientes web debe exponerse temporalmente mediante HTTPS o distribuirse en un host remoto. El inicio HTTP local no habilita autenticación y no debe publicarse directamente en producción.

Las aprobaciones, revisiones y la caché son persistentes y compartibles (sobreviven al reinicio) activando una ruta de estado escribible:

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

Sin PA_STATE_PATH el estado permanece en memoria (comportamiento habitual para desarrollo local y pruebas).

OAuth (HTTP, antes de exponer el endpoint)

OAuth 2.1 (alcance pa.read) está disponible mediante 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 sin configurar, el servidor HTTP permanece sin autenticación (adecuado para desarrollo y pruebas). En producción, los tokens OAuth deberían persistirse en el almacén compartido y debería configurarse la autorización por tenant.

Protección de infraestructura (HTTP)

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

• PA_MAX_BODY_BYTES — límite del cuerpo de las solicitudes (HTTP 413).

• PA_ANALYSIS_TIMEOUT_SECONDS — plazo máximo (deadline) para el análisis (por defecto 60 s; libera el slot y la aprobación).

• PA_ANALYSIS_QUOTA_PER_HOUR — cuota horaria de análisis por tenant (0 = ilimitada); clave de tenant vía PA_TENANT (por defecto anonymous).

Observabilidad (HTTP)

• GET /health/live — liveness.

• GET /health/ready — readiness (503 si no está listo; estado del almacén).

• GET /metrics — contadores operativos (sin datos personales).

Despliegue y documentos

Para publicar el conector se necesitará un endpoint estable (no el túnel): elige DEPLOY_GUIDE.md (incluye Dockerfile). Borrador del aviso de privacidad y de los términos en PRIVACY_NOTICE_DRAFT.md y TERMS_OF_USE_DRAFT.md (por revisar).

Para los clientes, los nuevos módulos pa_mcp/auth.py, pa_mcp/limits.py, pa_mcp/state.py, pa_mcp/oauth_provider.py, pa_mcp/quotas.py están incluidos en la wheel.

El servidor se comunica por stdio: cualquier cliente MCP puede conectarse. Ejemplo de configuración para un cliente genérico:

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

Prueba de las herramientas

Prueba offline del contrato y del flujo de aprobación:

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

Autocomprobación completa con datos de mercado:

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

Ejecuta todas las herramientas contra una configuración de prueba con datos reales (requiere red hacia Yahoo Finance) e imprime las claves de cada salida.

Nota sobre el motor

El wrapper reutiliza pa/src del motor PA. No recalcula nada: delega la pipeline completa al motor y serializa el informe JSON producido por export_report_json. Si el motor cambia la interfaz, actualizar pa_mcp/engine.py.

Corrección de errores aplicada al motor (numpy 2.x)

pa/src/core/stress_test.py: weights.to_numpy(dtype=float) con numpy 2.x devuelve un array de solo lectura y target /= target.sum() fallaba con ValueError: output array is read-only. Corregido con np.array(weights.to_numpy(dtype=float)). En proceso de upstream en el motor.

Hoja de ruta

1. Revisión profesional financiera, fiscal, de privacidad y licencias de datos.

2. Despliegue remoto con OAuth 2.1, aislamiento de tenant, cuotas y observabilidad.

3. Publicación en los registros compatibles tras una revisión de seguridad independiente.

La lista de verificación bloqueante está en GO_LIVE_CHECKLIST.md.