Alpaca MCP Gold Standard

Um servidor para interagir com a API de negociação Alpaca. Requer credenciais de API por meio de variáveis de ambiente.

GitHub
2

Documentação

Alpaca MCP Gold Standard

Uma implementação abrangente da arquitetura definitiva de servidor MCP (Model Context Protocol) para operações de trading profissionais, alcançando 100% de conformidade com os padrões gold standard documentados na arquitetura de referência Quick Data MCP.

🏆 O Que Torna Isso o Gold Standard?

Esta implementação representa a referência definitiva para desenvolvimento profissional de MCP, implementando todos os 7 padrões arquiteturais centrais com mais de 50 ferramentas abrangendo operações de trading, análises avançadas e capacidades universais de análise de dados.

📊 Métricas de Implementação

  • 31 Ferramentas MCP: Cobertura completa de operações de trading
  • 11 Espelhos de Recursos: Compatibilidade universal com clientes
  • 4 Prompts de Contexto: Orientação inteligente de conversas
  • 7/7 Padrões Arquiteturais: 100% de conformidade com o gold standard
  • Mais de 50 Capacidades Totais: Plataforma de trading abrangente
  • 91 Testes de API Reais: 100% de taxa de aprovação com integração real com a API Alpaca

🎯 Padrões Arquiteturais Gold Standard

1. Descoberta Adaptativa ✅

Classifica automaticamente ações e posições com atribuição inteligente de papéis:

  • Candidatos a Crescimento: Ações com indicadores de momentum positivos
  • Ativos Voláteis: Posições de alta volatilidade que exigem monitoramento ativo
  • Geradores de Renda: Posições com dividendos ou retorno estável
  • Instrumentos de Hedge: Ativos de gestão de risco e proteção de portfólio
  • Apostas Especulativas: Oportunidades de alto risco e alto retorno

2. Padrão de Espelho de Recursos ✅

Compatibilidade universal com QUALQUER cliente MCP:

  • 11 ferramentas espelho fornecem funcionalidade idêntica aos recursos
  • Zero sobrecarga de manutenção por meio de encapsulamento de funções
  • Fallback perfeito para clientes somente com ferramentas
  • Caminho de migração à prova de futuro

3. Prompts Sensíveis ao Contexto ✅

Iniciadores de conversa que referenciam seu portfólio real:

  • portfolio_first_look - Analisa suas posições específicas
  • trading_strategy_workshop - Personalizado para a composição do seu portfólio
  • market_analysis_session - Focado nos seus símbolos monitorados
  • list_mcp_capabilities - Guia completo de recursos

4. Execução Segura de Código Personalizado ✅

Execute análises personalizadas com isolamento de subprocesso:

  • Estratégias de Trading: Execute algoritmos personalizados com contexto do portfólio
  • Otimização de Portfólio: Otimização avançada com parâmetros de risco
  • Análise de Risco: Métricas e cálculos de risco personalizados
  • Analítica Universal: Funciona com QUALQUER estrutura de dados
  • Proteção de timeout de 30 segundos com tratamento abrangente de erros

5. Ferramentas de Análise Avançada ✅

Inteligência sofisticada de portfólio:

  • Avaliação de Saúde do Portfólio: Sistema de pontuação de 100 pontos
    • Análise de diversificação
    • Métricas de concentração de risco
    • Avaliação de equilíbrio de desempenho
    • Recomendações acionáveis com ferramentas específicas
  • Análise de Correlação de Mercado: Matrizes de correlação de 30 dias
    • Identificar posições supercorrelacionadas
    • Pontuação de diversificação
    • Insights de risco e recomendações

6. Agnosticismo Universal de Dados ✅

Além do trading - funciona com QUALQUER dado estruturado:

  • Descobre automaticamente tipos de colunas e relacionamentos
  • Ferramentas genéricas de correlação e segmentação
  • Capacidades de visualização adaptativas
  • Padrões de integração entre conjuntos de dados

7. Tratamento Consistente de Erros ✅

Gerenciamento de erros de nível profissional:

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

🚀 Início Rápido

Pré-requisitos

  • Python 3.12+
  • Gerenciador de pacotes uv
  • Conta de trading Alpaca (trading em papel suportado)

Instalação

# 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

Executando o 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

Testes

# 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

📋 Configuração do Cliente MCP

Para Claude Desktop

Adicione à sua configuração do 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 Ferramentas

Gerenciamento de Conta e Portfólio (4 ferramentas)

  • get_account_info_tool() - Status da conta em tempo real com insights de portfólio
  • get_positions_tool() - Posições com classificação adaptativa de papéis
  • get_open_position_tool(symbol) - Detalhes de posição específica
  • get_portfolio_summary_tool() - Análise abrangente com sugestões de IA

Dados de Mercado e Pesquisa (4 ferramentas)

  • get_stock_quote_tool(symbol) - Cotações em tempo real com análise de spread
  • get_stock_trade_tool(symbol) - Informações da negociação mais recente
  • get_stock_snapshot_tool(symbols) - Dados completos de mercado com volatilidade
  • get_historical_bars_tool(symbol, timeframe) - Dados históricos OHLCV

Gerenciamento de Ordens (5 ferramentas)

  • place_market_order_tool(symbol, side, quantity) - Execução imediata
  • place_limit_order_tool(symbol, side, quantity, price) - Definição de preço-alvo
  • place_stop_loss_order_tool(symbol, side, quantity, stop_price) - Gerenciamento de risco
  • get_orders_tool(status, limit) - Histórico e rastreamento de ordens
  • cancel_order_tool(order_id) - Cancelamento de ordens

Execução de Estratégia Personalizada (3 ferramentas)

  • execute_custom_trading_strategy_tool(code, symbols) - Executar algoritmos personalizados
  • execute_portfolio_optimization_strategy_tool(code, risk_tolerance) - Otimizar posições
  • execute_risk_analysis_strategy_tool(code, benchmarks) - Análises de risco

Análise Avançada (2 ferramentas)

  • generate_portfolio_health_assessment_tool() - Pontuação de saúde de 100 pontos
  • generate_advanced_market_correlation_analysis_tool(symbols) - Matrizes de correlação

Analítica Universal (2 ferramentas)

  • execute_custom_analytics_code_tool(dataset, code) - Análise de qualquer conjunto de dados
  • create_sample_dataset_from_portfolio_tool() - Converter portfólio em conjunto de dados

Espelhos de Recursos (11 ferramentas)

Cada recurso possui uma ferramenta correspondente para compatibilidade universal:

  • resource_account_info_tool() → trading://account/info
  • resource_portfolio_summary_tool() → trading://portfolio/summary
  • E mais 9 ferramentas espelho...

Ferramentas Utilitárias (1 ferramenta)

  • clear_portfolio_state_tool() - Redefinir estado para testes

🏗️ Visão Geral da Arquitetura

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)

🧪 Excelência em Testes

Suíte de Testes Abrangente

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

As Fixtures de Teste Fornecem

  • Limpeza automática de estado entre testes
  • API Alpaca simulada com respostas realistas
  • Funções auxiliares para validação de respostas
  • Rastreamento de uso de memória

💡 Inovações Principais

1. Classificação de Papéis de Entidades

Cada ação/posição é classificada de forma inteligente:

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

2. Gerenciamento de Estado Eficiente em Memória

# 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. Padrão de Isolamento de Subprocesso

# 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. Insights Adaptativos de Portfólio

# 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."

📊 Desempenho e Monitoramento

  • Tempos de Resposta: Média <100ms para operações de dados
  • Uso de Memória: ~50MB em repouso, ~200MB com portfólio completo carregado
  • Timeout de Subprocesso: Proteção de 30 segundos para código personalizado
  • Monitoramento de Saúde: Verificações contínuas de conexão com a API Alpaca
  • Rastreamento de Estado: Monitoramento de uso de memória em tempo real

🔧 Guia de Desenvolvimento

Adicionando Novas Ferramentas

  1. Crie a função no tools/category_tools.py apropriado
  2. Siga o formato padrão de resposta: 
    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. Registre no server.py com o decorador @mcp.tool()
  4. Adicione testes abrangentes
  5. Atualize a documentação

Padrões de Qualidade 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/

🔒 Melhores Práticas de Segurança

  • Gerenciamento de Credenciais: Somente variáveis de ambiente
  • Validação de Entrada: Modelos Pydantic para todas as entradas
  • Sanitização de Erros: Sem credenciais em mensagens de erro
  • Isolamento de Subprocesso: Código não confiável é executado em sandbox
  • Limitação de Taxa da API: Tratamento integrado de limite de taxa do Alpaca

📚 Estrutura da Documentação

  • README.md: Este guia abrangente
  • CLAUDE.md: Orientação para desenvolvimento com Claude Code
  • ai_docs/: Referências otimizadas para IA
    • alpaca_py_sdk_reference.md - Guia do SDK Alpaca
    • mcp_server_sdk_reference.md - Guia de padrões MCP
  • specs/: Especificações arquiteturais
    • architecture_overview.md - Padrões gold standard
    • custom_analytic_code.md - Design de subprocesso
    • poc_init_generic.md - Padrões universais
    • resource_workaround.md - Padrão de espelho
  • .claude/commands/: Fluxos de trabalho de desenvolvimento
    • Padrões de implementação paralela
    • Estruturas de validação

🚢 Implantação em Produção

Implantação com 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

Variáveis de Ambiente

# 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

🤝 Contribuindo

Este projeto serve como referência gold standard para desenvolvimento MCP. Ao contribuir:

  1. Siga os Padrões Arquiteturais: Mantenha todos os 7 padrões gold standard
  2. Testes Abrangentes: Cobertura mínima de 80% para código novo
  3. Documentação: Atualize os documentos relevantes para novos recursos
  4. Consistência: Corresponda ao estilo e padrões de código existentes
  5. Lista de Verificação de Revisão:
    • Testes passam com cobertura
    • Espelhos de recursos atualizados se necessário
    • Tratamento de erros segue o formato padrão
    • Documentação atualizada
    • Dicas de tipo incluídas

🌟 Por Que Esta Implementação é Importante

Este não é apenas mais um servidor MCP - é uma aula magistral de arquitetura de software:

  1. Implementação de Referência: Demonstra todas as melhores práticas de MCP
  2. Pronto para Produção: Tratamento abrangente de erros, monitoramento e testes
  3. Padrões Universais: Técnicas aplicáveis a QUALQUER domínio
  4. Valor Educacional: Aprenda padrões profissionais de desenvolvimento MCP
  5. Base Extensível: Fácil de adaptar para outros casos de uso

📈 Aprimoramentos Futuros

A arquitetura foi projetada para expansão:

  • Streaming de dados de mercado em tempo real via WebSocket
  • Algoritmos avançados de otimização de portfólio
  • Suporte a gerenciamento de múltiplas contas
  • Estrutura de backtesting de estratégias de trading
  • Integração com corretoras adicionais
  • Insights potencializados por machine learning

📄 Licença

Este projeto é licenciado sob os mesmos termos do servidor MCP Alpaca original.

🙏 Agradecimentos

Construído sobre a base do servidor MCP Alpaca original, implementando as melhores práticas abrangentes documentadas na análise do repositório pai sobre padrões gold standard de MCP. Agradecimentos especiais às comunidades MCP e Alpaca por sua excelente documentação e ferramentas.

Esta é a implementação de referência definitiva para desenvolvimento profissional de MCP. Seja você construindo sistemas de trading, plataformas de análise de dados ou qualquer outra aplicação potencializada por MCP, este código demonstra os padrões e práticas que levam a sistemas prontos para produção, sustentáveis e extensíveis.