AI Agent 接入 Zvec (一)：MCP 篇

在 AI 编程助手（如 Claude Code、Qoder）的日常工作流中，开发者经常需要与向量数据库交互——创建集合、写入数据、执行语义搜索。但这些操作通常需要切换到终端手动执行代码，打断了与 AI 的对话节奏。

Zvec MCP Server 通过 MCP（Model Context Protocol） 协议，将 Zvec 的全部能力以标准化工具的形式暴露给 AI 助手。配置完成后，AI 可以在对话中直接调用向量数据库操作——无需你离开编辑器，无需手写任何代码。

快速配置

Qoder（推荐）

使用 Qoder CLI（一键配置）：

# OpenAI
qodercli mcp add zvec-mcp uvx zvec-mcp-server 
  -e OPENAI_API_KEY=sk-xxx 
  -e OPENAI_BASE_URL= 
  -e OPENAI_EMBEDDING_MODEL=text-embedding-3-small

# 或 DashScope
qodercli mcp add zvec-mcp uvx zvec-mcp-server 
  -e OPENAI_API_KEY=sk-xxx 
  -e OPENAI_BASE_URL= 
  -e OPENAI_EMBEDDING_MODEL=text-embedding-v4

手动配置（~/.qoder/mcp.json）：

{
  "mcpServers": {
    "zvec-mcp": {
      "command": "uvx",
      "args": ["zvec-mcp-server"],
      "env": {
        "OPENAI_API_KEY": "sk-xxx",
        "OPENAI_BASE_URL": "https://api.openai.com/v1",
        "OPENAI_EMBEDDING_MODEL": "text-embedding-3-small"
      }
    }
  }
}

Claude Code

claude mcp add zvec-mcp uvx zvec-mcp-server 
  -e OPENAI_API_KEY=sk-xxx 
  -e OPENAI_BASE_URL= 
  -e OPENAI_EMBEDDING_MODEL=text-embedding-3-small

Claude Desktop

配置文件：~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "zvec-mcp": {
      "command": "uvx",
      "args": ["zvec-mcp-server"],
      "env": {
        "OPENAI_API_KEY": "sk-xxx"
      }
    }
  }
}

本地开发配置

如需本地开发（使用项目源码）：

{
  "mcpServers": {
    "zvec-mcp": {
      "command": "uv",
      "args": ["run", "python", "-m", "zvec_mcp"],
      "cwd": "/path/to/zvec-mcp-server",
      "env": {
        "OPENAI_API_KEY": "sk-xxx"
      }
    }
  }
}

环境变量说明：

• OPENAI_API_KEY（必需）：API 密钥
• OPENAI_BASE_URL（可选）：自定义端点，如 DashScope
• OPENAI_EMBEDDING_MODEL（可选）：默认 text-embedding-3-small

验证连接

配置完成后，输入以下命令验证：

列出当前可用的 MCP 工具

应返回 17 个 zvec-mcp 工具。如未显示，检查配置并重启客户端。

快速开始（日志故障排查场景）

Part 1 — 创建日志知识库

创建一个名为 log_knowledge 的向量集合，存储在 ./data/log_kb 目录下，
用于存储系统日志相关的故障排查知识。

Part 2 — 写入数据库故障日志知识

向 log_knowledge 写入以下故障案例：
- "ERROR: Connection pool exhausted. Max connections (100) reached. Unable to acquire connection from pool within 30s timeout. Consider increasing max pool size or check for connection leaks."
- "WARN: Slow query detected (execution time: 15.3s). Query: SELECT * FROM large_table WHERE unindexed_column = 'value'. Consider adding index on unindexed_column."

Part 3 — 写入应用层故障日志知识

向 log_knowledge 写入以下故障案例：
- "ERROR: OutOfMemoryError: Java heap space. Heap dump triggered. Analysis shows 85% memory consumed by cached user sessions. Recommendation: review session timeout settings and implement LRU cache eviction."
- "WARN: Circuit breaker 'payment-service' opened after 50 consecutive failures. Fallback strategy activated. Root cause: payment-service timeout (5s) insufficient under high load."

Part 4 — 写入基础设施故障日志知识

向 log_knowledge 写入以下故障案例：
- "ERROR: Disk full (99% usage) on /var/log. Log rotation failed due to permission denied on /etc/logrotate.d/app. Syslog daemon stopped accepting new messages."
- "CRITICAL: SSL certificate expired on 2024-01-15. HTTPS connections rejected. Renewal automation failed due to DNS challenge timeout."

语义搜索示例

根据错误现象搜索解决方案：

在 log_knowledge 中搜索 "数据库连接超时"

按故障级别过滤：

在 log_knowledge 中搜索 "内存问题"

按类别精确定位：

在 log_knowledge 中搜索 "证书相关错误"

多条件组合查询：

在 log_knowledge 中搜索 "服务不可用"，返回 json 格式

工具概览

故障排查