内容
# 矢量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)）。
#### stdio传输（推荐用于本地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`）或从 **远程部署** 进行消费。
部署指南提供了适用于所有四种传输方式的完整、可复制的 `mcp_config.json` 配置文件：
- **本地容器 / uv** - 从 `mcp_config.json` 启动服务器，使用 `uvx` 、 `docker run` 或 `podman run` ，或指向本地流式HTTP容器，使用 `url`。
- **远程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基础网址 |
| `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` | 矢量数据库/嵌入端点的基准网址 | `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和终端界面：
```yaml
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) 核心之上，支持标准的 security 参数：
### 访问控制和策略强制执行
- **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 HA）、连接配置和完整的数据库架构（带有图表）都在 [认知图部署指南](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
连接信息
猜你喜欢
暂无推荐服务器