内容
# 矢量MCP
## 命令行或API | MCP | 代理
*版本：2.0.0*
---
## 概述
**矢量MCP** 是一个生产级别的代理和模型上下文协议（MCP）服务器，旨在直接与MCP服务器集成RAG到AI代理。支持多种矢量数据库技术。
---
## 关键功能
- **合并的动作路由MCP工具：** 通过将方法分组为优化的、可切换的工具模块，最大限度地减少LLM上下文中的标记开销并消除工具膨胀。
- **企业级安全：** 完全支持Eunomia策略、OIDC令牌委托和粒度执行上下文跟踪。
- **集成图代理：** 内置Pydantic AI代理，支持代理控制协议（ACP）和标准Web接口（AG-UI）。
- **原生遥测和跟踪：** 开箱即用的OpenTelemetry导出和原生Langfuse跟踪。
---
## 命令行或API
此代理包装了通过MCP服务器将RAG集成到AI代理中。支持多种矢量数据库技术。 API。你可以通过编程方式或通过其集成的执行入口与它交互。
有关如何使用底层API包装器、扩展模式绑定和开发人员SDK引用的详细说明，请参阅 [docs/index.md](docs/index.md)。
---
## MCP
该服务器使用动态动作路由工具来优化标记开销并最大限度地提高IDE兼容性。
### 可用的MCP工具
_自动从实时MCP服务器生成 - 请勿手动编辑。_
<!-- MCP-TOOLS-TABLE:START -->
#### 精简的动作路由工具（默认 - `MCP_TOOL_MODE=condensed`）
| MCP工具 | 切换环境变量 | 描述 |
|----------|----------------|-------------|
| `vector_collection_management` | `COLLECTION_MANAGEMENTTOOL` | 管理集合管理操作。 |
#### 详细1：1 API映射工具（`MCP_TOOL_MODE=verbose`或`both`）
<details>
<summary>7个逐操作工具 - 每个公共API方法一个（点击展开）</summary>
| MCP工具 | 切换环境变量 | 描述 |
|----------|----------------|-------------|
| `vector_add_documents` | `APITOOL` | 添加文档。 |
| `vector_create_collection` | `APITOOL` | 创建集合。 |
| `vector_delete_collection` | `APITOOL` | 删除集合。 |
| `vector_lexical_search` | `APITOOL` | 执行词典搜索。 |
| `vector_list_collections` | `APITOOL` | 列出集合。 |
| `vector_search` | `SEARCHTOOL` | 执行混合搜索。 |
| `vector_semantic_search` | `APITOOL` | 执行语义搜索。 |
</details>
_1个动作路由工具（默认）· 7个详细1：1工具。每个工具都已启用，除非其`<DOMAIN>TOOL`切换为false；`MCP_TOOL_MODE`选择表面（`condensed`默认 · `verbose` 1：1 · `both`）。自动生成 - 请勿编辑。_
<!-- MCP-TOOLS-TABLE:END -->
有关工具模式、参数形状和验证约束的详细信息，请参阅 [docs/mcp.md](docs/mcp.md)。
### 动态工具选择和可见性
MCP服务器支持运行时动态工具集选择和可见性过滤。这允许您限制暴露的工具集，以防止LLM的上下文窗口爆炸。
您可以通过多个输入通道配置工具过滤：
- **命令行参数：** 在启动时传递 `--tools` 或 `--toolsets`（或其禁用对应项 `--disabled-tools` 和 `--disabled-toolsets`）。
- **环境变量：** 定义标准环境变量：
- `MCP_ENABLED_TOOLS` / `MCP_DISABLED_TOOLS`
- `MCP_ENABLED_TAGS` / `MCP_DISABLED_TAGS`
- **HTTP SSE请求头：** 在传输初始化期间传递自定义头：
- `x-mcp-enabled-tools` / `x-mcp-disabled-tools`
- `x-mcp-enabled-tags` / `x-mcp-disabled-tags`
- **HTTP SSE请求查询参数：** 直接将查询参数附加到传输连接URL：
- `?tools=tool1,tool2`
- `?tags=tag1`
当提供查询字符串或参数时，无LLM的 **知识图谱解析层** （使用 `DynamicToolOrchestrator`）将查询意图与已知工具标签、名称或描述进行匹配，并具有安全的回退和自动的24小时后台缓存刷新。
---
### MCP配置示例
> **安装精简的 `[mcp]` 额外组件。** 以下所有示例均安装
> `vector-mcp[mcp]` - MCP服务器额外组件，仅拉取FastMCP / FastAPI工具包（`agent-utilities[mcp]`）。它故意 **排除** 沉重的
> 代理运行时（认知图引擎，`pydantic-ai`，`dspy`，`llama-index`，
> `tree-sitter`），因此`uvx`/容器安装显著较小且更快。
> 仅当您需要集成Pydantic AI代理时，才使用完整的 `[agent]` 额外组件
> （请参阅 [安装](#installation)）。
#### 标准输入/输出传输（推荐用于本地IDE，例如Cursor，Claude Desktop）
在您的IDE的 `mcp.json` 中配置，以通过 `uvx` 启动MCP服务器：
```json
{
"mcpServers": {
"vector-mcp": {
"command": "uvx",
"args": [
"--from",
"vector-mcp[mcp]",
"vector-mcp"
],
"env": {
"VECTOR_URL": "your_vector_url_here",
"EMBEDDING_MODEL_ID": "your_embedding_model_id_here",
"CHUNK_SIZE": "your_chunk_size_here",
"VECTOR_API_KEY": "your_vector_api_key_here"
}
}
}
}
```
#### 流式HTTP传输（推荐用于生产部署）
在客户端的 `mcp.json` 中配置，以通过 `uvx` 启动流式HTTP服务器，并显式定义主机和端口：
```json
{
"mcpServers": {
"vector-mcp": {
"command": "uvx",
"args": [
"--from",
"vector-mcp[mcp]",
"vector-mcp"
],
"env": {
"TRANSPORT": "streamable-http",
"HOST": "0.0.0.0",
"PORT": "8000",
"VECTOR_URL": "your_vector_url_here",
"EMBEDDING_MODEL_ID": "your_embedding_model_id_here",
"CHUNK_SIZE": "your_chunk_size_here",
"VECTOR_API_KEY": "your_vector_api_key_here"
}
}
}
}
```
或者，连接到预先部署的远程或本地流式HTTP实例：
```json
{
"mcpServers": {
"vector-mcp": {
"url": "http://localhost:8000/vector-mcp/mcp"
}
}
}
```
使用Docker部署流式HTTP服务器：
```bash
docker run -d \
--name vector-mcp-mcp \
-p 8000:8000 \
-e TRANSPORT=streamable-http \
-e PORT=8000 \
-e VECTOR_URL="your_value" \
-e EMBEDDING_MODEL_ID="your_value" \
-e CHUNK_SIZE="your_value" \
-e VECTOR_API_KEY="your_value" \
blubird28/vector-mcp:mcp
```
> `:mcp` 标签是 **精简的MCP服务器镜像** （从
> `docker/Dockerfile --target mcp` 构建，安装 `vector-mcp[mcp]`）。默认
> `:latest` 标签是 **完整的代理镜像** （ `--target agent` ， `vector-mcp[agent]` ）
> ，它还捆绑了Pydantic AI代理和认知图引擎 - 在运行 `vector-agent` （代理）时使用，而不是仅使用MCP服务器。请参阅
> [容器镜像](#container-images-mcp-vs-agent)。
---
<!-- BEGIN GENERATED: additional-deployment-options -->
### 附加部署选项
`vector-mcp` 还可以作为 **本地容器** （Docker / Podman / `uv`）运行或从 **远程部署** 中使用。
[部署指南](https://knuckles-team.github.io/vector-mcp/deployment/) 提供了所有四种传输方式的完整、可复制的
`mcp_config.json` 配置文件： **标准输入/输出** 、 **流式HTTP** 、
**本地容器 / uv** 和 **远程URL** ：
- **本地容器 / uv** - 通过 `uvx` 、 `docker run` 或 `podman run` 从 `mcp_config.json` 启动服务器，或通过 `url` 指向本地流式HTTP容器。
- **远程URL** - 使用 `"url"` 键连接到在Caddy后面部署的服务器，网址为
`http://vector-mcp.arpa/mcp`。
<!-- END GENERATED: additional-deployment-options -->
---
## 环境变量
<!-- ENV-VARS-TABLE:START -->
#### 包环境变量
| 变量 | 示例 | 描述 |
|----------|---------|-------------|
| `HOST` | `0.0.0.0` | |
| `PORT` | `8000` | |
| `TRANSPORT` | `stdio` | 选项：stdio，streamable-http，sse |
| `ENABLE_OTEL` | `True` | |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://localhost:8080/api/public/otel` | |
| `OTEL_EXPORTER_OTLP_PUBLIC_KEY` | `pk-...` | |
| `OTEL_EXPORTER_OTLP_SECRET_KEY` | `sk-...` | |
| `OTEL_EXPORTER_OTLP_PROTOCOL` | `http/protobuf` | |
| `EUNOMIA_TYPE` | `none` | 选项：none，embedded，remote |
| `EUNOMIA_POLICY_FILE` | `mcp_policies.json` | |
| `EUNOMIA_REMOTE_URL` | `http://eunomia-server:8000` | |
| `LLM_BASE_URL` | `http://localhost:8000/v1` | 嵌入式/LLM API基准URL |
| `LLM_TOKEN` | — | 嵌入式/LLM端点的承载令牌 |
| `LLM_API_KEY` | — | 如果未设置LLM_TOKEN，则接受其别名 |
| `LLM_SSL_VERIFY` | `False` | 验证嵌入式/LLM端点的TLS |
| `DOCUMENT_DIRECTORY` | `/documents` | 摄取文档的默认目录 |
| `COLLECTION_MANAGEMENTTOOL` | `True` | |
| `SEARCHTOOL` | `True` | |
| `TEST_POSTGRES_CONNECTION_STRING` | `postgresql://postgres:password@localhost:5432/vectordb` | |
| `TEST_MONGODB_HOST` | `localhost` | |
| `TEST_MONGODB_PORT` | `27017` | |
| `TEST_MONGODB_DB` | `vectordb` | |
| `TEST_QDRANT_LOCATION` | `http://localhost:6333` | |
| `TEST_COUCHBASE_CONNECTION` | `couchbase://localhost` | |
| `TEST_COUCHBASE_USER` | `Administrator` | |
| `TEST_COUCHBASE_PASSWORD` | `password` | |
| `TEST_COUCHBASE_DB` | `vector_db` | |
#### 继承的agent-utilities变量（适用于每个连接器）
| 变量 | 示例 | 描述 |
|----------|---------|-------------|
| `MCP_TOOL_MODE` | `condensed` | 工具表面：`condensed` | `verbose` | `both` |
| `MCP_ENABLED_TOOLS` | — | 以逗号分隔的工具允许列表 |
| `MCP_DISABLED_TOOLS` | — | 以逗号分隔的工具拒绝列表 |
| `MCP_ENABLED_TAGS` | — | 以逗号分隔的标签允许列表 |
| `MCP_DISABLED_TAGS` | — | 以逗号分隔的标签拒绝列表 |
| `MCP_CLIENT_AUTH` | — | 出站MCP身份验证（用于fleet调用的`oidc-client-credentials`） |
| `OIDC_CLIENT_ID` | — | OIDC客户端ID（服务账户身份验证） |
| `OIDC_CLIENT_SECRET` | — | OIDC客户端密钥（服务账户身份验证） |
| `DEBUG` | `False` | 详细日志记录 |
| `PYTHONUNBUFFERED` | `1` | 无缓冲的stdout（推荐在容器中） |
| `MCP_URL` | `http://localhost:8000/mcp` | 代理连接到的MCP服务器的URL |
| `PROVIDER` | `openai` | 代理的LLM提供商 |
| `MODEL_ID` | `gpt-4o` | 代理的模型ID |
| `ENABLE_WEB_UI` | `True` | 提供AG-UI Web界面的服务 |
_27个包变量 + 14个继承变量。自动从 `.env.example` 和共享的agent-utilities集合中生成 - 请勿编辑。_
<!-- ENV-VARS-TABLE:END -->
每个变量服务器读取的变量，按用途分组。
### 连接与凭证
| 变量 | 描述 | 默认值 |
|----------|-------------|---------|
| `VECTOR_URL` | 矢量数据库/嵌入式端点的基准URL | `http://localhost:8000` |
| `VECTOR_API_KEY` | 矢量数据库/嵌入式提供商的API密钥 | — |
| `EMBEDDING_MODEL_ID` | 用于索引和搜索的嵌入式模型ID | `text-embedding-nomic-embed-text-v2-moe` |
| `CHUNK_SIZE` | 摄取文档的块大小 | `512` |
### MCP服务器/传输
| 变量 | 描述 | 默认值 |
|----------|-------------|---------|
| `TRANSPORT` | `stdio` 、 `streamable-http` 或 `sse` | `stdio` |
| `HOST` | 绑定主机（HTTP传输） | `0.0.0.0` |
| `PORT` | 绑定端口（HTTP传输） | `8000` |
| `MCP_TOOL_MODE` | 工具表面：`condensed` 、 `verbose` 或 `both` | `condensed` |
| `MCP_ENABLED_TOOLS` / `MCP_DISABLED_TOOLS` | 以逗号分隔的工具允许/拒绝列表 | — |
| `MCP_ENABLED_TAGS` / `MCP_DISABLED_TAGS` | 以逗号分隔的标签允许/拒绝列表 | — |
| `PYTHONUNBUFFERED` | 无缓冲的stdout（推荐在容器中） | `1` |
### 工具切换
每个动作路由工具都可以通过其切换环境变量来禁用（设置为 `false`）。
完整的列表在上面的 [可用MCP工具](#available-mcp-tools) 表中。
| 变量 | 描述 | 默认值 |
|----------|-------------|---------|
| `COLLECTION_MANAGEMENTTOOL` | 启用集合管理工具 | `True` |
| `SEARCHTOOL` | 启用搜索工具 | `True` |
### 遥测和治理
| 变量 | 描述 | 默认值 |
|----------|-------------|---------|
| `ENABLE_OTEL` | 启用OpenTelemetry导出 | `True` |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP收集器端点 | — |
| `OTEL_EXPORTER_OTLP_PUBLIC_KEY` / `OTEL_EXPORTER_OTLP_SECRET_KEY` | OTLP身份验证密钥 | — |
| `OTEL_EXPORTER_OTLP_PROTOCOL` | OTLP协议（例如 `http/protobuf` ） | — |
| `EUNOMIA_TYPE` | 授权模式：`none` 、 `embedded` 、 `remote` | `none` |
| `EUNOMIA_POLICY_FILE` | 嵌入式策略文件 | `mcp_policies.json` |
| `EUNOMIA_REMOTE_URL` | 远程Eunomia服务器URL | — |
### 代理CLI（仅限完整 `[agent]` 运行时）
| 变量 | 描述 | 默认值 |
|----------|-------------|---------|
| `MCP_URL` | 代理连接到的MCP服务器的URL | `http://localhost:8000/mcp` |
| `PROVIDER` | LLM提供商（例如 `openai` ） | `openai` |
| `MODEL_ID` | 模型ID（例如 `gpt-4o` ） | `gpt-4o` |
| `ENABLE_WEB_UI` | 提供AG-UI Web界面 | `True` |
参见 [.env.example](.env.example) 获取复制粘贴的起始点。
## 代理
本仓库包含一个完全集成的Pydantic AI图代理。它通过 **代理控制协议（ACP）** 进行通信，并与 **代理Web UI（AG-UI）** 和终端界面无缝交互。
### 运行代理CLI
要启动交互式命令行代理：
```bash
# 设置凭证
export VECTOR_URL="your_value"
export EMBEDDING_MODEL_ID="your_value"
export CHUNK_SIZE="your_value"
export VECTOR_API_KEY="your_value"
# 运行代理服务器
vector-agent --provider openai --model-id gpt-4o
```
### Docker Compose编排
以下 `docker/agent.compose.yml` 配置代理、Web UI和终端界面：
```yml
version: '3.8'
services:
vector-mcp-mcp:
image: blubird28/vector-mcp:mcp
container_name: vector-mcp-mcp
hostname: vector-mcp-mcp
restart: always
env_file:
- ../.env
environment:
- PYTHONUNBUFFERED=1
- HOST=0.0.0.0
- PORT=8000
- TRANSPORT=streamable-http
ports:
- "8000:8000"
healthcheck:
test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
interval: 30s
timeout: 10s
retries: 3
start_period: 10s
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"
vector-mcp-agent:
image: blubird28/vector-mcp:latest
container_name: vector-mcp-agent
hostname: vector-mcp-agent
restart: always
depends_on:
- vector-mcp-mcp
env_file:
- ../.env
command: [ "vector-agent" ]
environment:
- PYTHONUNBUFFERED=1
- HOST=0.0.0.0
- PORT=9023
- MCP_URL=http://vector-mcp-mcp:8000/mcp
- PROVIDER=${PROVIDER:-openai}
- MODEL_ID=${MODEL_ID:-gpt-4o}
- ENABLE_WEB_UI=True
- ENABLE_OTEL=True
ports:
- "9023:9023"
healthcheck:
test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:9023/health')"]
interval: 30s
timeout: 10s
retries: 3
start_period: 10s
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"
```
有关图形节点架构解释、自定义技能配置和代理跟踪指南，请参阅 [docs/agent.md](docs/agent.md)。
---
## 安全与治理
直接构建在企业级 [`agent-utilities`](https://github.com/Knuckles-Team/agent-utilities) 核心之上，支持标准安全参数：
### 访问控制和策略强制执行
- **Eunomia策略：** 细粒度、基于策略的工具授权。支持 `none` 、本地 `embedded` （ `mcp_policies.json` ）或集中式 `remote` 模式。
- **OIDC令牌委托：** 符合RFC 8693令牌交换，用于从Web UI / ACP → 代理 → MCP流动身份验证用户凭证。
- **作用域凭证：** 执行上下文运行受限于特定调用者身份。
### 运行时安全网格
| 功能 | 功能 | 启用 |
|---------|---------------|------------|
| **工具防护** | 敏感性检查，具有人工干预验证 | 默认启用 |
| **提示注入防御** | 输入扫描、重复次数监控和递归循环阻止 | 默认启用 |
| **上下文安全防护** | 卡死循环检测器和上下文溢出预警 | 默认启用 |
---
## 安装
选择与您期望运行的内容相匹配的附加组件：
| 附加组件 | 安装内容 | 使用场景 |
|-------|----------|----------|
| `vector-mcp[mcp]` | 仅安装精简的MCP服务器 (`agent-utilities[mcp]` — FastMCP/FastAPI) | 您仅运行 **MCP服务器**（最小安装/镜像） |
| `vector-mcp[agent]` | 完整代理运行时 (`agent-utilities[agent,logfire]` — Pydantic AI + 知识图引擎) | 您运行 **集成代理** |
| `vector-mcp[all]` | 所有内容（`mcp` + 所有向量后端 + `agent`） | 开发/两种界面 |
```bash
# 仅安装MCP服务器（推荐用于工具托管 — 精简依赖）
uv pip install "vector-mcp[mcp]"
# 完整代理运行时（Pydantic AI + 知识图引擎）
uv pip install "vector-mcp[agent]"
# 安装所有内容（开发）
uv pip install "vector-mcp[all]" # 或：python -m pip install "vector-mcp[all]"
```
### 容器镜像（`:mcp` vs `:agent`）
一个多阶段的 `docker/Dockerfile` 构建了两个合适大小的镜像，通过 `--target` 参数选择：
| 镜像标签 | 构建目标 | 内容 | 入口点 |
|-----------|--------------|----------|------------|
| `blubird28/vector-mcp:mcp` | `--target mcp` | `vector-mcp[mcp]` — **精简**，无引擎/`pydantic-ai`/`dspy`/`llama-index`/`tree-sitter` | `vector-mcp` |
| `blubird28/vector-mcp:latest` | `--target agent`（默认） | `vector-mcp[agent]` — **完整**代理运行时 + 知识图引擎 | `vector-agent` |
```bash
docker build --target mcp -t blubird28/vector-mcp:mcp docker/ # 精简MCP服务器
docker build --target agent -t blubird28/vector-mcp:latest docker/ # 完整代理
```
`docker/mcp.compose.yml` 运行精简的 `:mcp` 服务器；`docker/agent.compose.yml` 运行代理（`:latest`）和一个位于同一位置的 `:mcp` 边车。
### 知识图数据库（`epistemic-graph`）
**完整代理**（`[agent]` / `:latest`）嵌入了 **知识图引擎**（通过 `agent-utilities[agent]` 传递）。对于生产环境 — 或在多个代理之间共享一个知识图 — 运行 **知识图作为其自己的数据库容器**，并将代理指向它而不是嵌入它。部署方法（单节点 + Raft高可用性）、连接配置和完整的数据库架构（带图表）都在 [知识图部署指南](https://knuckles-team.github.io/epistemic-graph/deployment/) 中有详细说明。精简的 `[mcp]` 服务器 **不需要** 该数据库。
---
## 贡献
欢迎贡献！请在提交拉取请求之前通过执行本地检查确保代码质量：
- 使用 `ruff format .` 格式化代码
- 使用 `ruff check .` 检查代码
- 使用 `mypy .` 验证类型安全性
- 使用 `pytest` 执行测试套件
<!-- BEGIN agent-os-genesis-deploy （生成；请勿在标记之间编辑） -->
## 使用 `agent-os-genesis` 部署
该软件包可以通过 **`agent-os-genesis`** 通用技能为您提供支持 — 它的 *单软件包部署模式*：它选择您的安装方法、将机密数据播种到 OpenBao/Vault（或 `.env`）、信任您的企业CA、注册MCP服务器并验证它 — 与建立整个Agent OS的机制相同，但仅限于此软件包。要求您的代理 **"使用agent-os-genesis部署 `vector-mcp`"**。
| 安装模式 | 命令 |
|------|---------|
| 裸金属，生产（PyPI） | `uvx vector-mcp` · 或 `uv tool install vector-mcp` |
| 裸金属，开发（可编辑） | `uv pip install -e ".[all]"` · 或 `pip install -e ".[all]"` |
| 容器，生产 | 通过docker-compose / swarm / podman / podman-compose / kubernetes部署 `blubird28/vector-mcp:latest` |
| 容器，开发（可编辑） | 部署 `docker/compose.dev.yml`（源代码挂载到 `/src`；重启时编辑生效） |
机密数据通过 `vault_sync` 读取现有数据并播种 — 您只会被提示填写缺失的内容。
<!-- END agent-os-genesis-deploy -->
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器