gdrive-rag-mcp

Model Context Protocol(MCP)을 통해 노출되는 로컬 우선(local-first) Google Drive 하이브리드 인덱스입니다. 언어, 개인정보 보호 경계, 인프라에 맞는 임베딩 제공자와 모델을 선택한 다음 Codex, Hermes Agent 또는 표준을 준수하는 모든 MCP 클라이언트에서 동일한 영구 인덱스를 쿼리하세요. 인덱스는 이를 쿼리하는 에이전트에 묶여 있지 않습니다.

Google Drive/Workspace는 읽기 전용 원본 소스로 유지됩니다. 서비스는 다운로드한 원본 파일이 아니라 추출된 청크, 정규화된 임베딩, 메타데이터, 체크섬, 동기화 상태, 인덱스 데이터를 저장합니다. LlamaCloud가 필요 없으며 교체 가능한 청킹 경계에서만 LlamaIndex를 사용합니다.

중요: 검색은 연구를 돕는 도구일 뿐이며 법률, 세무, 재무, 경제 또는 비즈니스 조언이 아닙니다. 에이전트와 사용자는 연결된 출처, 발효일, 관할권, 이후 개정 사항을 반드시 확인해야 합니다. evidence.sufficient가 false이면 빈틈을 채우지 말고 기권하세요.

What the MVP does

• 읽기 전용 API로 구성된 Drive 폴더 또는 Shared Drive 범위 하나를 재귀적으로 읽습니다.

• Google Docs, Google Sheets, text/Markdown, 텍스트 기반 PDF, DOCX를 추출합니다.

• Gemini, 검증된 모든 OpenAI 호환 /embeddings 엔드포인트, 선택적 로컬 Sentence Transformers를 하나의 임베딩 프로토콜 뒤에서 지원합니다.

• 유니코드 안전 SQLite FTS5 키워드 검색과 sqlite-vec 코사인 검색을 결합합니다. 확장을 로드할 수 없을 때는 테스트된 Python 코사인 폴백을 사용합니다.

• 변경된 파일을 다시 인덱싱하고 이후 동기화에서 삭제되었거나 범위를 벗어난 파일을 제거합니다.

• 임베딩 지문을 기록하고 검증하여 서로 다른 제공자, 모델, 엔드포인트 또는 차원의 벡터가 인덱스를 공유하지 못하게 합니다.

• 인용, 소스 수정/인덱싱 시간, 보수적인 증거 판정을 반환합니다.

• 로컬 stdio와 bearer 보호 Streamable HTTP에서 동일한 읽기 전용 도구를 노출합니다.

Architecture

flowchart LR
    D[Selected Google Drive scope] -->|read-only Drive API| X[Format extractors]
    X --> L[LlamaIndex chunking boundary]
    L --> E{Embedding provider}
    E -->|Gemini| V[Normalized vectors]
    E -->|OpenAI-compatible HTTP| V
    E -->|Local Sentence Transformers| V
    L --> S[(SQLite documents + FTS5)]
    V --> Q[(sqlite-vec / cosine fallback)]
    S --> R[Hybrid ranking + evidence gate]
    Q --> R
    R --> M[Agent-neutral MCP tools]
    M --> A[Any compatible MCP client]

Google, 임베딩 제공자, 로컬 모델 자격 증명/리소스는 서비스 운영자에게 유지됩니다. 원격 클라이언트는 MCP URL과 bearer 토큰만 받습니다.

Embedding providers

언어 지원 범위는 인덱싱 '언어 모드'가 아니라 선택한 모델의 속성입니다. FTS5는 SQLite의 유니코드 토크나이저를 사용하고, 의미 품질은 모델과 도메인에 따라 달라집니다. 실제 언어와 문서를 평가하세요. 이 프로젝트는 모든 언어에 대한 완벽한 지원을 주장하지 않습니다.

임베딩 제공자, 모델, 엔드포인트 또는 차원을 변경하면 해당 벡터 인덱스를 다시 구축해야 합니다. MCP 클라이언트나 에이전트를 변경할 때는 다시 인덱싱할 필요가 없습니다.

HTTP 어댑터는 공식 OpenAI 임베딩 요청/응답 스키마를 따릅니다. 배치 문자열 입력, 순서가 있는 결과, 선택적 dimensions, float 벡터를 포함합니다. 전용 Ollama 어댑터는 제공되지 않습니다. 특정 Ollama 배포가 해당 /v1/embeddings 계약을 명시적으로 구현한다면 OpenAI 호환 엔드포인트로 테스트하고, 해당 배포가 dimensions 필드를 받아들이지 않으면 GDRIVE_RAG_EMBED_SEND_DIMENSIONS=false로 설정하세요.

Gemini는 공식 Gemini 임베딩 문서에 설명된 검색 전용 쿼리/문서 작업과 명시적 출력 차원을 사용합니다. 로컬 어댑터는 문서화된 Sentence Transformers encode_query 및 encode_document 메서드를 정규화된 출력과 함께 사용합니다.

Install

git clone https://github.com/phamviet86/gdrive-rag-mcp.git
cd gdrive-rag-mcp
python3.12 -m venv .venv
. .venv/bin/activate
pip install -e .
cp .env.example .env

로컬 제공자의 경우 대신 pip install -e '.[sentence-transformers]'를 설치하세요. 이 프로젝트는 .env를 자동으로 파싱하지 않습니다. 셸이나 프로세스 매니저로 로드하세요. 예를 들어 신뢰할 수 있는 대화형 셸에서 set -a; . ./.env; set +a를 실행하세요. .env를 커밋하지 마세요.

Configure an embedding provider

비밀 값은 GDRIVE_RAG_EMBED_API_KEY_ENV가 가리키는 환경 변수에서 가져옵니다. 변수 이름은 구성이며, 비밀 값은 인덱스 지문이나 샘플 파일에 저장되지 않습니다.

Gemini (backward-compatible default)

기존 환경 구성은 계속 유효합니다. 제공자 설정이 없으면 서비스는 Gemini, gemini-embedding-001, 768차원, GEMINI_API_KEY를 사용합니다.

export GDRIVE_RAG_EMBED_PROVIDER=gemini
export GDRIVE_RAG_EMBED_MODEL=gemini-embedding-001
export GDRIVE_RAG_EMBED_DIMENSIONS=768
export GDRIVE_RAG_EMBED_API_KEY_ENV=GEMINI_API_KEY
export GEMINI_API_KEY=your_runtime_secret

OpenAI-compatible endpoint

export GDRIVE_RAG_EMBED_PROVIDER=openai-compatible
export GDRIVE_RAG_EMBED_MODEL=text-embedding-3-small
export GDRIVE_RAG_EMBED_DIMENSIONS=1536
export GDRIVE_RAG_EMBED_BASE_URL=https://api.openai.com/v1
export GDRIVE_RAG_EMBED_API_KEY_ENV=OPENAI_API_KEY
export OPENAI_API_KEY=your_runtime_secret

다른 호환 엔드포인트의 경우 base URL, 모델, 차원, 키 변수를 교체하세요. base URL에 자격 증명을 넣지 마세요. 검증된 엔드포인트/모델이 해당 선택 필드를 받아들이지 않을 때만 GDRIVE_RAG_EMBED_SEND_DIMENSIONS=false로 설정하세요. 구성된 출력 차원은 모든 응답에서 계속 검증됩니다.

Local Sentence Transformers

pip install -e '.[sentence-transformers]'
export GDRIVE_RAG_EMBED_PROVIDER=sentence-transformers
export GDRIVE_RAG_EMBED_MODEL=sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2
export GDRIVE_RAG_EMBED_DIMENSIONS=384
export GDRIVE_RAG_EMBED_DEVICE=cpu  # or a device supported by your local installation

위의 모델 이름은 예시일 뿐 보편적인 권장 사항이 아닙니다. 모델 다운로드/캐시 동작, 라이선스, 언어 지원 범위, 메모리 사용량, 하드웨어 요구 사항은 선택한 모델에 속합니다.

일반적인 튜닝:

export GDRIVE_RAG_EMBED_BATCH_SIZE=32
export GDRIVE_RAG_EMBED_TIMEOUT_SECONDS=60

모든 제공자는 정규화된 벡터를 반환하며 정확히 구성된 차원을 반환해야 합니다.

Google authentication

Google Drive API를 사용 설정한 다음 한 가지 방법을 선택하세요.

Service account (recommended for least privilege)

1. 서비스 계정을 만들고 해당 JSON 키를 운영자 전용 비밀 디렉터리에 보관하세요.

2. 선택한 Drive 폴더만 해당 이메일과 **뷰어(Viewer)**로 공유하세요. 이렇게 하면 사용자 OAuth 토큰보다 더 강력한 폴더 경계가 만들어집니다.

3. GOOGLE_SERVICE_ACCOUNT_FILE과 GDRIVE_FOLDER_ID를 설정하세요. Shared Drive의 경우 최소 읽기 역할로 계정을 추가하고 GDRIVE_SHARED_DRIVE_ID를 설정하세요.

별도로 검토하지 않는 한 도메인 전체 위임을 사용 설정하지 마세요. 코드는 https://www.googleapis.com/auth/drive.readonly만 요청합니다.

User OAuth

1. OAuth 데스크톱 앱 클라이언트를 만들고 해당 JSON을 저장소 외부에 보관하세요.

2. GOOGLE_OAUTH_CLIENT_FILE과 GOOGLE_OAUTH_TOKEN_FILE을 설정하세요.

3. gdrive-rag-mcp auth-google을 한 번 실행하고 읽기 전용 액세스를 승인하세요.

Drive API에는 '이 기존 폴더만 읽기'를 의미하는 OAuth 범위가 없습니다. OAuth 토큰은 사용자가 읽을 수 있는 파일을 읽을 수 있으며, 인덱서는 탐색 중에 구성된 폴더를 강제합니다. Google의 Drive 권한 부여 가이드를 참조하세요.

Build, refresh, and migrate an index

gdrive-rag-mcp init-db
gdrive-rag-mcp sync
gdrive-rag-mcp status

sync를 주기적으로 실행하세요. 선택한 트리를 스캔하고 변경되지 않은 체크섬을 다시 청킹/재임베딩하지 않으며, 변경된 전체 파일을 다시 인덱싱하고, 오래된 레코드를 삭제하고, completed_at을 기록합니다.

Embedding fingerprint and legacy indexes

각 데이터베이스는 제공자, 모델, 차원, 엔드포인트 ID, SHA-256 지문을 기록합니다. MCP 상태 도구는 제공자/모델/차원/지문을 반환하지만 엔드포인트는 노출하지 않습니다.

0.1.x 버전 데이터베이스는 임베딩 ID를 기록하지 않았습니다. 비어 있지 않은 레거시 인덱스는 이전 Gemini 기본값을 사용했을 가능성이 높더라도 안전하게 추론할 수 없으므로 0.2 버전은 이를 열지 않습니다. 원하면 데이터베이스를 백업하고 동일한 Drive/제공자 자격 증명을 로드한 다음 명시적으로 다시 구축하세요:

gdrive-rag-mcp reindex --yes

이 명령은 선택한 데이터베이스에서 생성된 인덱스 데이터만 삭제하고 전체 Drive 동기화를 수행합니다. Drive는 수정하지 않습니다. 빈 레거시 데이터베이스는 자동으로 스탬프가 찍힙니다.

의도적인 여러 인덱스를 유지하려면 명명된 프로필이나 명시적 경로를 사용하세요:

GDRIVE_RAG_INDEX_PROFILE=gemini gdrive-rag-mcp sync
GDRIVE_RAG_INDEX_PROFILE=local-multilingual gdrive-rag-mcp sync
# Or set GDRIVE_RAG_DB_PATH explicitly for complete path control.

기본 프로필은 하위 호환되는 data/index.db 경로를 유지하며, 다른 프로필은 data/index-<profile>.db를 파생합니다.

MCP tools

모든 도구 이름과 지침은 에이전트 중립적이며 읽기 전용으로 표시됩니다.

약한 적중은 진단을 위해 candidate_results에 배치되며, 최고 점수가 GDRIVE_RAG_EVIDENCE_THRESHOLD보다 낮으면 일반 results는 비어 있습니다.

Local mode (stdio)

gdrive-rag-mcp serve --transport stdio

클라이언트가 이 프로세스를 시작합니다. 데이터베이스와 제공자 구성을 해당 하위 프로세스에서 사용할 수 있게 하세요. 검색은 쿼리 임베딩을 위해 제공자 액세스가 필요하며, 같은 프로세스가 동기화도 수행하지 않는 한 Google 자격 증명은 필요하지 않습니다.

Hermes Agent local YAML

Hermes는 ~/.hermes/config.yaml에서 MCP 서버를 읽고 환경 변수 치환을 지원합니다. 실제 비밀은 ~/.hermes/.env 또는 상위 환경에 보관하세요.

mcp_servers:
  gdrive_knowledge:
    command: "/path/to/gdrive-rag-mcp/.venv/bin/gdrive-rag-mcp"
    args: ["serve", "--transport", "stdio"]
    env:
      GDRIVE_RAG_DB_PATH: "${GDRIVE_RAG_DB_PATH}"
      GDRIVE_RAG_EMBED_PROVIDER: "${GDRIVE_RAG_EMBED_PROVIDER}"
      GDRIVE_RAG_EMBED_MODEL: "${GDRIVE_RAG_EMBED_MODEL}"
      GDRIVE_RAG_EMBED_DIMENSIONS: "${GDRIVE_RAG_EMBED_DIMENSIONS}"
      GDRIVE_RAG_EMBED_API_KEY_ENV: "${GDRIVE_RAG_EMBED_API_KEY_ENV}"
      GEMINI_API_KEY: "${GEMINI_API_KEY}"
    timeout: 120
    connect_timeout: 30
    supports_parallel_tool_calls: true

마지막 비밀 변수를 제공자 구성이 가리키는 변수로 교체하세요. 형식은 공식 Hermes MCP 가이드를 기반으로 합니다.

Codex local TOML

~/.codex/config.toml 또는 신뢰할 수 있는 프로젝트의 .codex/config.toml에 추가하세요:

[mcp_servers.gdrive_knowledge]
command = "/path/to/gdrive-rag-mcp/.venv/bin/gdrive-rag-mcp"
args = ["serve", "--transport", "stdio"]
cwd = "/path/to/gdrive-rag-mcp"
env_vars = [
  "GDRIVE_RAG_DB_PATH",
  "GDRIVE_RAG_EMBED_PROVIDER",
  "GDRIVE_RAG_EMBED_MODEL",
  "GDRIVE_RAG_EMBED_DIMENSIONS",
  "GDRIVE_RAG_EMBED_BASE_URL",
  "GDRIVE_RAG_EMBED_API_KEY_ENV",
  "GEMINI_API_KEY",
  "OPENAI_API_KEY",
]
startup_timeout_sec = 30
tool_timeout_sec = 120
required = true

Codex의 현재 stdio 전달 및 원격 bearer 토큰 키는 공식 Codex MCP 가이드에 문서화되어 있습니다.

Server mode (Streamable HTTP)

export GDRIVE_RAG_BEARER_TOKEN="$(openssl rand -hex 32)"
gdrive-rag-mcp serve --transport http

엔드포인트는 http://127.0.0.1:8000/mcp이며, GET /health는 인덱스 세부 정보를 반환하지 않는 인증 없는 활성 상태 확인입니다. 모든 /mcp 요청에는 Authorization: Bearer ...가 필요합니다.

신뢰할 수 있는 리버스 프록시/로드 밸런서에서 TLS를 종료하고, Authorization 헤더를 유지하며, 인바운드 네트워크를 제한하고, 애플리케이션을 프록시 네트워크에만 바인딩하세요. 평문 HTTP를 노출하거나 bearer 토큰을 URL이나 저장소에 넣지 마세요.

Docker Compose

기본 이미지에는 Gemini 및 HTTP 제공자가 포함되지만 PyTorch/Sentence Transformers는 포함되지 않습니다.

mkdir -p secrets
# Place service-account.json in secrets/; this directory is ignored.
export GDRIVE_FOLDER_ID=your-folder-id
export GDRIVE_RAG_BEARER_TOKEN="$(openssl rand -hex 32)"
export GDRIVE_RAG_EMBED_PROVIDER=gemini
export GDRIVE_RAG_EMBED_API_KEY_ENV=GEMINI_API_KEY
export GEMINI_API_KEY=your-runtime-secret
docker compose run --rm app sync
docker compose up -d app

로컬 Sentence Transformers의 경우 빌드 전에 GDRIVE_RAG_EXTRAS=sentence-transformers를 설정하고 하드웨어에 적합한 이미지/런타임을 선택하세요. 별도의 컨테이너 인덱스의 경우 /data 아래에 서로 다른 GDRIVE_RAG_DB_PATH 값을 설정하세요. index-data 볼륨은 SQLite 데이터를 유지합니다.

Hermes Agent remote YAML

mcp_servers:
  gdrive_knowledge:
    url: "https://knowledge.example.com/mcp"
    headers:
      Authorization: "Bearer ${GDRIVE_RAG_BEARER_TOKEN}"
    timeout: 120
    connect_timeout: 30
    supports_parallel_tool_calls: true

Codex remote TOML

[mcp_servers.gdrive_knowledge]
url = "https://knowledge.example.com/mcp"
bearer_token_env_var = "GDRIVE_RAG_BEARER_TOKEN"
startup_timeout_sec = 30
tool_timeout_sec = 120
required = true

일반 MCP 클라이언트

MCP 구성 파일 구문은 클라이언트별로 다릅니다. 표준을 준수하는 모든 클라이언트는 다음 중 하나를 사용할 수 있습니다:

• stdio: 명령 gdrive-rag-mcp, 인수 serve --transport stdio, 그리고 운영자의 인덱스 및 임베딩 환경; 또는

• Streamable HTTP: URL https://knowledge.example.com/mcp 및 헤더 Authorization: Bearer $GDRIVE_RAG_BEARER_TOKEN.

서버는 Google 또는 임베딩 제공자 자격 증명을 클라이언트에 노출하지 않습니다. OpenClaw 또는 여기에 검증된 네이티브 형식이 없는 다른 에이전트의 경우, 검증되지 않은 클라이언트별 스니펫을 복사하는 대신 해당 전송 값으로 표준 준수 MCP 어댑터를 구성하십시오.

보안 및 데이터 처리

• .env, 데이터베이스, OAuth 토큰, 클라이언트 시크릿, 서비스 계정 키, 다운로드된 파일, 모델 캐시 및 생성된 인덱스는 소스 제어 밖에 있어야 합니다.

• SQLite에는 추출된 소스 텍스트가 포함됩니다. 디스크/백업을 암호화하고 OS/볼륨 액세스를 제한하십시오.

• 호스팅된 임베딩 제공자는 동기화 중 추출된 청크와 검색 중 쿼리를 수신합니다. 해당 데이터 약관 및 리전을 검토하십시오. 데이터가 호스트를 벗어나면 안 되는 경우 적절한 로컬 모델을 사용하십시오.

• API 키 값은 환경 변수에서만 가져옵니다. 자격 증명이 포함된 기본 URL은 거부됩니다.

• 지문은 제공자/모델/차원/엔드포인트 ID를 저장하며 API 키는 절대 저장하지 않습니다. MCP 상태는 엔드포인트를 생략합니다.

• MCP, Google 및 임베딩 제공자 자격 증명을 교체하고 교체 후 다시 시작하십시오.

• 도구는 검색 전용입니다. Drive 쓰기 및 인덱스 변경은 MCP를 통해 노출되지 않습니다.

• 보고 및 배포 강화는 SECURITY.md를 참조하십시오.

정직한 한계

• 스캔/이미지 전용 PDF는 인덱싱 전에 OCR이 필요합니다. 이 프로젝트는 OCR을 수행하지 않습니다.

• 시트는 표시된 셀 값과 시트 이름을 인덱싱하며 차트, 주석 또는 수식 논리는 인덱싱하지 않습니다.

• Docs 주석, 제안, 개정 기록, 연결된 파일 및 리치 레이아웃은 보존되지 않습니다.

• 슬라이드, 이미지, 오디오, 비디오, 바로가기 및 임의의 바이너리 형식은 건너뜁니다.

• 동기화는 폴더 트리 스캔이며 Drive Changes API가 아닙니다. 변경 사항은 다음 성공적인 동기화 후에 나타납니다.

• 검색 점수는 휴리스틱이며 확률이 아닙니다. 고위험 사용 전에 도메인별 다국어 평가로 증거 임계값을 조정하십시오.

• FTS 토큰화는 유니코드를 인식하지만 언어별 형태소 분석기는 아닙니다. 공백이 없거나 복잡한 분할이 있는 언어는 의미론적 검색에 더 의존할 수 있습니다.

• SQLite는 소규모 공유 서비스에 적합하며 높은 쓰기 또는 대규모 분산 워크로드에는 적합하지 않습니다. 지속성과 검색은 격리되어 있으므로 나중에 교체할 수 있습니다.

개발

python3.12 -m venv .venv
. .venv/bin/activate
pip install -e '.[dev]'
ruff format --check .
ruff check .
mypy src/gdrive_rag_mcp
pytest

테스트는 가짜 소스, HTTP 전송 및 결정적 유니코드 안전 임베딩을 사용합니다. Google, Gemini, OpenAI 또는 로컬 모델 자격 증명이 필요하지 않습니다. CONTRIBUTING.md를 참조하십시오.

Khởi động nhanh bằng tiếng Việt

Đây là ví dụ cộng đồng; dự án không mặc định một ngôn ngữ. Chất lượng tìm kiếm ngữ nghĩa phụ thuộc vào model embedding đã chọn.

1. Tạo service account, bật Google Drive API, rồi chia sẻ chỉ thư mục cần lập chỉ mục với quyền Viewer.

2. Sao chép .env.example thành .env; cấu hình thư mục Drive, provider/model embedding và secret qua biến môi trường.

3. Chọn model có chất lượng tiếng Việt đã được bạn đánh giá, sau đó chạy gdrive-rag-mcp sync.

4. Chạy stdio hoặc HTTP MCP và kết nối bằng bất kỳ MCP client tương thích nào. Đổi agent không cần lập chỉ mục lại; đổi provider/model/dimensions thì chạy gdrive-rag-mcp reindex --yes hoặc dùng profile/database khác.

5. Khi evidence.sufficient=false, agent phải từ chối kết luận; luôn mở nguồn Drive, kiểm tra ngày hiệu lực và trích dẫn.

라이선스

MIT