语义文件搜索工具

语义文件搜索

按含义而不是关键字搜索文件。

一个本地macOS应用程序+MCP服务器，用于在文件系统上进行本地语义搜索。 完全基于Swift构建。通过MLX在Apple Silicon上运行。没有云，没有Python，没有依赖关系。

为什么？

Spotlight按名称查找文件。 grep 按精确文本查找文件。两人都不明白 意义.

语义文件搜索使用本地AI模型嵌入您的文档，然后让您按概念搜索——“移居日本”可以找到您的物流说明、住房研究和行动计划，即使它们从未提及这些确切的单词。

作为Mac应用程序独立工作，或作为 MCP服务器 因此，Claude Code和Cursor等AI编码工具也可以搜索您的文件。

特性

• 语义搜索 --按含义而非关键字查找文件
• 100%本地 --嵌入通过MLX在Apple Silicon GPU上运行，任何东西都不会离开你的机器
• 单个二进制 --原生SwiftUI应用程序，无Python，无sidecar进程，无运行时依赖关系
• MCP服务器 --Claude Code和Cursor可以通过以下方式搜索您的文件 --mcp 旗帜
• 多个模型 --在Qwen3 0.6B（本地）或Gemini Embedded 2（云）之间切换
• 智能排除 --系统模式（.git、node_modules）+自定义glob模式
• 实时索引 --一键重新索引，实时显示进度

截图

快速开始

需求

• macOS 14+与苹果硅（M1/M2/M3/M4）
• Xcode 16+（用于金属着色器编译）

构建与运行

git clone https://github.com/ryuseitaniguchi/semantic-file-search.git
cd semantic-file-search
./build.sh
open .xc-build/SemanticSearch.app

与Claude Code一起使用

claude mcp add semantic-search -- /path/to/SemanticSearch --mcp

然后在克劳德代码中：

> Use semantic_search to find files about "database architecture"
> Use refresh_index to index ~/Documents

建筑

单个Swift二进制文件——在一个进程中嵌入引擎、向量存储和UI。

SemanticSearch (one binary, two modes)
│
├── GUI mode (default)     → SwiftUI app
├── MCP mode (--mcp)       → headless stdio server for Claude Code
│
├── Core/
│   ├── SearchEngine       MLXEmbedders → Qwen3-Embedding (Apple Silicon GPU)
│   ├── Indexer            Walk dirs → chunk text → embed → store
│   ├── TextChunker        512-token recursive splitting with overlap
│   └── Config             ~/.config/semantic-file-search/config.json
│
├── MCP/
│   └── MCPServer          3 tools via modelcontextprotocol/swift-sdk
│
└── Views/                 SwiftUI (Dashboard, Search, Folders, Models, Settings)

没有Python。没有sidecar进程。组件之间没有HTTP。

MCP工具

支持的文件类型

.md .txt .py .js .ts .jsx .tsx .rs .go .java .c .cpp .h .swift .rb .php .kt .scala .sh .yaml .yml .toml .json .xml .html .css .scss .sql 以及10+以上。

运作原理

1. 将文件夹添加到索引（“已索引文件夹”屏幕或 refresh_index MCP工具）
2. 应用程序读取文本文件，将其分块为约512个令牌段
3. 每个块都使用Qwen3-embedded-0.6B在GPU上嵌入
4. 矢量存储在本地 ~/.local/share/semantic-file-search/
5. 搜索使用Accelerate vDSP余弦相似性（100K向量约10ms）

第一次运行从HuggingFace下载嵌入模型（~350MB）。

配置

配置在 ~/.config/semantic-file-search/config.json:

{
  "directories": ["~/Documents/notes", "~/projects"],
  "model": "mlx-community/Qwen3-Embedding-0.6B-4bit-DWQ",
  "user_excluded_patterns": ["*.log", "vendor/"],
  "max_file_size_mb": 10
}

技术栈

许可证

麻省理工学院