haroldorg-stockdata-mcp-server/README.md

Servidor MCP para consultar ações negociadas na B3 usando Model Context Protocol

# haroldorg-stockdata-mcp-server

Servidor MCP para consultar ações negociadas na B3 usando Model Context Protocol.

## Instalação

```bash
npm install -g haroldorg-stockdata-mcp-server
```

Ou execute diretamente com npx:

```bash
npx haroldorg-stockdata-mcp-server
```

## Como usar

1. **Inicie o servidor**
   
   No terminal, execute:
   ```bash
   npm start
   # ou
   node index.js
   # ou
   npx haroldorg-stockdata-mcp-server
   ```

2. **Endpoints disponíveis**

### `/mcp/tools`
- Lista todos os endpoints e ferramentas disponíveis no servidor MCP.
- Exemplo:
  - `GET http://localhost:3000/mcp/tools`

### `/mcp/stockdata`
- Retorna informações detalhadas sobre ações negociadas na B3.
- Suporta filtros dinâmicos via query string em todos os campos:
  - valor exato: `campo=valor`
  - maior: `campo_gt=valor`
  - maior ou igual: `campo_gte=valor`
  - menor: `campo_lt=valor`
  - menor ou igual: `campo_lte=valor`
  - contém: `campo_contains=valor`
  - intervalo: `campo_range=min,max`
  - expressão regular: `campo_regex=regex`
- Exemplo de uso:
  - `GET http://localhost:3000/mcp/stockdata?papel=BBAS3`
  - `GET http://localhost:3000/mcp/stockdata?pl_lt=10&divYield_gte=6`
  - `GET http://localhost:3000/mcp/stockdata?papel_regex=3$`
- O retorno inclui uma legenda explicativa dos campos e os dados filtrados.

#### Exemplo de resposta
```json
{
  "legenda": { "papel": "...", "cotacao": "...", ... },
  "dados": [
    {
      "papel": "BBAS3",
      "cotacao": 22.43,
      "pl": 3.86,
      "divYield": "10.60%",
      ...
    }
  ]
}
```

## Principais recursos
- Consulta de ações da B3 com múltiplos filtros avançados.
- Retorno de legenda explicativa dos campos.
- Endpoints REST simples e práticos para integração com outras ferramentas.
- Pronto para uso via npx ou instalação global.

## Repositório
https://github.com/haroldo-rg/stock-data-web-app