MCP Qdrant Semantic Search

🧠 MCP Qdrant语义搜索

A. 模型上下文协议（MCP） 通过Qdrant（一种高性能的向量数据库）为Claude提供持久语义记忆的服务器。

🎯 这是什么？

此MCP服务器允许Claude：

• 💾 门店信息 具有语义搜索功能
• 🔍 检索内容 基于含义，而不仅仅是关键字
• 🧠 记住 对话、代码、文档
• 🎯 智能搜索 通过知识库

真实世界用例

• 语义代码搜索：“查找处理JWT身份验证的代码”
• 团队知识库：存储和检索程序、最佳做法
• 会话记忆：克劳德记得偏好和背景
• 智能文档：即使使用不同的措辞，也能检索文档

✨ 特性

7种可用的MCP工具

🏗️ 建筑

┌─────────────┐         ┌──────────────┐         ┌─────────────┐
│   Claude    │ ◄─MCP──►│  MCP Server  │ ◄─────► │   Qdrant    │
│   Desktop   │         │  (TypeScript)│         │  Vector DB  │
└─────────────┘         └──────────────┘         └─────────────┘
                              │
                              ▼
                        ┌──────────────┐
                        │    OpenAI    │
                        │  Embeddings  │
                        └──────────────┘

🚀 快速开始

先决条件

• Node.js 18+
• 码头工人
• OpenAI API密钥
• 克劳德桌面版

安装

# 1. Install dependencies
npm install

# 2. Configure environment
cp .env.example .env
# Edit .env and add your OPENAI_API_KEY

# 3. Start Qdrant
docker-compose up -d

# 4. Build the project
npm run build

# 5. Configure Claude Desktop
# See INSTALL.md for details

有关完整安装，请参阅 安装.md.

📖 用法

Claude Desktop中的示例

1.店铺信息

Store this information: "Our API uses JWT for authentication.
Tokens expire after 24h and must be renewed via /refresh-token"

答复：

{
  "success": true,
  "message": "Memory stored successfully",
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "content": "Our API uses JWT for authentication..."
}

2.语义搜索

Search for how to handle user sessions

克劳德将使用 search_memory 即使单词不匹配，也能找到JWT信息！

3.使用元数据存储代码

Store this code with tags "authentication" and "nodejs":

function validateToken(token) {
  try {
    return jwt.verify(token, process.env.JWT_SECRET);
  } catch (error) {
    throw new Error('Invalid token');
  }
}

4.使用过滤器进行高级搜索

Search for authentication code, only JavaScript snippets

克劳德可以使用过滤器来优化搜索。

5.获取统计数据

Show me my semantic memory stats

答复：

{
  "success": true,
  "stats": {
    "name": "semantic_memory",
    "points_count": 42,
    "status": "green"
  },
  "embedding_model": "text-embedding-3-large",
  "embedding_dimensions": 1536
}

🎓 关键概念

嵌入（向量）

嵌入将文本转换为数字向量，以捕获 语义含义.

# Conceptual
"JWT authentication" → [0.234, -0.567, 0.891, ..., 0.123]
"Token security"     → [0.219, -0.543, 0.876, ..., 0.134]
# These two vectors are close = similar meaning!

余弦相似度

Qdrant使用余弦相似度来衡量两个向量之间的“语义接近度”。

• 得分1.0：相同
• 得分0.8-0.9：非常相似
• 得分0.7：类似（默认阈值）
• 得分\<0.7：不太相似

集合

集合类似于数据库表，但针对向量进行了优化。

🔧 配置

环境变量

可用的嵌入模型

📊 MCP API

store_memory

{
  content: string,      // Content to store
  metadata?: {          // Optional metadata
    tags?: string[],
    category?: string,
    source?: string,
    // ... other fields
  }
}

search_memory

{
  query: string,        // Natural language query
  limit?: number,       // Number of results (default: 5)
  threshold?: number,   // Min score 0-1 (default: 0.7)
  filter?: object       // Metadata filters
}

删除记忆

{
  id: string           // Memory ID
}

get_memory

{
  id: string           // Memory ID
}

list_memories

{
  limit?: number,      // Number of results (default: 10)
  offset?: string      // Starting ID for pagination
}

get_stats

没有参数。返回集合统计信息。

清除所有记忆

{
  confirm: boolean     // Must be true to confirm
}

🧪 高级示例

1.团队知识库

Store these:

1. "Staging server accessible via staging.example.com,
    port 3000, credentials in 1Password"

2. "To deploy to production, use 'npm run deploy:prod'
    after tests pass and PR approval"

3. "Rate limiting is 1000 req/min per API key,
    10000/min for enterprise clients"

然后搜索：

How do I deploy to production?
What are the API limits?

2.语义代码搜索

Store this code:

// Metadata: language=javascript, topic=authentication
async function authenticateUser(email, password) {
  const user = await db.users.findByEmail(email);
  if (!user) throw new Error('User not found');

  const valid = await bcrypt.compare(password, user.passwordHash);
  if (!valid) throw new Error('Invalid credentials');

  return generateJWT(user);
}

搜索：

How to verify user credentials?
Show me login code

3.会话记忆

Store my preferences:
- I prefer TypeScript over JavaScript
- I use React 18 with hooks
- My code style follows Airbnb ESLint
- I want JSDoc comments on public functions

克劳德会在以后的谈话中记住这一点！

🔍 高级功能

混合搜索（矢量+过滤器）

// In Claude
Search for authentication code,
only Python snippets created after 2024-01-01

服务器可以将语义搜索与元数据过滤器相结合。

大型文档的分块

对于存储大型文档，请拆分为块：

const chunkSize = 500; // words
const chunks = splitIntoChunks(document, chunkSize);

for (const chunk of chunks) {
  await storeMemory({
    content: chunk,
    metadata: {
      document_id: "doc-123",
      chunk_index: i,
      total_chunks: chunks.length
    }
  });
}

🐛 故障排除

错误：“OPENAI_API_KEY是必需的”

检查API密钥是否在Claude Desktop配置文件中定义。

Qdrant连接错误

# Check if Qdrant is running
docker ps | grep qdrant

# Restart if needed
docker-compose restart

空搜索结果

• 降低 threshold （例如，0.5而不是0.7）
• 检查是否有数据： get_stats
• 重新表述查询

OpenAI成本高

• 使用 text-embedding-3-small （便宜5倍）
• 将尺寸减小到512或1024
• 缓存频繁嵌入

🚀 未来改进

• \[\]支持Ollama（免费本地嵌入）
• \[\]用于可视化记忆的Web界面
• \[\]收款导出/导入
• \[\]多模式支持（图像+文本）
• \[\]基于历史的建议
• \[\]自动内存聚类
• \[\]分析和搜索见解

📚 资源

• 模型上下文协议
• Qdrant文件
• OpenAI嵌入指南
• 安装.md -详细的安装指南

🤝 贡献

欢迎投稿！请随意：

• 未解决的错误或建议问题
• 提交拉取请求
• 改进文档

📄 许可证

MIT许可证-请参阅 许可证 了解详情。

🙏 致谢

• Anthropic 对于模型上下文协议
• Qdrant 对于矢量数据库
• 开放人工智能 用于嵌入模型

______________________________________________________________________

备注：该项目用于教育和示范目的。对于生产使用，请考虑安全性、可扩展性和成本。

由...制作❤️ 学习MCP和语义搜索