# OpLab MCP Server

[![FastMCP 3.2.0](https://img.shields.io/badge/FastMCP-3.2.0-blue)](https://github.com/jlowin/fastmcp)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Servidor MCP (Model Context Protocol) para integração com as APIs do [OpLab](https://oplab.com.br), permitindo que agentes de IA acessem dados do mercado financeiro brasileiro.

## 📦 Ferramentas Disponíveis

| Ferramenta | Descrição |
|------------|-----------|
| `get_stock_info` | Informações detalhadas de ações (preço, volume, fundamentalistas) |
| `get_historical_data` | Dados históricos com múltiplas resoluções (1d, 1h, etc) |
| `get_options_chain` | Cadeia de opções completa com strikes e vencimentos |
| `get_stock_quote` | Cotações em tempo real de múltiplos ativos |
| `search_instruments` | Busca de ações, opções, fundos e índices |
| `get_market_status` | Status do mercado (aberto/fechado) |
| `get_interest_rates` | Taxas SELIC e CDI atualizadas |

## 🔧 Instalação

### Requisitos

- Docker e Docker Compose **OU**
- Python 3.11+
- Token de acesso OpLab ([obtenha aqui](https://oplab.com.br))

### Opção 1: Docker (Recomendado)

```bash
# 1. Clone o repositório
git clone https://github.com/seu-usuario/oplab-mcp.git
cd oplab-mcp

# 2. Build da imagem
docker build -t oplab-mcp:latest .

# 3. Execute o container
docker run -d \
  --name oplab-mcp \
  -p 8000:8000 \
  -e OPLAB_ACCESS_TOKEN=seu_token_aqui \
  -e SERVER_MODE=http \
  --restart unless-stopped \
  oplab-mcp:latest
```

### Opção 2: Python local

```bash
# 1. Clone e instale dependências
git clone https://github.com/seu-usuario/oplab-mcp.git
cd oplab-mcp
pip install -r requirements.txt

# 2. Configure o token
export OPLAB_ACCESS_TOKEN=seu_token_aqui

# 3. Execute em modo HTTP
export SERVER_MODE=http
python server.py

# OU em modo stdio (para uso local)
python server.py
```

## ⚙️ Configuração

### Variáveis de Ambiente

| Variável | Descrição | Padrão | Obrigatório |
|----------|-----------|--------|-------------|
| `OPLAB_ACCESS_TOKEN` | Token de API do OpLab | - | Sim |
| `SERVER_MODE` | Modo de execução: `http` ou `stdio` | `stdio` | Não |
| `SERVER_PORT` | Porta HTTP (apenas modo http) | `8000` | Não |
| `SERVER_HOST` | Host HTTP (apenas modo http) | `0.0.0.0` | Não |

### Modos de Operação

#### 🌐 Modo HTTP (para agentes remotos)

Expõe o servidor via HTTP com Server-Sent Events (SSE):

```bash
docker run -d \
  --name oplab-mcp \
  -p 8000:8000 \
  -e OPLAB_ACCESS_TOKEN=seu_token \
  -e SERVER_MODE=http \
  oplab-mcp:latest
```

**Endpoint MCP:** `http://localhost:8000/mcp`

#### 💻 Modo stdio (para agentes locais)

Executa via stdio para integração direta:

```bash
docker run -i --rm \
  -e OPLAB_ACCESS_TOKEN=seu_token \
  -e SERVER_MODE=stdio \
  oplab-mcp:latest
```

## 🤖 Integração com Agentes

### Claude Desktop

Arquivo: `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "oplab": {
      "url": "http://localhost:8000/mcp"
    }
  }
}
```

**Ou com Docker (stdio):**

```json
{
  "mcpServers": {
    "oplab": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "OPLAB_ACCESS_TOKEN=seu_token",
        "-e", "SERVER_MODE=stdio",
        "oplab-mcp:latest"
      ]
    }
  }
}
```

## 📖 Exemplos de Uso

Depois de configurado, você pode interagir com seu agente de IA:

```
👤 "Me mostre informações sobre PETR4"
🤖 [usa get_stock_info] Retorna preço, volume, variação...

👤 "Busque o histórico de VALE3 nos últimos 30 dias"
🤖 [usa get_historical_data] Retorna série histórica...

👤 "Quais opções estão disponíveis para ITUB4?"
🤖 [usa get_options_chain] Lista calls e puts com strikes...

👤 "O mercado está aberto agora?"
🤖 [usa get_market_status] Informa status atual...

👤 "Busque empresas de tecnologia"
🤖 [usa search_instruments] Lista empresas do setor...
```

## 🛠️ Desenvolvimento

### Estrutura do Projeto

```
oplab-mcp/
├── server.py             # Servidor MCP principal
├── requirements.txt      # Dependências Python
├── Dockerfile            # Imagem Docker
└── README.md             # Este arquivo
```

### Comandos Úteis

```bash
# Ver logs do container
docker logs -f oplab-mcp

# Reiniciar servidor
docker restart oplab-mcp

# Parar e remover
docker stop oplab-mcp && docker rm oplab-mcp

# Rebuild após mudanças
docker build -t oplab-mcp:latest . && docker restart oplab-mcp
```


### Token inválido

Erro: `OPLAB_ACCESS_TOKEN não configurado`

**Solução:** Certifique-se de passar o token via `-e OPLAB_ACCESS_TOKEN=...`

### Agente não conecta

1. Verifique se o servidor está rodando: `docker ps | grep oplab-mcp`
2. Teste o endpoint: `curl http://localhost:8000/mcp`
3. Verifique a URL na configuração do agente
4. Reinicie o agente após configurar

### Endpoints Utilizados

- `/market/stocks/{symbol}` - Informações de ações
- `/market/historical/{symbol}/{resolution}` - Dados históricos
- `/market/options/{symbol}` - Cadeia de opções
- `/market/quote` - Cotações em tempo real
- `/market/instruments/search` - Busca de instrumentos
- `/market/status` - Status do mercado
- `/market/interest_rates` - Taxas de juros

## 🤝 Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para:

1. Fazer fork do projeto
2. Criar uma branch para sua feature (`git checkout -b feature/MinhaFeature`)
3. Commit suas mudanças (`git commit -m 'Adiciona MinhaFeature'`)
4. Push para a branch (`git push origin feature/MinhaFeature`)
5. Abrir um Pull Request

## 📝 License

Este projeto está sob a licença MIT. Veja o arquivo [LICENSE](LICENSE) para mais detalhes.

## 🔗 Links Úteis

- [FastMCP Documentation](https://github.com/jlowin/fastmcp)
- [OpLab API Docs](https://oplab.com.br/docs)

## 💬 Suporte

Para dúvidas ou problemas:
- Abra uma [issue no GitHub](https://github.com/seu-usuario/oplab-mcp/issues)
- Consulte a [documentação do OpLab](https://oplab.com.br/docs)

---

Feito com ❤️ para a comunidade de desenvolvedores brasileiros