Pharus MCP

Ein Python-MCP-Server (Model Context Protocol) für die integrierte Erkennung und Abfrage von investigativen Diensten im Pharus-Ökosystem. Er stellt spezialisierte Tools zur Analyse von RIF-, SIMBA-, Telefônica-, Telemática-, KYT- und Graph-Daten über eine entkoppelte Dienstarchitektur bereit.

Funktionen

• Diensterkennung: Semantischer Katalog investigativer Dienste mit Metadaten und Anwendungsbeispielen

• MCP-Protokoll: Vollständige Implementierung des Model Context Protocol über HTTP Streamable

• Mehrere Datenquellen: Integration mit RIF, SIMBA, Telefônica, Telemática, KYT und Graphen

• Finanzanalyse: Spezialisierte Analysetools zur Untersuchung von Transaktionen und Bewegungen

• Graph-Algorithmen: Semantischer Katalog mit automatischen Algorithmus-Vorschlägen basierend auf Graph-Metadaten

• Automatische Dokumentation: Swagger UI und OpenAPI mit zugänglichen HTTP-Routen

• Flexible Konfiguration: Unterstützung für Umgebungsvariablen und dienstspezifische Konfigurationen

Voraussetzungen

• Python 3.12+

• pip (Python-Paketmanager)

• PowerShell 5.1+ (für Windows) oder bash (für Linux/macOS)

• Upstream-Dienste: RIF, SIMBA, Telefônica, Telemática, KYT, Graphen (nach Bedarf)

Installation

1. Virtuelle Umgebung einrichten

Erstellen und aktivieren Sie die virtualenv:

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

Unter Linux/macOS:

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

2. Abhängigkeiten installieren

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

3. Umgebungsvariablen konfigurieren

Kopieren Sie die Beispieldatei (optional):

Copy-Item .env.example .env

Bearbeiten Sie die .env-Datei mit den Basis-URLs der Dienste entsprechend Ihrer Umgebung:

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

Konfiguration

Unterstützte Umgebungsvariablen:

Ausführung

MCP-Server starten (via HTTP)

Methode 1: Über Python-Modul (empfohlen)

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

Methode 2: Über Startskript

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

Methode 3: Über Verknüpfung (nach Installation mit -e .[dev])

pharus-start-server

Upstream-Dienste verwalten

RIF, SIMBA, Telefônica, Telemática, KYT und Graphen starten:

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

Wartet auf den Start mit einem Standard-Timeout von 60s.

Konnektivität prüfen, ohne Prozesse zu starten:

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

Benutzerdefiniertes Timeout und strikten Modus festlegen:

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

Alle Dienste stoppen (Windows):

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

PIDs auflisten, ohne zu beenden (Dry-Run):

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

Zugriff auf den Server

Verfügbare HTTP-Routen

Das MCP-Protokoll läuft auf dem Endpunkt /mcp (nicht browserfreundlich). Zur Inspektion und Validierung:

Beispiele:

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

Dienstekatalog

Verfügbare Dienste

1. Grafo - Relationale Analyse mit Fallgraphen, Labels, KYT und Algorithmen

2. KYT - Anreicherung von Personen durch Dokumente, E-Mails und Telefonnummern

3. RIF - Analyse von Finanzberichten mit Transaktionen und Statistiken

4. SIMBA - Abfrage von Bankkonten und Bewegungen

5. Telefônica - Telefonie-Analyse mit CDRs, Standorten und Portabilität

6. Telemática - Analyse von Messaging-Apps und Kontakten

Jeder Dienst stellt eine Reihe spezialisierter Tools und einen semantischen Katalog für die empfohlene Nutzung bereit.

Entwicklung

Projektstruktur

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

Tests ausführen

.\.venv\Scripts\python -m pytest

Mit Ausführlichkeit:

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

Einen spezifischen Test ausführen:

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

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

Projektabhängigkeiten

Hauptabhängigkeiten gelistet in pyproject.toml:

• fastapi - Asynchrones Web-Framework

• httpx - Asynchroner HTTP-Client

• pydantic - Datenvalidierung

• mcp - Model Context Protocol

• sqlalchemy - ORM (falls zutreffend)

• pytest - Test-Framework

• python-dotenv - .env-Unterstützung

Mitwirken

Beiträge sind willkommen! Bitte:

1. Forken Sie das Repository

2. Erstellen Sie einen Branch für Ihr Feature (git checkout -b feature/neue-funktion)

3. Committen Sie Ihre Änderungen (git commit -am 'Fügt neue Funktion hinzu')

4. Pushen Sie auf den Branch (git push origin feature/neue-funktion)

5. Öffnen Sie einen Pull Request

Code-Standards

• Verwenden Sie Python 3.12+ mit Type Hints

• Befolgen Sie den PEP 8-Standard (formatiert mit Tools wie black oder autopep8)

• Dokumentieren Sie Funktionen und Klassen mit Docstrings auf Portugiesisch

• Schreiben Sie Unit-Tests für neue Funktionen

Fehlerbehebung

Fehler: "not a git repository"

Initialisieren Sie das Repository mit git init.

Fehler: "Connection refused" beim Aufruf eines Upstream-Dienstes

Überprüfen Sie, ob die URL in .env korrekt ist und ob der Dienst auf dem erwarteten Port aktiv ist.

Fehler: "Port already in use"

Ändern Sie den Port in der .env oder verwenden Sie --port in der Befehlszeile.

Tests schlagen fehl

Überprüfen Sie, ob die Upstream-Dienste laufen. Verwenden Sie --check-only zur Diagnose:

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

Lizenz

Dieses Projekt steht unter der MIT-Lizenz. Siehe die Datei LICENSE für Details.

Autoren und Betreuer

Entwickelt vom Technologie-Team MPMG

Für Fragen, Vorschläge oder Fehlerberichte öffnen Sie bitte ein Issue im GitHub-Repository.

Letzte Aktualisierung: April 2026
Version: 1.0.0
Status: Aktiv