gdrive-rag-mcp

一个通过模型上下文协议（MCP）暴露的本地优先 Google Drive 混合索引。选择适合您的语言、隐私边界和基础设施的嵌入提供方和模型；然后从 Codex、Hermes Agent 或任何符合标准的 MCP 客户端查询同一持久索引。该索引不依赖于查询它的代理。

Google Drive/Workspace 仍然是只读的事实来源。该服务存储提取的块、归一化嵌入、元数据、校验和、同步状态和索引数据——而不是下载的源文件。它不需要 LlamaCloud，并且仅在可替换的分块边界使用 LlamaIndex。

重要提示： 检索仅辅助研究；不构成法律、税务、财务、经济或商业建议。代理和人员必须检查链接的来源、生效日期、司法管辖区和后续修订。如果 evidence.sufficient 为 false，请弃权而不是填补空白。

MVP 的功能

• 使用只读 API 递归读取一个配置的 Drive 文件夹或共享云端硬盘范围。

• 提取 Google 文档、Google 表格、文本/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、嵌入提供方和本地模型凭据/资源由服务操作员保留。远程客户端仅接收 MCP URL 和 bearer 令牌。

嵌入提供方

语言覆盖范围是所选模型的属性，而不是索引的“语言模式”。FTS5 使用 SQLite 的 Unicode 分词器，而语义质量取决于模型和领域。请评估您的实际语言和文档；本项目不声称支持所有语言。

更改嵌入提供方、模型、端点或维度需要重建该向量索引。更改 MCP 客户端或代理不需要重新索引。

HTTP 适配器遵循官方 OpenAI 嵌入请求/响应模式，包括批量字符串输入、有序结果、可选维度和浮点向量。不声称有专用的 Ollama 适配器。如果特定的 Ollama 部署明确实现了该 /v1/embeddings 契约，请将其作为兼容 OpenAI 的端点进行测试，如果该部署不接受 dimensions 字段，请设置 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；请使用您的 shell 或进程管理器加载它。例如，在受信任的交互式 shell 中执行 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

对于其他兼容端点，请替换 base URL、模型、维度和密钥变量。切勿将凭据放在 base 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 身份验证

启用 Google Drive API，然后选择一种方法。

服务账户（推荐用于最低权限）

1. 创建服务账户，并将其 JSON 密钥保存在仅操作员可访问的密钥目录中。

2. 仅将选定的 Drive 文件夹与其电子邮件地址共享为查看者。这比用户 OAuth 令牌创建更强的文件夹边界。

3. 设置 GOOGLE_SERVICE_ACCOUNT_FILE 和 GDRIVE_FOLDER_ID。对于共享云端硬盘，请使用最低读取角色添加账户，并设置 GDRIVE_SHARED_DRIVE_ID。

除非单独审查，否则不要启用域范围委派。代码仅请求 https://www.googleapis.com/auth/drive.readonly。

用户 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 授权指南。

构建、刷新和迁移索引

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 中用于诊断；当最高分低于 GDRIVE_RAG_EVIDENCE_THRESHOLD 时，正常的 results 保持为空。

本地模式（stdio）

gdrive-rag-mcp serve --transport stdio

客户端启动此进程。使数据库和提供方配置可用于该子进程。搜索需要提供方访问权限来获取查询嵌入；除非同一进程还执行同步，否则它永远不需要 Google 凭据。

Hermes Agent 本地 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 本地 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 指南中有文档说明。

服务器模式（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 远程 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 远程 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 包含提取出的源文本。请加密磁盘/备份，并限制操作系统/卷的访问权限。

• 托管的嵌入提供方会在同步期间收到提取的文本块，在搜索期间收到查询。请审查其数据条款和驻留要求。当数据不得离开主机时，请使用合适的本地模型。

• API 密钥值只能来自环境变量。包含凭证的 Base URL 会被拒绝。

• 指纹存储的是提供方/模型/维度/端点的身份，而不是 API 密钥。MCP 状态不会显示该端点。

• 轮换 MCP、Google 和嵌入提供方的凭证，并在轮换后重启。

• 工具仅用于检索；Drive 写入和索引变更不会通过 MCP 暴露。

• 有关漏洞报告和部署加固，请参阅 SECURITY.md。

坦诚的局限性

• 纯扫描/纯图片 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 文件夹、嵌入 provider/model 和 secret。

3. 选择你已经评估过越南语质量的模型，然后运行 gdrive-rag-mcp sync。

4. 运行 stdio 或 HTTP MCP，并使用任何兼容的 MCP 客户端连接。更换智能体无需重新建立索引；更换 provider/model/dimensions 时，请运行 gdrive-rag-mcp reindex --yes 或使用其他 profile/database。

5. 当 evidence.sufficient=false 时，智能体必须拒绝下结论；始终打开 Drive 来源，检查生效日期并引用来源。

许可证

MIT