Pharus MCP

Servidor MCP (Model Context Protocol) en Python para el descubrimiento y consulta integrada de los servicios de investigación del ecosistema Pharus. Expone herramientas especializadas para el análisis de RIF, SIMBA, Telefónica, Telemática, KYT y Grafos a través de una arquitectura de servicios desacoplados.

Características

• Descubrimiento de Servicios: Catálogo semántico de servicios de investigación con metadatos y ejemplos de uso

• Protocolo MCP: Implementación completa del Model Context Protocol sobre HTTP Streamable

• Múltiples Fuentes de Datos: Integración con RIF, SIMBA, Telefónica, Telemática, KYT y Grafos

• Análisis Financiero: Herramientas analíticas especializadas para la investigación de transacciones y movimientos

• Algoritmos de Grafo: Catálogo semántico con sugerencias automáticas de algoritmos basadas en metadatos de grafos

• Documentación Automática: Swagger UI y OpenAPI con rutas HTTP accesibles

• Configuración Flexible: Soporte para variables de entorno y configuraciones por servicio

Requisitos previos

• Python 3.12+

• pip (gestor de paquetes de Python)

• PowerShell 5.1+ (para Windows) o bash (para Linux/macOS)

• Servicios upstream: RIF, SIMBA, Telefónica, Telemática, KYT, Grafos (según sea necesario)

Instalación

1. Configurar Entorno Virtual

Cree y active el virtualenv:

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

En Linux/macOS:

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

2. Instalar Dependencias

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

3. Configurar Variables de Entorno

Copie el archivo de ejemplo (opcional):

Copy-Item .env.example .env

Edite el .env con las URLs base de los servicios según su entorno:

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

Configuración

Variables de Entorno Soportadas:

Ejecución

Iniciar el Servidor MCP (vía HTTP)

Método 1: Vía módulo Python (recomendado)

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

Método 2: Vía script de inicialización

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

Método 3: Vía acceso directo (tras instalación con -e .[dev])

pharus-start-server

Gestionar Servicios Upstream

Iniciar RIF, SIMBA, Telefónica, Telemática, KYT y Grafos:

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

Espera a la subida con un tiempo de espera (timeout) predeterminado de 60s.

Verificar conectividad sin iniciar procesos:

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

Definir tiempo de espera personalizado y modo estricto:

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

Detener todos los servicios (Windows):

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

Listar PIDs sin finalizar (dry-run):

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

Acceder al Servidor

Rutas HTTP Disponibles

El protocolo MCP se ejecuta en el endpoint /mcp (no es amigable para el navegador). Para inspección y validación:

Ejemplos:

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

Servicios Disponibles

1. Grafo - Análisis relacional con grafos de caso, etiquetas, KYT y algoritmos

2. KYT - Enriquecimiento de personas por documentos, correos electrónicos y teléfonos

3. RIF - Análisis de informes de inteligencia financiera con transacciones y estadísticas

4. SIMBA - Consulta de cuentas bancarias y movimientos

5. Telefónica - Análisis de telefonía con CDRs, ubicaciones y portabilidad

6. Telemática - Análisis de aplicaciones de mensajería y contactos

Cada servicio expone un conjunto de tools especializadas y un catálogo semántico de uso recomendado.

Desarrollo

Estructura del Proyecto

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

Ejecutar Pruebas

.\.venv\Scripts\python -m pytest

Con verbosidad:

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

Ejecutar una prueba específica:

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

Dependencias del Proyecto

Principales dependencias listadas en pyproject.toml:

• fastapi - Framework web asíncrono

• httpx - Cliente HTTP asíncrono

• pydantic - Validación de datos

• mcp - Model Context Protocol

• sqlalchemy - ORM (cuando sea aplicable)

• pytest - Framework de pruebas

• python-dotenv - Soporte para .env

Contribución

¡Las contribuciones son bienvenidas! Por favor:

1. Haga un fork del repositorio

2. Cree una rama para su funcionalidad (git checkout -b feature/nueva-funcionalidad)

3. Confirme sus cambios (git commit -am 'Añade nueva funcionalidad')

4. Haga push a la rama (git push origin feature/nueva-funcionalidad)

5. Abra un Pull Request

Estándares de Código

• Use Python 3.12+ con type hints

• Siga el estándar PEP 8 (formateado con herramientas como black o autopep8)

• Documente funciones y clases con docstrings en portugués

• Escriba pruebas unitarias para nuevas funcionalidades

Solución de Problemas

Error: "not a git repository"

Inicialice el repositorio con git init.

Error: "Connection refused" al llamar al servicio upstream

Verifique si la URL en .env es correcta y si el servicio está activo en el puerto esperado.

Error: "Port already in use"

Cambie el puerto en el .env o use --port en la línea de comandos.

Pruebas fallando

Verifique si los servicios upstream están ejecutándose. Use --check-only para diagnosticar:

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

Licencia

Este proyecto está bajo la licencia MIT. Vea el archivo LICENSE para más detalles.

Autores y Mantenedores

Desarrollado por el equipo de Tecnología MPMG

Para preguntas, sugerencias o informes de errores, abra un issue en el repositorio de GitHub.

Última actualización: Abril de 2026
Versión: 1.0.0
Estado: Activo