内容
# Azure AI Search MCP 服务器
用于向兼容 MCP 的客户端公开 Azure AI Search 检索功能的自定义模型上下文协议（MCP）服务器。
该服务器为关键词搜索、语义搜索、向量搜索、混合搜索、语义混合搜索和 Azure AI Search 知识库检索提供了一个用户友好的工具层。
## 何时使用此项目
当您需要一个 MCP 服务器，通过一组小而稳定的工具集公开多个 Azure AI Search 检索模式时，请使用此项目。
Azure AI Search 知识库还公开了一个原生的 MCP 端点，用于直接进行知识库检索：
```text
https://<your-service-name>.search.windows.net/knowledgebases/<your-knowledge-base-name>/mcp?api-version=<api-version>
```
此原生端点适用于知识库对象，不适用于普通搜索索引。Microsoft 在 [使用检索操作或 MCP 端点查询知识库](https://learn.microsoft.com/azure/search/agentic-retrieval-how-to-retrieve#call-the-mcp-endpoint) 中对此进行了记录。
如果您的客户端只需要知识库检索，原生端点就足够了。如果您还需要直接访问传统的搜索模式，例如关键词、语义、向量、混合和语义混合检索，则此项目非常有用。
## 功能
- 关键词搜索，支持筛选器、选定字段和搜索字段范围。
- 语义搜索，支持语义排名、标题和答案。
- 使用索引向量化器进行向量搜索。
- 混合搜索，结合关键词和向量检索。
- 语义混合搜索，具有混合检索和语义重新排序。
- 通过 Azure AI Search Python SDK 预览客户端进行知识库检索。
- 面向常见用例的聚焦工具参数，支持低频率的 SDK 调整，位于 `advanced_options` 下。
## 快速入门
### 1. 安装
```bash
git clone https://github.com/HeyJiqingCode/AzureAISearchMCP.git
cd AzureAISearchMCP
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```
### 2. 配置
创建 `.env` 文件：
```bash
AZURE_SEARCH_ENDPOINT=https://your-search-service.search.windows.net
AZURE_SEARCH_QUERY_KEY=your-query-key
AZURE_SEARCH_ADMIN_KEY=your-admin-key
# 可选
# MCP_HOST=0.0.0.0
# MCP_PORT=8000
# AZURE_SEARCH_TIMEOUT=30
# AZURE_SEARCH_AGENTIC_TIMEOUT=90
# AZURE_SEARCH_AGENTIC_TIMEOUT_BUFFER=30
```
传统搜索工具使用 `AZURE_SEARCH_QUERY_KEY`。`agentic_retrieval` 工具使用 `AZURE_SEARCH_ADMIN_KEY`。
### 3. 运行
对于使用 stdio 的本地 MCP 客户端：
```bash
python src/mcp/server.py
```
对于 Streamable HTTP：
```bash
python src/mcp/server.py --transport streamable-http --host 0.0.0.0 --port 8000
```
对于 SSE：
```bash
python src/mcp/server.py --transport sse --host 0.0.0.0 --port 8000
```
您可以在环境中设置 `AZURE_SEARCH_ENDPOINT`，也可以在启动服务器时传递 `--endpoint`。
### 4. 连接 MCP 客户端
Streamable HTTP 配置示例：
```json
{
"mcpServers": {
"AzureAISearch": {
"type": "streamableHttp",
"url": "http://127.0.0.1:8000/mcp"
}
}
}
```
如果服务器部署在需要身份验证的网关或代理后面，请在 MCP 客户端中配置所需的头部。
## 配置
| 设置 | 必需 | 使用者 | 描述 |
| --- | --- | --- | --- |
| `AZURE_SEARCH_ENDPOINT` | 是 | 所有工具 | Azure AI Search 服务端点。 |
| `AZURE_SEARCH_QUERY_KEY` | 是 | 搜索工具 | 关键词、语义、向量、混合和语义混合工具的查询密钥。 |
| `AZURE_SEARCH_ADMIN_KEY` | Agentic 需要 | `agentic_retrieval` | 知识库检索使用的管理密钥。请将其视为敏感信息。 |
| `MCP_HOST` | 否 | HTTP 传输 | `http`、`streamable-http` 和 `sse` 使用的主机。默认：`0.0.0.0`。 |
| `MCP_PORT` | 否 | HTTP 传输 | `http`、`streamable-http` 和 `sse` 使用的端口。默认：`8000`。 |
| `AZURE_SEARCH_TIMEOUT` | 否 | 搜索工具 | 此 MCP 服务器等待标准搜索调用的时间。默认：`30`。 |
| `AZURE_SEARCH_AGENTIC_TIMEOUT` | 否 | `agentic_retrieval` | 此 MCP 服务器等待 Agentic 检索调用的时间。默认：`90`。 |
| `AZURE_SEARCH_AGENTIC_TIMEOUT_BUFFER` | 否 | `agentic_retrieval` | 设置 `max_runtime_seconds` 时添加的额外等待时间。默认：`30`。 |
### 超时设置
标准搜索工具使用 `AZURE_SEARCH_TIMEOUT`。
Agentic 检索使用两个超时层：
- `max_runtime_seconds`：工具参数，要求 Azure AI Search 在指定秒数后停止知识库检索操作。
- `AZURE_SEARCH_AGENTIC_TIMEOUT`：此 MCP 服务器愿意等待 Azure AI Search 响应的时间。
- `AZURE_SEARCH_AGENTIC_TIMEOUT_BUFFER`：当设置 `max_runtime_seconds` 时添加的额外等待时间。
示例：如果 `max_runtime_seconds=60` 且 `AZURE_SEARCH_AGENTIC_TIMEOUT_BUFFER=30`，则此 MCP 服务器最多等待 90 秒。这给了 Azure AI Search 60 秒的运行时间，再加上 30 秒的网络和响应开销。
## 工具
| 工具 | 使用场景 |
| --- | --- |
| `simple_search` | 需要标准关键词或 BM25 搜索时使用。 |
| `semantic_search` | 需要语义排名、标题或答案的语义配置索引时使用。 |
| `vector_search` | 需要使用集成向量化进行仅向量相似性搜索时使用。 |
| `hybrid_search` | 需要在一查询中进行关键词和向量检索时使用。 |
| `semantic_hybrid_search` | 需要混合检索加上语义重新排序、标题或答案时使用。 |
| `agentic_retrieval` | 需要 Azure AI Search 知识库 / Agentic 检索时使用。 |
搜索工具响应包括：
- `documents`：标准化的搜索结果，包括字段，如 `@search.score`（当返回时）。
- `count`：可用的总文档数。
- `answers`、`captions`、`facets`：当 Azure AI Search 返回时包含。
- `continuation_token`：当 SDK 报告继续令牌时包含。
## 工具参考
### `simple_search`
对索引使用简单查询语法进行关键词搜索。
```text
simple_search(index_name, query, top=5, skip=0, search_fields="", select="", filter="", search_mode="any", advanced_options="")
```
```json
{
"tool": "simple_search",
"arguments": {
"index_name": "knowledge-base",
"query": "如何为 Windows PC 配置 Wi-Fi？",
"top": 3,
"select": "title,body"
}
}
```
### `semantic_search`
对启用语义配置的索引进行语义重新排序搜索。
```text
semantic_search(index_name, query, semantic_configuration, top=5, skip=0, select="", filter="", query_caption="extractive", query_caption_highlight_enabled=True, query_answer="", advanced_options="")
```
```json
{
"tool": "semantic_search",
"arguments": {
"index_name": "knowledge-base",
"query": "如何为 Windows PC 配置 Wi-Fi？",
"semantic_configuration": "default",
"top": 3
}
}
```
### `vector_search`
使用集成向量化进行仅向量相似性搜索。
```text
vector_search(index_name, vector_fields, vector_text, k=10, select="", filter="", advanced_options="")
```
```json
{
"tool": "vector_search",
"arguments": {
"index_name": "knowledge-base",
"vector_fields": "text_vector",
"vector_text": "如何为 Windows PC 配置 Wi-Fi？",
"k": 5,
"select": "title,summary"
}
}
```
### `hybrid_search`
使用 Reciprocal Rank Fusion 进行混合关键词和向量搜索。
```text
hybrid_search(index_name, query, vector_fields, vector_text, k=10, top=10, select="", filter="", search_fields="", advanced_options="")
```
```json
{
"tool": "hybrid_search",
"arguments": {
"index_name": "knowledge-base",
"query": "如何为 Windows PC 配置 Wi-Fi？",
"vector_fields": "text_vector",
"vector_text": "如何为 Windows PC 配置 Wi-Fi？",
"k": 20,
"top": 5,
"search_fields": "title,body"
}
}
```
### `semantic_hybrid_search`
具有语义重新排序、标题和答案的混合检索。
```text
semantic_hybrid_search(index_name, query, vector_fields, semantic_configuration, vector_text, k=50, top=10, select="", filter="", search_fields="", query_caption="extractive", query_caption_highlight_enabled=True, query_answer="", advanced_options="")
```
```json
{
"tool": "semantic_hybrid_search",
"arguments": {
"index_name": "knowledge-base",
"query": "如何为 Windows PC 配置 Wi-Fi？",
"vector_fields": "text_vector",
"semantic_configuration": "default",
"vector_text": "如何为 Windows PC 配置 Wi-Fi？",
"k": 30,
"top": 5,
"query_caption": "extractive",
"query_answer": "extractive"
}
}
```
### `advanced_options`
`advanced_options` 是一个 JSON 对象字符串，用于调整不常见的 SDK 设置。不支持的键会被拒绝。
常见键：
```text
debug
```
语义键：
```text
semantic_query, query_answer_count, query_answer_threshold, semantic_error_mode, semantic_max_wait_in_milliseconds
```
向量键：
```text
exhaustive, weight, oversampling, filter_override, vector_filter_mode, vector_similarity_threshold, search_score_threshold
```
混合键：
```text
max_text_recall_size, count_and_facet_mode
```
示例：
```json
{
"advanced_options": "{\"max_text_recall_size\":100,\"vector_filter_mode\":\"preFilter\"}"
}
```
## Agentic 检索
`agentic_retrieval` 通过 Python SDK 预览客户端运行 Azure AI Search 知识库检索。
```text
agentic_retrieval(knowledge_base_name, query, intent_query="", reasoning_effort="low", output_mode="answerSynthesis", include_activity=True, max_runtime_seconds=0, max_output_size=0, max_output_documents=0, knowledge_source_configs="", query_source_authorization="")
```
常用参数：
| 参数 | 描述 |
| --- | --- |
| `knowledge_base_name` | Azure AI Search 知识库名称。 |
| `query` | 用户问题或检索查询。 |
| `reasoning_effort` | `minimal`、`low` 或 `medium`。默认：`low`。 |
| `output_mode` | `answerSynthesis` 或 `extractedData`。默认：`answerSynthesis`。 |
| `include_activity` | 包括查询规划和检索活动详情。 |
| `max_runtime_seconds` | 要求 Azure AI Search 限制服务侧检索运行时。 |
| `max_output_size` | 限制基础响应有效载荷大小。 |
| `max_output_documents` | 限制最终基础文档数量。 |
| `knowledge_source_configs` | JSON 对象或 JSON 数组字符串，用于运行时知识源设置。 |
| `query_source_authorization` | 查询时权限执行的端用户令牌。 |
`answerSynthesis` 需要基于消息的检索，因此请使用 `reasoning_effort="low"` 或 `reasoning_effort="medium"`。对于直接语义意图检索，请使用 `reasoning_effort="minimal"` 和 `output_mode="extractedData"`。
响应包括一个方便的 `answer`、格式化的 `references`、SDK 响应字段（`response`、`activity`、`raw_references`、`metadata`）以及用于调用的标准化 SDK 请求正文。
### 基本示例
```json
{
"tool": "agentic_retrieval",
"arguments": {
"knowledge_base_name": "kb-support",
"query": "如何重置我的 VPN 密码？",
"reasoning_effort": "low",
"output_mode": "answerSynthesis",
"include_activity": true
}
}
```
### 最小意图示例
```json
{
"tool": "agentic_retrieval",
"arguments": {
"knowledge_base_name": "kb-support",
"query": "如何重置我的 VPN 密码？",
"reasoning_effort": "minimal",
"output_mode": "extractedData"
}
}
```
### 知识源配置
使用 `knowledge_source_configs` 指定一个或多个具有每个源设置的知识源。传递 JSON 对象或 JSON 数组的字符串。
常见的知识源配置键：
| 键 | 类型 | 描述 |
| --- | --- | --- |
| `knowledgeSourceName` | 字符串 | 知识源名称。 |
| `kind` | 字符串 | 源类型，例如 `searchIndex`、`web`、`azureBlob`、`indexedOneLake` 或 SDK 支持的另一个预览种类。 |
| `includeReferences` | 布尔值 | 包括文档引用。 |
| `includeReferenceSourceData` | 布尔值 | 在引用中包括源数据。 |
| `rerankerThreshold` | 浮点数 | 最低重新排序分数阈值。 |
| `alwaysQuerySource` | 布尔值 | 当所选源类型支持时，强制查询。 |
| `failOnError` | 布尔值 | 将此源视为必需的。 |
| `maxOutputDocuments` | 整数 | 此源的候选文档数量上限。 |
| `filterAddOn` | 字符串 | 运行时 OData 筛选器，用于搜索索引知识源。 |
| `count`、`freshness`、`language`、`market` | 混合 | Web 源控件。 |
| `filterExpressionAddOn` | 字符串 | SharePoint 样式源的 KQL 筛选器表达式。 |
单个源：
```json
{
"tool": "agentic_retrieval",
"arguments": {
"knowledge_base_name": "kb-support",
"query": "如何重置我的 VPN 密码？",
"knowledge_source_configs": "{\"knowledgeSourceName\":\"ks-docs\",\"kind\":\"searchIndex\",\"includeReferences\":true}"
}
}
```
多个源：
```json
{
"tool": "agentic_retrieval",
"arguments": {
"knowledge_base_name": "kb-support",
"query": "最新的安全更新",
"knowledge_source_configs": "[{\"knowledgeSourceName\":\"ks-docs\",\"kind\":\"searchIndex\",\"includeReferences\":true},{\"knowledgeSourceName\":\"ks-web\",\"kind\":\"web\",\"count\":10,\"freshness\":\"week\"}]"
}
}
```
搜索字段选择由 Azure AI Search 基于知识库和索引配置处理。
## Docker
构建镜像：
```bash
docker build -t azure-ai-search-mcp:2.0.0 -f Dockerfile .
```
运行容器：
```bash
docker run -itd -p 8000:8000 --name AzureAISearch \
-e AZURE_SEARCH_ENDPOINT=https://your-search-service.search.windows.net \
-e AZURE_SEARCH_QUERY_KEY=your-query-key \
-e AZURE_SEARCH_ADMIN_KEY=your-admin-key \
-e MCP_HOST=0.0.0.0 \
-e MCP_PORT=8000 \
azure-ai-search-mcp:2.0.0
```
## 更多详情
请参阅 [Azure AI Search 的 MCP 服务器](https://heyjiqing.notion.site/MCP-Server-for-Azure-AI-Search-294de7b6e4e8805faccad1f60cc255e2?pvs=74)
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器