项目简介

这是一个利用DuckDB数据库实现混合搜索（全文本搜索FTS + 向量搜索VSS）的工具。它可以对内部Markdown文档进行高效索引，并通过Model Context Protocol (MCP) 作为标准I/O服务器暴露搜索功能，供AI编程代理（如VS Code或Cursor中的LLM客户端）调用，从而增强AI代理对本地文档上下文的感知能力。

主要功能点

高级文档分割和索引： 能够处理Markdown文档，进行智能分割和构建索引。
混合搜索： 结合全文本搜索和向量搜索的优势，提高搜索准确性。
支持日语： 内置日语形态学分析，优化对日语文档的搜索精度。
结果重排： 使用CrossEncoder模型对初步搜索结果进行重新排序，提升相关性。
MCP服务器集成： 提供标准I/O (stdio) 的MCP接口，方便与兼容的AI代理直接集成。

安装步骤

最推荐的方式是使用Docker镜像：

拉取最新的Docker镜像：

docker pull ghcr.io/upamune/duckdb-hybrid-doc-search:latest

（可选）创建索引：您需要先为您的文档创建索引数据库文件。这通常通过运行'index'命令完成。例如，索引'/path/to/docs'目录下的文档并保存到'/path/to/output/index.duckdb'：

docker run -v /path/to/docs:/docs -v /path/to/output:/output \
    ghcr.io/upamune/duckdb-hybrid-doc-search:latest \
    index /docs --db /output/index.duckdb --embedding-model cl-nagoya/ruri-v3-310m

您也可以选择使用预构建好索引的Docker镜像。

服务器配置（供MCP客户端使用）

本工具作为MCP标准I/O服务器运行。要让兼容的MCP客户端（如VS Code或Cursor）连接并使用它，您需要在客户端的MCP配置文件（通常是'.vscode/mcp.json' 或 'mcp.json'）中添加服务器配置。

配置信息通常是JSON格式，包含服务器名称、描述以及连接详细信息。其中，连接类型('type')必须设置为'stdio'，而关键在于指定服务器的启动命令('command')及其参数('args')。

以下是基于Docker运行服务器的典型配置参数说明：

服务器名称 (name): 给服务器起一个用户友好的名称，例如 "DuckDB Hybrid Doc Search"。
服务器描述 (description): 简要说明服务器功能，例如 "Document search server for Markdown files"。
连接类型 (connection.type): 必须是 "stdio"。
启动命令 (connection.command): 用于启动服务器的可执行文件路径或命令。如果使用Docker，通常是 "docker"。
命令参数 (connection.args): 传递给启动命令的参数列表。这些参数会告诉Docker如何运行容器以及容器内要执行什么命令。
- '"run"': Docker命令，表示运行一个容器。
- '"--rm"': Docker参数，表示容器停止后自动删除。
- '"-i"': Docker参数，保持标准输入流打开，这是stdio连接所必需的。
- '"-v", "${workspaceFolder}/index.duckdb:/app/index.duckdb"': Docker参数，挂载本地索引文件到容器内部的路径。'${workspaceFolder}' 是一个占位符，表示当前工作目录。'/app/index.duckdb' 是容器内程序期望的数据库路径。
- '"ghcr.io/upamune/duckdb-hybrid-doc-search:latest"': 要运行的Docker镜像名称。
- '"serve"': 容器启动后执行的命令，这是本工具用于启动MCP服务器的命令。
- '"--db", "/app/index.duckdb"': 'serve'命令的参数，指定容器内的数据库文件路径。
- '"--rerank-model", "cl-nagoya/ruri-v3-reranker-310m"': 'serve'命令的参数，指定用于重排搜索结果的模型。

基本使用方法

一旦在您的AI客户端中配置并连接了此MCP服务器，AI代理就可以通过调用服务器暴露的“工具”来执行文档搜索。您通常无需手动操作服务器的搜索命令，而是通过AI代理的界面或功能来触发。当AI代理需要查找与当前任务相关的文档上下文时，它会向此MCP服务器发送一个搜索请求（调用'search_documents'工具），服务器执行搜索并将相关的文档片段作为结果返回给AI代理，供其使用。

关键词

信息