AI导哈

本地语义索引工具

FolderMCP是一个本地优先的语义索引工具，可将文件夹内容转换为私有的、本地存储的语义索引，供AI助手搜索使用，所有数据均保留在用户机器上。

  • by gtm-k
  • Go
  • 本地部署
  • 更新于
在 GitHub 查看 gtm-k/foldermcp

使用说明

文件夹MCP

将任何文件夹转换为您的AI助手可以搜索的私有、本地优先语义索引——任何东西都不会离开您的机器。

将FolderMCP指向一个包含源代码、Markdown和文本文件的文件夹。它读过一次， 构建一个“搜索大脑” SQLite数据库在您自己的磁盘上，并将其提供给AI工具 （克劳德、光标、VS代码等） MCP（模型上下文协议）. 然后，您的助手可以通过以下方式找到合适的作品 意义，而不仅仅是关键字——即使 文件夹位于共享网络驱动器上，并且 无需将单个字节上传到云端.

Status v3是一个早期预览版。 今天，它进行了局部语义+关键字搜索 源代码和Markdown/文本文件，从源代码后面构建过渡 -v3 子命令。 结构化数据文件（CSV/JSON/YAML）、PDF/Office文本和图像 尚未编入索引，以及 没有实时文件监视器——全部在 路线图 在......下面原版 v0.1.0 MCP 工具服务器 --将函数和脚本文件夹转换为可调用的MCP工具——仍然 可用并记录在案 再往下.

运作原理

FolderMCP是一个 拆分守护进程 设计：重型 索引器 它写入索引， 只读 查询服务器 这回答了搜索。他们从不互相阻碍，他们共享一个 SQLite数据库。

flowchart TB
    FOLDER[Your folder<br/>local disk or NAS]
    subgraph CORE [FolderMCP core · runs on your machine]
      direction TB
      IDX[index-v3<br/>indexer · writes<br/>walk → chunk → embed]
      QRY[serve-v3<br/>query server · read-only<br/>hybrid search]
      STORE[(index.db · one SQLite database<br/>metadata · FTS5 keywords<br/>sqlite-vec vectors · pipeline state)]
      IDX -->|writes| STORE
      QRY -->|reads| STORE
    end
    SHIM[mcp-v3<br/>MCP stdio shim<br/>launched per session]
    AI[AI client<br/>Claude · Cursor · VS Code]
    FOLDER --> IDX
    AI <-->|MCP protocol| SHIM
    SHIM <-->|gRPC over Unix socket / Windows named pipe| QRY

索引器和查询服务器是分开的，因此长时间的索引运行永远不会阻止交互式搜索， 查询服务器可以只读方式打开数据库。文本、关键字索引和意义向量都存在 一个事务性SQLite 数据库，所以没有第二个存储——没有单独的向量数据库——来保持同步。

为什么选择FolderMCP

  • 本地优先，私人优先。 每个字节都留在你的机器上。没有云帐户，没有上传，没有每次查询的成本。
  • 混合检索。 关键字（FTS5/BM25）、文件名和语义向量搜索并行运行，并与往复式排名融合相融合，比任何单个通道都更稳健。
  • 一个数据库保存了所有内容。 元数据、关键字索引和向量都存在于一个SQLite数据库中——没有单独的向量存储来保持同步，也没有服务器来运行。
  • 适用于网络驱动器。 SMB、NFS和NAS装载是一流的；重新运行索引器仅重新处理内容发生更改的文件（通过哈希进行比较）。
  • 跨平台。 原生Windows、macOS和Linux——Go，带有SQLite引擎、向量数学和嵌入运行时，编译在二进制文件中或附带在二进制文件旁边（没有Python，没有Docker）。v3现在从源代码构建；一个独立的Windows捆绑包通过以下方式发货 make v3-package-windows，计划推出完整的本地发布矩阵。
  • MCP原生。 三个工具-- search, inspect, browse --任何MCP客户端都已经理解。没有自定义集成。

快速启动（v3）

v3目前从源代码构建，需要C工具链（它链接SQLite， sqlite-vec，以及 通过cgo看树）。自给自足的预构建捆绑包是通过以下方式生产的 make v3-package-windows （Windows今天；完整的发布矩阵正在路线图上）。

# 1. Fetch the embedding model (all-MiniLM-L6-v2, ~90 MB) + tokenizer
make v3-fetch-model

# 2. Build the v3 binary (cgo + SQLite FTS5)
make v3-build                      # -> bin/foldermcp-v3

# 3. Index a folder (writes the index to $FOLDERMCP_STORE)
export FOLDERMCP_STORE=~/.foldermcp/index
./bin/foldermcp-v3 index-v3 ./my-folder

# 4. Try a search from the CLI
./bin/foldermcp-v3 search-v3 "how is config loaded?"

要从AI客户端使用它，请将客户端的MCP配置指向 foldermcp-v3 mcp-v3 （垫片 客户端每次会话启动）。为了地方发展， all-v3 <folder> 运行索引器和查询 服务器在一个进程中。使用以下命令运行任何命令 --help 为了它的旗帜。

索引管道

index-v3 通过某种方式将原始文件转换为可搜索的索引 四通管道，每次通过 一份工作。二进制和媒体文件被检测并跳过，而不是作为垃圾分块；今日特供 对文本和代码进行索引（计划提取PDF和Office文档文本）。

flowchart TB
    F[Your folder] --> P0
    subgraph PIPE [Four-pass indexing pipeline]
      direction LR
      P0[Pass 0 · Walk<br/>list files, hash,<br/>classify by content] --> P1[Pass 1 · Structure<br/>tree-sitter parses<br/>Go and Python symbols]
      P1 --> P2[Pass 2 · Chunk<br/>code-aware /<br/>prose-aware splitting]
      P2 --> P3[Pass 3 · Embed<br/>each chunk → 384-dim<br/>vector · ONNX MiniLM]
    end
    P0 -. binary / media .-> SKIP[skip · not indexed]
    P3 --> DB[(index.db<br/>text · keywords · vectors)]

嵌入模型一次只能读取一个小窗口，因此文件被拆分为 块 --代码随 功能和类边界（通过树形图），沿着标题和段落的散文。每个区块 变成384数字 向量 捕获其含义，因此对“连接池”的查询可以匹配 一个块，上面写着“重用套接字”，没有共享单词。索引是 增量和可恢复：文件 被散列，只有更改的文件会被重新处理，中断的运行会从检查点恢复。

搜索

一个问题在人群中蔓延开来 三个独立频道 并将其与 互惠排名融合 （RRF） 进入一个排名列表。RRF对每个结果进行评分 等级 在每个频道，所以一个文件几个 通道排名从高到高，不需要分数校准（BM25分数和向量 距离没有可比性，但它们的排名是可比的）。

flowchart LR
    Q["Query<br/>(MCP search · inspect · browse,<br/>or search-v3)"] --> K[Keyword · FTS5 BM25<br/>exact words]
    Q --> N[Filename<br/>path-text match]
    Q --> V[Vector · sqlite-vec<br/>meaning match]
    K --> R{{RRF fusion}}
    N --> R
    V --> R
    R --> OUT[One ranked list<br/>files + snippets]

每个频道都对其他频道的内容视而不见：关键字搜索可以确定确切的术语和名称、文件名 match会找到明显的文件，矢量搜索会捕获释义。 search-v3 --mode 强迫一个人 频道(lexical, semantic, filename)或混合所有这些(auto，默认值）。

v3 CLI参考

命令 描述
foldermcp index-v3 [workspace] 在文件夹上运行索引器守护程序（cgo-build）。
foldermcp all-v3 [workspace] 在一个进程（本地开发）中运行indexer+gRPC查询服务器。
foldermcp serve-v3 对现有索引运行只读gRPC查询服务器。
foldermcp mcp-v3 运行MCP stdio垫片（由您的AI客户端在每个会话中启动）。
foldermcp search-v3 <query> 搜索索引（混合词汇+语义）并打印排名匹配项。
foldermcp auth-v3 init | rotate 生成/轮换gRPC身份验证令牌和自签名TLS证书。

环境： FOLDERMCP_STORE （索引所在的位置）， FOLDERMCP_MODEL_DIR （嵌入模型 目录）， FOLDERMCP_ORT_LIB （ONNX运行库）。一个自包含的包解析了模型和 运行时位于二进制文件旁边，因此这些是可选的。

堆栈

图层 选择 为什么
语言 走 每个操作系统一个静态二进制文件；易于分配；并行搜索通道具有良好的并发性。
CLI 眼镜蛇 清洁子命令和标志处理。
存储+词汇 SQLite+FTS5 一个完整的SQL数据库进程内，零服务器；FTS5提供BM25关键字搜索。
矢量索引 sqlite-vc 存储384个暗矢量 在同一SQLite数据库中 具有精确的KNN，因此没有单独的向量存储来保持同步。
嵌入件 ONNX运行时+全MiniLM-L6-v2 一个小型（约90 MB）模型在本地运行；文本→ 指没有云API的向量。
代码解析 树保姆 真正的语法树（今天的Go和Python），因此块与函数和类对齐。
运输 Unix套接字/命名管道上的gRPC 填充程序和查询服务器之间的快速、键入的本地IPC；按操作系统抽象。
AI接口 主控程序 标准的Claude、Cursor和VS Code已经说明了这一点——三个工具，即时兼容性。

统一的主线：每个选择同时保护四个属性-- 单店, 不 服务器/云, 在网络驱动器上工作，以及 私人的.

v0.1.0-MCP工具服务器

最初的FolderMCP将一个代码文件夹转换为可调用的 MCP工具：插入一个Python函数， TypeScript导出、OpenAPI规范或shell脚本，它成为一个工具；PDF、图像和CSV成为 MCP资源。默认情况下，它是安全的——每个工具都会启动 pending 默认情况下拒绝权限， 执行被沙盒化，有超时、输出限制和秘密编辑。

foldermcp init ./my-tools        # initialize a workspace
foldermcp review --approve-all   # review & approve discovered tools
foldermcp connect claude-desktop # wire into your AI client
foldermcp serve                  # start the MCP server
格式 扩展名 发现为
python .py 带有类型提示的函数→ 工具
Types/JS .ts, .js, .mjs, .cjs 导出函数→ 工具
OpenAPI .yaml, .json API操作→ 工具
壳牌 .sh, .bash 脚本包装器→ 工具
文档/图像 .pdf, .md, .txt, .csv, .png, .jpg, .svg MCP资源

关键命令： init, review, serve, connect, catalog, status, test, diff, doctor, deploy, export, logs, ui, completion所有人都支持 --json 全球旗帜。跑 foldermcp <command> --help 对于旗帜，以及 foldermcp ui 用于本地Developer Studio仪表板。

安全

FolderMCP遵循默认拒绝模式。对于v0.1工具服务器，每个工具都会启动 pending 和 必须得到明确批准；执行在具有超时和输出的隔离子流程中进行沙盒处理 限制；扫描输出以编辑AWS密钥、GitHub令牌、API密钥和私钥；每 调用记录在结构化审计日志中。v3索引器是只读的 文件，从不执行它们。看 安全.md 查看完整模型以及如何报告 脆弱性。

项目结构

cmd/foldermcp/       CLI entry point (v0.1 commands + the -v3 subcommands)
internal/
  v3/                v3 semantic-retrieval engine
    walker/          file enumeration, hashing, content classification
    chunker/         code-aware (tree-sitter) + recursive prose chunking
    embed/           ONNX embedding, BERT tokenizer, int8 quantization
    store/           SQLite schema, FTS5, sqlite-vec, migrations, fingerprint
    pipeline/        four-pass indexer orchestration
    grpc/            query server (search, inspect, browse) + admin
    mcp/             MCP stdio shim and tool routing
    transport/       Unix socket / Windows named pipe IPC
  audit/ cache/ config/ deps/ introspect/ lifecycle/ pythonrt/
  sandbox/ server/ state/ studio/ watcher/ workspace/   (v0.1 tool server)
examples/            sample projects (Python, OpenAPI, Shell)

路线图

v3是一个专注于代码和文本的早期预览版。下一步计划，按大致的优先级顺序：

  • 索引结构化数据文件 — .csv, .json, .yaml, .xml （目前被归类为数据并跳过）。
  • PDF和Office文本提取 --为内部文本建立索引 .pdf, .docx，以及 .odt （目前已跳过）。
  • 更多具有AST结构的语言 --Go和Python之外的树型语法（今天其他语法索引为散文）。
  • 新鲜生活 --一个自动为更改的文件重新索引的文件监视器（今天的重新索引是手动重新运行）。
  • 单命令客户端设置 --为v3编写MCP客户端配置，如下所示 connect 适用于v0.1.0。
  • 图像搜索 --视觉嵌入，使图像在自己的空间中变得可搜索。
  • 预构建捆绑包 --本地macOS和Linux版本（Windows捆绑包今天通过 make v3-package-windows).

贡献

欢迎捐款。请在提交之前打开一个问题来讨论非琐碎的更改 pull请求。

  1. 分叉存储库。
  2. 从以下位置创建要素分支 main.
  3. 添加新功能的测试。
  4. 跑 make test 和 make lint （或 make v3-test / make v3-lint 对于v3工作），然后提交。
  5. 打开一个包含更改清晰描述的拉取请求。

看 贡献.md 获取完整指南。

许可证

Apache许可证2.0

相关 MCP