使用说明

项目简介

MCP Memory Server with Qdrant Persistence 是一个基于 Model Context Protocol (MCP) 构建的后端服务器，旨在为大型语言模型 (LLM) 应用提供知识图谱的上下文记忆能力。它使用 Qdrant 向量数据库实现语义搜索，并通过文件持久化存储完整的知识图谱。该服务器允许 LLM 客户端通过 MCP 协议进行交互，管理实体、关系和执行语义搜索，从而增强 LLM 的上下文理解和推理能力。

主要功能点

知识图谱存储： 以实体和关系的形式存储结构化知识，支持创建、读取、更新和删除操作。
语义搜索： 利用 Qdrant 向量数据库和 OpenAI embeddings 实现基于语义相似度的知识检索，能够根据用户查询找到相关的实体和关系。
工具化操作： 通过 MCP 协议暴露一系列工具 (Tools)，允许 LLM 客户端调用这些工具来管理知识图谱，例如创建实体、创建关系、添加观察、删除实体、删除关系和执行语义搜索。
持久化存储： 支持文件 (memory.json) 和 Qdrant 向量数据库两种持久化方式，确保数据安全和快速访问。
易于部署： 提供 Docker 镜像，方便用户快速部署和运行服务器。
HTTPS 支持： 支持 HTTPS 连接和反向代理配置，保障数据传输安全。

安装步骤

本地安装：

安装 Node.js 和 npm: 确保你的系统已安装 Node.js 和 npm (Node 包管理器)。

克隆仓库: 使用 Git 克隆该 GitHub 仓库到本地：

git clone https://github.com/delorenj/mcp-qdrant-memory.git
cd mcp-qdrant-memory

安装依赖: 在仓库根目录下运行 npm 命令安装项目依赖：
```
npm install
```
构建项目: 运行 npm 命令构建项目，生成可执行的 JavaScript 文件：
```
npm run build
```

Docker 安装：

安装 Docker: 确保你的系统已安装 Docker。

构建 Docker 镜像: 在仓库根目录下运行 Docker 命令构建镜像：

docker build -t mcp-qdrant-memory .

服务器配置

为了让 MCP 客户端能够连接到该服务器，你需要在客户端的 MCP 设置中添加服务器配置信息。以下是基于仓库 'README.md' 提供的配置示例，你需要根据你的实际环境进行调整。

{
  "mcpServers": {
    "memory": {  // 服务器名称，可以自定义
      "command": "/bin/zsh",  // 启动服务器的命令，根据你的系统 Shell 决定，例如 /bin/bash 或 /bin/zsh
      "args": ["-c", "cd /path/to/server && node dist/index.js"], // 启动参数，需要替换 /path/to/server 为服务器代码实际存放的路径
      "env": {  // 环境变量配置
        "OPENAI_API_KEY": "your-openai-api-key",  // 你的 OpenAI API 密钥，用于生成 embeddings
        "QDRANT_API_KEY": "your-qdrant-api-key",  // 你的 Qdrant API 密钥 (如果 Qdrant 服务器需要认证)
        "QDRANT_URL": "http://your-qdrant-server:6333",  // 你的 Qdrant 服务器 URL，例如 http://localhost:6333 或 https://your-qdrant-server
        "QDRANT_COLLECTION_NAME": "your-collection-name"  // 你要使用的 Qdrant 集合名称
      },
      "alwaysAllow": [  // 默认允许客户端调用的工具列表
        "create_entities",
        "create_relations",
        "add_observations",
        "delete_entities",
        "delete_observations",
        "delete_relations",
        "read_graph",
        "search_similar"
      ]
    }
  }
}

Docker 运行配置：

如果你使用 Docker 运行服务器，则不需要配置 'command' 和 'args'，只需要配置 'server name'、'env' 和 'alwaysAllow'。环境变量需要在运行 Docker 容器时通过 '-e' 参数传入。

例如，运行 Docker 容器的命令可能如下所示：

docker run -d \
  -e OPENAI_API_KEY=your-openai-api-key \
  -e QDRANT_URL=http://your-qdrant-server:6333 \
  -e QDRANT_COLLECTION_NAME=your-collection-name \
  -e QDRANT_API_KEY=your-qdrant-api-key \
  --name mcp-qdrant-memory \
  mcp-qdrant-memory

基本使用方法

启动服务器:
- 本地运行: 在项目根目录下，设置好环境变量后，运行命令 'node dist/index.js' 或 'npm run start' (如果 package.json 中配置了 start 脚本)。
- Docker 运行: 参考 Docker 运行配置，启动 Docker 容器。
配置 MCP 客户端: 在你的 MCP 客户端应用中，根据 "服务器配置" 部分提供的 JSON 配置信息，配置连接到 'memory' 服务器。

调用工具 (Tools): 在 MCP 客户端中，你可以使用 'callTool' 方法调用服务器提供的工具，例如：

// 创建实体
await client.callTool("create_entities", {
  entities: [{
    name: "Project Alpha",
    entityType: "Project",
    observations: ["A new development project"]
  }]
});

// 语义搜索
const results = await client.callTool("search_similar", {
  query: "development projects",
  limit: 5
});
console.log(results);

具体的工具名称和参数请参考仓库 'README.md' 中的 "Tools" 章节和 'src/index.ts' 文件中 'setupToolHandlers' 方法的定义。

请确保已正确安装和配置 Qdrant 向量数据库和 OpenAI API 密钥，并根据你的实际需求配置服务器的环境变量和 MCP 客户端连接信息。

关键词