Wanaku를 사용하여 LLM이 실시간 데이터베이스를 쿼리할 수 있게 하는 MCP SQL 도구 구축하기

AI 어시스턴트는 추론 능력이 뛰어나지만, 근본적인 사각지대가 있습니다. 바로 그들의 답변이 시간 속에 얼어붙은 학습 데이터로부터 나온다는 점입니다. AI에게 "1000달러 미만의 노트북은 어떤 것들이 있나요?"라고 물으면 그럴듯해 보이는 답변을 얻겠지만, 그것은 지금 당장 귀하의 재고에 실제로 있는 내용을 반영한 답변은 아닙니다.

만약 AI가 그냥... 직접 확인할 수 있다면 어떨까요?

그것이 바로 Wanaku의 곧 출시될 sql-tool 서비스 템플릿이 해결하고자 하는 문제입니다. 버전 0.2.0으로 출시될 이 템플릿은 Model Context Protocol (MCP)을 통해 AI 어시스턴트를 실시간 관계형 데이터베이스(Relational Database)에 연결하여, AI가 오래된 지식으로 추측하는 대신 실제 데이터를 쿼리할 수 있도록 합니다.

잠깐, Wanaku가 무엇인가요? MCP는 무엇인가요?

처음 접하시는 분들을 위한 빠른 배경 설명입니다:

**MCP (Model Context Protocol)**는 AI 어시스턴트가 외부 도구를 사용하고, 리소스에 접근하며, 서비스를 표준화된 방식으로 상호작용할 수 있게 해주는 개방형 프로토콜입니다. AI를 위한 범용 API 레이어라고 생각하면 됩니다. 모든 AI 클라이언트가 개별적인 맞춤형 통합(Integration)을 구축할 필요 없이, 모두가 MCP로 통신할 수 있습니다.
Wanaku는 오픈 소스 MCP 라우터 및 기능 관리 플랫폼입니다. AI 클라이언트(Claude Desktop, Codex 또는 커스텀 LLM 앱 등)와 백엔드 서비스 사이의 접착제 역할을 합니다. 귀하는 기능을 MCP 호환 도구로 노출하고, Wanaku는 라우팅(Routing), 인증(Authentication), 서비스 디스커버리(Service Discovery)를 처리합니다.

곧 출시될 0.2.0 버전(PR #1358 병합 대기 중)은 _서비스 템플릿(Service Templates)_을 도입합니다. 이는 CLI 명령 하나만으로 인스턴스화할 수 있는 사전 패키징된 기능 패턴입니다. sql-tool 템플릿은 이 중 첫 번째이며, AI 어시스턴트와 관계형 데이터베이스 사이의 간극을 메우도록 설계되었습니다.

실시간 SQL 쿼리 vs 벡터 RAG (Vector RAG)

모든 엔터프라이즈 개발자가 경험해 보았을 시나리오가 있습니다. 시스템의 운영 데이터에 대해 AI 어시스턴트에게 물었을 때, AI가 자신 있게 오래되었거나 완전히 조작된 지표를 내뱉는 상황입니다.

전형적인 해결책은 **RAG (Retrieval-Augmented Generation, 검색 증강 생성)**입니다. 데이터를 미리 인덱싱하고, 이를 벡터 임베딩 (vector embeddings)으로 변환하여 AI가 검색할 수 있도록 벡터 데이터베이스 (vector database)에 저장하는 방식입니다. 이 방식은 텍스트 문서, 위키, 정적 데이터셋에는 매우 효과적으로 작동합니다.

RAG의 한계

**실시간 운영 데이터 (live operational data)**는 어떨까요? 계속 변하는 재고, 현재 고객 주문, 또는 실시간 애플리케이션 메트릭 (metrics)은 벡터 동기화(vector syncs)를 하기에는 변화 속도가 너무 빠릅니다. 이러한 데이터를 미리 인덱싱하고 싶지는 않을 것입니다. 대신 LLM이 SQL을 통해 온디맨드 (on-demand)로 직접 쿼리하기를 원할 것입니다.

해결책: SQL 쿼리를 MCP 도구로 노출하기

sql-tool 템플릿은 개발자가 실시간 SQL 데이터베이스 쿼리를 실행 가능한 MCP 도구로 안전하게 노출하는 데 필요한 모든 것을 패키징하여 제공합니다:

대상 데이터 저장소에 대해 안전한 쿼리를 실행하는 Apache Camel 라우트 (route).
호환 가능한 AI 클라이언트가 동적으로 발견하고 호출할 수 있는 MCP 도구 정의 (tool definition).
사전 패키징된 런타임 의존성 (JDBC 드라이버, SQL 컴포넌트, JSON 마샬링 (marshalling) 포함).
Camel Simple 표현식을 통해 AI 입력을 동적 SQL 쿼리로 매개변수화 (parameterizing)하는 기능 지원.

사용자는 데이터베이스 연결 정보와 기본 쿼리 구문만 제공하면 되며, 나머지 작업은 Wanaku 게이트웨이가 처리합니다.

단계별 가이드: LLM을 PostgreSQL에 연결하기

0.2.0 버전이 출시된 후 SQL 템플릿을 인스턴스화하는 방법의 미리보기입니다. 이 예제에서는 실시간 제품 카탈로그가 포함된 PostgreSQL 데이터베이스가 있으며, AI 어시스턴트가 _"800달러 미만의 노트북은 무엇이 있나요?"_라는 질문에 정확하게 답변하도록 만들고자 합니다.

1단계: PostgreSQL 데이터베이스 컨테이너 배포

Podman을 사용하여 로컬 PostgreSQL 인스턴스를 실행합니다 (Docker 명령어도 동일하게 작동합니다):

podman run --rm --name wanaku-postgres \
  -p 5432:5432 \
  -e POSTGRES_PASSWORD=wanaku \
...

스키마와 데이터를 로드합니다:

podman exec -i wanaku-postgres psql -U postgres -d postgres < sql-tool-demo.sql

데모 SQL 스크립트는 Wanaku 웹사이트에서 다운로드할 수 있습니다.

Step 2: Wanaku SQL 도구 템플릿 인스턴스화 (Instantiate)

이제 AI의 입력을 동적인 SQL 쿼리로 매핑함으로써, 여러분의 라이브 데이터베이스를 MCP 네트워크에 노출합니다:

wanaku service template instantiate \
  --name sql-tool \
  --property forage.jdbc.username=postgres \
...

쿼리 내의 ${body} 플레이스홀더(placeholder)가 보이시나요? 이것은 Camel Simple 표현식입니다. 런타임(runtime) 시점에 AI가 보내는 모든 입력값으로 교체됩니다. 따라서 사용자가 "800달러 미만인 노트북은 무엇인가요?"라고 물으면, AI는 800을 입력값으로 하여 도구를 호출하며, 쿼리는 다음과 같이 변합니다:

SELECT name, price FROM products WHERE price < 800 ORDER BY price

이것이 핵심 통찰입니다: SQL 템플릿은 정적 쿼리를 실행하는 것이 아니라, AI로부터 동적인 입력을 수용합니다. 이를 통해 진정한 대화형 도구가 됩니다.

Step 3: 카탈로그 배포 확인

새로운 서비스가 로컬 기능 카탈로그(capability catalog)에 올바르게 등록되었는지 확인하세요:

wanaku service catalog list

또한 다음 명령어를 사용하여 라이브 데이터 스토어(data store) 연결 항목을 확인할 수 있습니다:

wanaku data-store list --plain

Step 4: AI 클라이언트를 통한 라이브 데이터 쿼리

MCP 호환 AI 클라이언트(Claude Desktop 또는 Continue.dev 등)를 로컬 Wanaku 라우터 게이트웨이(router gateway)로 지정하세요. 그러면 LLM이 자동으로 제품 카탈로그 스키마 도구 기능(capability)을 발견하고 데이터베이스에 직접 쿼리합니다.

Output showing the results from the SQL tool

환각(hallucinations)도, 오래된 데이터 레이크(data lakes)도 없습니다. 오직 LLM에 의해 즉시 파싱되는 직접적이고 결정론적인(deterministic) SQL 결과만이 존재합니다.

내부 작동 원리 (How It Works Under the Hood)

AI 어시스턴트가 생성된 데이터베이스 도구를 호출하면, 오케스트레이션 파이프라인(orchestration pipeline)이 다음 계층들을 통해 실행됩니다:

도구 호출 (Tool Invocation): AI 클라이언트가 사용자의 필터링된 변수를 포함하는 MCP 페이로드 (payload)를 전송합니다.
라우팅 (Routing): Wanaku가 요청을 기반의 Apache Camel SQL 엔드포인트 (endpoint)로 매핑합니다.
파라미터 주입 (Parameter Injection): ${body} 런타임 표현식 (runtime expression)이 AI의 변수를 SQL 실행 컨텍스트 (execution context)에 안전하게 바인딩합니다.
실행 (Execution): 문장이 귀하의 PostgreSQL 배포 환경에서 네이티브하게 실행됩니다.
직렬화 (Serialization): 행 (rows) 데이터가 구조화된 JSON 문자열 페이로드 (payload)로 마샬링 (marshalled)됩니다.
응답 생성 (Response Generation): LLM이 원시 JSON을 수신하고 이를 사용자를 위한 자연어 응답으로 번역합니다.

템플릿이 이 모든 과정을 자동으로 연결합니다. 귀하는 쿼리와 연결 정보만 제공하면 됩니다.

동적 SQL을 사용한 AI 프롬프트의 파라미터화 (Parameterizing AI Prompts with Dynamic SQL)

sql-tool 템플릿은 Apache Camel SQL 컴포넌트 (component)를 기반으로 구축되었으므로, 해당 컴포넌트가 지원하는 모든 표현식을 사용할 수 있습니다.

단순 값 치환 (Simple value substitution):

SELECT * FROM products WHERE category_id = ${body}

헤더를 사용한 이름 지정 파라미터 (Named parameters with headers):

SELECT * FROM products WHERE price < :#maxPrice AND category_id = :#category

더욱 고급 패턴에 대해서는 Camel SQL 문서 (documentation)를 참조하십시오.

이것이 중요한 이유

이 데모는 세 개의 테이블과 열 개의 제품으로 구성된 작은 규모이지만, 이 패턴은 실제 사용 사례로 확장 가능합니다:

고객 지원 봇 (Customer support bots): 주문 내역, 계정 상태 또는 티켓 상세 정보를 실시간으로 조회
내부 도구 (Internal tools): AI 어시스턴트가 직원 디렉토리, 프로젝트 데이터베이스 또는 자산 인벤토리를 검색할 수 있도록 허용
분석 및 보고 (Analytics and reporting): 보고용 쿼리를 MCP 도구로 노출하여 AI가 필요할 때마다 최신 지표를 가져올 수 있도록 함
개발자 생산성 (Developer productivity): AI 코드 어시스턴트를 테스트 데이터베이스에 연결하여 문맥을 인식하는 제안 제공

핵심은 쿼리 자체가 아닙니다. AI가 더 이상 추측하는 것이 아니라, 직접 확인한다는 점입니다.

언제 시도해 볼 수 있나요?

sql-tool 템플릿은 곧 출시될 Wanaku 0.2.0 릴리스의 일부이며, 현재 PR #1358의 병합(merge)을 기다리고 있습니다. 출시되면 다음 단계를 따르세요:

Wanaku 설치하기
위의 설정 단계를 따라 템플릿을 인스턴스화(instantiate)합니다.
MCP 호환 AI 클라이언트를 Wanaku 라우터(router)에 연결합니다.

공식 릴리스 _전"에 미리 시도해 보고 싶다면, PR 브랜치에서 Wanaku를 빌드하거나 초기 빌드(early-builds) 중 하나를 사용할 수 있습니다.

참여하기

Wanaku는 오픈 소스이며, 여러분의 의견을 환영합니다:

⭐ GitHub에서 프로젝트에 Star를 눌러 다른 사람들이 발견할 수 있도록 도와주세요
💡 템플릿 아이디어가 있나요? 기여 가이드 (contributing guide)를 확인하세요
🐛 버그를 발견했거나 피드백이 있나요? GitHub에 이슈(issue)를 생성해 주세요

sql-tool 템플릿은 시작일 뿐입니다. 우리는 AI 어시스턴트를 실제 시스템에 아주 쉽게 연결할 수 있는 재사용 가능한 기능 패턴(capability patterns) 라이브러리를 구축하고 있습니다. 이 비전에 열정이 있다면, 저희와 함께 만들어 가요.