Milvus MCP Server

本程序是一个为大语言模型设计、遵循 Model Context Protocol (MCP) 协议的 Milvus 向量数据库接入服务。它可以作为大语言模型（如 Antigravity）的外部向量数据库交互工具。

支持 Milvus 2.6 向量数据库，内置 OpenAI 兼容的 Embedding 服务（如通义千问 text-embedding-v4），让大模型可以直接用自然语言进行语义搜索。

---

💡 功能亮点

1. 向量搜索：支持文本输入的语义搜索（自动 Embedding）和原始向量搜索。
2. 内置 Embedding：集成 OpenAI 兼容端点，大模型传入文本即自动转换为向量，无需外部 Embedding 服务。
3. Collection 全生命周期管理：创建、查看、删除 Collection，创建时自动建索引并加载。
4. 数据读写：支持向量数据插入和按条件删除。
5. 多连接管理：通过 JSON 配置文件定义多个命名连接，一个 MCP Server 实例即可服务多个 Milvus 实例。
6. 安全设计：drop_collection 和 delete_entities 作为独立工具可在 MCP 客户端单独开关；drop_collection 额外需要 confirmDrop=true 参数做双重保险。
7. 混合搜索：支持向量相似度搜索 + 标量过滤的组合查询。

---

⚙️ 运行环境要求

1. Node.js 环境：要求 Node.js 版本为 v18 或更高版本。
2. Milvus 实例：需要可访问的 Milvus 2.6 服务实例。
3. Embedding API：需要一个 OpenAI 兼容的 Embedding 服务端点（如通义千问百炼平台）。
4. 依赖包：在运行机器上需要执行 npm install --omit=dev 安装依赖。

---

🛠 安装与构建

1. 源码构建

npm install
npm run build

编译产物会存放在 ./dist 目录中。

2. 全局本地安装

npm link

执行完毕后，可以在系统任意处使用全局命令 milvus-mcp-server 快速唤起该服务。

---

📝 配置文件

使用 JSON 文件配置 Milvus 连接和 Embedding 服务。

配置文件示例

{
  "connections": [
    {
      "name": "my-milvus",
      "address": "localhost:19530",
      "username": "root",
      "password": "Milvus",
      "database": "default",
      "description": "本地开发 Milvus 实例，存储文档和图片的向量索引"
    }
  ],
  "embedding": {
    "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
    "apiKey": "sk-your-api-key",
    "model": "text-embedding-v4",
    "dimensions": 1024
  }
}

连接字段说明

字段	类型	必填	说明
name	string	✅	连接的唯一标识名称
address	string	✅	Milvus 服务地址，格式 host:port
username	string	✅	用户名
password	string	✅	密码
database	string	❌	数据库名，默认 "default"
description	string	❌	连接的业务描述

Embedding 字段说明

字段	类型	必填	说明
baseUrl	string	✅	OpenAI 兼容 API 端点
apiKey	string	✅	API Key
model	string	✅	模型名称，如 "text-embedding-v4"
dimensions	number	✅	输出向量维度。text-embedding-v4 支持：2048, 1536, 1024, 768, 512, 256, 128, 64

---

🚀 启动与使用

milvus-mcp-server --config <path-to-config.json>

参数列表：

• -c, --config <path>：配置文件路径（必填）。

---

🧠 MCP 客户端配置示例

以常规 MCP Client（如 Antigravity）的配置为例：

{
  "mcpServers": {
    "MilvusMCP": {
      "command": "node",
      "args": [
        "绝对路径/milvus_mcp_server/dist/index.js",
        "--config", "绝对路径/milvus-config.json"
      ]
    }
  }
}

---

🧰 模型所能调用的工具 (Tools)

1. list_milvus_connections

• 说明：列出所有配置的 Milvus 连接信息（脱敏，不含密码）。
• 参数：无。

2. list_collections

• 说明：列出指定连接下所有的 Collection。
• 参数：
  • connectionName (String): 目标连接名称。

3. describe_collection

• 说明：获取 Collection 的详细 schema 信息，包含字段定义、索引、行数统计。
• 参数：
  • connectionName (String): 目标连接名称。
  • collectionName (String): Collection 名称。

4. create_collection

• 说明：创建新 Collection。自动为向量字段创建 AUTOINDEX 索引并加载 Collection，使其立即可搜索。
• 参数：
  • connectionName (String): 目标连接名称。
  • collectionName (String): 新 Collection 名称。
  • description (String, 可选): Collection 描述。
  • fields (Array): 字段定义数组，每项包含 name, dataType, isPrimaryKey?, autoId?, dimension?, maxLength?, description?。

5. drop_collection

• 说明：永久删除一个 Collection 及其所有数据。不可逆操作。
• 参数：
  • connectionName (String): 目标连接名称。
  • collectionName (String): 要删除的 Collection 名称。
  • confirmDrop (Boolean): 必须设为 true 才能执行删除。安全双重确认机制。
• 开关控制：该工具可在 MCP 客户端中单独启用或禁用。

6. insert_vectors

• 说明：向 Collection 插入数据。每条数据为一个 JSON 对象，包含各字段值（包括向量字段）。
• 参数：
  • connectionName (String): 目标连接名称。
  • collectionName (String): 目标 Collection 名称。
  • data (Array): 数据数组。

7. delete_entities

• 说明：按过滤表达式删除实体。
• 参数：
  • connectionName (String): 目标连接名称。
  • collectionName (String): 目标 Collection 名称。
  • filter (String): Milvus 过滤表达式，如 'id in [1, 2, 3]'。
• 开关控制：该工具可在 MCP 客户端中单独启用或禁用。

8. vector_search

• 说明：向量相似度搜索。支持传入文本（自动调用 Embedding 服务转为向量）或原始向量。
• 参数：
  • connectionName (String): 目标连接名称。
  • collectionName (String): 目标 Collection 名称。
  • text (String, 可选): 搜索文本，与 vector 二选一。
  • vector (Number[], 可选): 原始搜索向量，与 text 二选一。
  • topK (Number, 可选): 返回条数，默认 10。
  • filter (String, 可选): 标量过滤表达式。
  • outputFields (String[], 可选): 要返回的字段列表。

9. query_entities

• 说明：按标量条件查询实体，不涉及向量搜索。
• 参数：
  • connectionName (String): 目标连接名称。
  • collectionName (String): 目标 Collection 名称。
  • filter (String): Milvus 过滤表达式。
  • outputFields (String[], 可选): 要返回的字段列表。
  • limit (Number, 可选): 最大返回条数，默认 100。

10. hybrid_search

• 说明：向量搜索 + 标量过滤的组合查询。与 vector_search 的区别在于 filter 为必填参数。
• 参数：
  • connectionName (String): 目标连接名称。
  • collectionName (String): 目标 Collection 名称。
  • text (String, 可选): 搜索文本，与 vector 二选一。
  • vector (Number[], 可选): 原始搜索向量，与 text 二选一。
  • filter (String): 必填，标量过滤表达式。
  • topK (Number, 可选): 返回条数，默认 10。
  • outputFields (String[], 可选): 要返回的字段列表。