Pharus MCP

Python-сервер MCP (Model Context Protocol) для интегрированного обнаружения и запроса следственных услуг в экосистеме Pharus. Он предоставляет специализированные инструменты для анализа данных RIF, SIMBA, Telefônica, Telemática, KYT и графов через архитектуру разделенных сервисов.

Характеристики

• Обнаружение сервисов: Семантический каталог следственных услуг с метаданными и примерами использования

• Протокол MCP: Полная реализация Model Context Protocol через HTTP Streamable

• Множественные источники данных: Интеграция с RIF, SIMBA, Telefônica, Telemática, KYT и графами

• Финансовый анализ: Специализированные аналитические инструменты для расследования транзакций и движений средств

• Алгоритмы графов: Семантический каталог с автоматическими предложениями алгоритмов на основе метаданных графов

• Автоматическая документация: Swagger UI и OpenAPI с доступными HTTP-маршрутами

• Гибкая конфигурация: Поддержка переменных окружения и конфигураций для каждого сервиса

Предварительные требования

• Python 3.12+

• pip (менеджер пакетов Python)

• PowerShell 5.1+ (для Windows) или bash (для Linux/macOS)

• Входящие сервисы: RIF, SIMBA, Telefônica, Telemática, KYT, Графы (по мере необходимости)

Установка

1. Настройка виртуального окружения

Создайте и активируйте virtualenv:

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

В Linux/macOS:

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

2. Установка зависимостей

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

3. Настройка переменных окружения

Скопируйте файл примера (необязательно):

Copy-Item .env.example .env

Отредактируйте .env с базовыми URL-адресами сервисов в соответствии с вашей средой:

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

Конфигурация

Поддерживаемые переменные окружения:

Запуск

Запуск сервера MCP (через HTTP)

Метод 1: Через модуль Python (рекомендуется)

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

Метод 2: Через скрипт инициализации

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

Метод 3: Через ярлык (после установки с -e .[dev])

pharus-start-server

Управление входящими сервисами

Запуск RIF, SIMBA, Telefônica, Telemática, KYT и графов:

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

Ожидает запуска с тайм-аутом по умолчанию 60 секунд.

Проверка подключения без запуска процессов:

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

Установка пользовательского тайм-аута и строгого режима:

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

Остановка всех сервисов (Windows):

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

Список PID без завершения (dry-run):

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

Доступ к серверу

Доступные HTTP-маршруты

Протокол MCP работает на эндпоинте /mcp (не предназначен для браузера). Для проверки и валидации:

Примеры:

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

Каталог сервисов

Доступные сервисы

1. Grafo - Реляционный анализ с графами дел, метками, KYT и алгоритмами

2. KYT - Обогащение данных о людях по документам, электронной почте и телефонам

3. RIF - Анализ отчетов финансовой разведки с транзакциями и статистикой

4. SIMBA - Запрос банковских счетов и движений средств

5. Telefônica - Анализ телефонии с CDR, местоположениями и переносимостью номеров

6. Telemática - Анализ мессенджеров и контактов

Каждый сервис предоставляет набор специализированных инструментов и семантический каталог рекомендуемого использования.

Разработка

Структура проекта

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

Запуск тестов

.\.venv\Scripts\python -m pytest

С подробным выводом:

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

Запуск конкретного теста:

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

Ручной Smoke-тест (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 .

Зависимости проекта

Основные зависимости, перечисленные в pyproject.toml:

• fastapi - Асинхронный веб-фреймворк

• httpx - Асинхронный HTTP-клиент

• pydantic - Валидация данных

• mcp - Model Context Protocol

• sqlalchemy - ORM (где применимо)

• pytest - Фреймворк для тестирования

• python-dotenv - Поддержка .env

Вклад в проект

Мы приветствуем ваш вклад! Пожалуйста:

1. Сделайте форк репозитория

2. Создайте ветку для вашей функции (git checkout -b feature/new-feature)

3. Закоммитьте изменения (git commit -am 'Добавлена новая функция')

4. Отправьте изменения в ветку (git push origin feature/new-feature)

5. Откройте Pull Request

Стандарты кода

• Используйте Python 3.12+ с подсказками типов (type hints)

• Следуйте стандарту PEP 8 (форматирование с помощью инструментов, таких как black или autopep8)

• Документируйте функции и классы с помощью docstrings на португальском языке

• Пишите модульные тесты для новых функций

Устранение неполадок

Ошибка: "not a git repository"

Инициализируйте репозиторий с помощью git init.

Ошибка: "Connection refused" при вызове входящего сервиса

Проверьте, правильный ли URL указан в .env и запущен ли сервис на ожидаемом порту.

Ошибка: "Port already in use"

Измените порт в .env или используйте --port в командной строке.

Тесты не проходят

Убедитесь, что входящие сервисы запущены. Используйте --check-only для диагностики:

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

Лицензия

Этот проект распространяется под лицензией MIT. Подробности см. в файле LICENSE.

Авторы и сопровождающие

Разработано командой технологий MPMG

По вопросам, предложениям или сообщениям об ошибках открывайте issue в репозитории GitHub.

Последнее обновление: Апрель 2026 г. Версия: 1.0.0 Статус: Активен