# knowledge-mcp **Repository Path**: mumangguo/knowledge-mcp ## Basic Information - **Project Name**: knowledge-mcp - **Description**: 基于MCP的知识库系统,支持文档导入、向量化存储和语义检索,可无缝集成到 Claude Desktop、Cursor 等 AI 工具中。 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 3 - **Forks**: 0 - **Created**: 2026-01-13 - **Last Updated**: 2026-01-13 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # MCP Knowledge Base 一个基于 MCP (Model Context Protocol) 的知识库系统,支持文档导入、向量化存储和语义检索,可无缝集成到 Claude Desktop、Cursor 等 AI 工具中。 ## ✨ 特性 - 🔍 **语义检索** - 基于向量相似度的智能搜索 - 📄 **多格式支持** - Markdown、PDF、DOCX、TXT、HTML - 🌏 **中文友好** - 支持多语言嵌入模型 - 🔌 **MCP 集成** - 一键接入 Claude Desktop / Cursor - 🖥️ **Web UI** - 可视化文档管理界面 - 🗄️ **多后端** - 支持 PgVector、ChromaDB、Milvus ## 📋 环境要求 - Python 3.10+ - Node.js 18+ (Web UI) - PostgreSQL + pgvector 扩展 (推荐) 或 其他向量数据库 ## 🚀 快速开始 ### 1. 安装依赖 ```bash # 克隆项目 git clone cd mcp-knowledge # 安装 Python 依赖 (使用 uv) uv sync # 安装前端依赖 cd ui && npm install && cd .. ``` ### 2. 配置 复制配置文件模板: ```bash # 复制环境变量配置 cp .env.example .env # 复制 YAML 配置 cp config.yaml.example config.yaml ``` 编辑 `config.yaml`,配置数据库连接: ```yaml vector_store: type: pgvector # 可选: chroma | pgvector | milvus pgvector: connection_string: postgresql://账号:密码@localhost:5432/数据库名 table_name: knowledge_embeddings distance_strategy: cosine embedding: provider: local model: paraphrase-multilingual-MiniLM-L12-v2 # 推荐中文场景 document: chunk_size: 1500 # 分块大小 chunk_overlap: 300 # 分块重叠 retrieval: default_top_k: 5 # 默认返回数量 use_mmr: true # 启用多样性检索 ``` > 💡 如使用 HuggingFace 镜像,请在 `.env` 中设置:`HF_ENDPOINT=https://hf-mirror.com` ### 3. 启动服务 ```bash # 启动后端 API (端口 8000) uv run python server.py # 启动前端 (端口 5173) cd ui && npm run dev ``` 访问 http://localhost:5173 使用 Web UI。 --- ## 🐳 Docker 部署 ### 使用 Docker Compose (推荐) ```bash # 复制 Docker 专用配置 cp config.docker.yaml config.yaml # 启动所有服务 (PostgreSQL + MCP Server + API) docker-compose up -d # 查看日志 docker-compose logs -f mcp-server ``` 服务端口: - **MCP Server (SSE)**: http://localhost:3001/sse - **REST API**: http://localhost:8000 - **PostgreSQL**: localhost:5432 - **Web UI**: http://localhost:8999 ### 远程 MCP 接入 (SSE 模式) Docker 部署默认使用 SSE 协议,可远程接入: ```json { "mcpServers": { "knowledge-base": { "url": "http://your-server-ip:3001/sse" } } } ``` ### 传输协议配置 通过环境变量 `MCP_TRANSPORT` 切换协议: | 协议 | 说明 | 端点 | |------|------|------| | `stdio` | 本地 Cursor/Claude 集成 (默认) | - | | `sse` | Server-Sent Events,远程访问 | `/sse` | | `streamable-http` | HTTP 流式传输 | `/mcp` | --- ## 🔌 MCP 接入指南 ### Cursor 集成 1. 打开 Cursor → Settings → MCP 2. 点击 "Add new global MCP server" 3. 配置如下: ```json { "mcpServers": { "knowledge-base": { "command": "E:/Python/Python310/Scripts/uv.exe", "args": [ "--directory", "E:/Desktop/mcp-knowledge", "run", "python", "main.py" ] } } } ``` > ⚠️ 请将路径替换为您的实际安装路径 ### Claude Desktop 集成 编辑 `%APPDATA%\Claude\claude_desktop_config.json`: ```json { "mcpServers": { "knowledge-base": { "command": "uv", "args": ["--directory", "E:/Desktop/mcp-knowledge", "run", "python", "main.py"] } } } ``` --- ## 📚 MCP 工具说明 集成后,AI 可调用以下工具: | 工具名 | 说明 | |--------|------| | `query_knowledge` | 查询知识库,返回相关文档 | | `add_document` | 添加单个文档到知识库 | | `list_documents` | 列出知识库中的文档 | | `get_stats` | 获取知识库统计信息 | ### 示例对话 ``` 用户: 帮我查一下 LangChain4j 的流式输出怎么配置 AI: [调用 query_knowledge("LangChain4j 流式输出")] 根据知识库,LangChain4j 流式输出配置步骤如下: 1. 引入依赖 spring-boot-starter-webflux 2. 在 application.properties 配置 streaming-chat-model ... ``` --- ## 🌐 REST API | 方法 | 端点 | 说明 | |------|------|------| | GET | `/api/stats` | 获取统计信息 | | POST | `/api/query` | 语义查询 | | GET | `/api/documents` | 列出文档 | | POST | `/api/documents` | 添加文档 | | DELETE | `/api/documents/{id}` | 删除文档 | | POST | `/api/upload` | 上传文件 | | POST | `/api/import/directory` | 导入目录 | ### 查询示例 ```bash curl -X POST http://localhost:8000/api/query \ -H "Content-Type: application/json" \ -d '{"query": "流式输出", "top_k": 5}' ``` --- ## 🧠 智能体提示词 (System Prompt Examples) 为了让 AI 更智能地使用这个“外挂大脑”,建议在 System Prompt 或项目规则(`.cursorrules`)中添加以下指令。 ### 通用增强版 (推荐) ```markdown # Role: 拥有长期记忆的 AI 助手 ## Capabilities 你拥有一个强大的外部知识库 (MCP Knowledge Base),这是你的长期记忆。 ## Rules for Using Knowledge Base 1. **Retrieve First (优先检索)**: - 当用户询问具体事实、项目细节、历史记录或非通用常识时,**必须先调用 `query_knowledge_base`**。 - 不要仅仅依赖你训练时的权重,因为知识库中的信息是最新的且特定的。 - 如果检索结果为空(Status: "知识库未命中"),请明确告知用户你不知道,不要编造。 2. **Memorize Explicitly (主动记忆)**: - 当用户向你提供新的重要信息(如:"记住,我的 API Key 是 xxx" 或 "项目部署流程是 xxx")时,**主动调用 `add_document`**。 - 保存时请提取核心内容,并设置合理的 `title` 和 `tags`(例如:tags=["config", "api-key"])。 3. **Anti-Hallucination (防幻觉)**: - 回答时请引用检索到的 `source`。 - 严禁捏造知识库中不存在的 "检索结果"。 ## Workflow Example User: "以前那个 docker 报错是怎么解决的?" Assistant: (Call `query_knowledge_base(query="docker 报错 解决")`) -> 根据返回结果回答。 ``` ### 针对开发者的 .cursorrules 示例 ```markdown # MCP Knowledge Base Rules ALWAYS query the knowledge base before answering questions about: - Project architecture / design patterns - Specific coding conventions used in this team - Historical bug fixes or incident reports WHEN you learn new information that seems valuable for the future: 1. Ask the user: "Should I save this to the knowledge base?" 2. If yes, use `add_document` with detailed tags. NEVER guess about internal APIs or proprietary logic; trust the `query_knowledge_base` tool. ``` --- ## ⚙️ 嵌入模型选择 | 模型 | 维度 | 推荐场景 | |------|------|----------| | `all-MiniLM-L6-v2` | 384 | 英文文档 | | `paraphrase-multilingual-MiniLM-L12-v2` | 384 | 中英混合 | | `shibing624/text2vec-base-chinese` | 768 | 纯中文 | | OpenAI `text-embedding-3-small` | 1536 | 高精度 (需API Key) | --- ## 📁 项目结构 ``` mcp-knowledge/ ├── main.py # MCP 服务器入口 ├── server.py # FastAPI REST 服务 ├── config.yaml # 配置文件 ├── src/ │ ├── knowledge_base.py # 知识库核心 │ ├── embeddings/ # 嵌入模型 │ ├── vectorstores/ # 向量存储适配器 │ └── models.py # 数据模型 ├── ui/ # Vue3 前端 └── docs/ # 示例文档 ``` --- ## 🐛 常见问题 ### Q: 检索结果不准确? - 检查嵌入模型是否适合您的语言(中文推荐 `paraphrase-multilingual-*`) - 确保导入数据使用的嵌入模型与查询一致 - 调整 `chunk_size` 参数 ### Q: MCP 连接失败? - 确保使用绝对路径配置 `uv.exe` - 检查 `--directory` 参数指向正确的项目目录 - 重启 Cursor/Claude Desktop ### Q: HuggingFace 下载超时? 在 `.env` 中设置镜像: ``` HF_ENDPOINT=https://hf-mirror.com ``` --- ## 📄 License MIT