Knowledge Engine

MCP服务器知识引擎

一个强大的模型上下文协议（MCP）服务器，可以将任何PDF文档集合转换为可通过Claude Desktop访问的智能、可搜索的知识库。该服务器具有使用TF-IDF评分、邻近度匹配和特定域优化的高级搜索功能。

🌟 主要特点

• 🔍 高级搜索引擎：基于TF IDF的倒排索引，具有接近度匹配功能，可获得高度相关的结果
• 📄 通用PDF支持：处理任何PDF集合-技术文档、法律文件、研究等
• ⚡ 高性能：缓存搜索索引、增量处理和后台初始化
• 🎯 领域优化：配置特定于域的关键字以提高搜索准确性
• ⚙️ 完全可配置：基于JSON的配置，支持环境变量
• 🛠️ 全面的CLI：通过直观的命令完成服务器管理
• 🔗 无缝MCP集成：已准备好与Claude Desktop、VS Code和其他MCP客户端一起使用
• 📊 智能缓存：基于MD5哈希的更改检测，实现高效更新

📋 快速开始

先决条件

• Python 3.8或更高版本
• pip（Python包管理器）
• Claude Desktop应用程序（用于MCP集成）

1.安装

# Clone the repository
git clone https://github.com/lhstorm/mcp_server_knowledge_engine.git
cd mcp_server_knowledge_engine

# Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

2.创建您的服务器

# Interactive setup
python manage_server.py create-config

# This will ask you for:
# - Server name (e.g., 'legal-docs-server')
# - Display name (e.g., 'Legal Documents Server')
# - PDF folder location
# - Domain-specific keywords

3.添加PDF文档

# Add individual PDFs
python manage_server.py add-pdf /path/to/document.pdf
python manage_server.py add-pdf /path/to/another-doc.pdf

# Or copy PDFs directly to your configured folder

4.工艺文件

# Convert PDFs to searchable format
python manage_server.py process-pdfs

5.生成MCP配置

# Generate configuration for Claude Desktop
python generate_mcp_config.py --merge

# Or get the config to copy manually
python generate_mcp_config.py

6.开始与Claude一起使用

重新启动Claude Desktop，您的服务器将出现在MCP工具菜单中！

💬 与Claude Desktop一起使用

配置后，您可以自然地与PDF交互：

示例提示：

• “在文档中搜索有关\[主题\]的信息”
• “文档对\[特定功能\]有什么说明？”
• “查找所有PDF中对\[关键字\]的所有引用”
• “显示\[文档名称\]的内容”
• “列出所有可用文档”

高级用法：

• “在\[term2\]附近搜索\[term1\]”-利用邻近匹配
• “获取\[文档\]的第15页”-检索特定页面
• “查找\[query\]的前10个结果”-调整结果计数

📁 项目结构

mcp_server_knowledge_engine/
├── server.py              # Main MCP server with search engine
├── config.py              # Configuration management & validation
├── manage_server.py       # CLI for server management
├── generate_mcp_config.py # MCP configuration generator
├── convert_pdfs.py        # Standalone PDF conversion utility
├── server_config.json     # Active server configuration
├── requirements.txt       # Python dependencies
├── examples/              # Example configurations
│   ├── legal_docs_config.json
│   ├── medical_docs_config.json
│   ├── research_papers_config.json
│   └── tech_docs_config.json
└── your-pdfs/             # Your PDF folder (configurable)
    ├── document1.pdf
    ├── document2.pdf
    └── markdown/          # Auto-generated cache
        ├── .pdf_cache.json      # Processing metadata
        ├── .search_index.pkl    # Cached search index
        ├── document1.md         # Converted documents
        └── document2.md

⚙️ 配置

服务器通过以下方式配置 server_config.json:

{
  "server": {
    "name": "my-docs-server",
    "display_name": "My Documents Server", 
    "description": "Search through my PDF collection",
    "version": "1.0.0"
  },
  "storage": {
    "pdf_folder": "./docs",
    "markdown_folder": "./docs/markdown",
    "domain_keywords": ["keyword1", "keyword2", "domain-term"]
  },
  "tools": {
    "search": {
      "name": "search_docs",
      "description": "Search through PDF documentation"
    },
    "list": {
      "name": "list_docs", 
      "description": "List all available documents"
    },
    "content": {
      "name": "get_document_content",
      "description": "Get full content from documents"
    },
    "max_results_default": 5
  },
  "processing": {
    "cache_enabled": true,
    "parallel_processing": true,
    "max_file_size_mb": 50,
    "context_size": 500
  }
}

🛠️ 管理命令

服务器管理

# Create new configuration
python manage_server.py create-config

# Test configuration
python manage_server.py test

# Generate MCP config
python manage_server.py generate-mcp-config

PDF管理

# List all PDFs
python manage_server.py list-pdfs

# Add PDF
python manage_server.py add-pdf document.pdf

# Remove PDF  
python manage_server.py remove-pdf document.pdf

# Process all PDFs
python manage_server.py process-pdfs

MCP配置

# Print MCP config
python generate_mcp_config.py

# Automatically merge with Claude Desktop config
python generate_mcp_config.py --merge

# Save to file
python generate_mcp_config.py --output my_mcp_config.json

💡 使用示例

法律文件服务器

{
  "server": {
    "name": "legal-docs-server",
    "display_name": "Legal Documents Server"
  },
  "storage": {
    "domain_keywords": ["contract", "liability", "jurisdiction", "plaintiff", "defendant"]
  }
}

技术文档服务器

{
  "server": {
    "name": "tech-docs-server", 
    "display_name": "Technical Documentation Server"
  },
  "storage": {
    "domain_keywords": ["API", "function", "class", "method", "parameter", "return"]
  }
}

研究论文服务器

{
  "server": {
    "name": "research-server",
    "display_name": "Research Papers Server"
  },
  "storage": {
    "domain_keywords": ["hypothesis", "methodology", "results", "conclusion", "analysis"]
  }
}

🔧 可用的MCP工具

每台服务器提供三个可配置的工具：

1. 搜索工具 （默认值： search_docs)

- 智能搜索所有文档 - TF-IDF评分与邻近匹配 - 返回相关摘录及其上下文

1. 列表工具 （默认值： list_docs)

- 列出所有可用文档 - 显示文档元数据和页数

1. 内容工具 （默认值： get_document_content)

- 检索完整文档内容 - 可以获取特定页面 - 包括完整的标记格式

🎯 域名定制

服务器通过以下方式适应您的域：

• 域名关键字：配置对您所在领域重要的术语
• 工具名称：自定义工具名称（例如。， search_legal_docs)
• 描述：为您的用例量身定制描述
• 上下文大小：调整在搜索结果中返回多少上下文

🔍 搜索引擎的工作原理

反向索引架构

服务器使用高级倒排索引进行闪电般快速的搜索：

1. 文档处理：PDF转换为markdown并标记
2. 建立索引：单词被映射到它们的位置（文档、页面、位置）
3. TF-IDF评分:

- TF（词频）：单词在文档中出现的频率 - IDF（反向文档频率）：一个单词在所有文档中有多罕见 - 综合得分确保相关、独特的结果排名更高

搜索功能

• 邻近性提升：当术语出现在一起时，多词查询得分更高
• 上下文提取：返回突出显示搜索词的相关片段
• 域名关键字识别：配置的关键字得到特殊处理
• 页面级精度：结果包括特定页码
• 智能缓存：搜索索引在服务器重新启动之间持续存在

📊 性能优化

• 增量处理：基于MD5哈希的更改检测-仅处理新的/修改的PDF
• 持久搜索索引：服务器重启时立即加载拾取索引
• 背景初始化：服务器在构建索引时接受连接
• 内存效率：流式PDF处理和降价存储
• 可配置限制：控制文件大小限制和处理参数

🐛 故障排除

常见问题及解决方案

服务器未出现在Claude Desktop中：

• 确保MCP配置已合并： python generate_mcp_config.py --merge
• 检查Python路径： which python 或 where python （Windows）
• 验证server_config json是否存在并且是有效的json
• 配置更改后重新启动Claude Desktop

未处理的PDF：

• 检查文件夹权限： ls -la /path/to/pdf/folder
• 验证PDF文件是否损坏： file document.pdf
• 查找stderr中的错误： python server.py 2>error.log
• 确保有足够的磁盘空间用于markdown缓存

搜索未返回结果或结果不佳：

• 初始索引可能需要时间-请检查stderr以了解进度
• 验证是否存在标记文件： ls markdown/*.md
• 检查搜索索引是否存在： ls markdown/.search_index.pkl
• 先尝试单字查询，然后展开
• 查看配置中的域关键字

服务器崩溃或挂起：

• 检查Python版本（需要3.8+）： python --version
• 验证已安装的所有依赖项： pip install -r requirements.txt
• 清除缓存并重新处理： rm -rf markdown/.pdf_cache.json markdown/.search_index.pkl
• 检查Windows上的文件锁定问题

调试模式

# Run with full debug output
python server.py 2>&1 | tee debug.log

# Check server initialization
grep "initialization" debug.log

# Monitor PDF processing
grep "Processing\|Error" debug.log

验证命令

# Test configuration validity
python manage_server.py test

# Verify configuration loading
python -c "from config import load_config_from_env_or_file; c=load_config_from_env_or_file(); print(f'✓ Config loaded: {c.server.name}')"

# Check MCP integration
python generate_mcp_config.py  # Should output valid JSON

🚀 高级用法

多个服务器

您可以运行多个专用服务器：

# Legal documents server
python manage_server.py --config legal_config.json create-config

# Technical docs server  
python manage_server.py --config tech_config.json create-config

# Research papers server
python manage_server.py --config research_config.json create-config

批处理

# Process multiple PDF folders
for folder in docs legal_docs tech_docs; do
    python convert_pdfs.py "$folder" "$folder/markdown"
done

自定义关键字

配置特定于域的关键字以获得更好的搜索相关性：

{
  "storage": {
    "domain_keywords": [
      "algorithm", "data structure", "complexity",
      "optimization", "performance", "scalability"
    ]
  }
}

🏗️ 架构概述

核心组件

1. 搜索索引类 (server.py:27-140)

- 使用TF-IDF评分实现倒排索引 - 处理单词标记和文档索引 - 为多词查询提供基于邻近度的排名

1. 通用PDF服务器类 (server.py:142-661)

- 使用MCP协议处理的主服务器实现 - 管理PDF处理管道 - 处理异步操作和后台初始化

1. 配置系统 (config.py)

- 基于数据类的类型安全配置 - JSON模式验证 - 环境变量支持

1. 管理CLI (manage_server.py)

- 交互式配置创建 - PDF管理操作 - 服务器测试和验证

数据流

PDFs → PDF Reader → Markdown Converter → Search Index → MCP Tools → Claude
         ↓                    ↓                ↓
    [.pdf files]      [.md cache files]  [.search_index.pkl]

🔄 当前服务器配置

存储库当前包含QuantConnect文档的配置(server_config.json).要创建自己的服务器，请执行以下操作：

# Option 1: Interactive setup
python manage_server.py create-config

# Option 2: Copy and modify an example
cp examples/tech_docs_config.json server_config.json
# Edit server_config.json with your settings

📚 示例用例

• 律师事务所：搜索合同、案件档案和法律文件
• 研究实验室：查询科学论文和技术报告
• 软件团队：访问API文档和技术规范
• 医疗实践：搜索患者记录和医学文献
• 教育机构：浏览课程材料和教科书

🤝 贡献

我们欢迎捐款！以下是一些帮助方法：

增强想法

1. 文档格式支持：添加对Word、HTML或其他格式的支持
2. 搜索改进：实现语义搜索、模糊匹配或基于机器学习的排名
3. 演出：添加数据库后端、并行处理或分布式索引
4. 工具：为特定领域创建专门的MCP工具
5. 用户界面：构建用于配置管理的web界面

开发指南

• 遵循现有的代码风格和模式
• 添加新功能的测试
• 更新新功能的文档
• 提交带有清晰描述的PR

🔐 安全考虑

• 服务器只能读取指定的PDF文件夹
• 操作期间不进行外部网络呼叫
• 敏感数据保持在本地，不会向外部服务发送任何内容
• 为PDF文件夹配置适当的文件权限

📄 许可证

这个项目是开源的。有关详细信息，请参阅LICENSE文件。

🙏 致谢

与 模型上下文协议 通过Anthropic。

______________________________________________________________________

准备好将您的PDF转换为可搜索的知识库了吗？

跑 python manage_server.py create-config 开始吧！ 🚀

📦 依赖项

• 主控程序：用于构建MCP服务器的模型上下文协议SDK
• PyPDF2：PDF解析和文本提取
• 异步：用于并发操作的异步I/O
• jsonschema：配置文件的JSON验证

所有依赖项都是轻量级的，对系统的要求最低。