Pharus MCP

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:

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

No Linux/macOS:

python3 -m venv .venv
source .venv/bin/activate

2. Instalar Dependências

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

3. Configurar Variáveis de Ambiente

Copie o arquivo de exemplo (opcional):

Copy-Item .env.example .env

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

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)

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

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

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

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

pharus-start-server

Gerenciar Serviços Upstream

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

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

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

Verificar conectividade sem iniciar processos:

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

Definir timeout customizado e modo estrito:

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

Parar todos os serviços (Windows):

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

Listar PIDs sem finalizar (dry-run):

.\.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:

# 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

.\.venv\Scripts\python -m pytest

Com verbosidade:

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

Rodar um teste específico:

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

Smoke Test Manual (HTTP)

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:

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:

.\.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