vector-mcp

用于受治理的向量集合管理与检索的操作路由 MCP 与代理接口。 原生默认值为 epistemic-graph。安全的可选提供程序涵盖 PostgreSQL/pgvector、 Qdrant 和 MongoDB Atlas。

版本：3.1.0

受治理能力

• MCP 工具：vector_collection_management 和 vector_search

• 技能提供程序：整合的 vector-mcp-operations 工作流

• 本体提供程序：打包的向量检索本体

• 源连接器提供程序：只读向量集合清单预设

• 运行时配置：AgentConfig、环境变量和密钥引用

• 隐私姿态：不包含已检入的端点、凭据、个人身份信息或主机路径

Related MCP server: production-grade-mcp-agentic-system

安装

使用部署所需的最小附加集：

uvx --from 'vector-mcp[mcp]' vector-mcp

运行时需要 agent-utilities>=2.0.0 及其自包含的完整 epistemic-graph 引擎契约。仅使用裸数字或部分引擎配置文件不是 受支持的部署方式。

对于选定的存储提供程序：

uv add 'vector-mcp[postgres]'
uv add 'vector-mcp[qdrant]'
uv add 'vector-mcp[mongodb]'

all 附加项启用每个可用的可选提供程序，外加 agent、Langfuse 和 Logfire 运行时。生产镜像应仅安装其实际运行的提供程序。

MCP 配置

该包包含一个中立的代理启动配置，仅包含命令、 压缩工具模式和工具开关。运行时值继承自 AgentConfig，或由 操作员注入。关于底层 API 包装器、扩展模式绑定和 开发者 SDK 引用的详细说明，请参见 docs/index.md。

MCP

该服务器使用动态 Action-Routed 工具来优化令牌开销并最大化 IDE 兼容性。

可用 MCP 工具

由实时 MCP 服务器自动生成 — 请勿手动编辑。

压缩操作路由工具（MCP_TOOL_MODE=condensed）

2 个操作路由工具 · 0 个详细 1:1 工具。每个工具在其 <DOMAIN>TOOL 切换环境变量设为 false 时被禁用；MCP_TOOL_MODE 选择表面（**intent 默认* — 六个动词工具，按需加载的粒度集合 · condensed 操作路由 · verbose 1:1 · both）。自动生成 — 请勿手动编辑。*

详细的工具模式、参数形状和验证约束保留在使用指南中。

动态工具选择与可见性

该 MCP 服务器支持运行时动态工具集选择与可见性过滤。这允许您限制暴露的工具集，以防止撑爆 LLM 的上下文窗口。

您可以通过多种输入渠道配置工具过滤：

• CLI 参数： 在启动时传递 --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] 来添加 FastMCP / FastAPI，通过 agent-utilities[mcp]；所需的 Agent Utilities 核心 仍然承载 epistemic-graph[full]。[agent-runtime] 附加项额外 启用模型编排。

stdio 传输（本地 IDE — Cursor、Claude Desktop、VS Code）

{
  "mcpServers": {
    "vector-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "vector-mcp[mcp]",
        "vector-mcp"
      ],
      "env": {
        "MCP_TOOL_MODE": "intent",
        "COLLECTION_MANAGEMENTTOOL": "True",
        "DATABASE_TYPE": "epistemic_graph",
        "LLM_SSL_VERIFY": "False",
        "SEARCHTOOL": "True",
        "VECTOR_DB_TYPE": "epistemic_graph"
      }
    }
  }
}

运行时引用需要一个支持别名的启动器，例如 GraphOS。其他 启动器必须省略这些条目，并通过其自身的运行时密钥边界注入解析后的值。

Streamable-HTTP 传输（网络化 / 生产环境）

{
  "mcpServers": {
    "vector-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "vector-mcp[mcp]",
        "vector-mcp",
        "--transport",
        "streamable-http",
        "--port",
        "8000"
      ],
      "env": {
        "TRANSPORT": "streamable-http",
        "HOST": "127.0.0.1",
        "PORT": "8000",
        "MCP_TOOL_MODE": "intent",
        "COLLECTION_MANAGEMENTTOOL": "True",
        "DATABASE_TYPE": "epistemic_graph",
        "LLM_SSL_VERIFY": "False",
        "SEARCHTOOL": "True",
        "VECTOR_DB_TYPE": "epistemic_graph"
      }
    }
  }
}

或者，通过 url 连接到预部署的 Streamable-HTTP 实例：

{
  "mcpServers": {
    "vector-mcp": {
      "url": "http://localhost:8000/vector-mcp/mcp"
    }
  }
}

将经过审查的容器镜像作为最小权限的 stdio 子进程运行（无 监听器或已发布端口）：

docker run -i --rm \
  --read-only \
  --cap-drop=ALL \
  --security-opt=no-new-privileges \
  --pids-limit=256 \
  --tmpfs /tmp:rw,noexec,nosuid,nodev,size=64m \
  -e TRANSPORT=stdio \
  -e MCP_TOOL_MODE=intent \
  -e COLLECTION_MANAGEMENTTOOL=True \
  -e DATABASE_TYPE=epistemic_graph \
  -e LLM_SSL_VERIFY=False \
  -e SEARCHTOOL=True \
  -e VECTOR_DB_TYPE=epistemic_graph \
  registry.example.invalid/vector-mcp@sha256:<digest> vector-mcp

对于容器化网络 HTTP，请提供经过认证的 TLS 入口（或 直接 TLS）、精确的 MCP_ALLOWED_HOSTS，以及通过操作员拥有的部署配置文件提供的精确可信代理 CIDR 策略。生成器不会发出未经认证的非回环监听器。

由代码读取环境表面自动生成（MCP_TOOL_MODE + 包变量）— 请勿手动编辑。

其他部署选项

vector-mcp 也可以作为本地容器（Docker / Podman / uv）运行，或从远程部署中消费。 部署指南 提供了所有四种传输方式的完整可复制 mcp_config.json — stdio、streamable-http、 本地容器 / uv 和 远程 URL：

• 本地容器 / uv — 通过 uvx、docker run 或 podman run 从 mcp_config.json 启动服务器，或指向一个本地 streamable-http 容器的 url。

• 远程 URL — 连接到部署在 Caddy 后面的服务器，使用 https://vector-mcp.example.invalid/mcp 的 "url" 键。

环境变量

包环境变量

继承的 agent-utilities 变量（适用于每个连接器）

31 个包变量 + 20 个继承变量。从 .env.example + 共享的 agent-utilities 集合自动生成 — 请勿编辑。

服务器读取的每个变量，按用途分组。请参阅 .env.example 获取规范的、可直接复制粘贴的列表 — 包括原生 epistemic-graph 后端的 DATABASE_TYPE / GRAPH_SERVICE_SOCKET / GRAPH_SERVICE_AUTH_SECRET 连接设置。可选提供商（Postgres/Qdrant/Mongo/Chroma/Couchbase）的后端端点、数据库位置和凭据绝不会以 README 文档中的字面值或 MCP 工具参数形式出现 — 它们通过 AgentConfig 和 secret:///env:///vault:// 引用在运行时解析。

MCP 服务器 / 传输

工具开关

每个动作路由的工具都可以通过其开关环境变量（设置为 false）单独禁用。完整列表见上文 可用 MCP 工具 表。

遥测与治理

代理 CLI（仅完整 [agent] 运行时）

请参阅 .env.example 获取可直接复制粘贴的起点。

提供商与本体集成

该包通过 Python 入口点贡献其技能、提示词、本体和源连接器。集合清单连接器有意设计为只读，仅注册集合元数据，不注册文档或嵌入负载。

生成的连接器签名必须仅在观察到已安装的 MCP 模式并在运行时提供发布签名密钥后重新创建。绝不能将旧工具模式或本体的签名向前复制。

开发检查

不启动提供商的低成本检查：

python scripts/security_sanitizer.py
python scripts/security_contract.py --contract .security/security-contract.json validate
python -m compileall -q vector_mcp

提供商测试使用模拟的 SDK 边界，不进行网络调用。实时资格认证是单独的部署门禁，必须使用操作员提供的 AgentConfig 和密钥。

文档

• 安装

• 配置与隐私

• 部署

• 使用

• 架构概述

精简版 :mcp streamable-http 容器（docker/mcp.compose.yml）发布 :8000 并带有 /health 检查；完整的 compose 服务定义请参阅 部署。

许可证

请参阅 LICENSE。

使用 agent-utilities-deployment 部署

使用整合的 agent-utilities-deployment 工作流来配置此包。它选择已安装包、可编辑源码或不可变容器路径；仅在 AgentConfig 中记录运行时密钥和 TLS 配置文件引用；并运行 doctor、注册、策略、可观测性和回滚门禁。请让您的代理 "使用 agent-utilities-deployment 部署 vector-mcp"。

该仓库不嵌入任何部署配置文件、凭据值、证书路径或环境特定端点。请在运行时通过 AgentConfig 和配置的密钥提供程序提供这些内容。

安装

选择与您要运行的内容匹配的附加项：

# MCP server only (recommended for tool hosting — slim deps)
uv pip install "vector-mcp[mcp]"

# Full agent runtime (Pydantic AI + epistemic-graph engine)
uv pip install "vector-mcp[agent]"

# Everything (development)
uv pip install "vector-mcp[all]"      # or: python -m pip install "vector-mcp[all]"

容器镜像（:mcp 与 :agent）

一个多阶段 docker/Dockerfile 构建两个尺寸合适的镜像，通过 --target 选择：

docker build --target mcp   -t knucklessg1/vector-mcp:mcp    docker/   # slim MCP server
docker build --target agent -t knucklessg1/vector-mcp:latest docker/   # full agent

docker/mcp.compose.yml 运行精简版 :mcp 服务器；docker/agent.compose.yml 运行 agent（:latest），并附带一个同址的 :mcp 边车。

知识图谱数据库（epistemic-graph）

完整版 agent（[agent] / :latest）内嵌了 epistemic-graph 引擎（通过 agent-utilities[agent] 间接引入）。对于生产环境——或需要跨多个 agent 共享同一个知识图谱时—— 请将 epistemic-graph 作为独立的数据库容器运行，并让 agent 指向它，而不是内嵌使用。 部署方案（单节点 + Raft）、连接配置以及完整的数据库架构（含示意图）均记录在 epistemic-graph 部署指南 中。 精简版 [mcp] 服务器不需要数据库。

仓库所有者

参与贡献

欢迎贡献！请在提交拉取请求之前，先执行本地检查以确保代码质量：

• 使用 ruff format . 格式化代码

• 使用 ruff check . 检查代码

• 使用 mypy . 验证类型安全

• 使用 pytest 执行测试套件

使用 agent-os-genesis 部署

此包可以由 agent-os-genesis 通用技能为你完成部署（其单包部署模式）： 它会自动选择安装方式、将密钥写入 OpenBao/Vault（或 .env）、信任你的企业 CA、 注册 MCP 服务器并验证结果——这套机制与部署整个 Agent OS 所用的完全相同，只是范围仅限于 此包。你可以让 agent 执行 "使用 agent-os-genesis 部署 vector-mcp"。

密钥会通过 vault_sync 读取已有值并补充写入——只会提示你输入缺失的部分。