配备Qdrant持久性的MCP内存服务器

此MCP服务器提供了一个由Qdrant向量数据库驱动的知识图谱实现，具有语义搜索功能。

特性

• 基于实体和关系的图表示
• 文件持久化（memory.json）
• 使用Qdrant向量数据库进行语义搜索
• 使用OpenAI嵌入进行语义相似度计算
• 支持HTTPS及反向代理兼容性
• 支持Docker以方便部署

环境变量

需要以下环境变量：

# 用于生成嵌入的OpenAI API密钥
OPENAI_API_KEY=your-openai-api-key

# Qdrant服务器URL（支持HTTP和HTTPS）
QDRANT_URL=https://your-qdrant-server

# Qdrant API密钥（如果启用了身份验证）
QDRANT_API_KEY=your-qdrant-api-key

# 要使用的Qdrant集合名称
QDRANT_COLLECTION_NAME=your-collection-name

设置

本地设置

1. 安装依赖项：

npm install

2. 构建服务器：

npm run build

Docker设置

1. 构建Docker镜像：

docker build -t mcp-qdrant-memory .

2. 使用所需环境变量运行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 m

添加到MCP设置中：

{
  "mcpServers": {
    "memory": {
      "command": "/bin/zsh",
      "args": ["-c", "cd /path/to/server && node dist/index.js"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key",
        "QDRANT_API_KEY": "your-qdrant-api-key",
        "QDRANT_URL": "http://your-qdrant-server:6333",
        "QDRANT_COLLECTION_NAME": "your-collection-name"
      },
      "alwaysAllow": [
        "create_entities",
        "create_relations",
        "add_observations",
        "delete_entities",
        "delete_observations",
        "delete_relations",
        "read_graph",
        "search_similar"
      ]
    }
  }
}

工具

实体管理

• create_entities：创建多个新实体
• create_relations：在实体之间创建关系
• add_observations：向实体添加观察
• delete_entities：删除实体及其关系
• delete_observations：删除特定观察
• delete_relations：删除特定关系
• read_graph：获取完整的知识图谱

语义搜索

• search_similar：搜索语义上相似的实体和关系

  interface SearchParams {
    query: string;     // 搜索查询文本
    limit?: number;    // 最大结果数（默认：10）
  }
  

实现细节

服务器维护两种形式的持久性：

1. 文件持久性（memory.json）：

   • 完整的知识图谱结构
   • 快速访问完整图谱
   • 用于图操作

2. Qdrant向量数据库：

   • 实体和关系的语义嵌入
   • 启用相似性搜索
   • 自动与文件存储同步

同步

当实体或关系被修改时：

1. 更改写入memory.json
2. 使用OpenAI生成嵌入
3. 向量存储在Qdrant中
4. 两个存储系统保持一致

搜索过程

当搜索时：

1. 查询文本转换为嵌入
2. Qdrant执行相似性搜索
3. 结果包括实体和关系
4. 结果按语义相似度排序

示例使用

// 创建实体
await client.callTool("create_entities", {
  entities: [{
    name: "项目",
    entityType: "任务",
    observations: ["一个新的开发项目"]
  }]
});

// 搜索相似概念
const results = await client.callTool("search_similar", {
  query: "开发任务",
  limit: 5
});

HTTPS和反向代理配置

服务器支持通过HTTPS和反向代理连接到Qdrant。这在以下情况下特别有用：

• 在Nginx或Apache等反向代理后面运行Qdrant
• 使用自签名证书
• 需要自定义SSL/TLS配置

使用反向代理设置

1. 配置您的反向代理（示例使用Nginx）：

server {
    listen 443 ssl;
    server_name qdrant.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:6333;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

2. 更新您的环境变量：

QDRANT_URL=https://qdrant.yourdomain.com

安全注意事项

服务器实现了强大的HTTPS处理，包括：

• 自定义SSL/TLS配置
• 正确的证书验证选项
• 连接池和长连接
• 自动重试并带有指数退避
• 可配置的超时

解决HTTPS连接问题

如果您遇到连接问题：

1. 验证您的证书：

openssl s_client -connect qdrant.yourdomain.com:443

2. 测试直接连接：

curl -v https://qdrant.yourdomain.com/collections

3. 检查任何代理设置：

env | grep -i proxy

贡献

1. 分叉仓库
2. 创建一个特性分支
3. 进行更改
4. 提交拉取请求

许可证

MIT