AI导哈

语义搜索服务器

Smart Search MCP Server是一个为Obsidian vaults提供语义搜索功能的服务器，通过预计算的嵌入向量实现基于含义的笔记搜索，无需运行Obsidian。

  • by ekmungi
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 ekmungi/smart-search-mcp

使用说明

智能搜索MCP服务器

黑曜石拱顶的语义搜索 克劳德代码。按含义查找注释，而不仅仅是关键字。

基于预先计算 智能连接 嵌入——确实如此 不 要求黑曜石正在运行。

运作原理

"What did we discuss in out last brainstorming session?"
        |
        v
  [bge-micro-v2]  Encode query -> 384-dim vector (ONNX, local)
        |
        v
  [AJSON Parser]  Load pre-computed note embeddings from .smart-env/
        |
        v
  [Cosine Sim]   Compare query vector vs. all stored vectors
        |
        v
  [Results]      Ranked note paths + similarity scores

服务器读取 .smart-env/multi/*.ajson Smart Connections在vault中生成的文件。查询编码使用相同的模型(TaylorAI/bge-micro-v2)因此向量空间匹配。

先决条件

  • Node.js >= 18
  • 克劳德代码 已安装CLI
  • 一 黑曜石拱顶 随着 智能连接 安装插件并生成嵌入（查找 .smart-env/multi/ vault中的文件夹）

快速开始

窗户：

git clone https://github.com/ekmungi/smart-search-mcp.git
cd smart-search-mcp
setup.bat                              REM auto-detects vault path
setup.bat C:\path\to\your\vault        REM or specify explicitly

macOS/Linux：

git clone https://github.com/ekmungi/smart-search-mcp.git
cd smart-search-mcp
./setup.sh                        # auto-detects vault path
./setup.sh /path/to/your/vault    # or specify explicitly

这两个脚本都安装依赖项，找到您的保管库，并使用Claude Code注册MCP服务器。

手动设置 （如果你愿意的话）：

npm install
claude mcp add -s user smart-search \
  -e OBSIDIAN_VAULT_PATH="/path/to/your/vault" \
  -- node /absolute/path/to/src/server.js

通过以下方式进行验证：

claude mcp list
# Should show: smart-search: ... - Connected

MCP工具

注册后，Claude Code会话中有四个工具可用：

工具 目的 关键参数
semantic_search 按含义查找注释 query （字符串）， limit （默认值10）， threshold （默认值0.3）， type （“源”或“块”）， folder （字符串）
find_related 查找与给定注释类似的注释 note_path （字符串）， limit （默认值10）， type （“源”或“块”）
vault_stats 检查嵌入健康状况 无
read_note 按路径读取笔记内容 note_path （字符串）

过滤参数：

  • type：筛选结果以记录级别条目("source")或航向水平块("block").省略返回两者。
  • folder：限制 semantic_search 到vault子文件夹（例如。 "Projects/").不区分大小写的前缀匹配。

示例用法（克劳德代码）

> Search my vault for notes about project planning

Claude uses semantic_search("project planning") and returns:
  01 PROJECTS/App_Redesign/Planning_Notes.md  (score: 0.847)
  02 REFERENCE/Agile_Sprint_Templates.md      (score: 0.723)
  00 INBOX/Meeting_Notes_Q1_Kickoff.md        (score: 0.681)

> Read that first note

Claude uses read_note("PROJECTS/App_Redesign/Planning_Notes.md") and returns
the full Markdown content of the note (truncated at 10,000 chars if needed).

分数解释

分数范围 含义
0.7-1.0 强匹配
0.5-0.7 中等匹配
0.3--0.5 弱匹配（默认阈值包括在内）
低于0.3 已过滤掉

建筑

src/
  server.js          MCP server entry point, tool registration
  search.js          Orchestrator: semantic search, find related, stats
  reader.js          Note reader: path extraction, safety validation, file reading
  ajson-parser.js    Parse Smart Connections .ajson embedding files
  embedder.js        Query encoding via @huggingface/transformers (ONNX)
  similarity.js      Cosine similarity computation
tests/
  server.test.js     18 tests
  search.test.js     35 tests
  reader.test.js     17 tests
  ajson-parser.test.js  18 tests
  embedder.test.js   13 tests
  similarity.test.js 15 tests

总共116个测试，91%的代码覆盖率。

发展

npm test                # Run all tests
npm run test:watch      # Watch mode
npm run test:coverage   # Coverage report

嵌入器测试在第一次运行时下载bge-micro-v2模型（约23 MB）。后续运行使用缓存的模型。

依赖项

包装 用途
@拥抱面/变压器 查询编码的ONNX模型推理
@模型上下文协议/sdk MCP服务器协议
黄道带 工具参数的模式验证

智能连接嵌入的工作原理

这 智能连接 黑曜石插件会预先计算保险库中每个音符和标题的嵌入。它将它们存储为 .ajson 文件在 .smart-env/multi/ （每张纸币一个文件）。每个文件包含：

  • 源条目 (smart_sources:)：整个音符嵌入一个
  • 阻止条目 (smart_blocks:)：每个标题部分嵌入一个

此服务器直接读取这些文件，因此Obsidian不需要运行。但是，如果您添加或编辑笔记，则需要打开一次Obsidian，以便Smart Connections可以重新索引。

许可证

麻省理工学院

相关 MCP