图书馆员MCP-企业RAG文献检索系统

版本: 2.0.3 状态：生产就绪

一个生产级文档搜索系统，通过具有企业级RAG（检索增强生成）功能的MCP（模型上下文协议）服务器，使LLM和人类能够访问技术文档。

特性

✅ 第一阶段（完成）：

用于Claude Desktop/Cline集成的HTTP/SSE MCP服务器
基于关键字的搜索与相关性排名
支持多种格式（.md、.txt、.docx）
通过自动索引更新实时查看文件
产品/组件层次组织

✅ 第2阶段（完成-2.0.0）：

E5-large-v2嵌入 （1024维，质量提高30-40%）
分层文档分块 （512个令牌块，128个令牌重叠）
持久矢量存储 （ChromaDB具有优化的HNSW）
两阶段重新评级 （交叉编码器，精度提高2倍）
查询嵌入缓存 （重复查询速度提高5倍）
BM25关键字搜索 （概率评分）
互易秩融合（RRF） （混合搜索优化）
语义+关键字混合搜索 （两全其美）

✅ 第2.5阶段（完成-2.0.3）：

重新排名模式 （两阶段搜索：语义检索+关键字细化）

- 过滤语义相似但上下文无关的文档 - 结合语义（70%）和关键字（30%）得分 - 可配置的候选者（默认值：50）和阈值（默认值为：0.1）

增强分块 （所有具有语义/固定策略的文件类型）

- Markdown的语义分块（基于##和###的标题） - 文本文件的固定大小分块（512个标记，128个重叠） - 句子边界保护

元数据 （标签、文档类型、时态查询的日期过滤）

- 从YAML frontmatter中提取标签（列表或逗号分隔） - 文档类型推断（6种类型：api、指南、架构、参考、自述、文档） - 时间过滤 modified_after / modified_before （ISO 8601）

✅ 电子邮件搜索操作员（完整版-2.0.4）：

Outlook/Gmail风格的查询运算符

- from:sender -按发件人筛选（部分匹配） - to:recipient -按收件人筛选（部分匹配） - cc:recipient -按CC收件人筛选（部分匹配） - subject:text -按主题行筛选 - in:folder -按电子邮件文件夹筛选（收件箱、已发送、重要等） - has:attachment -过滤带附件的电子邮件 - after:YYYY-MM-DD -按日期（之后）筛选 - before:YYYY-MM-DD -按日期（之前）筛选 - thread:id -按线程ID筛选

内联运算符解析

- 直接在搜索查询中键入运算符 - 支持引用值： subject:"Q4 Report" - 结合自由文本搜索： from:kiraly project deadline

文件夹提取

- 根据文件路径自动推断文件夹 - 支持常用文件夹：收件箱、已发送、草稿、重要等。

🔜 第三阶段（计划中）：

用于HTTP访问的REST API
面向人类用户的React web UI
高级分段级过滤

快速开始

先决条件

Python 3.10或更高版本
点
~ 2GB RAM用于RAG功能
~2GB磁盘用于矢量数据库

安装

克隆仓库

git clone 
cd librarian-mcp

创建虚拟环境

python3 -m venv venv
source venv/bin/activate  # On macOS/Linux
# venv\Scripts\activate  # On Windows

安装依赖项

cd backend
pip install -r requirements.txt

备注：首次运行将下载约1.4GB的型号：

E5-large-v2嵌入模型（~1.3GB）
交叉编码器重新排序模型（~80MB）
模型缓存在 ~/.cache/torch/sentence_transformers/

创建文档文件夹

mkdir -p docs/product-name/component-name

配置环境 （可选）

cp .env.example .env
# Edit .env to customize settings

运行服务器

cd backend
python main.py

服务器将于启动 http://127.0.0.1:3001

初始化输出:

INFO Embeddings enabled: True
INFO Search mode: hybrid
INFO Loading embedding model: intfloat/e5-large-v2
INFO Model loaded successfully. Embedding dimension: 1024
INFO Reranker model loaded successfully
INFO Hybrid search engine initialized in 'hybrid' mode (RRF)

文档结构

按此层次结构组织文档：

docs/
├── product-name/          # e.g., symphony, project-x
│   ├── component-name/    # e.g., PAM, auth, database
│   │   ├── file.md
│   │   ├── spec.docx      # Large DOCX files (200-600 pages supported)
│   │   └── notes.txt
│   └── architecture/
├── meetings/
│   └── product-name/
└── shared/               # Cross-product docs

Claude桌面集成

配置Claude桌面

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）：

{
  "mcpServers": {
    "doc-search": {
      "url": "http://127.0.0.1:3001/mcp"
    }
  }
}

重新启动克劳德桌面

验证集成

以下工具应出现在Claude的可用工具中：

search_documentation -混合搜索（语义+关键字）
get_document -检索完整文档内容
list_products -列出所有产品
list_components -列出产品的组件
get_index_status -获取索引统计信息

使用示例

基本搜索

You (to Claude): "How do I implement OAuth2 authentication?"

Claude will use semantic search to understand intent:
- Finds "OAuth implementation guide" even without exact keywords
- Returns relevant sections from 200-page DOCX files
- Understands related concepts (SSO, tokens, authorization flows)

混合搜索（最佳结果）

You: "Search for Python machine learning libraries"

Hybrid search combines:
- Keyword matching: exact terms "Python" and "machine learning"
- Semantic understanding: related concepts (NumPy, Pandas, scikit-learn)
- RRF fusion: optimal ranking from both engines

获取特定文档

You: "Show me the OAuth spec from symphony/PAM"

Claude will use get_document:
{
  "path": "symphony/PAM/oauth-spec.md"
}

列出可用产品

You: "What products do we have documentation for?"

Claude will use list_products

元数据过滤（v2.0.3）

You: "Find API documentation about authentication modified in the last 30 days"

Claude will search with metadata filters:
{
  "query": "authentication",
  "doc_type": "api",
  "modified_after": "2024-11-04"
}

Returns only API docs tagged with authentication from the last month

基于标签的搜索（v2.0.3）

You: "Show me all security-related guides"

Claude will search with tag filter:
{
  "query": "security",
  "tags": ["security", "auth", "encryption"]
}

Matches documents with YAML frontmatter:
---
tags: [security, best-practices]
---

时态查询（v2.0.3）

You: "What changed in the architecture docs this week?"

Claude will filter by date range:
{
  "query": "architecture",
  "doc_type": "architecture",
  "modified_after": "2024-11-27"
}

电子邮件搜索运算符（v2.0.4）

You: "Search for emails from kiraly about the project deadline"

Using inline operators:
{
  "query": "from:kiraly project deadline"
}

This parses to:
- Free text search: "project deadline"
- Filter: sender = "kiraly"

You: "Find emails in the important folder with attachments about budget"

Using multiple operators:
{
  "query": "in:important has:attachment budget"
}

This parses to:
- Free text search: "budget"
- Filter: folder = "important"
- Filter: has_attachments = true

You: "Search for emails from John to Alice about the Q4 Report"

Using quoted values:
{
  "query": "from:\"John Doe\" to:alice subject:\"Q4 Report\""
}

This parses to:
- Free text search: "" (empty)
- Filter: sender = "John Doe"
- Filter: recipient = "alice"
- Filter: subject_contains = "Q4 Report"

You: "Find emails from last month about security"

Using date operators:
{
  "query": "after:2024-11-01 before:2024-11-30 security"
}

建筑

搜索管道（混合模式）

User Query
    ↓
Parallel Retrieval:
├─ Keyword Engine → BM25 scoring → 30 results
└─ Semantic Engine:
       ├─ Query Embedding (e5-large-v2, cached)
       ├─ Vector Search (ChromaDB) → 50 candidates
       └─ Cross-Encoder Rerank → 30 results
    ↓
RRF Fusion: Combine 30 + 30 → top 10
    ↓
Return Results (150-200ms latency)

文档索引管道

DOCX File (300 pages)
    ↓
Parser → Enhanced Metadata (sections, headings, tables)
    ↓
Hierarchical Chunker → 200 chunks (512 tokens, 128 overlap)
    ↓
Embedding Generator (e5-large-v2, 1024d)
    ↓
Batch Insert → Persistent Vector DB (ChromaDB)
    ↓
Indexed: 200 chunks × 1024d embeddings

配置

config.json（生产设置）

{
  "system": {
    "version": "2.0.0"
  },
  "search": {
    "mode": "hybrid",
    "use_reranking": true,
    "reranker_model": "cross-encoder/ms-marco-MiniLM-L-6-v2",
    "use_rrf": true
  },
  "embeddings": {
    "enabled": true,
    "model": "intfloat/e5-large-v2",
    "dimension": 1024,
    "persist_directory": "./vector_db",
    "chunk_size": 512,
    "chunk_overlap": 128
  },
  "chunking": {
    "strategy": "hierarchical",
    "respect_boundaries": true,
    "preserve_tables": true
  },
  "cache": {
    "query_embedding_cache_size": 10000
  },
  "mcp": {
    "host": "127.0.0.1",
    "port": 3001
  }
}

搜索模式选项

混合模式（默认-最佳结果）:

{"search": {"mode": "hybrid", "use_rrf": true}}

结合关键字和语义搜索
RRF融合实现最优排名
最佳精确度和召回率

纯语义模式（上下文感知）:

{"search": {"mode": "semantic"}}

仅矢量相似性搜索
最适合概念查询
理解意图和背景

仅关键字模式（最快）:

{"search": {"mode": "keyword"}}

传统关键字匹配
亚毫秒级查询
适用于精确术语搜索

演出

预期性能（v2.0.0）

相关性指标:

Precision@10：~85%（v1.0中为~40%）
Recall@10：约75%（v1.0中为约30%）
文档覆盖率：100%（截断后为0.5%）

速度指标:

冷查询：150-200ms（模型加载的第一次查询）
温馨查询：150-200ms（语义+重排序+RRF）
缓存查询：10-20ms（5倍加速）
仅关键字：\<1ms

索引性能:

初始索引：500个文档约30秒（包括模型下载）
重新索引：500个文档（缓存模型）约5秒
大型DOCX：300页文档约1秒

规模指标:

文件：1000-10000（测试多达1000）
磁盘使用量：1000个大文档约1-2GB
RAM使用量：~2GB（型号+工作内存）

发展

运行测试

cd backend

# Run all tests
pytest tests/ -v

# Run RAG feature tests
python test_rag_features.py

# Run search pipeline tests
python test_search_pipelines.py

# With coverage
pytest tests/ --cov=core --cov=mcp --cov-report=html

项目结构

librarian-mcp/
├── backend/
│   ├── core/                 # Core components
│   │   ├── parsers.py        # File parsers (MD, TXT, DOCX)
│   │   ├── indexer.py        # Document indexing
│   │   ├── search.py         # Keyword search engine
│   │   ├── embeddings.py     # E5-large-v2 embeddings
│   │   ├── vector_db.py      # ChromaDB wrapper
│   │   ├── chunking.py       # Hierarchical chunking
│   │   ├── reranker.py       # Cross-encoder reranking
│   │   ├── cache.py          # Query embedding cache
│   │   ├── bm25_search.py    # BM25 keyword search
│   │   ├── semantic_search.py # Semantic search engine
│   │   └── hybrid_search.py  # Hybrid search (RRF)
│   ├── mcp/                  # MCP server
│   │   └── tools.py          # MCP tool definitions
│   ├── config/               # Configuration
│   │   └── settings.py       # Config management
│   ├── tests/                # Unit tests
│   ├── main.py               # Server entry point
│   └── requirements.txt      # Dependencies
├── docs/                     # Documentation files
├── config.json               # Configuration file
├── CLAUDE.md                 # Developer guide
├── QUICKSTART.md             # 5-minute setup
├── IMPLEMENTATION_COMPLETE.md # v2.0 implementation details
└── README.md                 # This file

MCP工具参考

搜索文档

使用混合搜索（语义+关键字）在所有文档中搜索。

参数：

query （str）：搜索查询（支持自然语言）
product （str，可选）：按产品筛选
component （str，可选）：按组件筛选
file_types （列表，可选）：按文件扩展名筛选
max_results （int，默认值=10）：最大结果
mode （str，可选）：覆盖搜索模式（关键字/语义/混合）

退货：

results：具有相关性得分的匹配文档列表
total：结果数量
query：使用的搜索查询
search_mode：使用的模式（关键字/语义/rrf）

示例:

{
  "query": "How to implement authentication",
  "product": "symphony",
  "max_results": 5
}

get_document

检索特定文档的完整内容。

参数：

path （str）：从文档根的相对路径
section （str，可选）：按标题提取特定部分

退货：

content：完整文档内容
headings标题列表
metadata：文档元数据（节、页、表）

产品列表

列出所有可用产品。

退货：

products：包含组件计数的产品列表
total：产品数量

列表_组件

列出特定产品的组件。

参数：

product （str）：产品名称

退货：

components：包含文档计数的组件列表
total：组件数量

get_index_status

获取当前索引状态和统计信息。

退货：

status：索引状态
total_documents：索引文档的数量
total_chunks：索引块的数量（使用RAG）
products：产品数量
embedding_model：当前嵌入模型
search_mode：当前搜索模式
last_indexed：上次索引更新时间

搜索邮件

使用Outlook/Gmail风格的操作符搜索电子邮件。

参数：

query （str）：使用可选内联运算符的搜索查询
sender （str，可选）：按发件人筛选（也可以使用 from: 在查询中）
recipient （str，可选）：按收件人筛选（也可以使用 to: 在查询中）
cc （str，可选）：按CC收件人筛选（也可以使用 cc: 在查询中）
thread_id （str，可选）：按线程ID过滤（也可以使用 thread: 在查询中）
subject_contains （str，可选）：按主题筛选（也可以使用 subject: 在查询中）
folder （str，可选）：按文件夹筛选（也可以使用 in: 在查询中）
has_attachments （bool，可选）：按附件过滤（也可以使用 has:attachment 在查询中）
date_after （str，可选）：日期后过滤（也可以使用 after: 在查询中）
date_before （str，可选）：日期前过滤（也可以使用 before: 在查询中）
max_results （int，默认值=10）：最大结果
mode （str，可选）：搜索模式（关键字/语义/混合/重新排序/hyde/auto）
parse_operators （bool，默认值=True）：启用内联运算符解析

支持的操作员：

操作员	示例	描述
`from:`	`from:kiraly`	按发件人筛选
`to:`	`to:alice`	按收件人筛选
`cc:`	`cc:manager`	按CC收件人筛选
`subject:`	`subject:"Q4 Report"`	按主题行筛选
`in:`	`in:important`	按文件夹筛选
`has:`	`has:attachment`	过滤带附件的电子邮件
`after:`	`after:2024-01-01`	日期后筛选
`before:`	`before:2024-12-31`	日期前筛选
`thread:`	`thread:abc123`	按线程ID筛选

示例:

{
  "query": "from:kiraly in:important project deadline"
}

这将在“重要”文件夹中的“kiraly”电子邮件中搜索“项目截止日期”。

故障排除

服务器无法启动

检查端口可用性：

lsof -i :3001

检查配置：

cat config.json
# Verify docs.root_path exists

模型下载问题

首次运行下载约1.4GB的型号:

# Manual download test
python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('intfloat/e5-large-v2')"

检查磁盘空间:

df -h ~/.cache/torch
# Need ~2GB free space

没有文档索引

检查文档路径：

ls -la docs/

检查文件权限：

chmod -R 755 docs/

克劳德桌面未连接

验证服务器是否正在运行：

curl http://127.0.0.1:3001/health

检查Claude桌面配置：

cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

重新启动克劳德桌面

搜索未返回任何结果

检查索引状态：

curl http://127.0.0.1:3001/health
# Or use get_index_status tool in Claude

验证嵌入是否已启用：

grep -A5 "embeddings" config.json
# Should show "enabled": true

检查矢量数据库：

ls -la vector_db/
# Should contain chroma.sqlite3 and other files

从v1.0迁移

自动迁移

无需采取任何行动。系统将：

首次启动时下载型号（约1.4GB，一次性）
使用新的组块重新索引现有文档
为所有块生成嵌入
默认情况下使用混合搜索

保持v1.0行为

要禁用RAG并保持仅关键字搜索，请执行以下操作：

{
  "search": { "mode": "keyword" },
  "embeddings": { "enabled": false }
}

清除旧数据

如果从v2.0测试版升级：

rm -rf ./vector_db
# Restart server to rebuild with new settings

文档

QUICKSTART.md -5分钟设置指南
CLAUDE.md -Claude Code开发人员指南
实施_已完成.md -v2.0.0实现细节
COMPREHENSIVE_TEST_REPORT.md -测试结果和验证
索引_GUIDE.md -文档索引文档
企业资源_RAG_ROADMA.md -RAG增强路线图

更新日志

v2.0.4（2026年1月）-电子邮件搜索运营商

新功能:

Outlook/Gmail风格的电子邮件搜索操作
搜索查询中的内联运算符解析
从文件路径中自动提取文件夹
支持9个操作符：from、to、cc、subject、in、has、after、before、thread
为带空格的运算符提供引用值支持
不区分大小写的运算符匹配

用法:

# Search emails from kiraly about project
from:kiraly project deadline

# Search in specific folder with attachments
in:important has:attachment budget

# Search with date range
after:2024-01-01 before:2024-12-31 quarterly report

# Search with quoted values
subject:"Q4 Report" from:"John Doe"

v2.0.0（2025年12月3日）-企业RAG发布

新功能:

E5-large-v2嵌入物（1024d，质量提高30-40%）
分层文档分块（512个标记，128个重叠）
持久矢量存储（ChromaDB优化）
两级重新排序（交叉编码器，精度提高2倍）
查询嵌入缓存（重复查询速度提高5倍）
BM25关键字搜索（概率评分）
交互秩融合（RRF混合搜索）

性能改进:

100%的文档覆盖率（截断后为0.5%）
Precision@10：约85%（原约40%）
Recall@10：约75%（原约30%）
可扩展到10000多个文档

重大变更:

无-完全向后兼容

v1.0.0（2024年11月）-首次发布

HTTP/SSE MCP服务器
基于关键字的搜索
支持多种格式（.md、.txt、.docx）
实时文件查看
产品/组件组织

许可证

\[您的许可证\]

贡献

\[贡献指南\]

支持

对于问题和疑问：

GitHub 问题: https://github.com/anthropics/librarian-mcp/issues
文档：请参阅CLAUDE.md和QUICKSTART.md
测试报告：请参阅COMPREHENSIVE_TEST_REPORT.md

______________________________________________________________________

建于:

FastAPI+FastMCP（HTTP/SSE MCP服务器）
句子转换器（E5-large-v2嵌入+交叉编码器）
ChromaDB（持久矢量数据库）
rank-bm25（BM25Okapi关键字搜索）
python docx（docx解析）
看门狗（文件监控）

Librarian MCP

快速接入

详细介绍

图书馆员MCP-企业RAG文献检索系统

特性

快速开始

先决条件

安装

运行服务器

文档结构

Claude桌面集成

使用示例

基本搜索

混合搜索（最佳结果）

获取特定文档

列出可用产品

元数据过滤（v2.0.3）

基于标签的搜索（v2.0.3）

时态查询（v2.0.3）

电子邮件搜索运算符（v2.0.4）

建筑

搜索管道（混合模式）

文档索引管道

配置

config.json（生产设置）

搜索模式选项

演出

预期性能（v2.0.0）

发展

运行测试

项目结构

MCP工具参考

搜索文档

get_document

产品列表

列表_组件

get_index_status

搜索邮件

故障排除

服务器无法启动

模型下载问题

没有文档索引

克劳德桌面未连接

搜索未返回任何结果

从v1.0迁移

自动迁移

保持v1.0行为

清除旧数据

文档

更新日志

v2.0.4（2026年1月）-电子邮件搜索运营商

v2.0.0（2025年12月3日）-企业RAG发布

v1.0.0（2024年11月）-首次发布

许可证

贡献

支持

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP