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=https://api.openai.com/v1 \
  -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=https://dashscope.aliyuncs.com/compatible-mode/v1 \
  -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=https://api.openai.com/v1 \
  -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 格式

工具概览

类别	工具	说明
集合管理	create_and_open_collection / open_collection / get_collection_info / destroy_collection	创建/打开/删除集合
文档操作	insert_documents / upsert_documents / update_documents / delete_documents / fetch_documents	CRUD 操作
向量查询	vector_query / multi_vector_query	单向量/多向量搜索
索引管理	create_index / drop_index / optimize_collection	索引管理
AI Embedding	generate_dense_embedding / embedding_write / embedding_search	文本嵌入与搜索

故障排查

问题	解决方案
工具不显示	检查配置文件路径，重启客户端
Embedding 报错	确认 OPENAI_API_KEY 和环境变量设置
集合不存在	先用 open_collection 打开集合
维度不匹配	检查 get_collection_info 中的维度定义
搜索无结果	确认有数据、已建索引、filter 条件合理