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

Interfaz PWrChat - Chatbot en React (barra lateral de sesiones, alternancia de modo oscuro/claro, tema persistente)
Enrutamiento inteligente de consultas - El sistema de barreras (guardrails) determina la relevancia de la consulta
Lenguaje natural a Cypher - Convierte preguntas en consultas de grafo
RAG de Grafo de Conocimiento - Generación aumentada por recuperación con Neo4j
Protocolo MCP - Interfaz estándar del Protocolo de Contexto de Modelo
Observabilidad - Integración opcional de seguimiento con Langfuse
Listo para Docker - Despliegue con un solo comando

Inicio rápido

# 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

Arquitectura

Descripción general del sistema

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

Servicio	Puerto	Descripción
`frontend`	80	PWrChat — Interfaz de chatbot en React servida por Nginx
`topwr-api`	8000	Backend FastAPI para la aplicación ToPWR
`mcp-server`	8005	Servidor MCP con canalización RAG
`neo4j`	7474/7687	Base de datos de grafo de conocimiento

Canalización RAG

El núcleo del sistema es una canalización RAG basada en LangGraph que procesa de forma inteligente las consultas de los usuarios:

Flujo de la canalización:

Barreras (Guardrails) - Un LLM rápido determina si la consulta es relevante para la base de conocimientos
Generación de Cypher - Un LLM preciso convierte el lenguaje natural en una consulta Cypher
Recuperación - Ejecuta la consulta contra el grafo de conocimiento de Neo4j
Respuesta - Devuelve datos de contexto estructurados

Canalización de datos

Canalización ETL separada para ingerir documentos en el grafo de conocimiento:

Pasos de la canalización:

Carga de documentos - Ingesta de documentos PDF y de texto
Extracción de texto - OCR y extracción de contenido
Procesamiento LLM - Generación de consultas Cypher a partir del contenido
Población del grafo - Ejecución de consultas para construir el grafo de conocimiento

Configuración

Copie .env.example a .env y configure:

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

Comandos

# 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

Estructura del proyecto

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

Uso de la API

Endpoint de chat

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

Respuesta:

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

Gestión de sesiones

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

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

Stack tecnológico

Tecnología	Propósito
React 18 + TypeScript	Interfaz de chat frontend
Vite + TailwindCSS v3	Herramientas de compilación y estilos
Nginx	Servicio de frontend + proxy de API
FastMCP	Servidor del Protocolo de Contexto de Modelo
LangGraph	Máquina de estados RAG
LangChain	Orquestación de LLM
Neo4j	Base de datos de grafo de conocimiento
FastAPI	Backend de API REST
Langfuse	Observabilidad (opcional)
Prefect	Orquestación de canalización de datos
Docker	Contenerización

SOLVRO MCP - Knowledge Graph RAG System