Alpaca MCP Gold Standard

Una implementación completa de la arquitectura de servidor MCP (Model Context Protocol) definitiva para operaciones de trading profesionales, que logra el 100% de cumplimiento de los patrones gold standard documentados en la arquitectura de referencia MCP de Quick Data.

🏆 ¿Qué hace que sea el estándar de oro?

Esta implementación representa la referencia definitiva para el desarrollo profesional de MCP, implementando los 7 patrones arquitectónicos centrales con 50+ herramientas que abarcan operaciones de trading, analítica avanzada y capacidades universales de análisis de datos.

métricas de implementación

• 31 herramientas MCP: Cobertura completa de las operaciones de trading
• 11 espejos de recursos: Compatibilidad universal con el cliente
• 4 Avisos de contexto: Guía de conversación inteligente
• 7/7 patrones de arquitectura: 100% de conformidad con las normas de oro
• 50+ Capacidades totales: Plataforma comercial integral
• 91 Pruebas de API reales: 100% de aprobados con integración real de la API de Alpaca

🎯 Patrones de arquitectura del estándar de oro

1. Descubrimiento adaptativo ✅

Clasifica automáticamente acciones y posiciones con asignación inteligente de roles:

• Candidatos de crecimiento: Valores con indicadores de impulso positivos
• Activos Volátiles: Posiciones de alta volatilidad que requieren una supervisión activa
• Generadores de ingresos: Dividendos o posiciones de rentabilidad estable
• Instrumentos de cobertura: Activos de gestión de riesgos y protección de carteras
• Posiciones especulativas: Oportunidades de alto riesgo y alta rentabilidad

2. Patrón espejo de recursos ✅

Compatibilidad universal con CUALQUIER cliente MCP:

• 11 herramientas espejo proporcionan una funcionalidad idéntica a los recursos
• Cero sobrecarga de mantenimiento gracias a la envoltura de funciones
• Fallback sin fisuras para clientes que sólo utilizan herramientas
• Ruta de migración preparada para el futuro

3. Avisos contextuales

Iniciadores de conversación que hacen referencia a su cartera real:

• portfolio_first_look - Analiza sus participaciones específicas
• trading_strategy_workshop - Adaptado a la composición de su cartera
• market_analysis_session - Centrado en sus símbolos de seguimiento
• list_mcp_capabilities - Guía completa de funciones

4. Ejecución segura de código personalizado ✅

Ejecute análisis personalizados con aislamiento de subprocesos:

• Estrategias de negociación: Ejecutar algoritmos personalizados con contexto de cartera
• Optimización de lacartera: Optimización avanzada con parámetros de riesgo
• Análisis de riesgos: Métricas y cálculos de riesgo personalizados
• Análisis universal: Funciona con CUALQUIER estructura de conjunto de datos
• protección de tiempo de espera de 30 segundos con gestión integral de errores

5. Herramientas de análisis avanzado ✅

Inteligencia de cartera sofisticada:

• Evaluación de la salud de la cartera: sistema de puntuación de 100 puntos
  • Análisis de diversificación
  • Métricas de concentración de riesgos
  • Evaluación del equilibrio de rendimiento
  • Recomendaciones prácticas con herramientas específicas
• Análisis de correlación de mercados: matrices de correlación a 30 días
  • Identificación de posiciones sobrecorrelacionadas
  • Puntuación de diversificación
  • Información y recomendaciones sobre riesgos

6. Agnosticismo universal de conjuntos de datos ✅

Más allá de la negociación: funciona con CUALQUIER dato estructurado:

• Autodescubre los tipos de columnas y las relaciones
• Herramientas genéricas de correlación y segmentación
• Capacidades de visualización adaptables
• Patrones de integración entre conjuntos de datos

7. Gestión de errores coherente ✅

Gestión de errores de nivel profesional:

{ "estado": "error", "message": "Descripción de error legible por humanos", "error_type": "ExceptionType", "metadata": {"context": "additional_info"} }

inicio rápido

Requisitos previos

• Python 3.12+
• gestor de paquetes uv
• Cuenta de trading alpaca (admite trading en papel)

Instalación

# Clonar y configurar git clone <repositorio> cd alpaca-mcp-gold-standard # Instalar dependencias uv sync # Configurar entorno cp .env.example .env # Editar .env con sus credenciales de la API Alpaca

Ejecutar el servidor

# Modo desarrollo uv run python main.py # Modo depuración con registro detallado LOG_LEVEL=DEBUG uv run python main.py # Modo producción con Docker docker build -t alpaca-mcp-gold . docker run -p 8000:8000 --env-file .env alpaca-mcp-gold

Pruebas

# Ejecutar todas las pruebas con cobertura uv run pytest tests/ -v --cov=src --cov-report=term-missing # Probar patrones gold standard específicos uv run pytest tests/test_resource_mirrors.py -v # Patrón de espejos de recursos uv run pytest tests/test_state_management.py -v # Gestión de estados uv run pytest tests/test_integration.py -v # Flujos de trabajo completos

📋 Configuración del cliente MCP

Para Claude Desktop

Añade a tu configuración Claude:

{ "mcpServers": { "alpaca-trading-gold": { "command": "/ruta/a/uv", "args": [ "--directory", "/absolute/path/to/alpaca-mcp-gold-standard", "run", "python", "main.py" ], "env": { "LOG_LEVEL": "INFO" } } } }

🛠️ Catálogo completo de herramientas

Gestión de cuentas y carteras (4 herramientas)

• get_account_info_tool() - Estado de la cuenta en tiempo real con información sobre la cartera
• get_positions_tool() - Carteras con clasificación de funciones adaptable
• get_open_position_tool(symbol) - Detalles específicos de la posición
• get_portfolio_summary_tool() - Análisis exhaustivo con sugerencias de IA

Datos e investigación de mercado (4 herramientas)

• get_stock_quote_tool(símbolo) - Cotizaciones en tiempo real con análisis de diferenciales
• get_stock_trade_tool(símbolo) - Información más reciente sobre operaciones
• get_stock_snapshot_tool(symbols) - Datos completos del mercado con volatilidad
• get_historical_bars_tool(symbol, timeframe) - Datos históricos OHLCV

Gestión de órdenes (5 herramientas)

• place_market_order_tool(símbolo, lado, cantidad) - Ejecución inmediata
• place_limit_order_tool(símbolo, lado, cantidad, precio) - Precio objetivo
• place_stop_loss_order_tool(símbolo, lado, cantidad, stop_precio) - Gestión de riesgos
• get_orders_tool(status, limit) - Historial y seguimiento de órdenes
• cancel_order_tool(order_id) - Cancelación de órdenes

Ejecución de estrategias personalizadas (3 herramientas)

• execute_custom_trading_strategy_tool(code, symbols) - Ejecución de algoritmos personalizados
• execute_portfolio_optimization_strategy_tool(code, risk_tolerance) - Optimización de carteras
• execute_risk_analysis_strategy_tool(code, benchmarks ) - Análisis de riesgos

Análisis avanzado (2 herramientas)

• generate_portfolio_health_assessment_tool() - Puntuación de salud de 100 puntos
• generate_advanced_market_correlation_analysis_tool(symbols) - Matrices de correlación

Análisis universal (2 herramientas)

• execute_custom_analytics_code_tool(dataset, code) - Análisis de cualquier conjunto de datos
• create_sample_dataset_from_portfolio_tool() - Convertir cartera en conjunto de datos

Espejos de recursos (11 herramientas)

Cada recurso tiene su herramienta correspondiente para una compatibilidad universal:

• resource_account_info_tool() → trading://cuenta/info
• resource_portfolio_summary_tool() → trading://cartera/summary
• Y 9 herramientas espejo más...

Herramientas de utilidad (1 herramienta)

• clear_portfolio_state_tool() - Restablecer estado para pruebas

🏗️ Visión general de la arquitectura

src/mcp_server/ ├── config/ # Configuración basada en el entorno │ ├── settings.py # Gestión de configuración Pydantic │ └── simple_settings.py # Simplified config loader ├── modelos/ # Core business logic │ ├── schemas.py # Entity classification & state management │ └── alpaca_clients.py # Singleton API client management ├── tools/ # 31 MCP tools by category │ ├── account_tools.py # Operaciones con cuentas │ ├── market_data_tools.py # Acceso a datos de mercado │ ├── order_management_tools.py # Operaciones de negociación │ ├── custom_strategy_execution.py # Ejecución de código seguro │ ├── advanced_analysis_tools.py # Portfolio analytics │ ├── execute_custom_analytics_code_tool.py # Universal analytics │ └── resource_mirror_tools.py # Capa de compatibilidad ├── resources/ # Acceso a datos basado en URI │ └── trading_resources.py # trading:// scheme handlers ├── prompts/ # Context-aware conversations │ └── trading_prompts.py # 4 generadores de prompt adaptables └── server.py # Registro FastMCP (31 herramientas)

🧪 Excelencia en las pruebas

Completo conjunto de pruebas

tests/ ├── conftest.py # Mock Alpaca API & fixtures ├── test_account_tools.py # Pruebas de funcionamiento de cuentas ├── test_market_data_tools.py # Pruebas de datos de mercado ├─ test_order_management_tools.py # Pruebas de operación de pedidos ├── test_resources.py # Pruebas de URI de recursos ├── test_resource_mirrors.py # Validación de consistencia de espejos ├── test_state_management.py # Pruebas de memoria y estado └─ test_integration.py # Pruebas de flujo de trabajo completo

Los dispositivos de prueba proporcionan

• Limpieza automática del estado entre pruebas
• API de Alpaca simulada con respuestas realistas
• Funciones de ayuda para la validación de respuestas
• Seguimiento del uso de memoria

principales innovaciones

1. Clasificación de roles de las entidades

Cada acción/posición se clasifica de forma inteligente:

entity = EntityInfo( symbol="AAPL", suggested_role=EntityRole.GROWTH_CANDIDATE, characteristics=["high_momentum", "tech_sector", "large_cap"], confidence_score=0.85 )

2. Gestión de estados eficiente desde el punto de vista de la memoria

# Limpieza y seguimiento automáticos StateManager.add_symbol("AAPL", entity_info) memory_usage = StateManager.get_memory_usage() # Devuelve los MB utilizados StateManager.clear_all() # Borrón y cuenta nueva

3. Patrón de aislamiento de subprocesos

# Safe execution with timeout async def execute_custom_code(code: str) -> str: process = await asyncio.create_subprocess_exec( 'uv', 'run', '--with', 'pandas', '--with', 'numpy', 'python', '-c', execution_code, stdout=asyncio.subproceso.PIPE, stderr=asyncio.subproceso.STDOUT ) stdout, _ = await asyncio.wait_for(process.communicate(), timeout=30)

4. Visión adaptativa de la cartera

# Sugerencias contextuales basadas en las posiciones actuales "Su cartera muestra una alta concentración en valores tecnológicos (65%). 
Considere la posibilidad de diversificarla con valores sanitarios o de consumo básico para equilibrar mejor el riesgo. Utilice get_stock_snapshot('JNJ,PG,KO') para buscar posiciones defensivas."

rendimiento y seguimiento

• Tiempos de respuesta: Media <100ms para operaciones de datos
• Uso de memoria: ~50MB en reposo, ~200MB con toda la cartera cargada
• Tiempo de espera de subprocesos: protección de 30 segundos para código personalizado
• Monitorización de la salud: Comprobaciones continuas de la conexión a la API de Alpaca
• Seguimiento del estado: Monitorización del uso de memoria en tiempo real

🔧 Guía de desarrollo

Añadir nuevas herramientas

1. Crea la función en el archivo tools/category_tools.py que corresponda
2. Sigue el formato de respuesta estándar:

   async def tu_nueva_herramienta(param: str) -> Dict[str, Any]: try: # Implementación return { "estado": "success", "data": result_data, "metadata": {"operación": "tu_nueva_herramienta"} } except Exception as e: return { "estado": "error", "message": str(e), "error_type": type(e).__name__ }

3. Registrar en server.py con el decorador @mcp.tool()
4. Añadir pruebas completas
5. Actualizar la documentación

Estándares de calidad del código

# Formatear código uv run black src/ tests/ # Lint code uv run ruff check src/ tests/ # Type checking uv run mypy src/ # Ejecutar todas las comprobaciones de calidad uv run black src/ tests/ && uv run ruff check src/ tests/ && uv run mypy src/

🔒 Buenas prácticas de seguridad

• Gestión de credenciales: Sólo variables de entorno
• Validación de entradas: Modelos pydantic para todas las entradas
• Sanitización deerrores: Sin credenciales en los mensajes de error
• Aislamiento de subprocesos: El código no fiable se ejecuta en un entorno aislado
• Limitación de velocidad de la API: Manejo de límite de tasa de Alpaca incorporado

estructura de la documentación

• README.md: Esta guía completa
• CLAUDE.md: Guía para el desarrollo del código Claude
• ai_docs/: Referencias optimizadas para IA
  • alpaca_py_sdk_reference.md - Guía del SDK de Alpaca
  • mcp_server_sdk_reference.md - Guía de patrones MCP
• specs/: Especificaciones arquitectónicas
  • architecture_overview.md - Patrones Gold Standard
  • custom_analytic_code.md - Diseño de subprocesos
  • poc_init_generic.md - Patrones universales
  • resource_workaround.md - Patrón espejo
• .claude/commands/: Flujos de trabajo de desarrollo
  • Patrones de implementación paralela
  • Marcos de validación

despliegue en producción

Despliegue en Docker

# Build production image docker build -t alpaca-mcp-gold . # Run with environment file docker run -d \ --name alpaca-mcp \ -p 8000:8000 \ --env-file .env \ --restart unless-stopped \ alpaca-mcp-gold

Variables de entorno

# Obligatorio ALPACA_API_KEY=su_clave_api ALPACA_SECRET_KEY=su_clave_secreta Opcional ALPACA_PAPER_TRADE=True Usar comercio en papel (recomendado) LOG_LEVEL=INFO Verbosidad del registro MCP_SERVER_NAME=alpaca-trading-gold

🤝 Contribución

Este proyecto sirve como referencia estándar de oro para el desarrollo de MCP. Al contribuir:

1. Siga los patrones de arquitectura: Mantenga los 7 patrones estándar de oro
2. Pruebas exhaustivas: Cobertura mínima del 80% para el código nuevo
3. Documentación: Actualizar la documentación pertinente para las nuevas funciones
4. Coherencia: Igualar el estilo y los patrones del código existente
5. Lista de comprobación
   • Pruebas superadas con cobertura
   • Actualización de las réplicas de recursos si es necesario
   • El tratamiento de errores sigue el formato estándar
   • Documentación actualizada
   • Se incluyen sugerencias de tipo

por qué es importante esta implementación

No se trata de un servidor MCP más: es una clase magistral de arquitectura de software:

1. Implementación de referencia: Demuestra cada una de las mejores prácticas de MCP
2. Listo para producción: Gestión integral de errores, supervisión y pruebas
3. Patrones universales: Técnicas aplicables a CUALQUIER dominio
4. Valor educativo: Aprenda patrones profesionales de desarrollo MCP
5. Base extensible: Fácil de adaptar para otros casos de uso

📈 Mejoras futuras

La arquitectura está diseñada para la expansión:

• Streaming de datos de mercado WebSocket en tiempo real
• Algoritmos avanzados de optimización de carteras
• Soporte de gestión multicuenta
• Marco de backtesting de estrategias de negociación
• Integración con otros brokers
• Información basada en aprendizaje automático

licencia

Este proyecto está licenciado bajo los mismos términos que el servidor original Alpaca MCP.

🙏 Agradecimientos

Construido sobre la base del servidor original Alpaca MCP, implementando las mejores prácticas integrales documentadas en el análisis de patrones MCP estándar de oro del repositorio padre. Agradecimientos especiales a las comunidades MCP y Alpaca por su excelente documentación y herramientas.

Esta es la implementación de referencia definitiva para el desarrollo profesional de MCP. Tanto si está construyendo sistemas de negociación, plataformas de análisis de datos o cualquier otra aplicación basada en MCP, esta base de código demuestra los patrones y prácticas que conducen a sistemas listos para la producción, mantenibles y extensibles.