Knowledge MCP (Maxzrff)

](https://mseep.ai/app/maxzrff-knowledgemcp)

MCP知识服务器

模型上下文协议（MCP）服务器，使AI编码助手和代理工具能够通过语义搜索利用本地知识。

状态: ✅ 全面运作 -所有用户故事均已实施并验证

特性

• ✅ 语义搜索：对文档集合的自然语言查询
• ✅ 多上下文支持：将文档组织到单独的上下文中，以便进行重点搜索
• ✅ 多格式支持：PDF、DOCX、PPTX、XLSX、HTML和图像（JPG、PNG、SVG）
• ✅ 智能OCR：自动检测仅扫描的PDF，并在需要时应用OCR
• ✅ 异步处理：背景索引和进度跟踪
• ✅ 永久存储：ChromaDB矢量存储，具有可靠的文档删除功能
• ✅ HTTP和标准传输：与GitHub Copilot CLI和Claude Desktop兼容
• ✅ MCP集成：与Claude Desktop、GitHub Copilot和其他MCP客户端兼容
• ✅ 本地和私人：所有处理都在本地进行，没有数据离开您的系统

多上下文组织

将文档组织到不同的上下文中，以便更好地组织和集中搜索结果。

什么是上下文？

上下文是孤立的知识领域，可以让你：

• 按主题组织：将AWS文档与医疗保健文档和项目特定文档分开
• 高效搜索：在特定上下文中搜索更快、更相关的结果
• 多域文档：将同一文档添加到多个上下文中
• 灵活的组织：每个上下文都是一个单独的ChromaDB集合

创建和使用上下文

from src.services.context_service import ContextService

# Create contexts
context_service = ContextService()
await context_service.create_context("aws-architecture", "AWS WAFR and architecture docs")
await context_service.create_context("healthcare", "Medical and compliance documents")

# Add documents to specific contexts
doc_id = await service.add_document(
    Path("wafr.pdf"),
    contexts=["aws-architecture"]
)

# Add to multiple contexts
doc_id = await service.add_document(
    Path("fin-services-lens.pdf"),
    contexts=["aws-architecture", "healthcare"]
)

# Search within a context
results = await service.search("security pillar", context="aws-architecture")

# Search across all contexts
results = await service.search("best practices")  # No context = search all

MCP上下文工具

# Create context
knowledge-context-create aws-docs --description "AWS documentation"

# List all contexts
knowledge-context-list

# Show context details
knowledge-context-show aws-docs

# Add document to context
knowledge-add /path/to/doc.pdf --contexts aws-docs

# Add to multiple contexts
knowledge-add /path/to/doc.pdf --contexts aws-docs,healthcare

# Search in specific context
knowledge-search "security" --context aws-docs

# Delete context
knowledge-context-delete test-context --confirm true

默认上下文

所有没有指定上下文的文档都会自动转到“默认”上下文。这确保了与现有工作流的向后兼容性。

智能OCR处理

该服务器包括智能OCR功能，可自动检测何时需要OCR：

自动OCR检测

系统分析提取的文本质量，并在以下情况下自动应用OCR：

• 提取的文本少于100个字符（可能是扫描）
• 文本中字母数字字符少于70%（乱码/编码问题）

强制OCR模式

即使文本提取可用，您也可以强制OCR处理：

# Python API
doc_id = await service.add_document(
    Path("document.pdf"),
    force_ocr=True  # Force OCR regardless of text quality
)

# MCP Tool (via GitHub Copilot or Claude)
knowledge-add /path/to/document.pdf --force_ocr=true

OCR要求

对于OCR功能，请安装Tesseract OCR：

# Ubuntu/Debian
sudo apt-get install tesseract-ocr poppler-utils

# macOS
brew install tesseract poppler

# Windows (via Chocolatey)
choco install tesseract poppler

OCR配置

在中配置OCR行为 config.yaml:

ocr:
  enabled: true              # Enable/disable OCR
  language: eng              # OCR language (eng, fra, deu, spa, etc.)
  force_ocr: false           # Global force OCR setting
  confidence_threshold: 0.0  # Accept all OCR results

处理方法跟踪

所有文档都包含显示其处理方式的元数据：

• text_extraction：标准文本提取
• ocr：使用了OCR处理
• image_analysis：仅图像文档

检查文档元数据中的处理方法：

documents = service.list_documents()
for doc in documents:
    print(f"{doc.filename}: {doc.processing_method}")
    if doc.metadata.get("ocr_used"):
        confidence = doc.metadata.get("ocr_confidence", 0)
        print(f"  OCR confidence: {confidence:.2f}")

快速开始

先决条件

• Python 3.11+或Python 3.12
• Tesseract OCR（可选，用于扫描文档）

自动设置

# One-command setup and demo
./quickstart.sh

这将：

• ✅ 创建虚拟环境
• ✅ 安装依赖项
• ✅ 下载嵌入模型
• ✅ 运行端到端演示
• ✅ 显示下一步

手动安装

# Clone repository
git clone https://github.com/yourusername/KnowledgeMCP.git
cd KnowledgeMCP

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Download embedding model (first run, ~91MB)
python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('sentence-transformers/all-MiniLM-L6-v2')"

基本用法

from pathlib import Path
from src.services.knowledge_service import KnowledgeService
import asyncio

async def main():
    # Initialize service
    service = KnowledgeService()
    
    # Add document to specific context
    doc_id = await service.add_document(
        Path("document.pdf"),
        metadata={"category": "technical"},
        contexts=["aws-docs"],  # Optional: organize by context
        async_processing=False
    )
    
    # Search within a context (faster, more focused)
    results = await service.search("neural networks", context="aws-docs", top_k=5)
    for result in results:
        print(f"{result['filename']}: {result['relevance_score']:.2f}")
        print(f"  Context: {result.get('context', 'default')}")
        print(f"  {result['chunk_text'][:100]}...")
    
    # Search across all contexts
    all_results = await service.search("neural networks", top_k=5)
    
    # Get statistics
    stats = service.get_statistics()
    print(f"\nDocuments: {stats['document_count']}")
    print(f"Chunks: {stats['total_chunks']}")
    print(f"Contexts: {stats['context_count']}")

asyncio.run(main())

运行MCP服务器

# Using the management script (recommended)
./server.sh start       # Start server in background
./server.sh status      # Check if running
./server.sh logs        # View live logs
./server.sh stop        # Stop server
./server.sh restart     # Restart server

# Or run directly (foreground)
python -m src.mcp.server

服务器脚本提供：

• ✅ 后台流程管理
• ✅ PID文件跟踪
• ✅ 日志文件管理
• ✅ 状态检查
• ✅ 平滑关闭

运行测试

# Unit tests
pytest tests/unit/ -v

# Integration tests
pytest tests/integration/ -v

# End-to-end demo
python tests/e2e_demo.py

MCP工具可用

服务器为AI助手提供了11个MCP工具：

文档管理

1. 知识添加：将文档添加到知识库（可选择上下文分配）
2. 知识搜索：使用自然语言查询的语义搜索（上下文感知）
3. 知识展示：列出所有文档（可按上下文筛选）
4. 知识删除：删除特定文档
5. 知识清晰：清除整个知识库
6. 知识状态：获取统计数据和健康状况
7. 知识任务状态：检查异步处理任务状态

上下文管理

1. 知识情境创建：创建用于组织文档的新上下文
2. 知识上下文列表：列出所有带有统计信息的上下文
3. 知识情境展示：显示特定上下文的详细信息
4. 知识上下文删除：删除上下文（文档保留在其他上下文中）

配置

服务器通过以下方式配置 config.yaml 在项目根中。提供默认配置。

配置文件

# config.yaml - Default configuration provided
storage:
  documents_path: ./data/documents
  vector_db_path: ./data/chromadb

embedding:
  model_name: sentence-transformers/all-MiniLM-L6-v2
  batch_size: 32
  device: cpu

chunking:
  chunk_size: 500
  chunk_overlap: 50
  strategy: sentence

processing:
  max_concurrent_tasks: 3
  max_file_size_mb: 100

ocr:
  enabled: true
  language: eng
  force_ocr: false
  confidence_threshold: 0.0  # Accept all OCR results

logging:
  level: INFO
  format: text

search:
  default_top_k: 10
  max_top_k: 50

自定义配置

创建自定义配置文件：

# Copy template
cp config.yaml.template config.yaml.local

# Edit your settings
nano config.yaml.local

# The server will use config.yaml.local if it exists

环境变量

配置可以用环境变量覆盖（前缀为 KNOWLEDGE_):

# Override storage path
export KNOWLEDGE_STORAGE__DOCUMENTS_PATH=/custom/path

# Increase batch size for faster processing
export KNOWLEDGE_EMBEDDING__BATCH_SIZE=64

# Enable debug logging
export KNOWLEDGE_LOGGING__LEVEL=DEBUG

# Increase search results
export KNOWLEDGE_SEARCH__DEFAULT_TOP_K=20

# Use GPU if available
export KNOWLEDGE_EMBEDDING__DEVICE=cuda

配置优先

1. 环境变量（最高优先级）
2. config.yaml.local （如果存在）
3. config.yaml （默认）

关键设置

与AI助手集成

克劳德桌面

增添 claude_desktop_config.json:

{
  "mcpServers": {
    "knowledge": {
      "command": "python",
      "args": ["-m", "src.mcp.server"],
      "cwd": "/path/to/KnowledgeMCP",
      "env": {
        "KNOWLEDGE_STORAGE__DOCUMENTS_PATH": "/path/to/docs"
      }
    }
  }
}

备注：Claude Desktop使用stdio传输。服务器会自动检测传输模式。

GitHub Copilot命令行界面

服务器使用MCP Streamable HTTP为Copilot CLI集成公开一个HTTP端点。

步骤1：启动服务器

./server.sh start

步骤2：配置Copilot CLI

增添 ~/.copilot/mcp-config.json:

{
  "knowledge": {
    "type": "http",
    "url": "http://localhost:3000"
  }
}

步骤3：验证集成

在Copilot CLI中，将提供以下工具：

• knowledge-add -将文档添加到知识库
• knowledge-search -使用自然语言查询进行搜索
• knowledge-show -列出所有文件
• knowledge-remove -删除文档
• knowledge-clear -清晰的知识库
• knowledge-status -获取统计数据
• knowledge-task-status -检查处理状态

Copilot CLI中的示例用法：

# Create organized contexts
> knowledge-context-create aws-docs --description "AWS architecture documents"

# Add documents to specific contexts
> knowledge-add /path/to/wafr.pdf --contexts aws-docs

# Search within a context for focused results
> knowledge-search "security pillar" --context aws-docs

# Ask Copilot to use the knowledge base
> What are the AWS WAFR security best practices?

建筑

• 矢量数据库：ChromaDB用于具有持久存储的语义搜索
• 嵌入模型：全MiniLM-L6-v2（384维，快速推理）
• OCR引擎：扫描文件的Tesseract
• 协议：MCP over HTTP（流式HTTP）和stdio传输
• 服务器框架：FastMCP用于HTTP端点管理

演出

在标准硬件（4核CPU，8GB RAM）上验证的性能：

• 索引：文件处理时间小于1秒（HTML），最多30秒（大型PDF）
• 搜索：对于包含数十个文档的知识库，\<200ms
• 记忆：\<500MB基线，随文档数量缩放
• 嵌入：批处理，模型本地缓存

项目结构

KnowledgeMCP/
├── src/                    # Source code
│   ├── models/            # Data models (Document, Embedding, etc.)
│   ├── services/          # Core services (KnowledgeService, VectorStore)
│   ├── processors/        # Document processors (PDF, DOCX, etc.)
│   ├── mcp/              # MCP server and tools
│   ├── config/           # Configuration management
│   └── utils/            # Utilities (chunking, validation, logging)
├── tests/                 # Test suite
│   ├── unit/             # Unit tests
│   ├── integration/      # Integration tests
│   └── e2e_demo.py       # End-to-end demonstration
├── docs/                  # Documentation
│   └── SERVER_MANAGEMENT.md  # Server management guide
├── server.sh             # Server management script ⭐
├── quickstart.sh         # Quick setup script ⭐
└── README.md             # This file

关键脚本

• server.sh -启动/停止/状态管理
• quickstart.sh -自动设置和演示
• tests/e2e_demo.py -完整系统演示

文档

• 更新日志 -版本历史和最近的更改
• 实施进度 -详细进度报告
• 配置指南 -完整的配置参考
• 服务器管理 -服务器生命周期管理
• 规格说明 -功能规格
• 实施计划 -技术方案
• 任务 -任务分解
• 快速入门指南 -详细使用指南
• MCP工具合同 -API规范

发展

代码质量

# Format code
black src/ tests/

# Lint
ruff check src/ tests/

# Type check
mypy src/

添加新的文档处理器

1. 在中创建处理器 src/processors/
2. 从……继承…… BaseProcessor
3. 实施 extract_text() 和 extract_metadata()
4. 注册 TextExtractor

已验证的用户故事

✅ 美国1：从文档中添加知识

• 多格式文档摄取
• 智能文本提取与OCR
• 带有进度跟踪的异步处理
• 多上下文分配

✅ 美国2：语义搜索知识

• 自然语言查询
• 相关性排名结果
• 快速语义搜索
• 上下文范围和跨上下文搜索

✅ 美国3：管理知识库

• 列出所有文件
• 删除特定文档
• 清晰的知识库
• 查看统计信息
• 上下文过滤

✅ 美国4：通过MCP与AI工具集成

• 实施了11个MCP工具（7个文档+4个上下文工具）
• JSON-RPC兼容
• 已准备好集成AI助手

✅ 美国5：多上下文组织

• 创建和管理上下文
• 将文档添加到多个上下文中
• 在特定上下文中搜索
• 使用单独的ChromaDB集合进行上下文隔离

许可证

麻省理工学院

贡献

欢迎投稿！在提交PR之前，请阅读规范和实施计划。

支持

• 问题：GitHub问题
• 文档：参见 docs/ 和 specs/ 目录
• 问题：检查快速启动指南和API合同

______________________________________________________________________

内置于：Python、ChromaDB、句子转换器、FastAPI、MCP SDK