Skip to main content
Glama
Pharus MCP
by rfalexandre

Pharus MCP

Python 3.12+ FastAPI Model Context Protocol

Python MCP (Model Context Protocol) server for integrated discovery and querying of investigative services in the Pharus ecosystem. It exposes specialized tools for analyzing RIF, SIMBA, Telefônica, Telemática, KYT, and Graph data through a decoupled service architecture.

Features

  • Service Discovery: Semantic catalog of investigative services with metadata and usage examples

  • MCP Protocol: Full implementation of the Model Context Protocol over HTTP Streamable

  • Multiple Data Sources: Integration with RIF, SIMBA, Telefônica, Telemática, KYT, and Graphs

  • Financial Analysis: Specialized analytical tools for investigating transactions and movements

  • Graph Algorithms: Semantic catalog with automatic algorithm suggestions based on graph metadata

  • Automatic Documentation: Swagger UI and OpenAPI with accessible HTTP routes

  • Flexible Configuration: Support for environment variables and per-service configurations

Prerequisites

  • Python 3.12+

  • pip (Python package manager)

  • PowerShell 5.1+ (for Windows) or bash (for Linux/macOS)

  • Upstream services: RIF, SIMBA, Telefônica, Telemática, KYT, Graphs (as needed)

Installation

1. Set Up Virtual Environment

Create and activate the virtualenv:

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

On Linux/macOS:

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

2. Install Dependencies

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

3. Configure Environment Variables

Copy the example file (optional):

Copy-Item .env.example .env

Edit the .env with the base URLs of the services according to your environment:

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

Configuration

Supported Environment Variables:

Variable

Description

Default

HOST

IP address for server binding

127.0.0.1

PORT

HTTP port

8000

LOG_LEVEL

Log level (DEBUG, INFO, WARNING, ERROR)

INFO

GRAFO_API_URL

Base URL for the Graph service

http://localhost:8001

RIF_API_URL

Base URL for the RIF service

http://localhost:8082

SIMBA_API_URL

Base URL for the SIMBA service

http://localhost:8003

TELEFONICA_API_URL

Base URL for the Telefônica service

http://localhost:8004

TELEMATICA_API_URL

Base URL for the Telemática service

http://localhost:8005

KYT_API_URL

Base URL for the KYT service

http://localhost:8006

MCP_STREAMABLE_HTTP_PATH

HTTP path for the MCP protocol

/mcp

DOCS_PATH

Path for HTTP documentation

/docs

Execution

Start the MCP Server (via HTTP)

Method 1: Via Python module (recommended)

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

Method 2: Via startup script

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

Method 3: Via shortcut (after installation with -e .[dev])

pharus-start-server

Manage Upstream Services

Start RIF, SIMBA, Telefônica, Telemática, KYT, and Graphs:

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

Waits for startup with a default timeout of 60s.

Check connectivity without starting processes:

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

Set custom timeout and strict mode:

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

Stop all services (Windows):

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

List PIDs without terminating (dry-run):

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

Accessing the Server

Available HTTP Routes

The MCP protocol runs on the /mcp endpoint (not browser-friendly). For inspection and validation:

Route

Description

/

Redirects to /docs

/health

Server health check

/docs

Interactive Swagger UI

/docs/openapi.json

Full OpenAPI specification

/docs/services

Investigative services catalog

/docs/tools

List of registered MCP tools

/docs/prompts

List of MCP prompts

/docs/resources

List of semantic resources

/docs/resource?uri=...

Content of a specific resource

/mcp

MCP endpoint (MCP protocol over HTTP)

Examples:

# 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'

Service Catalog

Available Services

  1. Graph - Relational analysis with case graphs, labels, KYT, and algorithms

  2. KYT - Person enrichment via documents, emails, and phone numbers

  3. RIF - Financial intelligence report analysis with transactions and statistics

  4. SIMBA - Bank account and movement queries

  5. Telefônica - Telephony analysis with CDRs, locations, and portability

  6. Telemática - Messaging app and contact analysis

Each service exposes a set of specialized tools and a semantic catalog of recommended usage.

Development

Project Structure

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

Run Tests

.\.venv\Scripts\python -m pytest

With verbosity:

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

Run a specific test:

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

Manual Smoke Test (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 .

Project Dependencies

Main dependencies listed in pyproject.toml:

  • fastapi - Asynchronous web framework

  • httpx - Asynchronous HTTP client

  • pydantic - Data validation

  • mcp - Model Context Protocol

  • sqlalchemy - ORM (when applicable)

  • pytest - Testing framework

  • python-dotenv - .env support

Contribution

Contributions are welcome! Please:

  1. Fork the repository

  2. Create a branch for your feature (git checkout -b feature/new-feature)

  3. Commit your changes (git commit -am 'Add new feature')

  4. Push to the branch (git push origin feature/new-feature)

  5. Open a Pull Request

Code Standards

  • Use Python 3.12+ with type hints

  • Follow PEP 8 standard (formatted with tools like black or autopep8)

  • Document functions and classes with docstrings in Portuguese

  • Write unit tests for new features

Troubleshooting

Error: "not a git repository"

Initialize the repository with git init.

Error: "Connection refused" when calling upstream service

Check if the URL in .env is correct and if the service is active on the expected port.

Error: "Port already in use"

Change the port in .env or use --port on the command line.

Tests failing

Check if upstream services are running. Use --check-only to diagnose:

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

License

This project is under the MIT license. See the LICENSE file for details.

Authors and Maintainers

Developed by the MPMG Technology team

For questions, suggestions, or bug reports, open an issue in the GitHub repository.


Last update: April 2026
Version: 1.0.0
Status: Active

Available Tools

63 tools
catalog_describe_serviceC

Describe um servico investigativo especifico do catalogo do Pharus.

Inputs: service (required). Returns: service, operation, query, summary, +6 more

catalog_list_servicesB

Lista os servicos investigativos conhecidos pelo catalogo do Pharus.

Inputs: no named parameters. Returns: service, operation, query, summary, +6 more

grafo_describe_algorithmC

Descreve um algoritmo especifico do modulo de grafos.

Inputs: familia (required), algoritmo (required). Returns: service, operation, query, summary, +6 more

grafo_describe_algorithm_familyD

Descreve uma familia de algoritmos do modulo de grafos.

Inputs: familia (required). Returns: service, operation, query, summary, +6 more

grafo_get_algorithm_helpC

Retorna ajuda em markdown para um enum de algoritmos do grafo-back, quando disponivel.

Inputs: enum_name (required). Returns: service, operation, query, summary, +6 more

grafo_get_graphB

Busca um grafo especifico por UUID.

Inputs: grafo_id (required). Returns: service, operation, query, summary, +6 more

grafo_list_algorithm_enumsB

Lista os enums e valores relevantes para o catalogo de algoritmos do modulo de grafos.

Inputs: no named parameters. Returns: service, operation, query, summary, +6 more

grafo_list_algorithm_familiesB

Lista as familias de algoritmos conhecidas para o modulo de grafos.

Inputs: no named parameters. Returns: service, operation, query, summary, +6 more

grafo_list_algorithmsA

Lista algoritmos do modulo de grafos, opcionalmente filtrando por familia.

Inputs: familia. Returns: service, operation, query, summary, +6 more

grafo_list_graphsC

Lista grafos do modulo de grafo por caso ou criador.

Inputs: caso_id, criado_por_id, pagina, itens_por_pagina. Returns: service, operation, query, summary, +6 more

grafo_list_kyt_layersC

Lista camadas KYT configuradas no modulo de grafo.

Inputs: eh_ativo, pagina, itens_por_pagina. Returns: service, operation, query, summary, +6 more

grafo_list_kyt_relationshipsC

Lista relacionamentos KYT configurados no modulo de grafo.

Inputs: eh_ativo, pagina, itens_por_pagina. Returns: service, operation, query, summary, +6 more

grafo_list_labelsC

Lista labels do modulo de grafo, incluindo schema_propriedades.

Inputs: label_type, label_code, pagina, itens_por_pagina. Returns: service, operation, query, summary, +6 more

grafo_suggest_algorithms_for_graphB

Sugere algoritmos para um grafo com base em seus metadados e em um objetivo investigativo opcional.

Inputs: grafo_id (required), objetivo. Returns: service, operation, query, summary, +6 more

kyt_get_by_documentC

Consulta a API KYT por documentos, em modo full ou lite.

Inputs: documentos (required), modo. Returns: service, operation, query, summary, +6 more

kyt_get_by_emailC

Consulta a API KYT por email, em modo full ou lite.

Inputs: emails (required), modo. Returns: service, operation, query, summary, +6 more

kyt_get_by_phoneC

Consulta a API KYT por telefone, em modo full ou lite.

Inputs: telefones (required), modo. Returns: service, operation, query, summary, +6 more

kyt_list_framesB

Lista os quadros e atributos conhecidos pela API KYT.

Inputs: no named parameters. Returns: service, operation, query, summary, +6 more

rif_analytics_get_resumoC

Retorna um resumo consolidado dos indicadores analiticos de uma origem.

Inputs: src_id (required), data_inicio, data_fim. Returns: service, operation, query, summary, +6 more

rif_analytics_list_funcoes_por_envolvidoC

Lista as funcoes exercidas por um CPF/CNPJ dentro dos indexadores da origem.

Inputs: src_id (required), cpf_cnpj (required). Returns: service, operation, query, summary, +6 more

rif_analytics_list_maiores_transacoesC

Lista as maiores transacoes associadas a uma origem (src_id).

Inputs: src_id (required), top. Returns: service, operation, query, summary, +6 more

rif_analytics_list_maiores_transacoes_por_pessoaC

Lista as maiores transacoes vinculadas a um CPF/CNPJ em uma origem.

Inputs: src_id (required), cpf_cnpj (required), top. Returns: service, operation, query, summary, +6 more

rif_analytics_list_pessoas_transacoes_por_tipoC

Lista pessoas relacionadas e valores de transacoes por tipo de operacao.

Inputs: src_id (required), cpf_cnpj (required), tipo_transacao (required), top. Returns: service, operation, query, summary, +6 more

simba_list_accountsC

Lista contas do SIMBA com filtros explicitos.

Inputs: banco_id, numero_conta, cpf_cnpj_titular, nome_titular, +2 more. Returns: service, operation, query, summary, +6 more

simba_list_accounts_by_personC

Lista contas do SIMBA por pessoa.

Inputs: cpf_cnpj (required). Returns: service, operation, query, summary, +6 more

simba_list_movements_by_person_and_fileC

Lista movimentacoes do SIMBA por pessoa e identificador de arquivo.

Inputs: cpf_cnpj (required), identificador (required). Returns: service, operation, query, summary, +6 more

simba_list_movements_by_srcC

Lista movimentacoes do SIMBA por src_id.

Inputs: src_id (required), pagina, itens_por_pagina. Returns: service, operation, query, summary, +6 more

telefonica_analytics_calls_by_caseC

Lista ligacoes de um numero por src_id com paginacao e ordenacao opcionais.

Inputs: src_id (required), numero_telefone (required), pagina, itens_por_pagina, +2 more. Returns: service, operation, query, summary, +6 more

telefonica_analytics_calls_by_fileC

Lista ligacoes de um numero por arquivo com paginacao e ordenacao opcionais.

Inputs: src_id (required), identificador (required), numero_telefone (required), pagina, +3 more. Returns: service, operation, query, summary, +6 more

telefonica_analytics_call_stats_by_caseC

Retorna estatisticas consolidadas de ligacoes para um numero por src_id.

Inputs: src_id (required), numero_telefone (required). Returns: service, operation, query, summary, +6 more

telefonica_analytics_call_stats_by_fileC

Retorna estatisticas de ligacoes para um numero em arquivo especifico.

Inputs: src_id (required), identificador (required), numero_telefone (required). Returns: service, operation, query, summary, +6 more

telefonica_analytics_connections_by_numberC

Lista conexoes de dados moveis de um numero por src_id.

Inputs: src_id (required), numero_telefone (required). Returns: service, operation, query, summary, +6 more

telefonica_analytics_distinct_numbers_by_caseB

Conta numeros distintos de origem e destino por src_id.

Inputs: src_id (required). Returns: service, operation, query, summary, +6 more

telefonica_analytics_distinct_numbers_by_fileC

Conta numeros distintos de origem e destino por arquivo da Telefonica.

Inputs: src_id (required), identificador (required). Returns: service, operation, query, summary, +6 more

telefonica_analytics_locations_by_numberC

Lista linha do tempo de locais por numero (voz + conexoes).

Inputs: src_id (required), numero_telefone (required). Returns: service, operation, query, summary, +6 more

telefonica_analytics_phones_by_antennaC

Lista telefones conectados a uma antena da Telefonica em um periodo opcional.

Inputs: src_id (required), cgi_erb (required), data_inicio, data_fim. Returns: service, operation, query, summary, +6 more

telefonica_analytics_portability_by_numberC

Lista eventos de portabilidade de um numero por src_id.

Inputs: src_id (required), numero_telefone (required). Returns: service, operation, query, summary, +6 more

telefonica_get_fileC

Busca um arquivo da Telefonica por src_id e identificador.

Inputs: src_id (required), identificador (required). Returns: service, operation, query, summary, +6 more

telefonica_get_file_statusC

Retorna o status de um arquivo da Telefonica.

Inputs: src_id (required), identificador (required). Returns: service, operation, query, summary, +6 more

telefonica_list_antennasC

Lista dados de antena de um arquivo da Telefonica.

Inputs: src_id (required), identificador (required), pagina, itens_por_pagina. Returns: service, operation, query, summary, +6 more

telefonica_list_connectionsC

Lista conexoes de um arquivo da Telefonica.

Inputs: src_id (required), identificador (required), pagina, itens_por_pagina. Returns: service, operation, query, summary, +6 more

telefonica_list_filesC

Lista arquivos da Telefonica por src_id.

Inputs: src_id (required). Returns: service, operation, query, summary, +6 more

telefonica_list_messagesC

Lista mensagens de um arquivo da Telefonica.

Inputs: src_id (required), identificador (required), pagina, itens_por_pagina. Returns: service, operation, query, summary, +6 more

telefonica_list_nat_ipsC

Lista IPs nateados de um arquivo da Telefonica.

Inputs: src_id (required), identificador (required), pagina, itens_por_pagina. Returns: service, operation, query, summary, +6 more

telefonica_list_portability_eventsC

Lista eventos de portabilidade de um arquivo da Telefonica.

Inputs: src_id (required), identificador (required), pagina, itens_por_pagina. Returns: service, operation, query, summary, +6 more

telefonica_list_supplementalC

Lista dados suplementares de um arquivo da Telefonica.

Inputs: src_id (required), identificador (required), pagina, itens_por_pagina. Returns: service, operation, query, summary, +6 more

telefonica_list_voiceC

Lista registros de voz de um arquivo da Telefonica.

Inputs: src_id (required), identificador (required), pagina, itens_por_pagina. Returns: service, operation, query, summary, +6 more

telematica_analytics_by_accountC

Retorna metricas analiticas da Telematica por source_id e identificador_conta.

Inputs: source_id (required), identificador_conta (required). Returns: service, operation, query, summary, +6 more

telematica_analytics_by_sourceC

Retorna metricas analiticas da Telematica por source_id.

Inputs: source_id (required). Returns: service, operation, query, summary, +6 more

telematica_analytics_connections_by_deviceC

Retorna total de conexoes da conta agrupado por dispositivo.

Inputs: source_id (required), identificador_conta (required). Returns: service, operation, query, summary, +6 more

telematica_analytics_contacts_by_cityC

Retorna distribuicao de contatos por municipio para a conta.

Inputs: source_id (required), identificador_conta (required). Returns: service, operation, query, summary, +6 more

telematica_analytics_distinct_ips_by_dayC

Retorna serie temporal de IPs distintos por dia da conta.

Inputs: source_id (required), identificador_conta (required), top_n, data_inicio, +1 more. Returns: service, operation, query, summary, +6 more

telematica_analytics_recent_groupsC

Retorna grupos recentes da conta com filtros opcionais de periodo.

Inputs: source_id (required), identificador_conta (required), top_n, data_inicio, +1 more. Returns: service, operation, query, summary, +6 more

telematica_analytics_relevant_groupsC

Retorna os grupos mais relevantes da conta por quantidade de participantes.

Inputs: source_id (required), identificador_conta (required), top_n. Returns: service, operation, query, summary, +6 more

telematica_analytics_verify_contactsC

Verifica se numeros informados sao contatos da conta e se ha simetria.

Inputs: source_id (required), identificador_conta (required), numeros (required). Returns: service, operation, query, summary, +6 more

telematica_get_recordB

Busca um registro detalhado da Telematica por UUID.

Inputs: registro_id (required). Returns: service, operation, query, summary, +6 more

telematica_list_connectionsC

Lista conexoes de registros da Telematica.

Inputs: registro_ids (required), pagina, itens_por_pagina. Returns: service, operation, query, summary, +6 more

telematica_list_contactsC

Lista contatos de registros da Telematica.

Inputs: registro_ids (required), pagina, itens_por_pagina. Returns: service, operation, query, summary, +6 more

telematica_list_devicesC

Lista dispositivos de registros da Telematica.

Inputs: registro_ids (required), pagina, itens_por_pagina. Returns: service, operation, query, summary, +6 more

telematica_list_emailsC

Lista emails de registros da Telematica.

Inputs: registro_ids (required), pagina, itens_por_pagina. Returns: service, operation, query, summary, +6 more

telematica_list_groupsC

Lista grupos de registros da Telematica.

Inputs: registro_ids (required), pagina, itens_por_pagina. Returns: service, operation, query, summary, +6 more

telematica_list_ipsC

Lista enderecos IP de registros da Telematica.

Inputs: registro_ids (required), pagina, itens_por_pagina. Returns: service, operation, query, summary, +6 more

telematica_list_recordsB

Lista registros da Telematica por origem/controle ou por usuario.

Inputs: source_id, identificador, criado_por_id, pagina, +1 more. Returns: service, operation, query, summary, +6 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.8/5.0

    Scored across 63 tools

    Disambiguation4/5

    Tools are well-organized into distinct modules (catalog, grafo, kyt, rif_analytics, simba, telefonica, telematica), with clear separation of purposes within each module. Some minor overlap exists within modules (e.g., multiple list tools for telefonica files), but descriptions clarify specific contexts like 'by_case' vs 'by_file'.

    Naming Consistency5/5

    Tool names follow a highly consistent snake_case pattern with a clear module_action_resource structure (e.g., grafo_list_algorithms, telefonica_analytics_calls_by_case). This predictability makes it easy for agents to understand and navigate the toolset across all 63 tools.

    Tool Count2/5

    With 63 tools, the count is excessive for a single server, making it overwhelming for agents to manage. While the tools cover multiple investigative domains, such a large number suggests poor scoping and could lead to confusion or inefficiency in tool selection.

    Completeness4/5

    The toolset provides comprehensive coverage for investigative analysis across multiple data sources (e.g., graphs, telecom, financial), with CRUD-like operations for listing, describing, and analyzing. Minor gaps may exist in update/delete operations, but the surface supports core investigative workflows effectively.

    Related MCP Connectors