MCP Vector Search

mcp矢量搜索

通过MCP对您的文档进行语义搜索，可供AI代理使用。

使用语义嵌入对文档、代码和知识库进行索引。AI助手可以按需搜索，而无需将所有内容加载到上下文中。

;; .mcp-vector-search/config.edn
{:sources [{:path "/docs/**/*.md"}]}

# Search from Claude Code
"Find authentication documentation"
→ Returns relevant docs based on semantic similarity

快速链接: 快速开始 · 安装 · 什么和为什么 · 高级功能

______________________________________________________________________

目录

• 快速开始
• 什么和为什么
• 安装
• 基本配置
• 使用搜索工具
• Claude代码插件
• 高级功能
• 发展
• 文档

快速开始

1.安装MCP服务器 （需要Clojure CLI工具）：

# Add to ~/.clojure/deps.edn
{:aliases
 {:mcp-vector-search
  {:replace-paths []
   :replace-deps {org.hugoduncan/mcp-vector-search
                  {:git/url "https://github.com/hugoduncan/mcp-vector-search"
                   :git/sha "LATEST_SHA_HERE"}
                  org.clojure/clojure {:mvn/version "1.12.3"}}
   :jvm-opts ["--enable-native-access=ALL-UNNAMED"]
   :exec-fn mcp-vector-search.main/start}}}

# Configure Claude Code
claude mcp add mcp-vector-search -- $(which clojure) -X:mcp-vector-search

2.创建配置文件 在 ~/.mcp-vector-search/config.edn 或 .mcp-vector-search/config.edn:

{:sources [{:path "/path/to/your/docs/**/*.md"}]}

3.重新启动克劳德代码 -搜索工具现在可用。

4.从克劳德代码搜索:

"Search for authentication best practices"
"Find code examples for user validation"
"Show me documentation about API rate limiting"

助手将使用搜索工具在语义上查找相关内容，而无需将所有文档加载到上下文中。

什么和为什么

它做什么

mcp矢量搜索是一个mcp服务器，它：

• 索引文档 使用语义嵌入（AllMiniLmL6V2模型）
• 提供搜索工具 通过模型上下文协议连接到AI助手
• 启用语义搜索 -按含义查找内容，而不仅仅是关键字
• 按元数据筛选 -将搜索范围缩小到特定项目、类别或文件类型
• 像图书馆一样工作 -使用捆绑文档嵌入到您自己的MCP服务器中

为什么使用它

扩展可访问的内容，而不是加载的内容。 AI代理的上下文窗口有限。他们不会预先加载所有文档，而是在需要时进行搜索。

主要优势:

• 使用比上下文窗口更大的知识库
• 通过语义相似性发现相关内容
• 及时检索信息，而不是猜测
• 搜索工具不使用上下文，只使用结果

何时使用:

• 大型文档集（数百页）
• 多项目代码库（跨项目查找模式）
• 历史背景（设计文档、决策日志）
• API引用（根据需要查找函数和示例）
• 需要对捆绑文档进行语义搜索的自定义MCP服务器

看 doc/about.md 详细解释问题和解决方案。

图书馆使用情况：mcp矢量搜索可以嵌入到您自己的mcp服务器中，以在捆绑的资源上提供语义搜索。看 doc/library-usage.md 了解详情。

安装

先决条件

• Clojure命令行界面工具
• Java 11+（嵌入模型所需）

配置Clojure别名

添加到 ~/.clojure/deps.edn:

{:aliases
 {:mcp-vector-search
  {:replace-paths []
   :replace-deps {org.hugoduncan/mcp-vector-search
                  {:git/url "https://github.com/hugoduncan/mcp-vector-search"
                   :git/sha "LATEST_SHA_HERE"}
                  org.clojure/clojure {:mvn/version "1.12.3"}}
   :jvm-opts ["--enable-native-access=ALL-UNNAMED"]
   :exec-fn mcp-vector-search.main/start}}}

备注：替换 LATEST_SHA_HERE 使用此存储库中的最新提交SHA。

添加到MCP客户端

克劳德代码：

claude mcp add mcp-vector-search -- $(which clojure) -X:mcp-vector-search

Claude Desktop、Cline和其他MCP客户端： 看 doc/install.md 有关设置说明和故障排除。

基本配置

配置文件位置（使用第一个找到的位置）：

• .mcp-vector-search/config.edn （项目特定）
• ~/.mcp-vector-search/config.edn （全球）

最小示例

{:sources [{:path "/docs/**/*.md"}]}

递归索引下的所有markdown文件 /docs/.

路径模式和元数据

路径规格支持globs(*, **)、正则表达式捕获和自定义元数据：

;; Basic: recursive glob
{:sources [{:path "/docs/**/*.md"}]}

;; With capture and metadata
{:sources [{:path "/docs/(?[^/]+)/*.md"
            :project "myapp"
            :type "documentation"}]}
;; File /docs/api/auth.md gets metadata:
;; {:project "myapp", :type "documentation", :category "api"}

除以下以外的任何配置键 :path, :name, :ingest，以及 :watch? 成为元数据。看 doc/path-spec.md 和 doc/using.md 查看完整的语法和示例。

使用搜索工具

只需让AI助手查找信息：

"Find documentation about rate limiting"
"Search for API documentation in the admin category"
"Show me code examples of input validation"

助手自动使用语义搜索。搜索可以按元数据（例如类别、项目、类型）进行过滤。

刀具参数：

• query （必填）：搜索文本
• limit （可选）：最大结果（默认值：10）
• metadata （可选）：按键值对过滤（AND逻辑）

Claude代码插件

有两种克劳德代码技能可用于指导配置和库集成：

安装插件

将mcp矢量搜索市场添加到Claude Code中：

/plugin marketplace add hugoduncan/mcp-vector-search

然后安装这两个插件：

/plugin install config-guide@mcp-vector-search-plugins
/plugin install embed-guide@mcp-vector-search-plugins

或者从本地克隆安装市场：

# From the mcp-vector-search directory
/plugin marketplace add ./

可用插件

配置指南 -互动式写作指南 .mcp-vector-search/config.edn 文件夹：

• 路径规范（文件系统/类路径、globs、捕获）
• 摄取策略（整个文档、名称空间文档、代码分析、分块、文件路径）
• 元数据抽取
• 文件监视设置

用途： /config-guide 克劳德代码

嵌入指南 -将mcp矢量搜索嵌入库的交互式指南：

• 添加依赖关系
• 资源绑定
• 类路径与文件系统源
• 使用构建脚本打包JAR

用途： /embed-guide 克劳德代码

这两种技能都提供了全面的互动指导，包括示例和最佳实践。

高级功能

摄入策略

控制文档的处理、嵌入和存储方式：

• :whole-document （默认）-嵌入并存储完整的文件内容
• :namespace-doc -嵌入Clojure命名空间文档字符串，返回完整源代码
• :file-path -嵌入内容，但仅存储文件路径（节省内存）
• :code-analysis -分析代码结构，为每个元素（函数、类等）创建段
• :chunked -将大型文档拆分为较小的段

{:sources [{:path "/src/**/*.clj"
            :ingest :namespace-doc}]}

文件监视

文件更改时自动重新索引：

{:watch? true
 :sources [{:path "/docs/**/*.md"}]}

自定义工具说明

为AI助手自定义搜索工具描述：

{:description "Search internal API documentation and code examples"
 :sources [{:path "/docs/**/*.md"}]}

有关完整的配置详细信息，包括策略选项、高级路径模式、元数据过滤和故障排除，请参阅 doc/using.md.

发展

设置

git clone https://github.com/hugoduncan/mcp-vector-search
cd mcp-vector-search

本地运行

# Start server with default config (~/.mcp-vector-search/config.edn)
clojure -X:run

# Use custom config
clojure -X:run :config-path '"/path/to/config.edn"'

测试

# Run all tests
clojure -M:test

# Run specific namespace
clojure -M:test --focus mcp-vector-search.config-test

REPL开发

(require 'clojure.repl.deps)
(clojure.repl.deps/sync-deps)

项目结构

• main.clj -服务器启动和协调
• config.clj -配置解析和路径规范处理
• ingest.clj -文件匹配、嵌入和存储（使用策略多方法）
• tools.clj -MCP搜索工具定义
• lifecycle.clj -系统生命周期管理
• server.clj -MCP协议实现

贡献

欢迎投稿！拜托：

1. 在提交PR之前运行测试
2. 遵循现有代码样式
3. 为新功能添加测试
4. 更新文档

释放

看 doc/releasing.md 发布过程和版本方案。

文档

• doc/about.md -项目目的、问题/解决方案、用例
• doc/install.md -各种MCP客户端的详细安装
• doc/using.md -完整的配置参考、策略、故障排除
• doc/library-usage.md -在自定义mcp服务器中使用mcp矢量搜索作为库
• doc/path-spec.md -形式化路径规范语法和语法
• CLAUDE.md -具有架构细节的开发人员/AI助理技术参考

许可证

版权所有©2025雨果·邓肯

在Eclipse公共许可证2.0下分发。