Alpaca MCP Gold Standard

Un servidor para interactuar con la API de trading de Alpaca. Requiere credenciales de API a través de variables de entorno.

GitHub
3

Documentación

Alpaca MCP Gold Standard

Una implementación integral de la arquitectura definitiva del servidor MCP (Model Context Protocol) para operaciones de trading profesionales, logrando un 100% de cumplimiento con los patrones de estándar de oro documentados en la arquitectura de referencia de Quick Data MCP.

🏆 ¿Qué Hace que Esto 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 principales con más de 50 herramientas que abarcan operaciones de trading, análisis avanzado y capacidades universales de análisis de datos.

📊 Métricas de Implementación

  • 31 Herramientas MCP: Cobertura completa de operaciones de trading
  • 11 Espejos de Recursos: Compatibilidad universal con clientes
  • 4 Prompts de Contexto: Guía inteligente de conversación
  • 7/7 Patrones de Arquitectura: 100% de cumplimiento con el estándar de oro
  • Más de 50 Capacidades Totales: Plataforma de trading integral
  • 91 Pruebas de API Reales: 100% de tasa de aprobación con integración real de Alpaca API

🎯 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: Acciones con indicadores de impulso positivo
  • Activos Volátiles: Posiciones de alta volatilidad que requieren monitoreo activo
  • Generadores de Ingresos: Posiciones de dividendos o retorno estable
  • Instrumentos de Cobertura: Activos de gestión de riesgos y protección de cartera
  • Jugadas Especulativas: Oportunidades de alto riesgo y alta recompensa

2. Patrón de Espejo de Recursos ✅

Compatibilidad universal con CUALQUIER cliente MCP:

  • 11 herramientas espejo proporcionan funcionalidad idéntica a los recursos
  • Cero sobrecarga de mantenimiento mediante envoltura de funciones
  • Respaldo sin interrupciones para clientes solo de herramientas
  • Ruta de migración a prueba de futuro

3. Prompts Conscientes del Contexto ✅

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

  • portfolio_first_look - Analiza sus tenencias específicas
  • trading_strategy_workshop - Personalizado según la composición de su cartera
  • market_analysis_session - Enfocado en sus símbolos rastreados
  • 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 Trading: Ejecute algoritmos personalizados con contexto de cartera
  • Optimización de Cartera: Optimización avanzada con parámetros de riesgo
  • Análisis de Riesgo: Métricas y cálculos de riesgo personalizados
  • Analítica Universal: Funciona con CUALQUIER estructura de datos
  • Protección de tiempo de espera de 30 segundos con manejo integral de errores

5. Herramientas de Análisis Avanzado ✅

Inteligencia sofisticada de cartera:

  • Evaluación de Salud de Cartera: Sistema de puntuación de 100 puntos
    • Análisis de diversificación
    • Métricas de concentración de riesgo
    • Evaluación del equilibrio de rendimiento
    • Recomendaciones accionables con herramientas específicas
  • Análisis de Correlación de Mercado: Matrices de correlación de 30 días
    • Identificar posiciones sobre-correlacionadas
    • Puntuación de diversificación
    • Perspectivas y recomendaciones de riesgo

6. Agnosticismo Universal de Datos ✅

Más allá del trading: funciona con CUALQUIER dato estructurado:

  • Auto-descubre tipos de columnas y relaciones
  • Herramientas genéricas de correlación y segmentación
  • Capacidades de visualización adaptativa
  • Patrones de integración entre conjuntos de datos

7. Manejo Consistente de Errores ✅

Gestión de errores de nivel profesional:

{
  "status": "error",
  "message": "Human-readable error description",
  "error_type": "ExceptionType",
  "metadata": {"context": "additional_info"}
}

🚀 Inicio Rápido

Requisitos Previos

  • Python 3.12+
  • Administrador de paquetes uv
  • Cuenta de trading de Alpaca (trading en papel compatible)

Instalación

# Clone and setup
git clone <repository>
cd alpaca-mcp-gold-standard

# Install dependencies
uv sync

# Configure environment
cp .env.example .env
# Edit .env with your Alpaca API credentials

Ejecutar el Servidor

# Development mode
uv run python main.py

# Debug mode with verbose logging
LOG_LEVEL=DEBUG uv run python main.py

# Production mode with Docker
docker build -t alpaca-mcp-gold .
docker run -p 8000:8000 --env-file .env alpaca-mcp-gold

Pruebas

# Run all tests with coverage
uv run pytest tests/ -v --cov=src --cov-report=term-missing

# Test specific gold standard patterns
uv run pytest tests/test_resource_mirrors.py -v  # Resource mirror pattern
uv run pytest tests/test_state_management.py -v  # State management
uv run pytest tests/test_integration.py -v        # Full workflows

📋 Configuración del Cliente MCP

Para Claude Desktop

Agregue a su configuración de Claude:

{
  "mcpServers": {
    "alpaca-trading-gold": {
      "command": "/path/to/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 Cuenta y Cartera (4 herramientas)

  • get_account_info_tool() - Estado de cuenta en tiempo real con perspectivas de cartera
  • get_positions_tool() - Tenencias con clasificación adaptativa de roles
  • get_open_position_tool(symbol) - Detalles de posición específica
  • get_portfolio_summary_tool() - Análisis integral con sugerencias de IA

Datos de Mercado e Investigación (4 herramientas)

  • get_stock_quote_tool(symbol) - Cotizaciones en tiempo real con análisis de spread
  • get_stock_trade_tool(symbol) - Información de la última operación
  • get_stock_snapshot_tool(symbols) - Datos completos de mercado con volatilidad
  • get_historical_bars_tool(symbol, timeframe) - Datos históricos OHLCV

Gestión de Órdenes (5 herramientas)

  • place_market_order_tool(symbol, side, quantity) - Ejecución inmediata
  • place_limit_order_tool(symbol, side, quantity, price) - Fijación de precios objetivo
  • place_stop_loss_order_tool(symbol, side, quantity, stop_price) - 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) - Ejecutar algoritmos personalizados
  • execute_portfolio_optimization_strategy_tool(code, risk_tolerance) - Optimizar tenencias
  • execute_risk_analysis_strategy_tool(code, benchmarks) - Analítica 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

Analítica 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 a conjunto de datos

Espejos de Recursos (11 herramientas)

Cada recurso tiene una herramienta correspondiente para compatibilidad universal:

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

Herramientas de Utilidad (1 herramienta)

  • clear_portfolio_state_tool() - Restablecer estado para pruebas

🏗️ Resumen de Arquitectura

src/mcp_server/
├── config/                     # Environment-based configuration
│   ├── settings.py            # Pydantic settings management
│   └── simple_settings.py     # Simplified config loader
├── models/                    # 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               # Account operations
│   ├── market_data_tools.py           # Market data access
│   ├── order_management_tools.py      # Trading operations
│   ├── custom_strategy_execution.py   # Safe code execution
│   ├── advanced_analysis_tools.py     # Portfolio analytics
│   ├── execute_custom_analytics_code_tool.py  # Universal analytics
│   └── resource_mirror_tools.py       # Compatibility layer
├── resources/                 # URI-based data access
│   └── trading_resources.py  # trading:// scheme handlers
├── prompts/                   # Context-aware conversations
│   └── trading_prompts.py    # 4 adaptive prompt generators
└── server.py                  # FastMCP registration (31 tools)

🧪 Excelencia en Pruebas

Suite Integral de Pruebas

tests/
├── conftest.py                # Mock Alpaca API & fixtures
├── test_account_tools.py      # Account operation tests
├── test_market_data_tools.py  # Market data tests
├── test_order_management_tools.py  # Order operation tests
├── test_resources.py          # Resource URI tests
├── test_resource_mirrors.py   # Mirror consistency validation
├── test_state_management.py   # Memory & state tests
└── test_integration.py        # Complete workflow tests

Los Accesorios de Prueba Proporcionan

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

💡 Innovaciones Clave

1. Clasificación de Roles de Entidades

Cada acción/posición se clasifica inteligentemente:

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

2. Gestión de Estado Eficiente en Memoria

# Automatic cleanup and tracking
StateManager.add_symbol("AAPL", entity_info)
memory_usage = StateManager.get_memory_usage()  # Returns MB used
StateManager.clear_all()  # Clean slate

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.subprocess.PIPE,
        stderr=asyncio.subprocess.STDOUT
    )
    stdout, _ = await asyncio.wait_for(process.communicate(), timeout=30)

4. Perspectivas Adaptativas de Cartera

# Context-aware suggestions based on actual holdings
"Your portfolio shows high concentration in tech stocks (65%). 
Consider diversifying with healthcare or consumer staples for 
better risk balance. Use get_stock_snapshot('JNJ,PG,KO') to 
research defensive positions."

📊 Rendimiento y Monitoreo

  • Tiempos de Respuesta: Promedio <100ms para operaciones de datos
  • Uso de Memoria: ~50MB en reposo, ~200MB con cartera completa cargada
  • Tiempo de Espera de Subprocesos: Protección de 30 segundos para código personalizado
  • Monitoreo de Salud: Verificaciones continuas de conexión con Alpaca API
  • Seguimiento de Estado: Monitoreo del uso de memoria en tiempo real

🔧 Guía de Desarrollo

Agregar Nuevas Herramientas

  1. Cree la función en el tools/category_tools.py apropiado
  2. Siga el formato de respuesta estándar: 
    async def your_new_tool(param: str) -> Dict[str, Any]:
    try:
        # Implementation
        return {
            "status": "success",
            "data": result_data,
            "metadata": {"operation": "your_new_tool"}
        }
    except Exception as e:
        return {
            "status": "error",
            "message": str(e),
            "error_type": type(e).__name__
        }
  3. Regístrese en server.py con el decorador @mcp.tool()
  4. Agregue pruebas integrales
  5. Actualice la documentación

Estándares de Calidad de Código

# Format code
uv run black src/ tests/

# Lint code
uv run ruff check src/ tests/

# Type checking
uv run mypy src/

# Run all quality checks
uv run black src/ tests/ && uv run ruff check src/ tests/ && uv run mypy src/

🔒 Mejores Prácticas de Seguridad

  • Gestión de Credenciales: Solo variables de entorno
  • Validación de Entradas: Modelos Pydantic para todas las entradas
  • Sanitización de Errores: Sin credenciales en mensajes de error
  • Aislamiento de Subprocesos: El código no confiable se ejecuta en sandbox
  • Limitación de Tasa de API: Manejo integrado de límites de tasa de Alpaca

📚 Estructura de Documentación

  • README.md: Esta guía integral
  • CLAUDE.md: Guía para el desarrollo con Claude Code
  • 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 del estándar de oro
    • custom_analytic_code.md - Diseño de subprocesos
    • poc_init_generic.md - Patrones universales
    • resource_workaround.md - Patrón de espejo
  • .claude/commands/: Flujos de trabajo de desarrollo
    • Patrones de implementación paralela
    • Marcos de validación

🚢 Despliegue en Producción

Despliegue con 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

# Required
ALPACA_API_KEY=your_api_key
ALPACA_SECRET_KEY=your_secret_key

# Optional
ALPACA_PAPER_TRADE=True  # Use paper trading (recommended)
LOG_LEVEL=INFO          # Logging verbosity
MCP_SERVER_NAME=alpaca-trading-gold

🤝 Contribuciones

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

  1. Siga los Patrones de Arquitectura: Mantenga los 7 patrones del estándar de oro
  2. Pruebas Integrales: Cobertura mínima del 80% para código nuevo
  3. Documentación: Actualice los documentos relevantes para nuevas funciones
  4. Consistencia: Iguale el estilo y los patrones de código existentes
  5. Lista de Verificación de Revisión:
    • Las pruebas pasan con cobertura
    • Los espejos de recursos se actualizan si es necesario
    • El manejo de errores sigue el formato estándar
    • Documentación actualizada
    • Sugerencias de tipo incluidas

🌟 Por Qué Esta Implementación Importa

Este no es solo otro servidor MCP: es una clase magistral de arquitectura de software:

  1. Implementación de Referencia: Demuestra cada mejor práctica de MCP
  2. Listo para Producción: Manejo integral de errores, monitoreo 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 expansión:

  • Transmisión de datos de mercado en tiempo real por WebSocket
  • Algoritmos avanzados de optimización de cartera
  • Soporte para gestión de múltiples cuentas
  • Marco de backtesting de estrategias de trading
  • Integración con corredores adicionales
  • Perspectivas impulsadas por aprendizaje automático

📄 Licencia

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

🙏 Agradecimientos

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

Esta es la implementación de referencia definitiva para el desarrollo profesional de MCP. Ya sea que esté construyendo sistemas de trading, plataformas de análisis de datos o cualquier otra aplicación impulsada por MCP, este código demuestra los patrones y prácticas que conducen a sistemas listos para producción, mantenibles y extensibles.