AI导哈

语义搜索服务器

一个隐私优先的本地模型上下文协议（MCP）服务器，使AI助手能够在工作区的Markdown文档中执行最先进的语义搜索。

  • by davoodwadi-lab
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 davoodwadi-lab/semantic-search-mcp

使用说明

语义搜索MCP服务器

隐私优先的本地模型上下文协议（MCP）服务器，使AI助手能够在工作区的Markdown文档中执行最先进的语义搜索。

此服务器使用 LanceDB 用于本地向量存储和运行Python驱动的微服务 Jina Embeddeds v5 (jinaai/jina-embeddings-v5-text-small)用于极其精确的1024维文本嵌入。

建筑

  1. MCP Node.js服务器(server.ts)：您的AI助手的入口点。它公开了两个工具： sync_markdown 和 search_markdown.
  2. Python嵌入器(embedder.py)：一个轻量级的FastAPI微服务。Node.js服务器会自动生成此进程，以利用PyTorch和GPU/CPU加速进行嵌入生成。
  3. LanceDB：直接存储在工作区中的快速本地矢量数据库(.lancedb).
  4. 智能同步：实现增量差分（集合论），因此它只进行块化和嵌入 新 或 已删除 文件，在第一次运行后保持近乎即时的同步时间。批处理保证了安全的内存边界。

先决条件

您的系统上必须安装以下内容：

  • Node.js （v18+）
  • python （v3.10+）
  • 紫外线 （非常快的Python包管理器）
    • 通过以下方式安装： curl -LsSf https://astral.sh/uv/install.sh | sh （Mac/Linux）或 powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" （Windows）

安装说明

1.安装节点依赖关系

从该项目的根目录开始，运行：

npm install

2.设置Python虚拟环境

我们使用 uv 创建虚拟环境(.venv)直接在项目根目录内。Node.js服务器是硬编码的，可以查找这个确切的环境！

# 1. Create the virtual environment
uv venv

# 2. Activate it (Optional for installation, but good practice)
# Mac/Linux:
source .venv/bin/activate
# Windows:
# .venv\Scripts\activate

# 3. Install the required Python packages into the .venv
uv pip install fastapi uvicorn torch transformers einops

注意：第一次运行服务器时，它将从Hugging Face下载Jina模型（~150MB）。后续运行将立即从缓存中加载。

MCP客户端安装

要使用此服务器，您必须配置您的AI助手以执行 server.ts 文件使用 npx tsx。以下是常见客户端的配置。

1.Cline（VS代码扩展）

在Cline中打开MCP设置文件（通常通过Cline设置面板访问或位于 ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json).

将以下内容添加到您的 mcpServers 对象（确保更换 /absolute/path/to/semantic-search-mcp 使用您的实际目录路径）：

{
  "mcpServers": {
    "semantic-search-mcp": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/semantic-search-mcp/server.ts"],
      "env": {}
    }
  }
}

2.克劳德代码（Anthropic CLI）

要为Claude Code CLI全局安装服务器，请在终端中运行以下命令：

claude mcp add semantic-search-mcp npx -- tsx /absolute/path/to/semantic-search-mcp/server.ts

3.游标/VS代码原生MCP

如果您使用的是Cursor或其他原生MCP消费者，请导航到“设置”>“功能”>“MCP”（或同等产品）。 添加新服务器：

  • 名字: semantic-search-mcp
  • 类型: stdio
  • 命令: npx tsx /absolute/path/to/semantic-search-mcp/server.ts

可用工具

一旦服务器连接，AI将可以访问以下工具：

sync_markdown

重要：指示你的代理人（通过 Rules 或自定义指令）调用 sync_markdown 在第一轮。

将本地markdown文件与矢量数据库同步。

  • 行动：扫描您的工作区以查找 .md 文件，将其与LanceDB状态进行比较，将新文档拆分为块（1000个字符，200个重叠），通过Jina微服务嵌入并保存。
  • 输入：无
  • 退货：添加和删除的文件的JSON摘要。

search_markdown

对索引的markdown文档执行语义搜索。

  • 行动：嵌入您的语句，并对LanceDB执行余弦距离矢量搜索。
  • 输入:
    • statement （string，必填）：一个详细的自然语言语句或问题，捕捉到你所要查找的内容的语义含义。（人工智能代理注意：不要使用AND、OR、NOT等布尔搜索运算符。将其表述为完整的描述性句子）。
    • topK （number，可选，默认值：3）：返回多少个结果块。
  • 退货：与语句匹配的顶部块的JSON数组，以及它们的源文件路径和距离分数。

本地测试

要独立于AI代理测试服务器，您可以运行内置的MCP检查器：

npm run inspect

这将启动本地web服务器（通常 http://localhost:5173)在那里，您可以手动单击并执行工具！

相关 MCP