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

PWrChat UI - React 챗봇 (세션 사이드바, 다크/라이트 모드 전환, 테마 유지)
지능형 쿼리 라우팅 - 가드레일 시스템이 쿼리의 관련성을 판단
자연어-Cypher 변환 - 질문을 그래프 쿼리로 변환
지식 그래프 RAG - Neo4j를 활용한 검색 증강 생성
MCP 프로토콜 - 표준 모델 컨텍스트 프로토콜 인터페이스
관측 가능성 - 선택적 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 — Nginx로 제공되는 React 챗봇 UI
`topwr-api`	8000	ToPWR 앱을 위한 FastAPI 백엔드
`mcp-server`	8005	RAG 파이프라인이 포함된 MCP 서버
`neo4j`	7474/7687	지식 그래프 데이터베이스

RAG 파이프라인

시스템의 핵심은 사용자 쿼리를 지능적으로 처리하는 LangGraph 기반 RAG 파이프라인입니다:

파이프라인 흐름:

가드레일 - 빠른 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	프론트엔드 채팅 UI
Vite + TailwindCSS v3	빌드 도구 및 스타일링
Nginx	프론트엔드 제공 + API 프록시
FastMCP	모델 컨텍스트 프로토콜 서버
LangGraph	RAG 상태 머신
LangChain	LLM 오케스트레이션
Neo4j	지식 그래프 데이터베이스
FastAPI	REST API 백엔드
Langfuse	관측 가능성 (선택 사항)
Prefect	데이터 파이프라인 오케스트레이션
Docker	컨테이너화

SOLVRO MCP - Knowledge Graph RAG System

빠른 시작

아키텍처

시스템 개요

RAG 파이프라인

데이터 파이프라인

설정

명령어

프로젝트 구조

API 사용법

채팅 엔드포인트

세션 관리

기술 스택

라이선스

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API