AI Agent 接入 Zvec (一)：MCP 篇

在 AI 编程助手如 Claude Code、Qoder的日常工作流中开发者经常需要与向量数据库交互——创建集合、写入数据、执行语义搜索。但这些操作通常需要切换到终端手动执行代码打断了与 AI 的对话节奏。Zvec MCP Server 通过 MCPModel Context Protocol 协议将 Zvec 的全部能力以标准化工具的形式暴露给 AI 助手。配置完成后AI 可以在对话中直接调用向量数据库操作——无需你离开编辑器无需手写任何代码。快速配置Qoder推荐使用 Qoder CLI一键配置# OpenAI qodercli mcp add zvec-mcp uvx zvec-mcp-server \ -e OPENAI_API_KEYsk-xxx \ -e OPENAI_BASE_URLhttps://api.openai.com/v1 \ -e OPENAI_EMBEDDING_MODELtext-embedding-3-small # 或 DashScope qodercli mcp add zvec-mcp uvx zvec-mcp-server \ -e OPENAI_API_KEYsk-xxx \ -e OPENAI_BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 \ -e OPENAI_EMBEDDING_MODELtext-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 Codeclaude mcp add zvec-mcp uvx zvec-mcp-server \ -e OPENAI_API_KEYsk-xxx \ -e OPENAI_BASE_URLhttps://api.openai.com/v1 \ -e OPENAI_EMBEDDING_MODELtext-embedding-3-smallClaude 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可选自定义端点如 DashScopeOPENAI_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_documentsCRUD 操作向量查询vector_query/multi_vector_query单向量/多向量搜索索引管理create_index/drop_index/optimize_collection索引管理AI Embeddinggenerate_dense_embedding/embedding_write/embedding_search文本嵌入与搜索故障排查问题解决方案工具不显示检查配置文件路径重启客户端Embedding 报错确认OPENAI_API_KEY和环境变量设置集合不存在先用open_collection打开集合维度不匹配检查get_collection_info中的维度定义搜索无结果确认有数据、已建索引、filter 条件合理点击了解更多