FAQ RAG MCP Server

Glean Solutions Engineering 기술 과제를 위해 의도적으로 작게 만든 RAG(Retrieval-Augmented Generation) 애플리케이션입니다. 제공된 FAQ Markdown 파일을 인덱싱하고, 코사인 유사도로 관련 구절을 검색하며, LLM을 통해 근거 기반 답변을 생성하고, 그 결과를 하나의 로컬 MCP 도구(ask_faq)로 노출합니다.

이 프로젝트는 완전히 크로스 플랫폼입니다. 모든 설정 및 실행 명령은 uv를 사용하며 Windows, macOS, Linux에서 동일합니다. 이것을 Claude Code를 사용하는 Windows 사용자에게 전달하시나요? START_HERE_WINDOWS.md부터 시작하세요. 저장소에는 Claude Code가 자동으로 읽는 CLAUDE.md 설정 런북과 faq-rag 서버를 위한 이식 가능한 프로젝트 범위 .mcp.json 정의가 포함되어 있습니다.

30초 설명

프로세스 시작 시 Python은 FAQ 파일을 읽고 약 200자 단위의 청크로 분할한 후 임베딩을 생성하고 정규화하여 인덱스를 메모리에 캐시합니다. 각 질문에 대해 질문을 임베딩하고 코사인 유사도로 청크 순위를 매긴 다음, 가장 좋은 네 개의 텍스트 청크를 설정된 LLM에 보내고 완성된 답변과 소스 파일 이름만 반환합니다.

flowchart LR
  A[FAQ Markdown files] --> B[~200-character chunks]
  B --> C[Document embeddings cached in RAM]
  Q[Question] --> D[Query embedding]
  C --> E[Cosine similarity]
  D --> E
  E --> F[Top 4 text chunks]
  F --> G[Grounded LLM generation]
  G --> H[answer + sources]
  H --> I[MCP client]

임베딩은 구절을 찾는 데만 사용됩니다. LLM은 원래 질문과 검색된 텍스트를 받지, 원시 임베딩 벡터를 받지 않습니다.

Related MCP server: Inkdex

정확한 MCP 계약

도구: ask_faq

입력:

{
  "question": "How do I reset my password?",
  "top_k": 4
}

출력—추가 키 없음:

{
  "answer": "Use the reset link on the login page [faq_auth.md].",
  "sources": ["faq_auth.md", "faq_sso.md"]
}

top_k는 1부터 10까지의 정수를 허용하며 기본값은 4입니다.

공급된 HTTP 옵션 대신 MCP를 사용하는 이유?

RAG 핵심은 어느 래퍼 뒤에서도 동일할 것입니다. MCP를 선택한 이유는 AI 클라이언트가 사용자 지정 HTTP 클라이언트, 포트, URL 또는 헬스 엔드포인트 없이도 도구 스키마를 발견하고, 호출 시점을 결정하며, 로컬 Python 프로세스를 시작하고, 구조화된 결과를 받을 수 있기 때문입니다. MCP는 상호 운용성을 향상시킬 뿐 자체적으로 검색 품질을 향상시키지는 않습니다.

이 구현은 과제에서 요구하는 stdio 전송 방식을 사용합니다. MCP 클라이언트는 mcp_server.py를 로컬 하위 프로세스로 시작하고 프로세스의 표준 입력과 출력을 통해 MCP 메시지를 교환합니다. 서버는 stdout에 일반 로그를 작성하지 않는데, 그 채널은 프로토콜 트래픽 전용이기 때문입니다.

설정 (모든 OS: Windows, macOS, Linux)

요구 사항:

• Git

• uv — 호환되는 Python을 자동으로 다운로드하므로 별도의 Python 설치가 필요 없습니다. Windows: winget install -e --id astral-sh.uv; macOS: brew install uv.

• 사용 가능한 API 크레딧이 있는 OpenAI API 키

• Claude Code 또는 Cursor 같은 MCP 클라이언트

명령은 PowerShell, zsh, bash에서 동일합니다:

git clone https://github.com/cq2wgwtzb5-lgtm/glean-faq-rag-mcp.git
cd glean-faq-rag-mcp
uv sync

.env.example을 복사하여 .env.local을 만든 다음 편집기에서 API 키를 추가하세요:

OPENAI_API_KEY=your_key_here

.env.local은 Git에서 무시됩니다. 절대 커밋하거나 공유하지 마세요.

결정적 테스트를 실행하세요(API 호출 없음):

uv run pytest -q

MCP를 추가하기 전에 직접 엔드투엔드 스모크 테스트를 실행하세요:

uv run rag_core.py

Claude Code는 이 폴더에서 세션이 시작되면 체크인된 .mcp.json을 자동으로 발견합니다. 승인, 확인 및 호출하려면 docs/WINDOWS_MCP_SETUP.md를 따르세요(단계는 모든 OS에 적용됩니다). Windows 사용자는 동일한 uv 명령을 래핑한 setup_windows.ps1을 대신 실행할 수도 있습니다.

머신의 모든 채팅 스레드에서 사용하기

프로젝트 범위의 .mcp.json은 이 폴더 안에서 시작된 세션에서만 로드됩니다. 컴퓨터의 모든 Claude Code 세션에서 ask_faq를 사용하려면 클론의 절대 경로를 사용하여 사용자 범위에서 서버를 한 번 등록하세요(모든 OS에서 동일한 명령):

claude mcp add --scope user faq-rag -- uv run --directory "<absolute path to this repo>" mcp_server.py

저장소 내부의 세션은 계속 프로젝트 범위 항목을 사용하고, 다른 모든 세션은 사용자 범위 항목을 사용합니다. 제거하려면 claude mcp remove --scope user faq-rag를 실행하세요.

평가

단위 테스트는 결정적 가짜 임베딩을 사용하며 모델 호출을 하지 않습니다:

uv run pytest -q

실시간 평가기는 실제 모델 API에 대해 대표 질문 다섯 개를 실행하고 예상 소스, 필수 사실, 기권(abstention) 동작을 확인합니다:

uv run evaluate.py --output eval-results.json

eval-results.json은 모델 출력과 계정 구성이 다를 수 있으므로 의도적으로 무시됩니다. 면접 중에 보고서를 캡처하거나 화면 공유하세요.

중요한 설계 결정

인메모리 NumPy 인덱스

제공된 코퍼스는 몇 개의 청크만 생성합니다. 벡터 데이터베이스를 사용하면 결과가 개선되지 않으면서 배포 및 리뷰 복잡성만 추가됩니다. 정규화된 NumPy 벡터는 코사인 유사도를 단순한 행렬-벡터 곱으로 만듭니다.

경계 인지 청킹

요구 사항대로 대상 크기는 약 200자로 유지됩니다. 구현은 문단, 줄, 문장, 단어 경계를 우선하므로 정확한 숫자를 맞추기 위해 텍스트가 임의의 위치에서 잘리지 않습니다.

시작 시 한 번의 임베딩 패스

문서 임베딩은 프로세스 시작 시 한 번 생성되어 RAM에 캐시됩니다. 각 질문은 새로운 쿼리 임베딩을 받습니다. 캐시는 대화나 사용자 세션 메모리가 아니라 공유되는 코퍼스 데이터입니다. 프로세스가 종료되면 캐시는 사라지고 다음 시작 시 다시 구축됩니다.

근거 기반 생성 및 인용

생성 프롬프트는 모델을 검색된 FAQ 컨텍스트로 제한하고 정확한 파일 이름 인용을 요구하며 FAQ가 질문에 답하지 못할 때 그렇게 말하도록 지시합니다. 응답의 sources 목록은 검색 순서를 유지하며 검색된 청크의 파일 이름만 포함합니다.

명시적 실패 동작

애플리케이션은 OPENAI_API_KEY가 없으면 즉시 실패하고, 빈 질문과 잘못된 top_k를 거부하며, 30초 모델 타임아웃을 사용하고, SDK 재시도를 두 번 허용합니다. 오류는 지어낸 FAQ 답변이 아니라 MCP 오류로 유지됩니다.

알려진 제한 사항과 프로덕션 진화

이 과제는 영구 인덱스, 증분 수집, 접근 제어, 하이브리드 어휘 검색, 재순위화, 최신성 및 권위 신호, 감사 로그, 사용자별 개인화를 의도적으로 생략합니다.

엔터프라이즈 시스템에서는 권한이 검색 전에 적용되어야 권한 없는 텍스트가 모델 컨텍스트에 들어가지 않습니다. 검색 품질도 코사인 유사도만이 아니라 어휘, 의미, 최신성, 권위, 그래프 신호를 사용할 것입니다. 이는 프로덕션의 핵심 문제지만, 로컬 파일 세 개를 위해 구현하는 것은 가벼운 솔루션을 요구하는 과제의 요청에 어긋납니다.

저장소 안내

• rag_core.py — 수집, 청킹, 임베딩, 검색 및 생성

• mcp_server.py — stdio를 통한 하나의 ask_faq MCP 도구

• faqs/ — 제공된 FAQ 코퍼스

• tests/ — 결정적 단위 및 구성 테스트

• evals/cases.json — 실시간 평가 케이스 5개

• evaluate.py — 실시간 평가 실행기

• pyproject.toml / uv.lock — 고정된 크로스 플랫폼 환경 (uv sync)

• setup_windows.ps1 — 동일한 uv 단계를 감싼 Windows 편의 래퍼

• CLAUDE.md — Claude Code를 위한 자동 설정 및 안내 지침

• .mcp.json — 이식 가능한 프로젝트 범위 Claude Code MCP 구성

• START_HERE_WINDOWS.md — Windows 사용자를 위한 원프롬프트 핸드오프

• docs/WINDOWS_MCP_SETUP.md — Claude Code 연결 단계

• docs/TALK_TRACK.md — 면접 프레젠테이션 및 예상 질문

• docs/REQUIREMENTS_TRACEABILITY.md — 과제-코드 증거 매핑

• docs/VALIDATION.md — 통과된 검사 및 남은 실시간 테스트 경계

보안

API 키를 커밋하지 마세요. MCP 서버를 활성화하기 전에 검토하세요. 로컬 stdio 서버는 클라이언트를 시작한 사용자의 권한으로 실행됩니다. 이 서버는 설정된 FAQ 디렉터리만 읽고 설정된 OpenAI 모델만 호출합니다.

면접 준비

docs/TALK_TRACK.md를 활용하세요. 아키텍처, 각 선택의 이유, MCP가 HTTP와 다른 점, 그리고 이 작은 과제가 Glean의 엔터프라이즈 검색 및 근거 기반 답변 문제에 어떻게 대응되는지 설명합니다.