Pharus MCP

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:

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:

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