Skip to main content
Glama
omgamy1179-dev

localgate

by omgamy1179-dev
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

LocalGate

CI CodeQL Python License: MIT Release Security policy

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: bigos

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。

工具:

工具

说明

localgate_search

混合检索(BM25 + 向量融合),返回片段与路径

localgate_status

索引健康:文档/分块数、自检状态、白名单

localgate_get_document

按 doc_id 取回文档元数据与分块

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

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

端点

说明

GET /health

存活检查(自检循环用它自 ping)

GET /

最小只读状态面板(索引/进度/错误,HTML 已转义)

GET /api/status

索引统计、监听与自检状态、生效配置

POST /api/search

{"query": "...", "top_k": 8};query ≤ 8192 字符,top_k ≥ 1(服务端上限 100)

GET /api/document/{id}

文档元数据与分块;id 为 16 位十六进制 doc_id

GET /api/logs/selfcheck?lines=50

最近自检 JSONL 记录(1 ≤ lines ≤ 1000)

GET /api/logs/service?lines=50

最近服务 JSONL 记录(同上)

POST /api/rescan

触发一次白名单扫描;返回真实调度状态

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. 故障排查

现象

处理

启动即告警 "whitelist is empty"

正常。把你的目录加入 paths.whitelist 才会索引

config error: ... ollama_url ...

嵌入地址必须能解析到本机回环;远程地址一律拒绝

文件改了但检索结果没更新

watcher 轮询有间隔;或 POST /api/rescan 立即扫描,GET /api/status 观察 ingest.scanning

OCR 全部 ocr_unavailable

未安装 tesseract 且(非 macOS 或无 swiftc);属预期降级,图片仍会建立索引记录

索引疑似损坏

重启服务即可:加载器容忍坏行并记录,自检会定位并单文件重建

端口被占用

换 server.port;服务只能绑定回环地址,非回环会在启动时被拒绝

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. 文档与社区

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

Available Tools

3 tools
localgate_get_documentB

Fetch one indexed document's metadata and chunk texts by doc_id.

ParametersJSON Schema
NameRequiredDescriptionDefault
doc_idYes

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden of behavioral disclosure. "Fetch" implies a read-only operation and the return contents are mentioned (metadata and chunk texts), but there is no explicit statement about side effects, permissions, rate limits, pagination, or error behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence with no filler; the core action, resource, return content, and key parameter are front-loaded efficiently.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter read tool with no output schema and no annotations, the description covers the basic purpose and the returned fields. However, it omits sibling-routing guidance and parameter format details, leaving some gaps for an agent choosing between document retrieval and search.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for the single undocumented parameter. Saying "by doc_id" identifies the parameter's role as the document identifier, but it adds no format, matching rules, or example beyond the parameter name itself.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ("Fetch") and resource ("one indexed document's metadata and chunk texts") with a clear scope ("by doc_id"). This distinguishes it clearly from sibling tools localgate_search and localgate_status without needing to open the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given about when to use this tool instead of localgate_search or localgate_status, nor about prerequisites or exclusions. The description only states what it does, leaving usage inference to the agent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

localgate_statusA

Index health: doc/chunk counts, self-check status, whitelist.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It does disclose what the call surfaces (counts, self-check status, whitelist), which is meaningful for a zero-parameter tool, but it never states that it is a side-effect-free read or whether whitelist output is sensitive configuration data.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded fragment with no filler; the resource leads and the returned fields follow as a compact list. Nothing could be removed without losing information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description sensibly enumerates the return contents, which is the key thing an agent needs. Minor gaps remain around authentication requirements and what 'self-check status' concretely reports, but for a zero-param status call this is close to sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters and the schema confirms an empty object, so the baseline is 4. There are no arguments whose semantics could be clarified.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Names the resource (index health) and enumerates the concrete signals returned: doc/chunk counts, self-check status, whitelist. The verb is only implied by the 'status' name, but the tool is unambiguously distinct from the search and get_document siblings, which retrieve content rather than report index state.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied rather than stated: 'Index health' tells an agent this is a diagnostic/monitoring call, but there is no explicit guidance on when to reach for it versus search or get_document, and no preconditions or alternatives are named.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.1.0
    • First observedlocalgate_get_document
    • First observedlocalgate_search
    • First observedlocalgate_status
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.8/5.0

Scored across 3 tools

Disambiguation5/5

Each tool targets a distinct operation: search performs discovery, get_document retrieves full content by id, and status reports index health. There is no overlap in purpose or selection ambiguity.

Naming Consistency5/5

All tools share the same localgate_ prefix and use snake_case consistently. The verb/noun structure (search, get_document) is predictable, with only status being a natural noun exception.

Tool Count5/5

Three tools is well-scoped for a focused local search server. Each tool covers a core need—querying, retrieving, and monitoring the index—without redundant or bloated operations.

Completeness4/5

The surface covers the essential read-only lifecycle: searching, fetching a document by id, and checking index status. Minor gaps like listing available documents or triggering a reindex may exist, but agents can work around them via search.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • OmniDocs-RAG-CN

    ybhuang995-dev
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables AI agents to index and search local files, websites, GitHub repos, and packages with hybrid AI-powered retrieval, all locally through IDE chat.
    Apache 2.0

  • bigos

    FPGArtktic
    A
    license
    Not graded
    quality
    F
    maintenance
    Enables fully local, cross-lingual retrieval over documents and source code by indexing files and providing search and ingest tools, with all data staying on the machine.
    GPL 2.0

  • Keepygaga RAG

    TimWongUp
    A
    license
    A
    quality
    C
    maintenance
    Enables local-first hybrid knowledge retrieval from authorized Markdown and plain-text files, combining full-text and vector search with reranking and traceable source references via a single search tool.
    1
    MIT

  • loci-mcp

    morozov551
    F
    license
    Not graded
    quality
    A
    maintenance
    Enables AI agents and MCP hosts to search and question a local, hybrid-indexed corpus of scattered notes, docs, and chat logs, returning section-level citations rather than whole files.
    -

Appeared in Searches