gdrive-rag-mcp

Локальный гибридный индекс Google Drive, доступный через Model Context Protocol (MCP). Выберите провайдера эмбеддингов и модель, подходящие под ваши языки, границы приватности и инфраструктуру; затем запрашивайте тот же долговечный индекс из Codex, Hermes Agent или любого MCP-клиента, соответствующего стандарту. Индекс не привязан к агенту, который его запрашивает.

Google Drive/Workspace остаётся источником истины в режиме только для чтения. Сервис хранит извлечённые фрагменты, нормализованные эмбеддинги, метаданные, контрольные суммы, состояние синхронизации и данные индекса — но не скачанные исходные файлы. Он не требует LlamaCloud и использует LlamaIndex только на заменяемой границе фрагментации.

Важно: поиск помогает исследованию; это не юридическая, налоговая, финансовая, экономическая или деловая консультация. Агенты и люди должны проверять связанный источник, дату вступления в силу, юрисдикцию и последующие поправки. Если evidence.sufficient равно false, воздержитесь от ответа вместо заполнения пробелов.

Что делает MVP

• Рекурсивно читает одну настроенную папку Drive или область Shared Drive через API только чтения.

• Извлекает Google Docs, Google Sheets, текст/Markdown, текстовые PDF и DOCX.

• Поддерживает Gemini, любую проверенную OpenAI-совместимую конечную точку /embeddings и опциональные локальные Sentence Transformers за одним протоколом эмбеддингов.

• Сочетает Unicode-безопасный полнотекстовый поиск SQLite FTS5 с косинусным поиском sqlite-vec. Проверенный Python-фолбэк для косинуса используется, если расширение не загружается.

• Переиндексирует изменённые файлы и удаляет удалённые или вышедшие из области файлы при последующих синхронизациях.

• Предотвращает совместное использование индекса векторами от разных провайдеров, моделей, конечных точек или размерностей, записывая и проверяя отпечаток эмбеддинга.

• Возвращает цитаты, время изменения/индексации источника и консервативное решение по доказательствам.

• Предоставляет одни и те же инструменты только чтения через локальный stdio и защищённый bearer-токеном Streamable HTTP.

Архитектура

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, провайдера эмбеддингов и локальной модели остаются у оператора сервиса. Удалённые клиенты получают только URL MCP и bearer-токен.

Провайдеры эмбеддингов

Языковое покрытие — это свойство выбранной модели, а не «языковой режим» индексации. FTS5 использует Unicode-токенизатор SQLite, а семантическое качество зависит от модели и домена. Оценивайте свои реальные языки и документы; этот проект не претендует на идеальную поддержку всех языков.

Изменение провайдера эмбеддингов, модели, конечной точки или размерности требует пересборки этого векторного индекса. Смена MCP-клиентов или агентов не требует переиндексации.

HTTP-адаптер следует официальной схеме запроса/ответа эмбеддингов OpenAI, включая пакетный строковый ввод, упорядоченные результаты, опциональные размерности и векторы с плавающей точкой. Отдельный адаптер Ollama не заявлен. Если конкретное развёртывание Ollama явно реализует этот контракт /v1/embeddings, протестируйте его как OpenAI-совместимую конечную точку и установите GDRIVE_RAG_EMBED_SEND_DIMENSIONS=false, если это развёртывание не принимает поле размерности.

Gemini использует задачи запроса/документа, специфичные для поиска, и явные выходные размерности, описанные в официальной документации эмбеддингов Gemini. Локальный адаптер использует документированные методы Sentence Transformers encode_query и encode_document с нормализованным выводом.

Установка

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.

Настройка провайдера эмбеддингов

Секретные значения берутся из переменной окружения, имя которой задаётся GDRIVE_RAG_EMBED_API_KEY_ENV. Имя переменной — это конфигурация; секретное значение никогда не хранится в отпечатке индекса или файлах примеров.

Gemini (обратно совместимый по умолчанию)

Существующая конфигурация окружения остаётся действительной: если настройки провайдера отсутствуют, сервис использует 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-совместимая конечная точка

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

Для другой совместимой конечной точки замените базовый URL, модель, размерности и переменную ключа. Никогда не помещайте учётные данные в базовый URL. Устанавливайте GDRIVE_RAG_EMBED_SEND_DIMENSIONS=false только когда проверенная конечная точка/модель не принимает это необязательное поле; настроенная выходная размерность всё равно проверяется в каждом ответе.

Локальные 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

Включите API Google Drive, затем выберите один метод.

Сервисный аккаунт (рекомендуется для минимальных привилегий)

1. Создайте сервисный аккаунт и храните его JSON-ключ в каталоге секретов, доступном только оператору.

2. Поделитесь только выбранной папкой Drive с его email как Viewer. Это создаёт более строгую границу папки, чем пользовательский OAuth-токен.

3. Установите GOOGLE_SERVICE_ACCOUNT_FILE и GDRIVE_FOLDER_ID. Для Shared Drive добавьте аккаунт с минимальной ролью чтения и установите GDRIVE_SHARED_DRIVE_ID.

Не включайте делегирование на уровне домена без отдельного рассмотрения. Код запрашивает только https://www.googleapis.com/auth/drive.readonly.

Пользовательский OAuth

1. Создайте клиент OAuth Desktop-приложения и храните его JSON вне репозитория.

2. Установите GOOGLE_OAUTH_CLIENT_FILE и GOOGLE_OAUTH_TOKEN_FILE.

3. Запустите gdrive-rag-mcp auth-google один раз и одобрите доступ только чтения.

API Drive не имеет OAuth-области, означающей «только чтение этой существующей папки». OAuth-токен может читать файлы, которые пользователь может читать; индексатор применяет настроенную папку во время обхода. См. руководство по авторизации Drive.

Создание, обновление и миграция индекса

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

Запускайте sync периодически. Он сканирует выбранное дерево, избегает повторной фрагментации/ повторного эмбеддинга неизменённых контрольных сумм, переиндексирует изменённый целый файл, удаляет устаревшие записи и записывает completed_at.

Отпечаток эмбеддинга и унаследованные индексы

Каждая база данных записывает провайдера, модель, размерность, идентичность конечной точки и SHA-256 отпечаток. Инструмент статуса MCP возвращает провайдера/модель/размерность/отпечаток, но не раскрывает конечную точку.

Базы данных версии 0.1.x не записывали идентичность эмбеддинга. Непустой унаследованный индекс не может быть безопасно выведен — даже если он, вероятно, использовал старое значение по умолчанию 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

Все имена инструментов и инструкции нейтральны к агенту и помечены как только чтение.

Слабые совпадения помещаются в candidate_results для диагностики; обычные results остаются пустыми, когда верхний балл ниже GDRIVE_RAG_EVIDENCE_THRESHOLD.

Локальный режим (stdio)

gdrive-rag-mcp serve --transport stdio

Клиент запускает этот процесс. Сделайте базу данных и конфигурацию провайдера доступными этому подпроцессу. Поиск требует доступа к провайдеру для эмбеддинга запроса; он никогда не требует учётных данных Google, если только тот же процесс не выполняет также синхронизацию.

Локальный YAML Hermes Agent

Hermes читает MCP-серверы из ~/.hermes/config.yaml и поддерживает подстановку переменных окружения. Храните фактические секреты в ~/.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.

Локальный TOML Codex

Добавьте в ~/.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

Текущие ключи пересылки stdio и удалённого bearer-токена Codex документированы в официальном руководстве Codex MCP.

Серверный режим (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 перед сборкой и выберите подходящий образ/рантайм для оборудования. Для отдельных контейнерных индексов установите разные значения GDRIVE_RAG_DB_PATH в /data. Том index-data сохраняет данные SQLite.

Удалённый YAML Hermes Agent

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

Удалённый TOML Codex

[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 содержит извлечённый исходный текст. Шифруйте диски/резервные копии и ограничивайте доступ на уровне ОС/томов.

• Хостируемые провайдеры эмбеддингов получают извлечённые фрагменты при синхронизации и запросы при поиске. Изучите их условия обработки данных и требования к локализации. Используйте подходящую локальную модель, если данные не должны покидать хост.

• Значения API-ключей берутся только из переменных окружения. Базовые URL, содержащие учётные данные, отклоняются.

• Отпечаток хранит идентификационные данные провайдера/модели/размерности/конечной точки, но никогда не API-ключ. Статус MCP не включает конечную точку.

• Меняйте учётные данные MCP, Google и провайдера эмбеддингов и перезапускайте сервис после ротации.

• Инструменты предназначены только для поиска; запись в Drive и изменение индекса не доступны через MCP.

• О сообщении об уязвимостях и усилении безопасности развёртывания см. SECURITY.md.

Честные ограничения

• Отсканированные PDF-файлы и PDF только с изображениями требуют OCR перед индексацией; этот проект не выполняет OCR.

• Sheets индексируют отображаемые значения ячеек и имена листов, а не диаграммы, комментарии или логику формул.

• Комментарии, предложения, история изменений, связанные файлы и расширенная вёрстка Docs не сохраняются.

• Slides, изображения, аудио, видео, ярлыки и произвольные бинарные форматы пропускаются.

• Синхронизация — это сканирование дерева папок, а не Drive Changes API. Изменения появляются после следующей успешной синхронизации.

• Оценки поиска — это эвристики, а не вероятности. Настраивайте порог доказательности с помощью предметно-ориентированной многоязычной оценки перед использованием в ответственных сценариях.

• Токенизация FTS учитывает Unicode, но не является языко-специфичным морфологическим анализатором. Языки без пробелов или со сложной сегментацией могут в большей степени полагаться на семантический поиск.

• 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-транспорты и детерминированные Unicode-безопасные эмбеддинги. Для них не нужны учётные данные Google, Gemini, OpenAI или локальных моделей. См. CONTRIBUTING.md.

Быстрый старт на вьетнамском

Это пример сообщества; проект не задаёт язык по умолчанию. Качество семантического поиска зависит от выбранной модели эмбеддингов.

1. Создайте сервисный аккаунт, включите Google Drive API и предоставьте доступ только к папке, которую нужно индексировать, с правами Viewer.

2. Скопируйте .env.example в .env; настройте папку Drive, провайдера/модель эмбеддингов и секрет через переменные окружения.

3. Выберите модель, качество которой для вьетнамского языка вы уже оценили, затем запустите gdrive-rag-mcp sync.

4. Запустите MCP через stdio или HTTP и подключитесь с помощью любого совместимого MCP-клиента. Смена агента не требует повторной индексации; при смене провайдера/модели/размерностей запустите gdrive-rag-mcp reindex --yes или используйте другой профиль/базу данных.

5. Когда evidence.sufficient=false, агент должен отказаться от выводов; всегда открывайте источник в Drive, проверяйте дату актуальности и цитируйте.

Лицензия

MIT