知识MCP

Name: 知识MCP
Author: maxzrff

作者：maxzrff3 星标更新：2025-11-22

安装使用来源：spider==github.com

项目介绍

MCP 知识服务器

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

状态: ✅ 完全运行 - 所有用户故事已实现并验证

功能

✅ 语义搜索: 对您的文档集合进行自然语言查询
✅ 多上下文支持: 将文档组织到不同的上下文中以进行有针对性的搜索
✅ 多格式支持: PDF, DOCX, PPTX, XLSX, HTML 和图像 (JPG, PNG, SVG)
✅ 智能OCR: 自动检测仅扫描的PDF并根据需要应用OCR
✅ 异步处理: 后台索引并跟踪进度
✅ 持久存储: 使用可靠的文档删除功能的ChromaDB向量存储
✅ HTTP & Stdio传输: 兼容GitHub Copilot CLI和Claude Desktop
✅ MCP集成: 兼容Claude Desktop、GitHub Copilot和其他MCP客户端
✅ 本地及私密: 所有处理都在本地进行，数据不会离开系统

多上下文组织

将您的文档组织到不同的上下文中，以便更好地组织和获得有针对性的搜索结果。

上下文是什么？

上下文是隔离的知识领域，让您能够：

按主题组织: 将AWS文档与医疗文档以及项目特定文档分开
高效搜索: 在特定上下文中搜索以获得更快、更相关的结果
多领域文档: 将同一文档添加到多个上下文中
灵活组织: 每个上下文都是一个独立的ChromaDB集合

创建和使用上下文

from src.services.context_service import ContextService

# 创建上下文
context_service = ContextService()
await context_service.create_context("aws-architecture", "AWS WAFR和架构文档")
await context_service.create_context("healthcare", "医学和合规性文档")

# 将文档添加到特定上下文
doc_id = await service.add_document(
    Path("wafr.pdf"),
    contexts=["aws-architecture"]
)

# 添加到多个上下文
doc_id = await service.add_document(
    Path("fin-services-lens.pdf"),
    contexts=["aws-architecture", "healthcare"]
)

# 在特定上下文中搜索
results = await service.search("安全支柱", context="aws-architecture")

# 跨所有上下文搜索
results = await service.search("最佳实践")  # 无上下文 = 搜索所有

MCP上下文工具

# 创建上下文
knowledge-context-create aws-docs --description "AWS文档"

# 列出所有上下文
knowledge-context-list

# 显示上下文详情
knowledge-context-show aws-docs

# 将文档添加到上下文
knowledge-add /path/to/doc.pdf --contexts aws-docs

# 添加到多个上下文
knowledge-add /path/to/doc.pdf --contexts aws-docs,healthcare

# 在特定上下文中搜索
knowledge-search "安全" --context aws-docs

# 删除上下文
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  # 不管文本质量如何都强制使用OCR
)

# MCP工具（通过GitHub Copilot或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（通过Chocolatey）
choco install tesseract poppler

OCR配置

在config.yaml中配置OCR行为：

ocr:
  enabled: true              # 开启/关闭OCR
  language: eng              # OCR语言（eng, fra, deu, spa等）
  force_ocr: false           # 全局强制OCR设置
  confidence_threshold: 0.0  # 接受所有OCR结果

处理方法跟踪

所有文档都包含元数据，显示它们是如何被处理的：

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:.2f}")

快速开始

前提条件

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

自动化设置

# 一键设置和演示
./quickstart.sh

这将：

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

手动安装

# 克隆仓库
git clone https://github.com/yourusername/KnowledgeMCP.git
cd KnowledgeMCP

# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate  # 在Windows上：venv\Scripts\activate

# 安装依赖项
pip install -r requirements.txt

# 下载嵌入式模型（首次运行，约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():
    # 初始化服务
    service = KnowledgeService()
    
    # 将文档添加到特定上下文
    doc_id = await service.add_document(
        Path("document.pdf"),
        metadata={"category": "技术"},
        contexts=["aws-docs"],  # 可选：按上下文组织
        async_processing=False
    )
    
    # 在特定上下文中搜索（更快，更专注）
    results = await service.search("神经网络", context="aws-docs", top_k=5)
    for result in results:
        print(f"{result['filename']}: {result['relevance_score']:.2f}")
        print(f"  上下文: {result.get('context', '默认')}")
        print(f"  {result['chunk_text'][:100]}...")
    
    # 跨所有上下文搜索
    all_results = await service.search("神经网络", top_k=5)
    
    # 获取统计数据
    stats = service.get_statistics()
    print(f"\n文档数: {stats['document_count']}")
    print(f"片段数: {stats['total_chunks']}")
    print(f"上下文数: {stats['context_count']}")

asyncio.run(main())

运行MCP服务器

# 使用管理脚本（推荐）
./server.sh start       # 在后台启动服务器
./server.sh status      # 检查是否正在运行
./server.sh logs        # 查看实时日志
./server.sh stop        # 停止服务器
./server.sh restart     # 重启服务器

# 或直接运行（前台）
python -m src.mcp.server

服务器脚本提供：

✅ 后台进程管理
✅ PID文件跟踪
✅ 日志文件管理
✅ 状态检查
✅ 平稳关机

运行测试

# 单元测试
pytest tests/unit/ -v

# 集成测试
pytest tests/integration/ -v

# 端到端演示
python tests/e2e_demo.py

可用的MCP工具

服务器公开了11个MCP工具供AI助手使用：

文档管理

knowledge-add: 将文档添加到知识库（可选分配上下文）
knowledge-search: 语义搜索，使用自然语言查询（上下文感知）
knowledge-show: 列出所有文档（可按上下文过滤）
knowledge-remove: 移除特定文档
knowledge-clear: 清空整个知识库
knowledge-status: 获取统计信息和健康状况
knowledge-task-status: 检查异步处理任务状态

上下文管理

knowledge-context-create: 创建新的上下文来组织文档
knowledge-context-list: 列出所有上下文及其统计信息
knowledge-context-show: 显示特定上下文的详细信息
knowledge-context-delete: 删除上下文（文档仍保留在其他上下文中）

配置

服务器通过项目根目录下的config.yaml进行配置。提供了默认配置。

配置文件

# config.yaml - 提供的默认配置
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  # 接受所有OCR结果

logging:
  level: INFO
  format: text

search:
  default_top_k: 10
  max_top_k: 50

自定义配置

创建自定义配置文件：

# 复制模板
cp config.yaml.template config.yaml.local

# 编辑您的设置
nano config.yaml.local

# 如果存在，服务器将使用config.yaml.local

环境变量

可以通过环境变量覆盖配置（前缀为KNOWLEDGE_）：

# 覆盖存储路径
export KNOWLEDGE_STORAGE__DOCUMENTS_PATH=/custom/path

# 增加批次大小以加快处理速度
export KNOWLEDGE_EMBEDDING__BATCH_SIZE=64

# 启用调试日志
export KNOWLEDGE_LOGGING__LEVEL=DEBUG

# 增加搜索结果数量
export KNOWLEDGE_SEARCH__DEFAULT_TOP_K=20

# 如果可用，使用GPU
export KNOWLEDGE_EMBEDDING__DEVICE=cuda

配置优先级

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

关键设置

设置	描述	默认值	备注
`chunk_size`	每个片段的字符数	500	较大 = 更多上下文
`batch_size`	每批嵌入的数量	32	较高 = 更快，更多内存
`device`	计算设备	cpu	使用'cuda'表示GPU
`max_file_size_mb`	最大文件大小	100	增加以适应大型文档
`log_level`	日志详细程度	INFO	使用DEBUG进行开发
`collection_prefix`	ChromaDB集合前缀	knowledge_	用于上下文集合
`default_context`	默认上下文名称	默认	向后兼容

与AI助手的集成

Claude Desktop

添加到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 CLI

服务器通过MCP流式HTTP公开HTTP端点，用于Copilot CLI集成。

步骤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中的示例用法：

# 创建组织化的上下文
> knowledge-context-create aws-docs --description "AWS架构文档"

# 将文档添加到特定上下文
> knowledge-add /path/to/wafr.pdf --contexts aws-docs

# 在特定上下文中搜索以获得有针对性的结果
> knowledge-search "安全支柱" --context aws-docs

# 让Copilot使用知识库
> 什么是AWS WAFR的安全最佳实践？

架构

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

性能

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

索引: 文档处理时间<1秒（HTML），最多30秒（大型PDF）
搜索: 知识库中有数十篇文档时<200毫秒
内存: 基线<500MB，随文档数量扩展
嵌入: 批量处理，模型本地缓存

项目结构

KnowledgeMCP/
├── src/                    # 源代码
│   ├── models/            # 数据模型（文档、嵌入等）
│   ├── services/          # 核心服务（知识服务、向量存储）
│   ├── processors/        # 文档处理器（PDF、DOCX等）
│   ├── mcp/              # MCP服务器和工具
│   ├── config/           # 配置管理
│   └── utils/            # 工具（分块、验证、日志）
├── tests/                 # 测试套件
│   ├── unit/             # 单元测试
│   ├── integration/      # 集成测试
│   └── e2e_demo.py       # 端到端演示
├── docs/                  # 文档
│   └── SERVER_MANAGEMENT.md  # 服务器管理指南
├── server.sh             # 服务器管理脚本 ⭐
├── quickstart.sh         # 快速设置脚本 ⭐
└── README.md             # 此文件

关键脚本

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

文档

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

开发

代码质量

# 格式化代码
black src/ tests/

# 代码检查
ruff check src/ tests/

# 类型检查
mypy src/

添加新的文档处理器

在src/processors/中创建处理器
继承自BaseProcessor
实现extract_text()和extract_metadata()
注册到TextExtractor

验证的用户故事

✅ US1: 从文档中添加知识

多格式文档摄入
智能文本提取 vs OCR
异步处理并跟踪进度
多上下文分配

✅ US2: 语义搜索