Metadata-Version: 2.4
Name: milvus-text-search-mcp
Version: 0.4.0
Summary: MCP Server for semantic text search in Milvus: converts natural language to vectors automatically, no manual vector input required.
License: MIT
Keywords: ai,embedding,mcp,milvus,semantic-search,vector-search
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: mcp>=1.0.0
Requires-Dist: openai>=1.0.0
Requires-Dist: pymilvus>=2.4.0
Description-Content-Type: text/markdown

# milvus-text-search-mcp

MCP Server for semantic text search in Milvus: converts natural language to vectors automatically — no manual vector input required.

将自然语言查询文本自动转换为向量嵌入，再执行 Milvus 向量相似度搜索。  
无需 Agent 手动传入 1024 维向量数组，解决了 `mcp-server-milvus` 的 `milvus-vector-search` 工具需要传入向量的限制。

## 安装

```bash
# 使用 uvx 直接运行（无需预装，推荐）
uvx milvus-text-search-mcp

# 或使用 uv tool install 预装
uv tool install milvus-text-search-mcp

# 或使用 pip
pip install milvus-text-search-mcp
```

## 配置（环境变量）

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `MILVUS_URI` | Milvus 服务地址 | `http://localhost:19530` |
| `EMBEDDING_API_BASE` | OpenAI 兼容 Embedding API 基础地址 | 无 |
| `EMBEDDING_API_KEY` | Embedding API 密钥（**必填**） | 无 |
| `EMBEDDING_MODEL` | Embedding 模型名称 | 无 |

> 支持任何 OpenAI 兼容的 Embedding API，如 SiliconFlow、Azure OpenAI、本地部署的 Ollama 等。

## 在 workmate 平台配置工具集

在工具集配置 JSON 中填写（替换为你的实际地址和密钥）：

```json
{
  "command": "uvx",
  "args": ["milvus-text-search-mcp"],
  "env": {
    "MILVUS_URI": "http://your-milvus-host:19530",
    "EMBEDDING_API_BASE": "https://your-embedding-api/v1",
    "EMBEDDING_API_KEY": "your-api-key",
    "EMBEDDING_MODEL": "your-embedding-model-name"
  },
  "timeout": 120
}
```

## 提供的工具

### `milvus_semantic_text_search`（核心工具）

将自然语言文本转换为向量后执行语义相似度搜索。

```python
# Agent 调用示例
milvus_semantic_text_search(
    query_text="有5年Java开发经验的后端工程师",
    collection_name="resumes_collection",
    top_k=10,
    filter_expr='age >= 25 && age <= 40',  # 可选
    output_fields="name,age,email"           # 可选
)
```

### `milvus_get_text_embedding`（辅助工具）

仅将文本转换为向量嵌入，不执行搜索。  
通常不需要直接调用，请优先使用 `milvus_semantic_text_search`。

## 与 mcp-server-milvus 的关系

| 工具集 | 输入 | 适用场景 |
|--------|------|---------|
| `mcp-server-milvus` | 需要 float 向量数组 | 已有向量的场景 |
| `milvus-text-search-mcp`（本包） | 自然语言文本 | 语义搜索场景（推荐） |

两者可同时配置给同一个数字员工，互补使用。

## License

MIT