LocalGate

LocalGate 是一个隐私优先的本地检索网关:把你自己电脑上分散的笔记、PDF、 DOCX、源码、聊天记录导出和图片(本地 OCR)统一建立本机索引,通过 **MCP Server(stdio)+ HTTP API(仅回环)**供本地 AI Agent 调用。

• 数据不出本机:解析、分块、向量嵌入、检索全部本地执行;索引只写入你 配置的本地目录。

• 只读红线:对你的文件只读,绝不编辑/创建/删除/重命名白名单内的文件。

• 默认零扫描:发行版配置的白名单为空——不添加白名单,一个文件都不会被索引。

• 零强制依赖:核心只用 Python 标准库,离线可用。

不适合的场景:需要云端同步/多人协作的检索;让数据出本机的 RAG 服务; 作为笔记编辑器或聊天界面(它刻意不做这些)。

平台:Linux / macOS / Windows,Python 3.10+。

1. 安装

从源码安装(推荐放入虚拟环境):

python -m pip install .            # 核心零第三方依赖
python -m pip install ".[yaml,pdf]"  # 可选:更完整的 YAML 解析与 PDF 抽取

安装后提供 localgate 命令;也可以不经安装直接运行 python main.py ...。

Related MCP server: loci-mcp

2. 最小配置

当前目录没有 config.yaml 时,程序使用安全的内置默认值(空白名单、 仅回环、索引写入 ./data)。要真正开始检索,创建一份配置:

cp config.yaml myconfig.yaml

编辑 myconfig.yaml,把你要检索的目录加入白名单(其他默认值已经安全):

paths:
  whitelist:
    - /home/me/Notes        # 换成你自己的目录;支持 ~/ 展开
    - ~/Documents/vault

说明:

• 相对路径(如 data_dir: ./data)一律相对于配置文件所在目录解析,与 启动时的工作目录无关;

• blacklist 优先级高于 whitelist;

• embedding.backend 默认 local(内置哈希嵌入,离线、确定性); 若改为 ollama,只允许本机回环地址(如 http://127.0.0.1:11434)。 配置加载时会做严格校验:远程 IP、非回环 DNS 解析、https、URL 用户信息、 非常规路径等一律拒绝(fail closed),并把地址重写为解析后的字面 IP, 防止 DNS rebinding。

3. 运行

localgate serve  -c myconfig.yaml   # 启动网关:HTTP API + 文件监听 + 自检守护
localgate index  -c myconfig.yaml   # 一次性扫描白名单建索引后退出
localgate status -c myconfig.yaml   # 打印网关状态 JSON
localgate mcp    -c myconfig.yaml   # 运行 stdio MCP Server(供 Agent 拉起)

不加 -c 时读取 ./config.yaml;仍找不到则使用内置默认值(空白名单, 只读服务,索引文档数为 0 并打印告警)。

4. 接入 MCP 客户端

MCP Server 通过 stdio 与客户端通信,把工具调用代理到本机网关(默认 http://127.0.0.1:8770)。客户端配置示例(.mcp.json / claude_desktop_config.json):

{
  "mcpServers": {
    "localgate": {
      "command": "localgate",
      "args": ["mcp"]
    }
  }
}

从源码运行可用:"command": "python3", "args": ["/path/to/localgate/main.py", "mcp"]。

协议支持矩阵:MCP 协议版本 2025-06-18、2025-03-26、2024-11-05 (初始化时与客户端协商,按官方规范回退到服务端最新版本)。已通过 MCP 官方 Python SDK 的客户端完成端到端握手测试;未对全部第三方客户端逐一 验证,遇到问题请附带客户端名称与版本提 issue。

工具:

5. HTTP API(默认仅绑定 127.0.0.1:8770)

服务端校验 Host 必须是回环地址、Origin 若存在必须是回环来源 (防 DNS rebinding 与跨站请求),JSON POST 接口要求 Content-Type: application/json。

POST /api/rescan 的响应是可观察的执行状态,例如:

{"rescan_started": true, "mode": "watcher", "reason": ""}

• watcher 线程存活:mode: "watcher",请求进入其下一轮;

• watcher 未启用/已停止:直接启动一次性后台扫描(mode: "oneshot");

• 已有扫描在跑:rescan_started: false,原因写明。

进度与完成情况通过 GET /api/status 的 ingest.scanning 与 watcher.last_pass 观察;空白名单时 rescan 明确拒绝(reason: "whitelist is empty; nothing to scan"),绝不假成功。

错误约定:参数/校验错误返回 4xx 与简短消息;内部错误统一返回 {"error": "internal server error"},详细堆栈只写入本地结构化日志。

6. OCR 与嵌入

• OCR:ocr.mode: auto 时按 tesseract → macOS Vision(首次用系统 swiftc 在本地编译助手,缓存于索引目录 bin/)→ 跳过并计数的顺序降级, 绝不联网。配置里的语言标签是 BCP-47(如 zh-Hans),Vision 直接使用; 传给 tesseract 前会映射为 chi_sim+eng 风格的语言码。

• 嵌入:local 后端为纯本地哈希嵌入(离线、确定性、无模型下载); ollama 后端调用本机 Ollama(地址强制回环,禁用跟随重定向)。

7. 自检循环

服务启动后,自检守护按配置间隔(默认 300 秒)执行 7 项检查:文件源、 索引完整性、性能指标、嵌入健康、服务存活、资源阈值、安全自动优化 (孤儿清理/段合并/单文件重试)。每轮写一条 JSONL 结构化日志;连续出错 按指数退避降频;白名单根目录暂时不可访问(如外置卷未挂载)时保留索 引不清空,只有可确认的文件删除才会移除对应索引条目。

8. 故障排查

9. 开发与测试

python -m pip install -e .[dev]
python -m pytest tests --cov=localgate      # 单元 + 安全边界测试(覆盖率报告)
python tests/run_scenarios.py               # 端到端场景套件(真实子进程服务)
python -m ruff check localgate tests main.py
python -m mypy
python -m build && python -m twine check dist/*

测试全部使用临时目录与动态端口,不依赖开发者机器上的路径或既有索引。

10. 卸载

python -m pip uninstall localgate
# 索引与日志是本地数据,不会被包管理器删除;确认无用后手动删除:
#   rm -rf ./data ./logs

11. 文档与社区

• 许可证:LICENSE(MIT)

• 安全策略与漏洞报告:SECURITY.md

• 贡献指南:CONTRIBUTING.md

• 行为准则:CODE_OF_CONDUCT.md

• 变更记录:CHANGELOG.md

• 支持渠道与边界:SUPPORT.md

GitHub 标签:local-rag mcp-server ollama privacy-first vector-search agent-tool local-index