┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  Frontend   │────▶│  ToPWR API  │────▶│  MCP Server │────▶│    Neo4j    │
│    :80      │     │    :8000    │     │    :8005    │     │    :7687    │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
React + Nginx         FastAPI              FastMCP          Knowledge Graph

PWrChat UI — React-чат-бот (боковая панель сессий, переключатель темной/светлой темы, сохранение темы)
Интеллектуальная маршрутизация запросов — система фильтров (guardrails) определяет релевантность запроса
Естественный язык в Cypher — преобразование вопросов в графовые запросы
RAG на графе знаний — генерация с дополнением извлечением (Retrieval-Augmented Generation) с использованием Neo4j
Протокол MCP — стандартный интерфейс Model Context Protocol
Наблюдаемость — опциональная интеграция трассировки Langfuse
Готовность к Docker — развертывание одной командой

Быстрый старт

# Setup
just setup
cp .env.example .env  # Edit with your API keys

# Run with Docker
just up      # Start Neo4j + MCP Server + API
just logs    # View logs
just down    # Stop services

Архитектура

Обзор системы

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  Frontend   │────▶│  ToPWR API  │────▶│  MCP Server │────▶│    Neo4j    │
│    :80      │     │    :8000    │     │    :8005    │     │    :7687    │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
React + Nginx         FastAPI              FastMCP          Knowledge Graph

Сервис	Порт	Описание
`frontend`	80	PWrChat — React-интерфейс чат-бота, обслуживаемый Nginx
`topwr-api`	8000	Бэкенд FastAPI для приложения ToPWR
`mcp-server`	8005	MCP-сервер с конвейером RAG
`neo4j`	7474/7687	База данных графа знаний

Конвейер RAG

Сердцем системы является конвейер RAG на базе LangGraph, который интеллектуально обрабатывает запросы пользователей:

Поток конвейера:

Фильтры (Guardrails) — быстрая LLM определяет, относится ли запрос к базе знаний
Генерация Cypher — точная LLM преобразует естественный язык в запрос Cypher
Извлечение — выполнение запроса к графу знаний Neo4j
Ответ — возврат структурированных контекстных данных

Конвейер данных

Отдельный ETL-конвейер для загрузки документов в граф знаний:

Этапы конвейера:

Загрузка документов — прием PDF и текстовых документов
Извлечение текста — OCR и извлечение контента
Обработка LLM — генерация запросов Cypher из контента
Наполнение графа — выполнение запросов для построения графа знаний

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

Скопируйте .env.example в .env и настройте:

########################################
# LLM / AI Provider Keys
########################################

# OpenAI API key (optional)
OPENAI_API_KEY=

# DeepSeek API key (optional)
DEEPSEEK_API_KEY=

# Google Generative AI / PaLM API key (optional)
GOOGLE_API_KEY=

# CLARIN LLM API key (optional, used by API & client)
CLARIN_API_KEY=


########################################
# Langfuse Observability
########################################

LANGFUSE_SECRET_KEY=
LANGFUSE_PUBLIC_KEY=
LANGFUSE_HOST=https://cloud.langfuse.com


########################################
# Neo4j Database
########################################

# URI used by data pipeline, MCP server and graph config
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=


########################################
# Data Pipeline Runtime Controls
########################################

# Max parallel pages processed per batch
DATA_PIPELINE_MAX_CONCURRENCY=4

# Minutes after which a stuck in-progress hash can be reclaimed
DATA_PIPELINE_CLAIM_STALE_MINUTES=30


########################################
# MCP Server Networking
########################################

# Bind host for the MCP server process
MCP_BIND_HOST=0.0.0.0

# Host/port used by API and MCP client to reach the MCP server
MCP_HOST=127.0.0.1
MCP_PORT=8005

Команды

# Docker Stack
just up          # Start all services (including frontend at :80)
just down        # Stop services
just logs        # View logs
just ps          # Service status
just nuke        # Remove everything

# Local Development
just mcp-server  # Run MCP server
just api         # Run FastAPI
just kg "query"  # Query knowledge graph

# Frontend
just frontend-install  # Install npm dependencies
just frontend-dev      # Start dev server at :3000 (requires running API)
just frontend-build    # Build for production

# Quality
just lint        # Format & lint
just test        # Run tests
just ci          # Full CI pipeline
uv run --with pytest python -m pytest tests/data_pipeline/test_pipeline_concurrency.py -q
                # Run pipeline concurrency/idempotency tests only

# Data Pipeline
just prefect-up  # Start Prefect
just pipeline    # Run ETL

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

src/
├── mcp_server/      # MCP server + RAG pipeline
├── mcp_client/      # CLI client
├── topwr_api/       # FastAPI backend
├── config/          # Configuration
└── data_pipeline/   # Prefect ETL flows

frontend/
├── src/
│   ├── api/         # API client
│   ├── hooks/       # useUserId, useSessions, useChat, useTheme
│   ├── components/  # Sidebar, Chat, shared UI
│   └── types/       # TypeScript mirrors of backend models
└── package.json     # React + Vite + TailwindCSS

docker/
├── compose.stack.yml    # Main stack (Neo4j + MCP + API + Frontend)
├── compose.prefect.yml  # Data pipeline
├── Dockerfile.mcp       # MCP server image
├── Dockerfile.api       # FastAPI image
├── Dockerfile.frontend  # React + Nginx image
└── nginx.conf           # SPA fallback + API proxy

Использование API

Эндпоинт чата

curl -X POST http://localhost:8000/api/chat \
  -H "Content-Type: application/json" \
  -d '{"user_id": "user1", "message": "Czym jest nagroda dziekana?"}'

Ответ:

{
  "session_id": "abc123",
  "message": "Nagroda dziekana to wyróżnienie przyznawane...",
  "metadata": {
    "source": "mcp_knowledge_graph",
    "trace_id": "xyz789"
  }
}

Управление сессиями

# Get session history
curl http://localhost:8000/api/sessions/{session_id}/history

# List user sessions  
curl http://localhost:8000/api/users/{user_id}/sessions

Технологический стек

Технология	Назначение
React 18 + TypeScript	Фронтенд-интерфейс чата
Vite + TailwindCSS v3	Инструменты сборки и стилизация
Nginx	Обслуживание фронтенда + проксирование API
FastMCP	Сервер Model Context Protocol
LangGraph	Машина состояний RAG
LangChain	Оркестрация LLM
Neo4j	База данных графа знаний
FastAPI	Бэкенд REST API
Langfuse	Наблюдаемость (опционально)
Prefect	Оркестрация конвейера данных
Docker	Контейнеризация

SOLVRO MCP - Knowledge Graph RAG System