gdrive-rag-mcp

Un índice híbrido local-first de Google Drive expuesto a través del Protocolo de Contexto de Modelo (MCP). Elige un proveedor de embeddings y un modelo que se adapten a tus idiomas, límites de privacidad e infraestructura; luego consulta el mismo índice duradero desde Codex, Hermes Agent o cualquier cliente MCP compatible con estándares. El índice no está vinculado al agente que lo consulta.

Google Drive/Workspace sigue siendo la fuente de verdad de solo lectura. El servicio almacena fragmentos extraídos, embeddings normalizados, metadatos, sumas de verificación, estado de sincronización y datos de índice, no los archivos fuente descargados. No requiere LlamaCloud y usa LlamaIndex solo en el límite de fragmentación reemplazable.

Importante: la recuperación asiste a la investigación; no es asesoramiento legal, fiscal, financiero, económico ni empresarial. Los agentes y las personas deben inspeccionar la fuente vinculada, la fecha de vigencia, la jurisdicción y las enmiendas posteriores. Si evidence.sufficient es falso, abstente en lugar de rellenar vacíos.

Qué hace el MVP

• Lee recursivamente una carpeta de Drive configurada o el ámbito de un Shared Drive con la API de solo lectura.

• Extrae Google Docs, Google Sheets, texto/Markdown, PDFs basados en texto y DOCX.

• Admite Gemini, cualquier endpoint /embeddings compatible con OpenAI verificado y Sentence Transformers local opcional detrás de un protocolo de embeddings unificado.

• Combina la búsqueda de palabras clave FTS5 de SQLite (segura para Unicode) con la búsqueda coseno de sqlite-vec. Se usa un fallback coseno en Python probado cuando la extensión no puede cargarse.

• Reindexa archivos modificados y elimina archivos borrados o fuera de alcance en sincronizaciones posteriores.

• Evita que vectores de diferentes proveedores, modelos, endpoints o dimensiones compartan un índice al registrar y validar una huella de embedding.

• Devuelve citas, tiempos de modificación/indexación de la fuente y una decisión de evidencia conservadora.

• Expone las mismas herramientas de solo lectura sobre stdio local y HTTP Streamable protegido por bearer.

Arquitectura

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]

Las credenciales/recursos de Google, del proveedor de embeddings y del modelo local permanecen con el operador del servicio. Los clientes remotos reciben solo una URL MCP y un token bearer.

Proveedores de embeddings

La cobertura de idiomas es una propiedad del modelo seleccionado, no un "modo de idioma" de indexación. FTS5 usa el tokenizador Unicode de SQLite, mientras que la calidad semántica depende del modelo y del dominio. Evalúa tus idiomas y documentos reales; este proyecto no afirma soporte perfecto para todos los idiomas.

Cambiar el proveedor de embeddings, el modelo, el endpoint o las dimensiones requiere reconstruir ese índice de vectores. Cambiar los clientes o agentes MCP no requiere reindexar.

El adaptador HTTP sigue el esquema oficial de solicitud/respuesta de embeddings de OpenAI, incluida la entrada de cadenas por lotes, resultados ordenados, dimensiones opcionales y vectores flotantes. No se afirma un adaptador dedicado de Ollama. Si una implementación particular de Ollama implementa explícitamente ese contrato /v1/embeddings, pruébala como un endpoint compatible con OpenAI y establece GDRIVE_RAG_EMBED_SEND_DIMENSIONS=false si esa implementación no acepta el campo de dimensiones.

Gemini usa tareas de consulta/documento específicas de recuperación y dimensiones de salida explícitas descritas en la documentación oficial de embeddings de Gemini. El adaptador local usa los métodos documentados de Sentence Transformers encode_query y encode_document con salida normalizada.

Instalación

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

Para el proveedor local, instala pip install -e '.[sentence-transformers]' en su lugar. El proyecto no analiza .env automáticamente; cárgalo con tu shell o administrador de procesos. Por ejemplo, set -a; . ./.env; set +a en un shell interactivo de confianza. Nunca hagas commit de .env.

Configurar un proveedor de embeddings

Los valores secretos provienen de la variable de entorno nombrada por GDRIVE_RAG_EMBED_API_KEY_ENV. El nombre de la variable es configuración; el valor secreto nunca se almacena en la huella del índice ni en archivos de muestra.

Gemini (predeterminado compatible con versiones anteriores)

La configuración de entorno existente sigue siendo válida: si los ajustes del proveedor están ausentes, el servicio usa Gemini, gemini-embedding-001, 768 dimensiones y 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

Endpoint compatible con 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

Para otro endpoint compatible, reemplaza la URL base, el modelo, las dimensiones y la variable de clave. Nunca pongas credenciales en la URL base. Establece GDRIVE_RAG_EMBED_SEND_DIMENSIONS=false solo cuando el endpoint/modelo verificado no acepte ese campo opcional; la dimensión de salida configurada aún se valida en cada respuesta.

Sentence Transformers local

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

El nombre del modelo anterior es un ejemplo, no una recomendación universal. La descarga/caché del modelo, las licencias, la cobertura de idiomas, el uso de memoria y los requisitos de hardware pertenecen al modelo seleccionado.

Ajuste común:

export GDRIVE_RAG_EMBED_BATCH_SIZE=32
export GDRIVE_RAG_EMBED_TIMEOUT_SECONDS=60

Todos los proveedores devuelven vectores normalizados y deben devolver exactamente las dimensiones configuradas.

Autenticación de Google

Habilita la API de Google Drive y luego elige un método.

Cuenta de servicio (recomendada para privilegios mínimos)

1. Crea una cuenta de servicio y guarda su clave JSON en un directorio de secretos solo para operadores.

2. Comparte solo la carpeta de Drive seleccionada con su correo como Lector. Esto crea un límite de carpeta más fuerte que un token OAuth de usuario.

3. Establece GOOGLE_SERVICE_ACCOUNT_FILE y GDRIVE_FOLDER_ID. Para un Shared Drive, agrega la cuenta con el rol de lectura mínimo y establece GDRIVE_SHARED_DRIVE_ID.

No habilites la delegación de todo el dominio a menos que se revise por separado. El código solicita solo https://www.googleapis.com/auth/drive.readonly.

OAuth de usuario

1. Crea un cliente de aplicación de escritorio OAuth y guarda su JSON fuera del repositorio.

2. Establece GOOGLE_OAUTH_CLIENT_FILE y GOOGLE_OAUTH_TOKEN_FILE.

3. Ejecuta gdrive-rag-mcp auth-google una vez y aprueba el acceso de solo lectura.

La API de Drive no tiene un ámbito OAuth que signifique "solo leer esta carpeta existente". El token OAuth puede leer archivos que el usuario puede leer; el indexador aplica la carpeta configurada durante el recorrido. Consulta la guía de autorización de Drive de Google.

Construir, actualizar y migrar un índice

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

Ejecuta sync periódicamente. Escanea el árbol seleccionado, evita re-fragmentar/re-embedding de sumas de verificación sin cambios, reindexa un archivo completo modificado, elimina registros obsoletos y registra completed_at.

Huella de embedding e índices heredados

Cada base de datos registra proveedor, modelo, dimensiones, identidad del endpoint y una huella SHA-256. La herramienta de estado MCP devuelve proveedor/modelo/dimensiones/huella, pero no expone el endpoint.

Las bases de datos de la versión 0.1.x no registraban la identidad del embedding. Un índice heredado no vacío no puede inferirse de manera segura, incluso si probablemente usaba el predeterminado antiguo de Gemini, por lo que la versión 0.2 se niega a abrirlo. Haz una copia de seguridad de la base de datos si lo deseas, carga las mismas credenciales de Drive/proveedor y luego reconstruye explícitamente:

gdrive-rag-mcp reindex --yes

El comando elimina solo los datos de índice generados en la base de datos seleccionada y realiza una sincronización completa de Drive. No modifica Drive. Una base de datos heredada vacía se sella automáticamente.

Para mantener múltiples índices intencionales, usa perfiles nombrados o rutas explícitas:

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.

El perfil predeterminado mantiene la ruta compatible con versiones anteriores data/index.db; otros perfiles derivan data/index-<profile>.db.

Herramientas MCP

Todos los nombres de herramientas e instrucciones son neutrales para agentes y están marcados como de solo lectura.

Los resultados débiles se colocan en candidate_results para diagnóstico; los results normales permanecen vacíos cuando la puntuación máxima está por debajo de GDRIVE_RAG_EVIDENCE_THRESHOLD.

Modo local (stdio)

gdrive-rag-mcp serve --transport stdio

El cliente lanza este proceso. Haz que la base de datos y la configuración del proveedor estén disponibles para ese subproceso. La búsqueda necesita acceso al proveedor para el embedding de la consulta; nunca necesita credenciales de Google a menos que el mismo proceso también realice la sincronización.

YAML local de Hermes Agent

Hermes lee los servidores MCP desde ~/.hermes/config.yaml y admite sustitución de entorno. Mantén los secretos reales en ~/.hermes/.env o en el entorno padre.

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

Reemplaza la variable secreta final con la nombrada por tu configuración de proveedor. El formato se basa en la guía oficial de MCP de Hermes.

TOML local de Codex

Agrega a ~/.codex/config.toml o a un .codex/config.toml de proyecto de confianza:

[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

Las claves actuales de reenvío stdio y token bearer remoto de Codex están documentadas en la guía oficial de MCP de Codex.

Modo servidor (HTTP Streamable)

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

El endpoint es http://127.0.0.1:8000/mcp; GET /health es una verificación de vida no autenticada que no devuelve detalles del índice. Cada solicitud /mcp requiere Authorization: Bearer ....

Termina TLS en un proxy inverso/balanceador de carga de confianza, conserva el encabezado Authorization, restringe las redes entrantes y vincula la aplicación solo a la red del proxy. Nunca expongas HTTP plano ni pongas un token bearer en una URL o repositorio.

Docker Compose

La imagen base incluye los proveedores Gemini y HTTP, pero no 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

Para Sentence Transformers local, establece GDRIVE_RAG_EXTRAS=sentence-transformers antes de construir y elige una imagen/tiempo de ejecución adecuado para el hardware. Para índices de contenedores separados, establece valores distintos de GDRIVE_RAG_DB_PATH bajo /data. El volumen index-data persiste los datos de SQLite.

YAML remoto de 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 remoto de 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

Cliente MCP genérico

La sintaxis del archivo de configuración de MCP es específica de cada cliente. Cualquier cliente compatible con los estándares puede utilizar cualquiera de las dos opciones:

• stdio: comando gdrive-rag-mcp, argumentos serve --transport stdio, más el índice y el entorno de embeddings del operador; o

• Streamable HTTP: URL https://knowledge.example.com/mcp y cabecera Authorization: Bearer $GDRIVE_RAG_BEARER_TOKEN.

El servidor no expone las credenciales de Google ni del proveedor de embeddings al cliente. Para OpenClaw u otro agente sin un formato nativo verificado aquí, configura su adaptador MCP compatible con los estándares con esos valores de transporte en lugar de copiar un fragmento específico de un cliente no verificado.

Seguridad y manejo de datos

• .env, bases de datos, tokens OAuth, secretos de cliente, claves de cuentas de servicio, archivos descargados, cachés de modelos e índices generados deben permanecer fuera del control de versiones.

• SQLite contiene el texto fuente extraído. Cifra los discos/copias de seguridad y restringe el acceso del sistema operativo y de los volúmenes.

• Los proveedores de embeddings alojados reciben fragmentos extraídos durante la sincronización y consultas durante la búsqueda. Revisa sus condiciones de datos y de residencia. Utiliza un modelo local adecuado cuando los datos no deban salir del host.

• Los valores de las claves de API provienen únicamente de variables de entorno. Se rechazan las URL base que contienen credenciales.

• La huella almacena una identidad de proveedor/modelo/dimensión/endpoint, nunca una clave de API. El estado de MCP omite el endpoint.

• Rota las credenciales de MCP, de Google y del proveedor de embeddings y reinicia tras la rotación.

• Las herramientas son solo de recuperación; las escrituras en Drive y la mutación de índices no se exponen a través de MCP.

• Consulta SECURITY.md para notificar vulnerabilidades y reforzar el despliegue.

Limitaciones honestas

• Los PDF escaneados o de solo imagen requieren OCR antes de indexarse; este proyecto no hace OCR.

• Sheets indexa los valores de celda mostrados y los nombres de las hojas, no los gráficos, los comentarios ni la lógica de las fórmulas.

• Los comentarios, las sugerencias, el historial de revisiones, los archivos vinculados y el diseño enriquecido de Docs no se conservan.

• Se omiten Slides, las imágenes, el audio, el vídeo, los accesos directos y los formatos binarios arbitrarios.

• La sincronización es un escaneo del árbol de carpetas, no una API de cambios de Drive. Los cambios aparecen tras la siguiente sincronización correcta.

• Las puntuaciones de búsqueda son heurísticas, no probabilidades. Ajusta el umbral de evidencia con evaluación específica del dominio y multilingüe antes en usos de alto riesgo.

• La tokenización de FTS es compatible con Unicode, pero no es un analizador morfológico específico del idioma. Los idiomas sin espacios en blanco o con segmentación compleja pueden depender en mayor medida de la recuperación semántica.

• SQLite es apto para un servicio compartido pequeño, no para cargas de alta escritura ni grandes cargas distribuidas. La persistencia y la recuperación se mantienen aisladas para poder sustituirse más adelante.Sustituirse.

Desarrollo

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

Las pruebas usan fuentes simuladas, transportes HTTP y embeddings deterministas y seguros para Unicode. No requieren credenciales de Google, Gemini, OpenAI ni de modelos locales. Consulta CONTRIBUTING.md.

Inicio rápido vietnamita

Tu proyecto es un ejemplo de la comunidad; el proyecto no establece un idioma por defecto. La calidad de la búsqueda semántica depende del modelo de embeddings elegido.

1. Crea un service account, activa la API de Google Drive y comparte solo las carpetas que desees indexar con el permiso de Viewer.

2. Copia .env.example a .env; configura la carpeta de Drive, el provider/modelo de embeddings y los secretos mediante variables de entorno.

3. Elige un modelo con calidad vérbena para el vietnamita que hayas evaluow, y luego ejecuta gdrive-rag-mcp sync.

4. Ejecuta MCP por stdio o HTTP y conéctate con cualquier cliente MCP compatible. Cambiar de agente no requiere reindexar; si cambias el provider/modelo/dimensiones, ejecuta gdrive-rag-mcp reindex --yes o usa otro perfil/database.

5. Cuando evidence.sufficient=false, el agent debe rechazar concluir; haz uso siempre del origen en Drive, verifica la fecha de vigencia y cita la fuente.

Licencia

MIT