AI导哈

Markdown语义搜索服务器

一个本地语义搜索MCP服务器，用于Markdown文档库，可作为OpenClaw或其他MCP代理的辅助工具。

  • by eman-hc
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 eman-hc/vault-semantic-mcp

使用说明

vault语义mcp

Markdown库的本地语义搜索MCP服务器。旨在作为OpenClaw或其他启用MCP的代理的侧车。

它做什么

  • 索引 vault根目录下的markdown文件（收件箱、项目、决策、实体、内存、会话、模板）
  • 块 内容按标题排列，大部分段落细分
  • 嵌入 使用OpenAI的块 text-embedding-3-small （以JSON格式存储在SQLite v1中）
  • 搜索 将FTS5关键字搜索与余弦相似度语义搜索和基于文件夹的排名相结合
  • 相关说明 查找与给定路径类似的注释
  • 文件监视器 在文件更改时保持索引同步
  • MCP工具 通过stdio将所有内容暴露给代理

重要提示： 保险库标记文件是事实的来源。SQLite数据库只是一个派生搜索索引。如果数据库丢失，可以使用完整的重新索引进行重建。

建筑

  • 保险库根目录 → scan .md 文件→ 按标题解析正文
  • 块 → OpenAI嵌入→ 使用FTS5存储在SQLite中，用于全文
  • 搜索 → 混合FTS+语义→ 文件夹提升（内存/实体/决策>项目/会话>收件箱）
  • 主控程序 → stdio传输→ 工具调用搜索/获取/最近/相关/重新索引/状态

设置

  1. 要求： Node.js 20+

  2. 安装：

    npm install

  3. 配置： 复制 .env.example 到 .env:

    cp .env.example .env

    集 OPENAI_API_KEY 并调整路径：

    • VAULT_ROOT –vault目录（默认 ./data/vault)
    • SQLITE_PATH –索引数据库（默认 ./data/index/vault.db)

  4. 运行：

    npm run dev   # development with watch
npm run build && npm start   # production

环境变量

变量 默认值 描述
OPENAI_API_KEY （必需） 用于嵌入的OpenAI API密钥
VAULT_ROOT ./data/vault markdown vault的根目录
SQLITE_PATH ./data/index/vault.db SQLite索引数据库的路径
EMBEDDING_MODEL text-embedding-3-small OpenAI嵌入模型
TOP_K_DEFAULT 8 默认搜索结果数

MCP使用

配置您的MCP客户端（例如OpenClaw）以通过stdio运行此服务器：

{
  "mcpServers": {
    "vault": {
      "command": "node",
      "args": ["/path/to/vault-semantic-mcp/dist/index.js"],
      "env": {
        "OPENAI_API_KEY": "...",
        "VAULT_ROOT": "/path/to/vault",
        "SQLITE_PATH": "/path/to/index/vault.db"
      }
    }
  }
}

或者使用tsx进行开发：

{
  "mcpServers": {
    "vault": {
      "command": "npx",
      "args": ["tsx", "/path/to/vault-semantic-mcp/src/index.ts"],
      "env": { ... }
    }
  }
}

工具

工具 参数 描述
vault_search query, folders?, topK? 对保险库进行混合搜索
vault_get path 获取文件的完整降价
vault_recent folder?, topK? 最近索引的文档
vault_related path, topK? 与给定路径相关的注释
vault_reindex path? 重新索引一条路径或整个保险库
vault_status – 保险库根、计数、观察者状态

本地验证（测试线束）

在连接到OpenClaw之前，请在本地验证索引和检索：

种子库

回购包括以下示例注释 data/vault/ 跨项目、决策、实体、内存、会话和收件箱。根据需要添加或编辑markdown文件。

运行测试线束

# Reindex and run all evaluation queries (uses OPENAI_API_KEY)
npm run test:search

# Skip reindex, reuse existing index (faster for iterating on queries)
SKIP_REINDEX=1 npm run test:search

线束的运行方式相同 hybridSearch 被...使用 vault_search，因此结果反映了真实的MCP行为。

评估查询

查询ID 目的
exact_keyword_sqlite FTS精确术语匹配
exact_keyword_chunking FTS通用术语
semantic_memory_routing 语义：“代理应该如何存储持久知识”
embedding_cost_strategy 语义：“为什么选择OpenAI而不是本地嵌入”
file_watcher_reindex 语义：“编辑vault文件时会发生什么”
related_notes_openclaw 语义：“与语义搜索sidecar相关的注释”
decision_log_architecture 语义：“我们在哪里决定将金库文件作为真相的来源？”
fts_keyword_mcp FTS精确术语

检查什么

  • 精确匹配 （SQLite、MCP、分块）：FTS应该将这些笔记浮出水面
  • 语义匹配：不同的措辞应找到正确的注释（例如“持久知识”→ 记忆/持久知识存储）
  • 去重：结果中每个文档最多一个块
  • 文件夹排名：对于类似内容，内存/实体/决策的排名应高于收件箱
  • 代码片段：块状文本应可读且相关

仅重新索引

npm run reindex
VERBOSE=1 npm run reindex   # log each file

嵌入

  • v1使用 开放人工智能 text-embedding-3-small 并将向量存储为 JSON 在SQLite中。
  • 没有sqlite-vec或向量扩展。未来的版本可能会添加Ollama支持。

许可证

麻省理工学院

相关 MCP