# Milvus MCP Server

本程序是一个为大语言模型设计、遵循 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 协议的 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. 源码构建

```bash
npm install
npm run build
```

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

### 2. 全局本地安装

```bash
npm link
```

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

---

## 📝 配置文件

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

### 配置文件示例

```json
{
  "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 |

---

## 🚀 启动与使用

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

**参数列表：**
- `-c, --config <path>`：配置文件路径（必填）。

---

## 🧠 MCP 客户端配置示例

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

```json
{
  "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[], 可选): 要返回的字段列表。