Knowledge Base MCP

本项目是一个本地知识库管理与语义检索系统，基于 FastAPI + ChromaDB + BGE-M3 构建，并提供 MCP Server，可接入 Claude Code、Cursor、Cline、Windsurf 等支持 MCP 的 AI 工具。

项目适合用于个人/团队文档知识库、论文资料检索、Agent 长期记忆和本地 RAG 检索组件。仓库不包含模型权重和运行时数据，首次启动时会自动下载 BAAI/bge-m3。

Features

  • 多知识库管理：创建、更新、删除知识库，按知识库隔离文档与向量集合。
  • 多格式文档接入：支持 txt、md、pdf、docx、csv、xls/xlsx。
  • 本地语义检索：BGE-M3 生成 1024 维向量，ChromaDB 持久化存储与相似度检索。
  • 文档处理流程：MD5 去重、递归分块、PDF 英文空格修复、上传进度 SSE 推送。
  • Web 管理界面：支持知识库管理、文件上传、文本录入和语义搜索。
  • MCP 工具服务：暴露知识库 CRUD、文档上传、文档列表、语义搜索等工具能力。
  • 本地优先：SQLite + ChromaDB 本地存储，模型默认缓存在本机目录。

Tech Stack

Layer Implementation
API 服务 FastAPI, Uvicorn, Pydantic
元数据存储 SQLite, SQLModel
向量检索 ChromaDB
Embedding BAAI/bge-m3, sentence-transformers
文档解析 pdfplumber, python-docx, pandas, openpyxl
MCP mcp, httpx
Web UI 原生 HTML/CSS/JavaScript

Project Structure

knowledge-base-mcp/
├── config.py
├── requirements.txt
├── database/
│   ├── models.py
│   ├── sqlite.py
│   └── chroma.py
├── knowledge_base/
│   ├── main.py
│   ├── chunker.py
│   ├── document_loader.py
│   ├── routers/
│   │   ├── knowledge_base.py
│   │   ├── document.py
│   │   └── search.py
│   └── static/index.html
├── mcp/server.py
├── model/embedding.py
└── skill/SKILL.md

运行后会自动生成：

data/
├── kb_data.db
└── chroma_data/

model/models/
└── BAAI/bge-m3/

这些目录已加入 .gitignore，不应提交到仓库。

Quick Start

1. Install

python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate

pip install -r requirements.txt

2. Start Web Service

python -m knowledge_base.main

打开浏览器访问：

http://localhost:8000

首次启动会下载 BAAI/bge-m3。如 Hugging Face 访问较慢，可设置镜像：

# Windows PowerShell
$env:HF_ENDPOINT="https://hf-mirror.com"

# macOS / Linux
export HF_ENDPOINT=https://hf-mirror.com

3. Run MCP Server

python mcp/server.py

默认配置：

Item Default
Web API http://127.0.0.1:8000
MCP SSE http://0.0.0.0:8765/sse

可通过环境变量调整：

KB_SERVICE_PORT=8080 python -m knowledge_base.main
KB_SERVICE_URL=http://127.0.0.1:8080 KB_MCP_PORT=8766 python mcp/server.py

MCP Client Config

Claude Code / Cline / Cursor

{
  "mcpServers": {
    "knowledge-base": {
      "command": "python",
      "args": ["mcp/server.py"],
      "cwd": "D:/path/to/knowledge-base-mcp",
      "env": {
        "KB_SERVICE_PORT": "8000"
      }
    }
  }
}

Windows 上如果直接启动失败，可用：

{
  "mcpServers": {
    "knowledge-base": {
      "command": "cmd",
      "args": ["/c", "python", "mcp/server.py"],
      "cwd": "D:/path/to/knowledge-base-mcp"
    }
  }
}

API Examples

创建知识库：

curl -X POST http://localhost:8000/api/kb \
  -H "Content-Type: application/json" \
  -d "{\"name\":\"AI Papers\",\"description\":\"paper notes\"}"

上传文本：

curl -X POST http://localhost:8000/api/kb/1/docs \
  -F "title=Transformer Note" \
  -F "content=Attention is all you need..."

语义搜索：

curl "http://localhost:8000/api/search?q=transformer&top_k=5"

MCP Tools

Tool Description
kb_list 列出知识库
kb_create 创建知识库
kb_delete 删除知识库及其向量集合
doc_upload_text 上传文本到指定知识库
doc_list 查看知识库内文档
doc_delete 删除文档及其向量
search 在单个或全部知识库中进行语义搜索

Configuration

Environment Variable Description Default
KB_SERVICE_PORT FastAPI 服务端口 8000
KB_SERVICE_URL MCP server 调用的后端地址 http://127.0.0.1:8000
KB_MCP_HOST MCP SSE 监听 host 0.0.0.0
KB_MCP_PORT MCP SSE 监听端口 8765
KB_DATA_DIR SQLite 与 ChromaDB 数据目录 ./data
KB_MODEL_CACHE embedding 模型缓存目录 ./model/models

Resume Summary

构建本地知识库管理与 MCP 语义检索系统，基于 FastAPI 实现知识库 CRUD、文档上传、SSE 进度推送和搜索 API，使用 SQLite/SQLModel 管理元数据，ChromaDB 持久化存储向量；基于 BGE-M3 完成多语言 embedding，支持 PDF、Word、Excel、Markdown 等文档解析、MD5 去重、递归分块和跨知识库检索。同时实现 MCP Server，将知识库管理和语义搜索封装为 Agent 可调用工具，支持接入 Claude Code、Cursor、Cline 等 MCP 客户端。

License

MIT