gogoymh/auto-ontology-mcp

NVIDIA Auto Ontology's semantic layer and a personal knowledge base as an MCP server for Claude, ChatGPT and other MCP clients. No LLM API key needed.

Auto Ontology MCP — AI 어시스턴트가 구축하고 쿼리하는 의미론적 계층

한 줄 요약: Auto Ontology MCP는 AI 코딩 어시스턴트(Claude Code, Codex, Cursor, VS Code 등)에게 데이터베이스와 문서에 대한 신뢰할 수 있는 "의미론적 계층"을 제공하는 도구입니다. 따라서 평이한 영어로 질문할 때 어시스턴트가 테이블 이름이나 조인 로직을 추측하는 대신, 검토 및 검증된 데이터 모델을 기반으로 작업하게 됩니다.

해결하는 문제

Text-to-SQL(AI에게 평이한 영어로 데이터베이스 쿼리를 작성하게 하는 것)은 조용히 실패합니다. 쿼리는 실행되고 숫자가 반환되지만, 그것이 틀렸다는 것을 알려주는 것은 아무것도 없습니다. README는 구체적인 예를 제시합니다:

  • 모델이 billing_city_id와 delivery_city_id 중 무엇이 "고객의 주"를 의미하는지 추측함
  • 정수 값이 우연히 일치하지만 실제로는 관련이 없는 열에서 두 테이블을 조인함
  • 저장된 값이 'Pennsylvania'인데 state_name = 'pennsylvania'로 필터링함
  • 주문 라인에 조인한 후 제품 가격을 합산하여 총액이 부풀려짐("팬아웃" 오류)

Auto Ontology MCP는 의미론적 계층(검토된 비즈니스 용어, 테이블 관계, 검증 규칙 세트)을 구축하고 유지함으로써 이를 수정하며, 어시스턴트는 SQL을 작성하기 전과 작성하는 동안 이를 참조합니다.

작동 방식

두 가지 구성 요소가 함께 작동합니다:

  1. MCP 클라이언트의 모델(Claude, Codex 등)이 언어 작업을 수행합니다: 스키마 읽기, 문서에서 사실 추출, 개념 명명, 답변 판단, SQL 작성.
  2. 서버가 결정론적 작업을 수행합니다: 스키마 추출, 데이터 프로파일링, 키 추론, 검증, 저장 및 읽기 전용 쿼리 실행. 이 모든 작업은 로컬 SQLite 파일 내에서 이루어집니다.

이는 Next.js/FastAPI/Postgres 스택 뒤에서 자체 LLM을 실행하는 NVIDIA의 오리지널 Auto Ontology와 의도적으로 대조됩니다. 이 프로젝트는 모든 언어 단계를 이미 가지고 있는 모델에 맡기므로 호스팅할 모델 엔드포인트나 구성할 API 키가 없습니다.

두 가지 주요 작업

1. 데이터베이스에 질문하기

데이터베이스를 지정하면 어시스턴트는 다음을 수행합니다:

  • 비즈니스 용어 구축(예: "수익" = order_lines.line_total)
  • 테이블 간 조인을 검토하고 올바른 경로 기록
  • 서버가 온톨로지 및 실제 데이터에 대해 검증한 SQL로 질문에 답변

검증은 알 수 없는 열, 온톨로지가 모르는 조인, 근사치 리터럴(예: 'pennsylvania' 대 'Pennsylvania'), 백분율 대 분수 임계값, 일대다 팬아웃 오류를 잡아냅니다.

2. 개인 지식 베이스 유지

영수증, 명세서, 논문, 독서 노트 또는 스크린샷을 어시스턴트와 공유하세요. 어시스턴트는 이를 읽고 다음을 저장합니다:

  • 사실을 타입이 지정된 레코드로
  • 아이디어를 타입이 지정된 관계(예: "원인", "부분")가 있는 연결된 개념으로
  • 구절을 전체 텍스트 인덱스에서 다시 찾을 수 있도록
  • 출처 — 모든 레코드는 그 기원과 인용문을 유지

원본 전체는 Obsidian 볼트에 남습니다. 나중에 질문하면 정확한 숫자, 검색 가능한 인용문, 원본 문서로의 링크를 얻을 수 있습니다.

이는 "LLM Wiki" 패턴(모델이 소스를 컴파일하여 마크다운 페이지로 만드는 Karpathy의 아이디어)을 대체하는 드롭인 솔루션으로 자리 잡았습니다. 흩어진 페이지 대신 SQL로 합산/필터링/비교할 수 있는 타입이 지정된 테이블, 타입이 지정된 링크가 있는 개념 페이지, 그리고 모든 내용을 [[links]]와 그래프 뷰가 있는 Obsidian 볼트로 작성하는 export_wiki 명령을 얻게 됩니다.

주요 기능(README에서)

기능 설명
카탈로그 및 프로파일링 테이블/열/키를 읽고 행을 샘플링하여 상위 값, 고유성, NULL 비율, 범위, 날짜 형식, 작은 열거형의 전체 값 세트, 목록을 저장하는 텍스트 열을 기록
키 추론 이름으로 선언되지 않은 기본/외래 키를 찾고 값 포함 관계로 확인; 역할(billing_ 대 delivery_), 자기 참조, 브리지 테이블 감지
모델을 사용한 모델링 샘플과 키가 포함된 테이블을 한 번에 하나씩 모델에 전달; 제안된 용어와 열 매핑을 검증 및 저장
SQL 속성 실행된 쿼리에서 재사용 가능한 필터, 측정값, 조인 패턴을 마이닝; 저장 전 데이터베이스에 대해 각 후보를 테스트
답변 가능성 질문의 엔티티가 용어, 속성 또는 저장된 값으로 커버되는지 확인; 일치하는 테이블이 어떻게 연결되는지(행 대 행, 공유 부모, 또는 연결 없음) 검증
검증 알 수 없는 열, 알 수 없는 조인, 근사치 리터럴, 목록 열 동등성, 백분율 대 분수 실수, 팬아웃 오류를 잡아내고 드라이 런 실행
거버넌스 용어의 초안/인증/폐기 상태; 인증된 정의를 편집하면 초안으로 돌아감
지식 저장소 엔티티, 개념, 구절, 출처를 위한 쓰기 가능한 저장소. 모든 레코드에 로케이터/인용문 포함
전체 텍스트 검색 bm25 랭킹이 포함된 FTS5 인덱스; 접두사 매칭이 한국어 조사(기억 → 기억을)를 처리; 스니펫과 [[links]] 반환
SQL 내 개념 그래프 용어, 관계, 구절은 쿼리 가능한 테이블이므로 하나의 검증된 쿼리로 텍스트 검색, 재귀적 관계 탐색, 레코드를 결합 가능
Obsidian 내 원본 각 소스의 전체 텍스트는 볼트에 남음; 저장소는 요약과 제목으로의 링크를 유지
제자리 업데이트 재스캔을 통해 용어, 인증, 검토된 조인을 유지; 변경된 문서는 모든 것을 재구축하지 않고 자신의 구절을 대체
휴대성 전체 의미론적 계층을 하나의 YAML 또는 JSON 문서로 내보내기/가져오기

데모

README에는 가상의 소매점을 사용한 데모(auto-ontology-mcp demo)가 포함되어 있습니다: 11개의 테이블, 3,200개의 주문, 지식 저장소의 3개 문서, 그리고 둘 다 필요한 질문. 다음을 보여줍니다:

  • SQL 작성 전 답변 가능성을 확인하는 어시스턴트
  • 잘못된 조인과 잘못된 리터럴을 잡아내는 검증
  • 질문에 답할 수 없는 경우(예: "광고비 대비 수익" — 데이터베이스에 매출은 있지만 광고비 데이터가 없음)에 대한 설명
  • 구조화된 데이터(수익 수치)와 비구조화된 문서(수익이 감소한 이유)의 결합
  • 전체 텍스트 검색 + 타입이 지정된 관계 탐색 + 구절 조인을 하나의 SQL 문으로 실행

시작하기

uv가 필요합니다.

  1. 데모 설정: uvx --from git+https://github.com/gogoymh/auto-ontology-mcp auto-ontology-mcp demo
  2. 클라이언트 연결: Cursor 또는 VS Code는 원클릭 설치; 다른 클라이언트는 구성 스니펫 사용(config 명령이 절대 경로와 함께 출력).

안전 주의사항

모든 SQL 실행은 읽기 전용입니다 — 서버는 로컬 SQLite 파일에 대해 쿼리를 실행하고 실행 전 온톨로지에 대해 검증합니다.

라이선스

Apache-2.0. Python 3.12+.

관련

  • 프로젝트
  • 프로젝트
  • 프로젝트
  • 프로젝트