使用说明
本地文档MCP
一个集成了MCP（模型上下文协议）的模块化语义搜索系统，用于搜索本地文档。检索增强生成（RAG）系统不仅可以让您管理用于知识检索的文档块，还可以通过MCP为AI助手提供语义搜索功能。
主要特点
| 核心能力 | 技术实现 |
|---|---|
| 文献检索 | 一个完整的索引管道，用于处理来自 docs/ 目录，将它们分块，并使用以下命令创建嵌入 奥拉玛.与 Cocoindex，它只更新已更改的部分——当用户编辑或添加新内容时，系统会检测到这些更改并选择性地更新。 |
| 矢量数据库 | 用途 Qdrant 存储用于语义搜索的文档嵌入。 |
| 检索 | 搜索服务提供具有多种策略的语义搜索功能(语义, 混合，以及 过滤的). |
| MCP集成 | The MCP服务器 将这些检索功能暴露给AI助手。 |
快速开始
安装
- 克隆并设置项目：
git clone git@github.com:nguyenchiencong/local-docs-mcp.git
cd local-docs-mcp
- 启动所需服务：
# Start Qdrant
docker run -d -p 6334:6334 -p 6333:6333 qdrant/qdrant
# Make sure Ollama is running with the embedding model
ollama pull hf.co/Qwen/Qwen3-Embedding-0.6B-GGUF:F16
# Setup postgres for cocoindex
docker compose -f <(curl -L https://raw.githubusercontent.com/cocoindex-io/cocoindex/refs/heads/main/dev/postgres.yaml) up -d
- 配置环境：
# Edit .env with your specific configuration
cp .env.example .env
# Don't forget to setup your .cocoignore file
cp .cocoignore.example .cocoignore
- 安装依赖项：
uv sync
用法
在建立索引之前，请将文档添加到“文档”文件夹中。
要为文档建立索引，请执行以下操作：
uv run python -m src.indexing.main_flow
# To run the force reindex utility
uv run python -m src.indexing.force_reindex
要启动MCP服务器，请执行以下操作：
uv run python -m src.mcp_server.server
使CLI在PATH上可用
如果你想跑步 local-docs-mcp 从任何目录：
-
Windows（PowerShell）：
setx PATH "path\to\local-docs-mcp\.venv\Scripts;$($env:Path)" -
Linux/macOS（bash/zsh）：
echo 'export PATH="/path/to/local-docs-mcp/.venv/bin:$PATH"' >> ~/.bashrc
要直接从CLI运行MCP工具（一次性调用）：
# Start the server (default behavior)
local-docs-mcp
# Run a semantic search once and exit
local-docs-mcp semantic_search --query "vector search overview" --limit 5
# Run hybrid search
local-docs-mcp hybrid_search --query "async await" --semantic-weight 0.7 --limit 5
# Run a filtered search with metadata (JSON object)
local-docs-mcp search_with_metadata_filter --query "UI tutorial" --metadata-filter '{"filename": "ui.md"}' --limit 5
# Retrieve a specific document by ID
local-docs-mcp document_retrieval --document-id "doc-123"
# Fetch collection info
local-docs-mcp get_collection_info --json
配置
系统设置
所有配置都在中管理 pyproject.toml 在...之下 [tool.local-docs] 章节：
[tool.local-docs]
# Qdrant configuration
qdrant_url = "http://localhost:6334"
qdrant_collection = "local-docs-collection"
# Ollama configuration
ollama_url = "http://localhost:11434"
ollama_model = "hf.co/Qwen/Qwen3-Embedding-0.6B-GGUF:F16"
embedding_dimension = 1024
# Document configuration
docs_directory = "docs"
supported_extensions = [".md", ".rst", ".txt"]
# Search configuration
search_limit = 10
# Chunking configuration
chunk_size = 1200
chunk_overlap = 200
# Search configuration
search_limit = 10
similarity_threshold = 0.15
search_hnsw_ef = 256
hybrid_semantic_weight = 0.85
mmr_lambda = 0.75
环境变量：用以下命令覆盖任何设置 LOCAL_DOCS_* 环境变量：
export LOCAL_DOCS_SEARCH_LIMIT=20
export LOCAL_DOCS_OLLAMA_MODEL="different-model"
MCP客户端设置
将此添加到您的MCP客户端配置中（例如，Claude Code）：
{
"mcpServers": {
"local-docs-mcp": {
"command": "uv",
"args": ["run", "--project", "/path/to/local-docs-mcp", "-m", "src.mcp_server.server"]
}
}
}
MCP工具
MCP服务器向AI助手公开以下语义搜索工具：
| 工具 | 目的 | 参数 | 示例提示 |
|---|---|---|---|
semantic_search |
对索引文档执行语义搜索。根据含义和上下文而不是确切的关键字查找内容。 | query （必填字符串）， limit （可选数字，默认值：10）， min_similarity_score （可选数字，默认值：0.0） |
“在代码库中查找有关错误处理模式的信息” |
hybrid_search |
将语义搜索与关键字匹配相结合。当确切的术语与概念意义同时重要时，这很有用。 | query （必填字符串）， semantic_weight （可选数字，默认值：0.7）， limit （可选数字，默认值：10）， min_similarity_score （可选数字，默认值：0.0） |
“搜索‘异步等待’模式和异步编程概念” |
document_retrieval |
按ID检索完整文档。当您需要搜索结果中找到的特定文档的完整上下文时，请使用此功能。 | document_id （必填字符串） |
“获取ID'doc_12345'的完整文档” |
search_with_metadata_filter |
使用元数据约束进行搜索。使用此功能可按特定文档属性缩小搜索结果的范围。 | query （必填字符串）， metadata_filter （可选对象）， limit （可选数字，默认值：10）， min_similarity_score （可选数字，默认值：0.0） |
“在文件名包含“API”的文件中搜索API文档” |
get_collection_info |
获取有关索引文档集合的信息，包括统计信息和状态。 | 无 | “显示收藏统计信息和索引状态” |
用例
文件研究：
- “什么是信号，它们在Godot中是如何工作的？”
- “查找有关角色控制器的教程”
- “解释运动体和刚体之间的区别”
问题解决：
- “如何修复‘找不到节点’错误？”
- “性能优化的最佳实践是什么？”
- “在Godot中搜索调试技术”
学习路径：
- “我是初学者，请向我展示入门内容”
- “基本GDScript之后我应该学习什么？”
- “查找有关物理的中级教程”
具体搜索：
- “显示关于动画的前5个最相关的结果”
- “仅查找有关UI设计的教程文件”
- “查找性能优化指南”
发展
运行测试
uv run pytest tests/
贡献
- 分叉存储库
- 创建要素分支
- 添加新功能的测试
- 提交拉取请求
许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
