链接文档系统
一个生产就绪的RAG系统，配备双接口：REST API + MCP协议\ 使Web应用程序和AI助手能够利用混合语义+关键词搜索技术，智能地搜索和引用文档。
🎯 这是什么？
这是一个 完整的RAG（检索增强生成）系统 这提供了两种访问强大文档搜索功能的方式：
- REST API服务器 (
main.py) - 基于FastAPI的HTTP服务器，用于Web应用程序和集成 - MCP 服务器 （
mcp_server.py) - 人工智能助手（Cursor、Claude Desktop）的模型上下文协议服务器
两台服务器共享同一个混合搜索引擎，无论您是在构建网络应用还是增强人工智能助手的功能，都能实现精准的文档检索。
主要特点
- 智能混合搜索结合语义理解（FAISS嵌入）与关键词匹配（BM25）
- 智能排名标题/元数据增强，多段文档扩展，相关性评分
- 多格式支持PDF、Markdown 和网页文档（通过内置抓取器）
- MCP Native（MCP本地/原生）在Cursor、Claude Desktop以及其他MCP兼容工具中无缝工作
- 企业级就绪访问控制、审计日志、本地优先架构
- 快200毫秒以下的搜索延迟，优化的分块和索引
- 零成本完全本地运行，无需API密钥或云依赖
🏗️ 工作原理
┌─────────────────────────────────────────────────────────┐
│ AI Assistant (Cursor/Claude) │
└────────────────────┬────────────────────────────────────┘
│ MCP Protocol (JSON-RPC over stdio)
▼
┌─────────────────────────────────────────────────────────┐
│ mcp_server.py │
│ ┌─────────────────────────────────────────────────┐ │
│ │ Tools: search_documentation(), list_sources() │ │
│ └─────────────────────────────────────────────────┘ │
└────────────────────┬────────────────────────────────────┘
│
┌────────────────┼────────────────┐
▼ ▼ ▼
┌─────────┐ ┌──────────┐ ┌──────────────┐
│ Hybrid │ │ Access │ │ Audit Logger │
│ Search │ │ Control │ │ │
└────┬────┘ └──────────┘ └──────────────┘
│
├─ Semantic Search (FAISS + embeddings)
│ • Title/metadata boosting
│ • Multi-chunk document expansion
│
└─ Keyword Search (BM25)
• Exact term matching
• Traditional ranking项目结构
LinkedDocsMCP/
├── mcp_server.py # Main MCP server (stdio interface)
├── main.py # FastAPI server (for testing/debugging)
├── download_docs.py # Web documentation scraper CLI
├── connectors/ # Document format handlers
│ ├── pdf.py # PDF extraction
│ └── markdown.py # Markdown parsing
├── indexing/ # Search engine core
│ ├── chunker.py # Semantic text chunking
│ ├── embedder.py # Sentence transformers
│ ├── vector_store.py # FAISS vector database
│ ├── keyword_search.py # BM25 implementation
│ └── hybrid_search.py # Combined search with boosting
├── schemas/ # Data models
│ ├── config.py # Settings & configuration
│ └── document.py # Document schemas
├── core/ # Cross-cutting concerns
│ ├── access_control.py # Permission system
│ └── audit.py # Query logging
└── data/ # Local storage
├── sources/ # Your documents (PDF, MD)
└── vector_store/ # Indexed vectors & metadata🚀 快速入门（5分钟）
先决条件
- Python 3.10及以上版本
- Cursor 或 Claude Desktop（用于MCP集成）
1. 安装依赖项
pip install -r requirements.txt首次运行下载约80MB的嵌入模型（一次性）
2. 添加文档
选项A：从网页下载
# Download Factorio wiki (example)
python download_docs.py https://wiki.factorio.com/Tutorials --crawl --max 20选项B：添加您自己的文件
# Copy PDFs or Markdown files
copy your-docs.pdf data/sources/
copy your-guide.md data/sources/3. 在Cursor（或其他LLM服务）中设置MCP
添加到你的 Cursor MCP 配置中（~/.cursor/mcp.json 或者 C:\Users\\.cursor\mcp.json):
{
"mcpServers": {
"linked-docs": {
"command": "python",
"args": ["C:/full/path/to/LinkedDocsMCP/mcp_server.py"]
}
}
}4. 重启光标并使用！
在Cursor的聊天中：
What are the different enemy types in Factorio?该人工智能将自动搜索您的文档，并提供准确且有引用来源的答案！ ✨
关键特性解析
混合搜索
结合了两种互补的方法：
语义搜索（权重70%）
- 用途
sentence-transformers（全MiniLM-L6-v2模型） - 理解含义：“认证设置”与“配置认证”意思相同
- 将文本转换为384维向量
- 使用FAISS进行快速相似度搜索
关键词搜索（权重30%）
- 使用BM25算法（与Elasticsearch相同）
- 精确术语匹配：非常适合技术术语、代码等。
- 传统的排名方法，采用文档长度归一化
智能排名增强功能：
- 标题优化标题与查询匹配的文档获得3倍加权
- 多块扩展从高度相关的文档中返回最多3个连续的片段
- 文档分组按来源文档分组的结果，以便更好地理解上下文
语义分块
与简单的字符拆分不同，这种方法使用了智能边界：
- Markdown 标题 (
##，###- 保持各部分在一起 - 段落分隔 （
\n\n) - 保持主题连贯性 - 句子 - 用于非结构化文本的备用方案
设置：
- 块大小：2048个字符（完整段落，非片段）
- 重叠：200个字符（防止边界处上下文丢失）
网页文档抓取器
内置工具，用于下载和转换网页文档：
# Download single page
python download_docs.py https://wiki.example.com/Guide
# Crawl multiple pages (with smart duplicate detection)
python download_docs.py https://wiki.example.com/Main --crawl --max 50
# Force re-download (skip existing detection)
python download_docs.py https://wiki.example.com/Main --crawl --force
# Filter by language
python download_docs.py https://wiki.example.com/Main --crawl --languages en,de特点：
- 自动检测并跳过已存在的页面（节省时间与带宽）
- 尊重同源策略和链接模式
- 礼貌爬取，支持配置延迟
- 将HTML转换为带有元数据的简洁Markdown
- 保留文档结构（标题、列表、表格）
🔒 安全与访问控制
内置功能：
- 四层访问权限等级：公开 → 内部 → 限制 → 机密
- 基于用户权限的查询时过滤
- 全面审计日志记录（追踪每个查询）
- 仅本地处理（数据不会离开您的机器）
审计日志 (data/audit.log)：
{
"timestamp": "2025-10-21T14:30:00Z",
"event_type": "search",
"user_id": "mcp_client",
"query": "enemy types",
"results_count": 5,
"search_time_ms": 143
}⚙️ 配置
编辑 schemas/config.py 或者设置环境变量：
# Search weights
SEMANTIC_WEIGHT = 0.7 # Meaning-based search
KEYWORD_WEIGHT = 0.3 # Exact term matching
# Chunking
CHUNK_SIZE = 1280 # Larger chunks for complete sections
CHUNK_OVERLAP = 128 # Overlap for context continuity
# Model
EMBEDDING_MODEL = "all-MiniLM-L6-v2" # Fast, accurate, small🔧 高级用法
REST API（用于测试/调试）
# Start FastAPI server
python main.py
# Search via REST
curl -X POST http://localhost:8000/api/v1/search_docs \
-H "Content-Type: application/json" \
-d '{"query": "getting started", "top_k": 5}'
# Interactive API docs
open http://localhost:8000/docs程序化使用
from indexing.embedder import Embedder
from indexing.vector_store import VectorStore
from indexing.hybrid_search import HybridSearchEngine
# Initialize
embedder = Embedder(model_name="all-MiniLM-L6-v2")
vector_store = VectorStore(embedding_dim=384)
search_engine = HybridSearchEngine(vector_store, keyword_searcher, embedder)
# Search
results = search_engine.search("how to configure auth", top_k=5)
for chunk, score in results:
print(f"{score:.3f}: {chunk.text[:100]}...")技术亮点
- 混合搜索 优于仅使用纯语义或单独关键词的方法
- 智能分块 保持文档结构
- 标题提升 显著提升排名质量
- 多块扩展 提供完整上下文
- 无云依赖 - 以隐私为先的架构
- MCP 原生（或 MCP 原装） - 与任何兼容的AI助手协同工作
🙏 致谢
构建于：
- FastAPI - 现代Python网络框架
- 句子变换器（或句子表示模型） - 语义嵌入
- FAISS（快速应用索引库） - 向量相似度搜索
- BM25 (rank-bm25) - 关键词排名
- MCP（Minimum Change Perception） - 由Anthropic提出的模型上下文协议
______________________________________________________________________
状态✅ 已准备好演示 | 版本1.0.0 | 已更新2025年10月