RAGmonsters 맞춤형 PostgreSQL MCP 서버

RAGmonsters를 위한 맞춤형 PostgreSQL MCP 서버

개요

이 저장소는 모델 컨텍스트 프로토콜(MCP)을 사용하여 대용량 언어 모델(LLM)을 데이터베이스와 통합하는 더욱 발전된 접근 방식을 보여줍니다. 일반 MCP PostgreSQL 서버를 사용하면 LLM이 원시 SQL 쿼리를 통해 데이터베이스를 탐색할 수 있지만, 이 프로젝트는 애플리케이션의 요구에 맞춰 도메인별 API를 제공하는 맞춤형 MCP 서버를 구축하여 다른 접근 방식을 취합니다.

이 구현에서는 LLM과의 도구 기반 상호작용에 대한 효율성과 안정성을 개선하는 모델 컨텍스트 프로토콜의 고성능 구현인 FastMCP를 사용합니다.

이 프로젝트는 RAGmonsters 데이터셋을 기반으로 합니다. RAGmonsters는 다양한 속성, 능력, 관계를 가진 몬스터들의 풍부한 가상 데이터셋을 제공하는 오픈소스 프로젝트로, 특히 검색 증강 생성(RAG) 시스템을 시연하고 테스트하기 위해 설계되었습니다.

일반 MCP 데이터베이스 액세스의 문제점

일반 MCP PostgreSQL 서버는 LLM에 다음을 수행할 수 있는 query 도구를 제공합니다.

데이터베이스 스키마 탐색
자연어 질문을 기반으로 SQL 쿼리를 공식화합니다.
데이터베이스에 대해 해당 쿼리를 실행합니다.

이러한 접근 방식은 효과적이지만 실제 응용 프로그램에는 몇 가지 제한 사항이 있습니다.

인지 부하 : LLM은 전체 데이터베이스 스키마를 이해해야 합니다.
비효율성 : 하나의 질문에 답하기 위해 종종 여러 개의 SQL 쿼리가 필요합니다.
보안 문제 : 원시 SQL 액세스에는 주입 공격을 방지하기 위한 신중하고 신속한 엔지니어링이 필요합니다.
성능 : LLM이 데이터베이스의 인덱싱 전략을 이해하지 못하는 경우 복잡한 쿼리는 비효율적일 수 있습니다.
도메인 지식 격차 : LLM은 비즈니스 규칙과 도메인별 제약에 대한 이해가 부족합니다.

RAGmonsters 데이터세트에 대하여

RAGmonsters는 검색 증강 생성(RAG) 시스템의 테스트 및 시연을 위해 특별히 설계된 오픈 데이터셋입니다. 풍부한 속성, 능력, 관계를 가진 가상 몬스터에 대한 정보를 포함하고 있어 자연어 쿼리 시연에 적합합니다.

RAGmonsters의 PostgreSQL 버전은 다음을 포함하여 여러 테이블과 관계를 갖춘 잘 구성된 관계형 데이터베이스를 제공합니다.

다양한 속성(공격력, 방어력, 체력 등)을 가진 몬스터
몬스터가 가질 수 있는 능력
복잡한 관계를 가진 요소(불, 물, 흙 등)
괴물이 발견되는 서식지
진화 사슬과 몬스터 간의 관계

이 풍부하고 상호 연결된 데이터 세트는 도메인별 API와 일반 SQL 액세스의 힘을 비교하는 데 이상적입니다.

당사 솔루션: 도메인별 MCP API

이 프로젝트는 RAGmonsters 데이터세트에 대한 상위 수준의 도메인별 API를 제공하는 맞춤형 MCP 서버를 구축하는 방법을 보여줍니다. MCP 서버는 원시 SQL 기능을 노출하는 대신, 다음과 같은 특수 목적 함수를 제공합니다.

추상 데이터베이스 복잡성 : 기본 스키마 및 SQL 세부 정보 숨기기
도메인별 작업 제공 : 비즈니스 개념에 맞는 기능 제공
일반적인 질문에 대한 최적화 : 자주 묻는 질문에 대한 효율적인 쿼리 패턴 구현
비즈니스 규칙 적용 : 도메인별 논리 및 제약 조건 포함
보안 강화 : SQL 직접 액세스를 제거하여 공격 표면을 제한합니다.

웹 인터페이스

이 프로젝트에는 RAGmonsters 데이터 세트와 상호 작용하기 위한 두 가지 주요 인터페이스가 포함되어 있습니다.

탐색기 인터페이스

MCP API를 통해 RAGmonsters 데이터 세트를 탐색하고 필터링하기 위한 데이터 중심 인터페이스:

카테고리, 서식지, 희귀도별로 필터링하여 모든 몬스터를 찾아보세요
각 몬스터에 대한 자세한 정보를 확인하세요
Bootstrap으로 구축된 대화형 UI

채팅 인터페이스

RAGmonsters 데이터 세트와 상호 작용하기 위한 자연어 인터페이스:

자연어로 괴물에 대한 질문을 하세요
다양한 서식을 사용하여 마크다운 형식의 응답을 받으세요
LangGraph의 ReAct 에이전트 패턴으로 구동됨
MCP 도구와의 원활한 통합

이 인터페이스를 통해 사용자는 다음을 수행할 수 있습니다.

데이터 세트의 모든 몬스터를 탐색합니다
서식지, 범주 및 희귀도에 따라 몬스터 필터링
각 몬스터의 능력, 강점, 약점을 포함한 자세한 정보를 확인하세요.

예: 도메인별 API 대 일반 SQL

일반 MCP PostgreSQL 접근 방식:

지엑스피1

맞춤형 MCP 서버 접근 방식:

User: "What are the top 3 monsters with the highest attack power that are vulnerable to fire?"

LLM: (Uses our domain-specific API)
1. Single call: getMonsters({ vulnerableTo: "fire", sortBy: "attackPower", limit: 3 })

프로젝트 구조

├── .env.example        # Example environment variables
├── package.json        # Node.js project configuration
├── README.md           # This documentation
├── img/                # Images for documentation
├── scripts/
│   ├── testMcpServer.js # Test script for the MCP server
│   └── testLogger.js    # Logger for test script
├── src/
│   ├── index.js        # Main application server
│   ├── mcp-server/     # Custom MCP server implementation with FastMCP
│   │   ├── index.js    # Server entry point
│   │   ├── tools/      # Domain-specific tools
│   │   │   ├── index.js      # Tool registration
│   │   │   └── monsters.js   # Monster-related operations
│   │   └── utils/     # Helper utilities
│   │       └── logger.js     # Logging functionality
│   ├── llm.js          # LangChain integration for LLM
│   └── public/         # Web interface files
│       ├── index.html  # Monster explorer interface
│       └── chat.html   # Chat interface for LLM interactions

특징

FastMCP를 사용한 맞춤형 MCP 서버 : RAGmonsters 데이터를 위한 고성능 도메인별 API
최적화된 쿼리 : 미리 구축된 효율적인 데이터베이스 작업
비즈니스 로직 계층 : API에 내장된 도메인 규칙 및 제약 조건
구조화된 응답 형식 : LLM 사용을 위한 일관된 JSON 응답
포괄적 로깅 : 디버깅 및 모니터링을 위한 자세한 로깅
테스트 모음 : 서버 기능 및 LLM 통합을 검증하는 스크립트
LLM 통합 :
- OpenAI 및 기타 호환 LLM 공급자와 LangChain.js 통합
- 효율적인 도구 사용을 위한 LangGraph ReAct 에이전트 패턴
- 도구 호출 및 응답의 자동 처리
웹 인터페이스 :
- 몬스터 탐색 및 필터링을 위한 탐색기 인터페이스
- 자연어 상호 작용을 위한 마크다운 렌더링을 사용한 채팅 인터페이스

특징

LangChain.js 통합 : MCP 도구와 완벽하게 통합된 LLM 상호 작용
웹 인터페이스 : RAGmonsters 데이터 세트와 상호 작용하기 위한 탐색기 및 채팅 인터페이스
배포 준비 완료 : Clever Cloud와 같은 플랫폼에 쉽게 배포할 수 있도록 구성됨

이 접근 방식의 이점

향상된 성능 : 최적화된 쿼리 및 캐싱 전략
더 나은 사용자 경험 : 더욱 정확하고 빠른 응답
토큰 사용량 감소 : LLM은 복잡한 SQL이나 스키마 정보를 처리할 필요가 없습니다.
강화된 보안 : SQL에 직접 접근하지 않으므로 주입 공격 위험이 줄어듭니다.
유지 관리성 : 데이터베이스 스키마 변경으로 인해 LLM 재교육이 필요하지 않습니다.
확장성 : 더 크고 복잡한 데이터베이스를 처리할 수 있습니다.

시작하기

설치

이 저장소를 복제하세요
종속성 설치: npm install
.env.example``.env 로 복사하고 PostgreSQL 연결 문자열과 LLM API 키를 구성합니다.
MCP 서버 테스트 스크립트를 실행합니다: npm run test
LLM 통합 테스트 스크립트를 실행합니다: npm run test:llm
서버를 시작합니다: npm start

사용 가능한 도구

MCP 서버는 다음과 같은 도구를 제공합니다.

getMonsters - 필터링, 정렬, 페이지 매김 등의 선택적 기능을 갖춘 몬스터 목록을 가져옵니다.
- 매개변수: 필터(범주, 서식지, 희귀도), 정렬(필드, 방향), 제한, 오프셋
- 반환: 기본 정보가 포함된 몬스터 객체 배열
getMonsterById - ID로 특정 몬스터에 대한 자세한 정보를 가져옵니다.
- 매개변수: monsterId
- 반환: 모든 속성, 힘, 능력, 강점 및 약점을 갖춘 자세한 몬스터 객체
add - 두 숫자를 더하는 간단한 유틸리티(테스트용)
- 매개변수: a, b
- 반환: 두 숫자의 합

LLM 통합 아키텍처

이 프로젝트에서는 도메인별 도구와 LLM을 통합하는 현대적인 접근 방식을 사용합니다.

LangGraph ReAct 에이전트 패턴

이 애플리케이션은 LangGraph의 ReAct(추론 및 행동) 에이전트 패턴을 사용합니다.

사용자 쿼리를 처리하여 의도를 파악합니다.
쿼리에 따라 사용할 도구를 결정합니다.
자동으로 적절한 도구를 실행합니다
결과를 일관된 응답으로 종합합니다.
필요할 때 여러 단계의 추론을 처리합니다.

LLM 통합 테스트

이 프로젝트에는 LangChain.js를 사용하여 LLM을 MCP 서버와 통합하는 방법을 보여주는 테스트 스크립트가 포함되어 있습니다.

npm run test:llm

이 스크립트:

StdioClientTransport를 사용하여 MCP 서버에 연결합니다.
LangChain의 MCP 어댑터를 사용하여 사용 가능한 모든 MCP 도구를 로드합니다.
OpenAI API를 사용하여 LangChain 에이전트를 생성합니다.
몬스터에 대한 자연어 쿼리를 처리합니다.
LLM이 정보를 검색하기 위해 도구 호출을 수행하는 방법을 보여줍니다.
상호작용에 대한 자세한 정보를 기록합니다.

스크립트의 테스트 쿼리를 수정하여 시스템의 다양한 기능을 살펴볼 수 있습니다. 스크립트는 scripts/testLlmWithMcpServer.js 에 있습니다.

필수 조건

Node.js 23 이상
RAGmonsters 데이터가 포함된 PostgreSQL 데이터베이스
LLM API(예: OpenAI)에 대한 액세스
FastMCP 패키지(종속성에 포함됨)

환경 변수

다음 변수를 사용하여 .env 파일을 만듭니다.

# PostgreSQL connection string
POSTGRESQL_ADDON_URI=postgres://username:password@host:port/database

# LLM API configuration
LLM_API_KEY=your_openai_api_key
LLM_API_MODEL=gpt-4o-mini
LLM_API_URL=https://api.openai.com/v1

LLM 구성

LLM_API_KEY : OpenAI API 키 또는 호환 공급자 키
LLM_API_MODEL : 사용할 모델(기본값: gpt-4o-mini)
LLM_API_URL : API 엔드포인트(기본값: OpenAI의 엔드포인트)

이 애플리케이션은 자체 호스팅 모델과 대체 공급자를 포함한 모든 OpenAI 호환 API를 지원합니다.

Clever Cloud에 배포

Clever Cloud CLI 사용

Clever Cloud CLI를 설치하세요:
npm install -g clever-tools
Clever Cloud 계정에 로그인하세요:
clever login
새로운 애플리케이션을 만드세요:
clever create --type node <APP_NAME>
도메인을 추가하세요(선택 사항이지만 권장):
clever domain add <YOUR_DOMAIN_NAME>
PostgreSQL 애드온을 만들고 애플리케이션에 연결합니다.
clever addon create <APP_NAME>-pg --plan dev clever service link-addon <APP_NAME>-pg
이렇게 하면 애플리케이션에서 POSTGRESQL_ADDON_URI 환경 변수가 자동으로 설정됩니다.
필요한 환경 변수를 설정하세요.
clever env set LLM_API_KEY "your-openai-api-key" clever env set LLM_API_MODEL "gpt-4o-mini" # Optional, defaults to gpt-4o-mini clever env set LLM_API_URL "https://api.your-llm-provider.com" # Optional, for alternative OpenAI-compatible providers
애플리케이션을 배포하세요.
clever deploy
신청서를 엽니다:
clever open

Clever Cloud Console 사용

Clever Cloud Console 에서 직접 배포할 수도 있습니다.

콘솔에서 새 애플리케이션을 만듭니다.
런타임으로 Node.js를 선택하세요
PostgreSQL 애드온을 생성하고 애플리케이션에 연결하세요
콘솔에서 필요한 환경 변수를 설정합니다.
- LLM_API_KEY : OpenAI API 키
- LLM_API_MODEL : (선택 사항) 사용할 모델이며 기본값은 gpt-4o-mini입니다.
Git 또는 GitHub 통합을 사용하여 애플리케이션 배포

중요 참고 사항

POSTGRESQL_ADDON_URI 환경 변수는 PostgreSQL 애드온을 애플리케이션에 연결할 때 Clever Cloud에서 자동으로 설정됩니다.
이 애플리케이션에는 Clever Cloud에서 사용 가능한 Node.js 20 이상이 필요합니다.
이 애플리케이션은 Clever Cloud의 Node.js 애플리케이션에 대한 기본 포트인 포트 8080에서 자동으로 실행됩니다.

특허

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.

감사의 말

샘플 데이터 세트에 대한 RAGmonsters
MCP 사양을 위한 모델 컨텍스트 프로토콜
고성능 MCP 구현을 위한 FastMCP
호스팅 기능을 위한 Clever Cloud

RAGmonsters Custom PostgreSQL MCP Server

Integrations