AI Agent 接入 Zvec (一)：MCP 篇

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

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

快速配置

Qoder（推荐）

使用 Qoder CLI（一键配置）：

# OpenAIqodercli 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# 或 DashScopeqodercli 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"}}}}

环境变量说明：

1. OPENAI_API_KEY（必需）：API 密钥
2. OPENAI_BASE_URL（可选）：自定义端点，如 DashScope
3. 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 格式

工具概览

故障排查