gdrive-rag-mcp

Ein lokaler, hybrider Google-Drive-Index, der über das Model Context Protocol (MCP) bereitgestellt wird. Wählen Sie einen Embedding-Anbieter und ein Modell, das zu Ihren Sprachen, Ihrer Datenschutzgrenze und Ihrer Infrastruktur passt; fragen Sie dann denselben dauerhaften Index von Codex, Hermes Agent oder einem beliebigen standardkonformen MCP-Client ab. Der Index ist nicht an den Agenten gebunden, der ihn abfragt.

Google Drive/Workspace bleibt die schreibgeschützte Quelle der Wahrheit. Der Dienst speichert extrahierte Chunks, normalisierte Embeddings, Metadaten, Prüfsummen, Synchronisierungsstatus und Indexdaten – nicht heruntergeladene Quelldateien. Er benötigt kein LlamaCloud und verwendet LlamaIndex nur an der austauschbaren Chunking-Grenze.

Wichtig: Die Abfrage unterstützt die Recherche; sie ist keine Rechts-, Steuer-, Finanz-, Wirtschafts- oder Geschäftsberatung. Agenten und Personen müssen die verlinkte Quelle, das Datum des Inkrafttretens, die Gerichtsbarkeit und spätere Änderungen prüfen. Wenn evidence.sufficient falsch ist, enthalten Sie sich, anstatt Lücken zu füllen.

Was die MVP leistet

• Liest rekursiv einen konfigurierten Drive-Ordner oder Shared-Drive-Bereich mit der schreibgeschützten API.

• Extrahiert Google Docs, Google Sheets, Text/Markdown, textbasierte PDFs und DOCX.

• Unterstützt Gemini, jeden verifizierten OpenAI-kompatiblen /embeddings-Endpunkt und optionale lokale Sentence Transformers hinter einem einheitlichen Embedding-Protokoll.

• Kombiniert Unicode-sichere SQLite-FTS5-Keyword-Suche mit sqlite-vec-Kosinus-Suche. Ein getesteter Python-Kosinus-Fallback wird verwendet, wenn die Erweiterung nicht geladen werden kann.

• Indiziert geänderte Dateien neu und entfernt gelöschte oder nicht im Bereich liegende Dateien bei späteren Synchronisierungen.

• Verhindert, dass Vektoren von verschiedenen Anbietern, Modellen, Endpunkten oder Dimensionen einen Index teilen, indem ein Embedding-Fingerprint aufgezeichnet und validiert wird.

• Gibt Zitate, Quell-Änderungs-/Indizierungszeiten und eine konservative Evidenzentscheidung zurück.

• Stellt dieselben schreibgeschützten Tools über lokales stdio und bearer-geschütztes Streamable HTTP bereit.

Architektur

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-, Embedding-Anbieter- und lokale Modell-Anmeldeinformationen/Ressourcen bleiben beim Betreiber des Dienstes. Remote-Clients erhalten nur eine MCP-URL und ein Bearer-Token.

Embedding-Anbieter

Die Sprachabdeckung ist eine Eigenschaft des ausgewählten Modells, kein „Sprachmodus“ der Indizierung. FTS5 verwendet den Unicode-Tokenizer von SQLite, während die semantische Qualität vom Modell und der Domäne abhängt. Bewerten Sie Ihre tatsächlichen Sprachen und Dokumente; dieses Projekt beansprucht keine perfekte Unterstützung für jede Sprache.

Das Ändern des Embedding-Anbieters, -Modells, -Endpunkts oder der Dimensionen erfordert einen Neuaufbau dieses Vektorindex. Das Ändern von MCP-Clients oder -Agenten erfordert keine Neuindizierung.

Der HTTP-Adapter folgt dem offiziellen OpenAI-Embeddings-Anfrage-/Antwortschema, einschließlich Batch-String-Eingabe, geordneter Ergebnisse, optionaler Dimensionen und Float-Vektoren. Ein dedizierter Ollama-Adapter wird nicht beansprucht. Wenn eine bestimmte Ollama-Bereitstellung explizit diesen /v1/embeddings-Vertrag implementiert, testen Sie sie als OpenAI-kompatiblen Endpunkt und setzen Sie GDRIVE_RAG_EMBED_SEND_DIMENSIONS=false, wenn diese Bereitstellung das Feld dimensions nicht akzeptiert.

Gemini verwendet abfragespezifische Query-/Dokumentaufgaben und explizite Ausgabedimensionen, die in der offiziellen Gemini-Embedding-Dokumentation beschrieben sind. Der lokale Adapter verwendet die dokumentierten Sentence-Transformers-Methoden encode_query und encode_document mit normalisierter Ausgabe.

Installation

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

Für den lokalen Anbieter installieren Sie stattdessen pip install -e '.[sentence-transformers]'. Das Projekt parst .env nicht automatisch; laden Sie es mit Ihrer Shell oder Ihrem Prozessmanager. Zum Beispiel set -a; . ./.env; set +a in einer vertrauenswürdigen interaktiven Shell. Committen Sie niemals .env.

Konfigurieren eines Embedding-Anbieters

Geheime Werte stammen aus der Umgebungsvariable, die durch GDRIVE_RAG_EMBED_API_KEY_ENV benannt ist. Der Variablenname ist Konfiguration; der geheime Wert wird niemals im Index-Fingerprint oder in Beispieldateien gespeichert.

Gemini (abwärtskompatibler Standard)

Die bestehende Umgebungskonfiguration bleibt gültig: Wenn Anbietereinstellungen fehlen, verwendet der Dienst Gemini, gemini-embedding-001, 768 Dimensionen und 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-kompatibler Endpunkt

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

Ersetzen Sie für einen anderen kompatiblen Endpunkt die Basis-URL, das Modell, die Dimensionen und die Schlüsselvariable. Setzen Sie niemals Anmeldeinformationen in die Basis-URL. Setzen Sie GDRIVE_RAG_EMBED_SEND_DIMENSIONS=false nur, wenn der verifizierte Endpunkt/das Modell dieses optionale Feld nicht akzeptiert; die konfigurierte Ausgabedimension wird bei jeder Antwort weiterhin validiert.

Lokale 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

Der obige Modellname ist ein Beispiel, keine universelle Empfehlung. Modell-Download-/Cache-Verhalten, Lizenzen, Sprachabdeckung, Speichernutzung und Hardwareanforderungen gehören zum ausgewählten Modell.

Häufige Optimierung:

export GDRIVE_RAG_EMBED_BATCH_SIZE=32
export GDRIVE_RAG_EMBED_TIMEOUT_SECONDS=60

Alle Anbieter geben normalisierte Vektoren zurück und müssen genau die konfigurierten Dimensionen zurückgeben.

Google-Authentifizierung

Aktivieren Sie die Google-Drive-API und wählen Sie dann eine Methode.

Dienstkonto (empfohlen für minimale Rechte)

1. Erstellen Sie ein Dienstkonto und bewahren Sie seinen JSON-Schlüssel in einem nur für Betreiber zugänglichen Geheimnisverzeichnis auf.

2. Teilen Sie nur den ausgewählten Drive-Ordner mit seiner E-Mail als Betrachter. Dies schafft eine stärkere Ordnerbegrenzung als ein Benutzer-OAuth-Token.

3. Setzen Sie GOOGLE_SERVICE_ACCOUNT_FILE und GDRIVE_FOLDER_ID. Für einen Shared Drive fügen Sie das Konto mit der minimalen Leserolle hinzu und setzen Sie GDRIVE_SHARED_DRIVE_ID.

Aktivieren Sie keine domainweite Delegierung, es sei denn, sie wurde separat überprüft. Der Code fordert nur https://www.googleapis.com/auth/drive.readonly an.

Benutzer-OAuth

1. Erstellen Sie einen OAuth-Desktop-App-Client und bewahren Sie seinen JSON außerhalb des Repositorys auf.

2. Setzen Sie GOOGLE_OAUTH_CLIENT_FILE und GOOGLE_OAUTH_TOKEN_FILE.

3. Führen Sie einmal gdrive-rag-mcp auth-google aus und genehmigen Sie den schreibgeschützten Zugriff.

Die Drive-API hat keinen OAuth-Bereich, der „nur diesen vorhandenen Ordner lesen“ bedeutet. Das OAuth-Token kann Dateien lesen, die der Benutzer lesen kann; der Indexer erzwingt den konfigurierten Ordner während der Traversierung. Siehe den Drive-Autorisierungsleitfaden von Google.

Index erstellen, aktualisieren und migrieren

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

Führen Sie sync regelmäßig aus. Es scannt den ausgewählten Baum, vermeidet das erneute Chunking/Embedding unveränderter Prüfsummen, indiziert eine geänderte ganze Datei neu, löscht veraltete Datensätze und zeichnet completed_at auf.

Embedding-Fingerprint und Legacy-Indexe

Jede Datenbank zeichnet Anbieter, Modell, Dimensionen, Endpunktidentität und einen SHA-256-Fingerprint auf. Das MCP-Statustool gibt Anbieter/Modell/Dimensionen/Fingerprint zurück, legt den Endpunkt jedoch nicht offen.

Version-0.1.x-Datenbanken haben keine Embedding-Identität aufgezeichnet. Ein nicht leerer Legacy-Index kann nicht sicher abgeleitet werden – selbst wenn er wahrscheinlich den alten Gemini-Standard verwendet hat –, daher weigert sich Version 0.2, ihn zu öffnen. Sichern Sie die Datenbank bei Bedarf, laden Sie dieselben Drive-/Anbieter-Anmeldeinformationen und erstellen Sie dann explizit neu:

gdrive-rag-mcp reindex --yes

Der Befehl löscht nur generierte Indexdaten in der ausgewählten Datenbank und führt eine vollständige Drive-Synchronisierung durch. Er ändert Drive nicht. Eine leere Legacy-Datenbank wird automatisch gestempelt.

Um mehrere beabsichtigte Indexe zu behalten, verwenden Sie benannte Profile oder explizite Pfade:

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.

Das Standardprofil behält den abwärtskompatiblen Pfad data/index.db; andere Profile leiten data/index-<profile>.db ab.

MCP-Tools

Alle Toolnamen und Anweisungen sind agentenneutral und als schreibgeschützt markiert.

Schwache Treffer werden für Diagnosen in candidate_results platziert; normale results bleiben leer, wenn die höchste Punktzahl unter GDRIVE_RAG_EVIDENCE_THRESHOLD liegt.

Lokaler Modus (stdio)

gdrive-rag-mcp serve --transport stdio

Der Client startet diesen Prozess. Stellen Sie die Datenbank- und Anbieterkonfiguration für diesen Unterprozess bereit. Die Suche benötigt Anbieterzugriff für das Abfrage-Embedding; sie benötigt niemals Google-Anmeldeinformationen, es sei denn, derselbe Prozess führt auch die Synchronisierung durch.

Hermes Agent lokales YAML

Hermes liest MCP-Server aus ~/.hermes/config.yaml und unterstützt Umgebungsersetzung. Bewahren Sie tatsächliche Geheimnisse in ~/.hermes/.env oder der übergeordneten Umgebung auf.

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

Ersetzen Sie die letzte geheime Variable durch die, die von Ihrer Anbieterkonfiguration benannt wird. Das Format basiert auf dem offiziellen Hermes-MCP-Leitfaden.

Codex lokales TOML

Fügen Sie zu ~/.codex/config.toml oder einem vertrauenswürdigen Projekt-.codex/config.toml hinzu:

[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

Die aktuelle stdio-Weiterleitung und Remote-Bearer-Token-Schlüssel von Codex sind im offiziellen Codex-MCP-Leitfaden dokumentiert.

Servermodus (Streamable HTTP)

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

Der Endpunkt ist http://127.0.0.1:8000/mcp; GET /health ist ein nicht authentifizierter Liveness-Check, der keine Indexdetails zurückgibt. Jede /mcp-Anfrage erfordert Authorization: Bearer ....

Beenden Sie TLS an einem vertrauenswürdigen Reverse-Proxy/Load-Balancer, bewahren Sie den Authorization-Header, beschränken Sie eingehende Netzwerke und binden Sie die Anwendung nur an das Proxy-Netzwerk. Setzen Sie niemals unverschlüsseltes HTTP ein oder platzieren Sie ein Bearer-Token in einer URL oder einem Repository.

Docker Compose

Das Basisimage enthält Gemini- und HTTP-Anbieter, aber nicht 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

Für lokale Sentence Transformers setzen Sie GDRIVE_RAG_EXTRAS=sentence-transformers vor dem Build und wählen Sie ein geeignetes Image/Laufzeit für die Hardware. Für separate Container-Indexe setzen Sie unterschiedliche GDRIVE_RAG_DB_PATH-Werte unter /data. Das index-data-Volume persistiert SQLite-Daten.

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

Generischer MCP-Client

Die Syntax der MCP-Konfigurationsdatei ist clientspezifisch. Jeder standardkonforme Client kann eine der folgenden Varianten verwenden:

• stdio: Befehl gdrive-rag-mcp, Argumente serve --transport stdio, plus die Index- und Embedding-Umgebung des Betreibers; oder

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

Der Server gibt keine Google- oder Embedding-Anbieter-Anmeldedaten an den Client weiter. Für OpenClaw oder einen anderen Agenten, für den hier kein verifiziertes natives Format vorliegt, konfigurieren Sie dessen standardkonformen MCP-Adapter mit diesen Transportwerten, anstatt einen unverifizierten clientspezifischen Ausschnitt zu kopieren.

Sicherheit und Datenverarbeitung

• .env, Datenbanken, OAuth-Tokens, Client-Secrets, Service-Account-Schlüssel, heruntergeladene Dateien, Modell-Caches und generierte Indizes müssen außerhalb der Versionskontrolle bleiben.

• SQLite enthält extrahierten Quelltext. Verschlüsseln Sie Datenträger/Sicherungen und beschränken Sie den OS-/Volume-Zugriff.

• Gehostete Embedding-Anbieter erhalten extrahierte Chunks während der Synchronisierung und Abfragen während der Suche. Prüfen Sie deren Datenschutzbestimmungen und -residenz. Verwenden Sie ein geeignetes lokales Modell, wenn Daten den Host nicht verlassen dürfen.

• API-Schlüsselwerte stammen ausschließlich aus Umgebungsvariablen. Basis-URLs mit Anmeldedaten werden abgelehnt.

• Der Fingerprint speichert eine Provider/Modell/Dimension/Endpunkt-Identität, niemals einen API-Schlüssel. Der MCP-Status lässt den Endpunkt aus.

• Rotieren Sie MCP-, Google- und Embedding-Anbieter-Anmeldedaten und starten Sie danach neu.

• Tools sind nur für den Abruf; Drive-Schreibvorgänge und Index-Mutationen werden nicht über MCP bereitgestellt.

• Siehe SECURITY.md für Meldung und Deployment-Härtung.

Ehrliche Einschränkungen

• Gescannte/reine Bild-PDFs benötigen vor der Indizierung OCR; dieses Projekt führt keine OCR durch.

• Sheets indizieren angezeigte Zellwerte und Blattnamen, nicht Diagramme, Kommentare oder Formellogik.

• Docs-Kommentare, Vorschläge, Versionsverlauf, verknüpfte Dateien und reichhaltiges Layout werden nicht beibehalten.

• Folien, Bilder, Audio, Video, Verknüpfungen und beliebige Binärformate werden übersprungen.

• Synchronisierung ist ein Ordnerbaum-Scan, nicht die Drive Changes API. Änderungen erscheinen nach der nächsten erfolgreichen Synchronisierung.

• Suchbewertungen sind Heuristiken, keine Wahrscheinlichkeiten. Passen Sie die Evidenzschwelle mit domänenspezifischer, mehrsprachiger Evaluierung an, bevor Sie sie für risikoreiche Zwecke verwenden.

• FTS-Tokenisierung ist Unicode-bewusst, aber kein sprachspezifischer morphologischer Analysator. Sprachen ohne Leerzeichen oder mit komplexer Segmentierung können stärker von semantischem Abruf abhängen.

• SQLite eignet sich für einen kleinen gemeinsamen Dienst, nicht für hohe Schreiblasten oder große verteilte Arbeitslasten. Persistenz und Abruf bleiben isoliert, sodass sie später ersetzt werden können.

Entwicklung

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

Tests verwenden Fake-Quellen, HTTP-Transports und deterministische Unicode-sichere Embeddings. Sie benötigen keine Google-, Gemini-, OpenAI- oder lokalen Modell-Anmeldedaten. Siehe CONTRIBUTING.md.

Schnellstart auf Vietnamesisch

Dies ist ein Community-Beispiel; das Projekt legt keine Sprache als Standard fest. Die Qualität der semantischen Suche hängt vom gewählten Embedding-Modell ab.

1. Erstellen Sie einen Service-Account, aktivieren Sie die Google Drive API und teilen Sie nur den zu indizierenden Ordner mit Viewer-Berechtigung.

2. Kopieren Sie .env.example in .env; konfigurieren Sie Drive-Ordner, Embedding-Provider/Modell und Secret über Umgebungsvariablen.

3. Wählen Sie ein Modell mit von Ihnen bewerteter vietnamesischer Qualität und führen Sie dann gdrive-rag-mcp sync aus.

4. Führen Sie stdio oder HTTP MCP aus und verbinden Sie sich mit einem beliebigen kompatiblen MCP-Client. Ein Agentenwechsel erfordert keine Neuindizierung; ein Wechsel von Provider/Modell/Dimensionen erfordert gdrive-rag-mcp reindex --yes oder ein anderes Profil/eine andere Datenbank.

5. Wenn evidence.sufficient=false, muss der Agent Schlussfolgerungen verweigern; öffnen Sie immer die Drive-Quelle, prüfen Sie das Gültigkeitsdatum und zitieren Sie.

Lizenz

MIT