# Pharus MCP

[![Python 3.12+](https://img.shields.io/badge/Python-3.12%2B-blue?style=flat-square)](https://www.python.org/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.100%2B-009485?style=flat-square)](https://fastapi.tiangolo.com/)
[![Model Context Protocol](https://img.shields.io/badge/MCP-Enabled-brightgreen?style=flat-square)](https://modelcontextprotocol.io/)

Servidor MCP (Model Context Protocol) em Python para descoberta e consulta integrada dos serviços investigativos do ecossistema Pharus. Expõe ferramentas especializadas para análise de RIF, SIMBA, Telefônica, Telemática, KYT e Grafos através de uma arquitetura de serviços desacoplados.

## Características

- **Descoberta de Serviços**: Catálogo semântico de serviços investigativos com metadados e exemplos de uso
- **Protocolo MCP**: Implementação completa do Model Context Protocol sobre HTTP Streamable
- **Múltiplas Fontes de Dados**: Integração com RIF, SIMBA, Telefônica, Telemática, KYT e Grafos
- **Análise Financeira**: Ferramentas analíticas especializadas para investigação de transações e movimentações
- **Algoritmos de Grafo**: Catálogo semântico com sugestões automáticas de algoritmos baseadas em metadados de grafos
- **Documentação Automática**: Swagger UI e OpenAPI com rotas HTTP acessíveis
- **Configuração Flexível**: Suporte a variáveis de ambiente e configurações por serviço

## Pré-requisitos

- **Python 3.12+**
- **pip** (gerenciador de pacotes Python)
- **PowerShell 5.1+** (para Windows) ou bash (para Linux/macOS)
- Serviços upstream: RIF, SIMBA, Telefônica, Telemática, KYT, Grafos (conforme necessário)

## Instalação

### 1. Configurar Ambiente Virtual

Crie e ative a virtualenv:

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
```

**No Linux/macOS:**
```bash
python3 -m venv .venv
source .venv/bin/activate
```

### 2. Instalar Dependências

```powershell
python -m pip install --upgrade pip
python -m pip install -e .[dev]
```

### 3. Configurar Variáveis de Ambiente

Copie o arquivo de exemplo (opcional):

```powershell
Copy-Item .env.example .env
```

Edite o `.env` com as URLs base dos serviços conforme seu ambiente:

```env
HOST=127.0.0.1
PORT=8000
LOG_LEVEL=INFO
GRAFO_API_URL=http://localhost:8001
RIF_API_URL=http://localhost:8082
SIMBA_API_URL=http://localhost:8003
TELEFONICA_API_URL=http://localhost:8004
TELEMATICA_API_URL=http://localhost:8005
KYT_API_URL=http://localhost:8006
```

## Configuração

Variáveis de Ambiente Suportadas:

| Variável | Descrição | Padrão |
|----------|-----------|--------|
| `HOST` | Endereço IP para bind do servidor | `127.0.0.1` |
| `PORT` | Porta HTTP | `8000` |
| `LOG_LEVEL` | Nível de log (DEBUG, INFO, WARNING, ERROR) | `INFO` |
| `GRAFO_API_URL` | URL base do serviço de Grafos | `http://localhost:8001` |
| `RIF_API_URL` | URL base do serviço RIF | `http://localhost:8082` |
| `SIMBA_API_URL` | URL base do serviço SIMBA | `http://localhost:8003` |
| `TELEFONICA_API_URL` | URL base do serviço Telefônica | `http://localhost:8004` |
| `TELEMATICA_API_URL` | URL base do serviço Telemática | `http://localhost:8005` |
| `KYT_API_URL` | URL base do serviço KYT | `http://localhost:8006` |
| `MCP_STREAMABLE_HTTP_PATH` | Caminho HTTP para o protocolo MCP | `/mcp` |
| `DOCS_PATH` | Caminho para a documentação HTTP | `/docs` |

## Execução

### Iniciar o Servidor MCP (via HTTP)

**Método 1: Via módulo Python (recomendado)**

```powershell
.\.venv\Scripts\python -m pharus_mcp --transport http --host 127.0.0.1 --port 8000
```

**Método 2: Via script de inicialização**

```powershell
.\.venv\Scripts\python .\scripts\start_server.py
```

**Método 3: Via atalho (após instalação com -e .[dev])**

```powershell
pharus-start-server
```

### Gerenciar Serviços Upstream

**Iniciar RIF, SIMBA, Telefônica, Telemática, KYT e Grafos:**

```powershell
.\.venv\Scripts\python .\scripts\start_services.py
```

Aguarda a subida com timeout padrão de 60s.

**Verificar conectividade sem iniciar processos:**

```powershell
.\.venv\Scripts\python .\scripts\start_services.py --check-only
```

**Definir timeout customizado e modo estrito:**

```powershell
.\.venv\Scripts\python .\scripts\start_services.py --timeout 90 --strict
```

**Parar todos os serviços (Windows):**

```powershell
.\.venv\Scripts\python .\scripts\stop_services.py
```

**Listar PIDs sem finalizar (dry-run):**

```powershell
.\.venv\Scripts\python .\scripts\stop_services.py --dry-run
```

## Acessar o Servidor

### Rotas HTTP Disponíveis

O protocolo MCP roda no endpoint `/mcp` (não é amigável para navegador). Para inspeção e validação:

| Rota | Descrição |
|------|-----------|
| `/` | Redireciona para `/docs` |
| `/health` | Health check do servidor |
| `/docs` | Swagger UI interativa |
| `/docs/openapi.json` | Especificação OpenAPI completa |
| `/docs/services` | Catálogo de serviços investigativos |
| `/docs/tools` | Lista de tools MCP registradas |
| `/docs/prompts` | Lista de prompts MCP |
| `/docs/resources` | Lista de resources semânticos |
| `/docs/resource?uri=...` | Conteúdo de um resource específico |
| `/mcp` | Endpoint MCP (protocolo MCP sobre HTTP) |

**Exemplos:**

```bash
# Health check
curl http://127.0.0.1:8000/health

# Catálogo de serviços
curl http://127.0.0.1:8000/docs/services

# Detalhe de um serviço (RIF)
curl 'http://127.0.0.1:8000/docs/resource?uri=pharus://services/rif'
```

## Catálogo de Serviços

### Serviços Disponíveis

1. **Grafo** - Análise relacional com grafos de caso, labels, KYT e algoritmos
2. **KYT** - Enriquecimento de pessoas por documentos, emails e telefones
3. **RIF** - Análise de relatórios de inteligência financeira com transações e estatísticas
4. **SIMBA** - Consulta de contas bancárias e movimentações
5. **Telefônica** - Análise de telefonia com CDRs, locais e portabilidade
6. **Telemática** - Análise de aplicativos de mensageria e contatos

Cada serviço expõe um conjunto de tools especializadas e um catálogo semântico de uso recomendado.

## Desenvolvimento

### Estrutura do Projeto

```
pharus-mcp/
├── src/pharus_mcp/
│   ├── adapters/          # Adaptadores para serviços upstream (RIF, SIMBA, etc.)
│   ├── catalog/           # Catálogo semântico de serviços e algoritmos
│   ├── config/            # Configuração e settings
│   ├── models/            # Modelos de dados (Pydantic)
│   ├── server/            # Servidor FastAPI e registro MCP
│   ├── app.py             # Aplicação FastAPI principal
│   ├── cli.py             # Interface de linha de comando
│   ├── commands.py        # Comandos e orquestração
│   └── __main__.py        # Ponto de entrada
├── tests/                 # Suite de testes
├── scripts/               # Scripts auxiliares de inicialização
├── pyproject.toml         # Configuração Poetry/pip
└── README.md              # Este arquivo
```

### Executar Testes

```powershell
.\.venv\Scripts\python -m pytest
```

Com verbosidade:

```powershell
.\.venv\Scripts\python -m pytest -v
```

Rodar um teste específico:

```powershell
.\.venv\Scripts\python -m pytest tests/test_catalog.py::test_catalog_contains_expected_services -v
```

### Smoke Test Manual (HTTP)

**PowerShell:**

```powershell
$headers = @{ Accept = "application/json" }

Invoke-WebRequest -Uri "http://127.0.0.1:8000/health" -Headers $headers -Method GET
Invoke-WebRequest -Uri "http://127.0.0.1:8000/docs/services" -Headers $headers -Method GET
Invoke-WebRequest -Uri "http://127.0.0.1:8000/docs/resource?uri=pharus://services/rif" -Headers $headers -Method GET
```

**bash/curl:**

```bash
curl -s http://127.0.0.1:8000/health | jq .
curl -s http://127.0.0.1:8000/docs/services | jq .
curl -s 'http://127.0.0.1:8000/docs/resource?uri=pharus://services/rif' | jq .
```

### Dependências do Projeto

Principais dependências listadas em `pyproject.toml`:

- **fastapi** - Framework web assíncrono
- **httpx** - Cliente HTTP assíncrono
- **pydantic** - Validação de dados
- **mcp** - Model Context Protocol
- **sqlalchemy** - ORM (quando aplicável)
- **pytest** - Framework de testes
- **python-dotenv** - Suporte a .env

## Contribuição

Contribuições são bem-vindas! Por favor:

1. Faça um fork do repositório
2. Crie uma branch para sua feature (`git checkout -b feature/nova-funcionalidade`)
3. Commit suas mudanças (`git commit -am 'Adiciona nova funcionalidade'`)
4. Push para a branch (`git push origin feature/nova-funcionalidade`)
5. Abra um Pull Request

### Padrões de Código

- Use Python 3.12+ com type hints
- Siga o padrão PEP 8 (formatado com tools como `black` ou `autopep8`)
- Documente funções e classes com docstrings em português
- Escreva testes unitários para novas funcionalidades

## Solução de Problemas

### Erro: "not a git repository"
Inicialize o repositório com `git init`.

### Erro: "Connection refused" ao chamar serviço upstream
Verifique se a URL em `.env` está correta e se o serviço está ativo na porta esperada.

### Erro: "Port already in use"
Altere a porta no `.env` ou use `--port` na linha de comando.

### Testes falhando
Verifique se os serviços upstream estão rodando. Use `--check-only` para diagnosticar:

```powershell
.\.venv\Scripts\python .\scripts\start_services.py --check-only
```

## Licença

Este projeto está sob licença **MIT**. Veja o arquivo `LICENSE` para detalhes.

## Autores e Mantedores

**Desenvolvido pelo time de Tecnologia MPMG**

Para questões, sugestões ou reports de bugs, abra uma issue no repositório GitHub.

---

**Última atualização:** Abril de 2026  
**Versão:** 1.0.0  
**Status:** Ativo