zvec MCP

zvec-mcp

Claude Code MCP服务器，为您的AI代理提供 本地矢量数据库 用于RAG知识检索和长期记忆——由 实验.

______________________________________________________________________

目录

• 它做什么
• 安装

- 选项A——桌面扩展名（.mcpb） - 选项B-pip安装 - 选项C——来源

• 使用Claude Code注册

- 用户范围 - 项目范围 - 验证

• 嵌入后端

- HTTP——LM工作室/Ollama/vLLM - 本地-句子转换 - 开放人工智能

• 配置参考
• 工具参考

- 知识库（RAG） - 记忆 - 状态

• 使用示例
• 建筑
• 数据存储
• 故障排除
• 许可证

______________________________________________________________________

它做什么

zvec-mcp作为一个 模型上下文协议 服务器通过stdio。一旦连接，Claude Code就会 11种新工具 用于存储、搜索和管理本地矢量数据库——完全离线，没有数据离开您的机器。

______________________________________________________________________

安装

先决条件

• Python 3.10或更高版本
• macOS、Linux或Windows
• 嵌入源（其中之一）：

- 像这样的本地服务器 LM 工作室, 奥拉玛，或 虚拟大语言模型 （推荐） - 句子变换器 本地安装 - 一 开放人工智能 API密钥

选项A——桌面扩展名（.mcpb）

最快的开始方式。下载预构建 .mcpb 文件并将其拖动到Claude Code中。

1. 下载 zvec-mcp-0.1.0.mcpb 从 最新版本
2. 打开克劳德代码
3. 去 扩展 标签
4. 拖动 .mcpb 将文件放入放置区
5. 在显示的设置中配置您的嵌入后端

注： 这 .mcpb bundle默认为 超文本传输协议 嵌入后端，不包括句子转换器。要使用本地嵌入，请通过pip安装（选项B）。

选项B-pip安装

pip install zvec-mcp

这将安装 zvec-mcp 命令行入口点。要获取本地离线嵌入：

pip install zvec-mcp sentence-transformers

对于OpenAI嵌入：

pip install "zvec-mcp[openai]"

选项C——来源

git clone https://github.com/cluster2600/zvec-mcp.git
cd zvec-mcp

# Create a virtual environment and install
uv venv --python 3.10
uv pip install -e .

# Optional: local embeddings
uv pip install sentence-transformers

# Optional: OpenAI embeddings
uv pip install openai

______________________________________________________________________

使用Claude Code注册

安装后，您需要告诉Claude Code在哪里可以找到服务器。

用户范围（适用于所有项目）

claude mcp add-json zvec-mcp \
  '{"type":"stdio","command":"zvec-mcp","args":[],"env":{"ZVEC_MCP_DATA_DIR":"'"$HOME"'/.zvec-mcp","ZVEC_MCP_EMBEDDING":"http"}}' \
  --scope user

如果从源代码安装，请使用venv二进制文件的完整路径：

claude mcp add-json zvec-mcp \
  '{"type":"stdio","command":"'"$(pwd)"'/.venv/bin/zvec-mcp","args":[],"env":{"ZVEC_MCP_DATA_DIR":"'"$HOME"'/.zvec-mcp","ZVEC_MCP_EMBEDDING":"http"}}' \
  --scope user

项目范围（通过共享 .mcp.json)

创建或编辑 .mcp.json 在项目根目录中：

{
  "mcpServers": {
    "zvec-mcp": {
      "command": "zvec-mcp",
      "args": [],
      "env": {
        "ZVEC_MCP_DATA_DIR": "${HOME}/.zvec-mcp",
        "ZVEC_MCP_EMBEDDING": "http",
        "ZVEC_MCP_HTTP_URL": "http://127.0.0.1:1234/v1/embeddings",
        "ZVEC_MCP_HTTP_MODEL": "text-embedding-nomic-embed-text-v1.5@f16",
        "ZVEC_MCP_HTTP_DIM": "768"
      }
    }
  }
}

替换 "zvec-mcp" 如果命令不在您的 PATH （例如。 /path/to/zvec-mcp/.venv/bin/zvec-mcp).

验证

claude mcp list
# zvec-mcp: zvec-mcp  - ✓ Connected

您还可以在Claude Code内部通过以下方式进行检查：

“zvec-mcp的现状如何？”

克劳德会打电话给 zvec_status 工具并显示后端、维度和集合统计信息。

______________________________________________________________________

嵌入后端

zvec-mcp支持三个嵌入后端。您可以通过以下方式选择一个 ZVEC_MCP_EMBEDDING 环境变量。

HTTP——LM工作室/Ollama/vLLM

调用任何兼容OpenAI的 /v1/embeddings 终点。这是 推荐 setup——它保持嵌入在本地，在GPU上运行（如果可用），并且不需要大量的Python依赖（使用Python的内置 urllib).

使用LM Studio进行设置：

1. 安装 LM 工作室
2. 下载嵌入模型（例如。 nomic-embed-text-v1.5)
3. 启动本地服务器（LM Studio→ 开发者→ 启动服务器）
4. 注意端口（默认 1234)和API密钥，如果您启用了身份验证

{
  "mcpServers": {
    "zvec-mcp": {
      "command": "zvec-mcp",
      "args": [],
      "env": {
        "ZVEC_MCP_EMBEDDING": "http",
        "ZVEC_MCP_HTTP_URL": "http://127.0.0.1:1234/v1/embeddings",
        "ZVEC_MCP_HTTP_MODEL": "text-embedding-nomic-embed-text-v1.5@f16",
        "ZVEC_MCP_HTTP_API_KEY": "your-api-key",
        "ZVEC_MCP_HTTP_DIM": "768"
      }
    }
  }
}

与Ollama一起设置：

1. 安装 奥拉玛
2. 拉动嵌入模型： ollama pull nomic-embed-text
3. Ollama在港口服务 11434 默认情况下

{
  "env": {
    "ZVEC_MCP_EMBEDDING": "http",
    "ZVEC_MCP_HTTP_URL": "http://127.0.0.1:11434/v1/embeddings",
    "ZVEC_MCP_HTTP_MODEL": "nomic-embed-text",
    "ZVEC_MCP_HTTP_DIM": "768"
  }
}

重要提示： 这 ZVEC_MCP_HTTP_DIM 值必须与所选模型的输出维度匹配。常见值： 768 对于nomic嵌入文本， 384 对于所有MiniLM-L6-v2， 1024 对于BGE大。

本地-句子转换

跑 all-MiniLM-L6-v2 在您的机器上完全离线。384维，在Apple Silicon上使用MPS加速。不需要API密钥。

要求： pip install sentence-transformers （导入PyTorch，约500 MB）

{
  "env": {
    "ZVEC_MCP_EMBEDDING": "local"
  }
}

该模型在首次使用时会自动下载（约80 MB，缓存在 ~/.cache/torch/).

开放人工智能

使用OpenAI嵌入API。需要有效的API密钥。

{
  "env": {
    "ZVEC_MCP_EMBEDDING": "openai",
    "OPENAI_API_KEY": "sk-..."
  }
}

您可以自定义模型和尺寸：

{
  "env": {
    "ZVEC_MCP_EMBEDDING": "openai",
    "OPENAI_API_KEY": "sk-...",
    "ZVEC_MCP_OPENAI_MODEL": "text-embedding-3-large",
    "ZVEC_MCP_OPENAI_DIM": "3072"
  }
}

______________________________________________________________________

配置参考

所有设置都由环境变量驱动，通过 env MCP配置中的块。

______________________________________________________________________

工具参考

知识库（RAG）

记忆

状态

______________________________________________________________________

使用示例

注册后，您可以在与Claude Code的对话中自然地使用这些工具：

RAG的摄入文件：

“摄入以下内容 docs/api-reference.md 进入知识库。"

克劳德会打电话的 knowledge_ingest_file 沿着这条路。然后，您可以提出以下问题：

“身份验证流程是如何工作的？”

克劳德会打电话的 knowledge_search 检索相关块并在其答案中使用它们。

将项目上下文存储为内存：

“记住，这个项目使用PostgreSQL 16，主数据库名为 appdb."

克劳德会打电话的 memory_remember 与类别 "project"。稍后，在任何对话中：

“这个项目使用什么数据库？”

克劳德会打电话的 memory_recall 并检索存储的事实。

按类别组织记忆：

类别可帮助您组织不同类型的信息：

• "preference" --编码风格、工具选择、命名约定
• "project" -体系结构决策、数据库模式、API合同
• "person" --团队成员角色、联系信息
• "decision" --过去有理由的决定

“请记住，我们决定使用JWT进行身份验证而不是会话——主要原因是无状态扩展。”

克劳德把这个放在 "decision" 类别。

清理：

“从源中删除所有知识 docs/old-api.md." “忘记所有的记忆 project 类别。"

______________________________________________________________________

建筑

┌─────────────┐    stdio/JSON-RPC    ┌──────────────────────────┐
│ Claude Code  │◄───────────────────►│  zvec-mcp (FastMCP)      │
│   (client)   │                     │                          │
└─────────────┘                     │  ┌──────────┐            │
                                     │  │ knowledge │ chunk →   │
                                     │  │ manager   │ embed →   │
                                     │  │           │ store     │
                                     │  └─────┬────┘            │
                                     │        │                 │
                                     │  ┌─────▼────┐            │
                                     │  │   zvec    │ vector    │
                                     │  │collection │ search    │
                                     │  └─────┬────┘            │
                                     │        │                 │
                                     │  ┌─────▼────┐            │
                                     │  │  memory   │ remember  │
                                     │  │  manager  │ recall    │
                                     │  └──────────┘            │
                                     │                          │
                                     │  ┌──────────┐            │
                                     │  │embeddings│ local /   │
                                     │  │ (lazy)   │ openai /  │
                                     │  │          │ http      │
                                     │  └──────────┘            │
                                     └──────────────────────────┘

源布局

src/zvec_mcp/
├── server.py       # FastMCP server — 11 tools registered via @mcp.tool()
├── config.py       # Env-driven dataclass, reads all ZVEC_MCP_* variables
├── embeddings.py   # Lazy-loaded embedding singleton (local, OpenAI, or HTTP)
├── knowledge.py    # RAG pipeline: chunk → embed → upsert → query
└── memory.py       # Semantic memory: remember → recall → forget

RAG摄入是如何工作的

1. 文本在句子边界处被分割成重叠的块（可配置大小和重叠）
2. 每个块都通过配置的后端嵌入
3. 块存储在zvec中 Collection 带字段： source, chunk_idx, text, created_at
4. 块ID是内容寻址的(sha256(source:idx))--重新摄取相同的源更新

记忆是如何工作的

1. 每个事实/观察都嵌入并存储了一个类别标签
2. 内存ID是内容寻址的(sha256(text))--将同一文本存储两次是不可行的（重复数据删除）
3. Recall使用余弦相似度和可选的类别过滤
4. 分类让你组织记忆（例如。 preference, project, person, decision)

______________________________________________________________________

数据存储

所有数据都存在于 ZVEC_MCP_DATA_DIR （默认值 ~/.zvec-mcp/):

~/.zvec-mcp/
├── knowledge/    # zvec collection for RAG chunks
└── memory/       # zvec collection for memories

集合在首次使用时自动创建。要重置所有内容，请删除目录：

rm -rf ~/.zvec-mcp

______________________________________________________________________

故障排除

服务器未显示为已连接

# Check MCP registration
claude mcp list

# Test the server directly (should print JSON-RPC on stdout)
zvec-mcp
# Or from source:
/path/to/zvec-mcp/.venv/bin/zvec-mcp

如果找不到该命令，请确保安装目录在您的 PATH，或在MCP配置中使用完整路径。

HTTP嵌入错误

• 连接被拒绝： 确保LM Studio/Ollama/vLLM服务器正在运行
• 401未经授权： 集 ZVEC_MCP_HTTP_API_KEY 到服务器的API密钥
• 尺寸不匹配： 如果在更改模型后搜索时出错，请删除数据目录(rm -rf ~/.zvec-mcp)并重新摄取——您不能在同一集合中混合不同维度的嵌入

首次运行时本地嵌入速度较慢

这 all-MiniLM-L6-v2 首次使用时下载型号（约80 MB）。后续运行从缓存加载(~/.cache/torch/).

sentence-transformers 未找到

本地后端需要 sentence-transformers.安装它：

pip install sentence-transformers

或者切换到 http 如果您正在运行LM Studio或Ollama，则使用后端。

重置数据库

要重新开始，请删除数据目录：

rm -rf ~/.zvec-mcp

下次使用时会自动重新创建集合。

______________________________________________________________________

构建.mcpb包

要从源代码构建桌面扩展，请执行以下操作：

# Install mcpb CLI
npm install -g @anthropic-ai/mcpb

# Install bundled dependencies (core only, no torch/sentence-transformers)
# IMPORTANT: let pip resolve versions — do NOT use --no-deps
pip install --target bundle/server/lib "mcp[cli]>=1.0.0" zvec numpy

# Copy zvec_mcp source into the bundle
cp -r src/zvec_mcp bundle/server/lib/zvec_mcp

# Strip caches (keep .dist-info — needed for importlib.metadata)
cd bundle/server/lib
find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null
find . -name "*.pyc" -delete 2>/dev/null
cd ../../..

# Validate manifest and pack
mcpb validate bundle/manifest.json
mcpb pack bundle/ zvec-mcp-0.1.0.mcpb

不要 剥离 .dist-info 目录——MCP SDK使用 importlib.metadata.version("mcp") 在导入时，如果没有它们，将失败。 不要 使用 --no-deps --pydantic和pydantic核具有严格的版本耦合，必须一起解决。

______________________________________________________________________

依赖项

许可证

阿帕奇-2.0