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中。
- 下载
zvec-mcp-0.1.0.mcpb从 最新版本 - 打开克劳德代码
- 去 扩展 标签
- 拖动
.mcpb将文件放入放置区 - 在显示的设置中配置您的嵌入后端
> 注: 这 .mcpb bundle默认为 超文本传输协议 嵌入后端,不包括句子转换器。要使用本地嵌入,请通过pip安装(选项B)。
选项B-pip安装```bash
pip install zvec-mcp
这将安装 `zvec-mcp` 命令行入口点。要获取本地离线嵌入:```bash
pip install zvec-mcp sentence-transformers
对于OpenAI嵌入:```bash
pip install "zvec-mcp[openai]"
### 选项C——来源```bash
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在哪里可以找到服务器。
用户范围(适用于所有项目)```bash
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二进制文件的完整路径:```bash
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 在项目根目录中:```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`).
### 验证```bash
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进行设置:
- 安装 LM 工作室
- 下载嵌入模型(例如。
nomic-embed-text-v1.5) - 启动本地服务器(LM Studio→ 开发者→ 启动服务器)
- 注意端口(默认
1234)和API密钥,如果您启用了身份验证```json
{
"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. 安装 奥拉玛
1. 拉动嵌入模型: `ollama pull nomic-embed-text`
1. Ollama在港口服务 `11434` 默认情况下```json
{
"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)```json
{
"env": {
"ZVEC_MCP_EMBEDDING": "local"
}
}
该模型在首次使用时会自动下载(约80 MB,缓存在 `~/.cache/torch/`).
### 开放人工智能
使用OpenAI嵌入API。需要有效的API密钥。```json
{
"env": {
"ZVEC_MCP_EMBEDDING": "openai",
"OPENAI_API_KEY": "sk-..."
}
}
您可以自定义模型和尺寸:```json
{
"env": {
"ZVEC_MCP_EMBEDDING": "openai",
"OPENAI_API_KEY": "sk-...",
"ZVEC_MCP_OPENAI_MODEL": "text-embedding-3-large",
"ZVEC_MCP_OPENAI_DIM": "3072"
}
}
______________________________________________________________________
## 配置参考
所有设置都由环境变量驱动,通过 `env` MCP配置中的块。
|变量|默认值|描述|
|----------|---------|-------------|
| `ZVEC_MCP_DATA_DIR` | `~/.zvec-mcp` |矢量数据库集合的根目录|
| `ZVEC_MCP_EMBEDDING` | `local` |嵌入后端: `local`, `openai`,或 `http` |
| `ZVEC_MCP_CHUNK_SIZE` | `512` |用于知识摄取的每个块的字符数|
| `ZVEC_MCP_CHUNK_OVERLAP` | `64` |连续块之间的重叠|
| **HTTP后端** | | |
| `ZVEC_MCP_HTTP_URL` | `http://127.0.0.1:1234/v1/embeddings` |OpenAI兼容的嵌入端点|
| `ZVEC_MCP_HTTP_MODEL` | `text-embedding-nomic-embed-text-v1.5@f16` |发送到端点的模型名称|
| `ZVEC_MCP_HTTP_API_KEY` |--|承载令牌(可选,取决于您的服务器)|
| `ZVEC_MCP_HTTP_DIM` | `768` |嵌入尺寸(必须与您的模型匹配)|
| **OpenAI后端** | | |
| `OPENAI_API_KEY` |--|使用OpenAI后端时需要|
| `ZVEC_MCP_OPENAI_MODEL` | `text-embedding-3-small` |OpenAI模型名称|
| `ZVEC_MCP_OPENAI_DIM` | `1536` |嵌入尺寸|
______________________________________________________________________
## 工具参考
### 知识库(RAG)
|工具|说明|
|------|-------------|
| `knowledge_ingest` |分块、嵌入和存储文本以供以后检索。接受 `text` 以及一个可选 `source` 标签。 |
| `knowledge_ingest_file` |从磁盘读取文件并摄取其内容。接受文件 `path`. |
| `knowledge_search` |对摄入的文档进行语义搜索。接受a `query` 可选 `topk` (默认值5)。 |
| `knowledge_delete_source` |从给定的块中删除所有块 `source`. |
| `knowledge_stats` |返回集合统计信息(单据数、嵌入维度、路径)。 |
### 记忆
|工具|说明|
|------|-------------|
| `memory_remember` |储存一个事实、偏好或观察结果。接受 `text` 可选 `category` (默认值 `"general"`). |
| `memory_recall` |通过查询进行语义回忆。接受 `query`,可选 `topk` (默认值5),可选 `category` 过滤器。 |
| `memory_forget` |按以下方式删除特定内存 `memory_id`. |
| `memory_forget_category` |删除a中的所有记忆 `category`. |
| `memory_stats` |返回内存存储统计信息。 |
### 状态
|工具|说明|
|------|-------------|
| `zvec_status` |返回两个集合的服务器配置、嵌入后端和统计数据。 |
______________________________________________________________________
## 使用示例
注册后,您可以在与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. 文本在句子边界处被分割成重叠的块(可配置大小和重叠)
1. 每个块都通过配置的后端嵌入
1. 块存储在zvec中 `Collection` 带字段: `source`, `chunk_idx`, `text`, `created_at`
1. 块ID是内容寻址的(`sha256(source:idx)`)--重新摄取相同的源更新
### 记忆是如何工作的
1. 每个事实/观察都嵌入并存储了一个类别标签
1. 内存ID是内容寻址的(`sha256(text)`)--将同一文本存储两次是不可行的(重复数据删除)
1. Recall使用余弦相似度和可选的类别过滤
1. 分类让你组织记忆(例如。 `preference`, `project`, `person`, `decision`)
______________________________________________________________________
## 数据存储
所有数据都存在于 `ZVEC_MCP_DATA_DIR` (默认值 `~/.zvec-mcp/`):```
~/.zvec-mcp/
├── knowledge/ # zvec collection for RAG chunks
└── memory/ # zvec collection for memories
集合在首次使用时自动创建。要重置所有内容,请删除目录:```bash
rm -rf ~/.zvec-mcp
______________________________________________________________________
## 故障排除
### 服务器未显示为已连接```bash
# 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.安装它:```bash
pip install sentence-transformers
或者切换到 `http` 如果您正在运行LM Studio或Ollama,则使用后端。
### 重置数据库
要重新开始,请删除数据目录:```bash
rm -rf ~/.zvec-mcp
下次使用时会自动重新创建集合。
构建.mcpb包
要从源代码构建桌面扩展,请执行以下操作:```bash
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核具有严格的版本耦合,必须一起解决。
依赖项
| 包 | 角色 |
|---|---|
| 实验 | 矢量数据库引擎 |
| 主控程序 | 模型上下文协议SDK(FastMCP) |
| 句子变换器 | 本地嵌入(可选) |
| 开放人工智能 | OpenAI嵌入(可选) |
许可证
阿帕奇-2.0
