使用说明

Azure AI搜索MCP服务器

模型上下文协议（MCP）服务器，将Azure AI搜索功能集成到代理工作流中。该服务器为AI代理提供语义搜索、混合搜索、文本搜索和文档检索工具。

特性

🔍 语义搜索：理解上下文和含义的人工智能搜索
🔀 混合搜索：结合全文和矢量搜索以获得平衡的结果
📝 文本搜索：传统的基于关键字的搜索
🔎 筛选的搜索：使用OData筛选器表达式进行搜索
📄 文档提取：按ID检索特定文档
📊 索引架构资源：访问索引字段定义和元数据

安装

作为NPM包

npm install azure-ai-search-mcp

来源

git clone https://github.com/tomgutt/azure-ai-search-mcp.git
cd azure-ai-search-mcp
npm install
npm run build

配置

环境变量

创建一个 .env 在项目根目录中创建文件或设置以下环境变量：

AZURE_SEARCH_ENDPOINT=https://your-search-service.search.windows.net
AZURE_SEARCH_API_KEY=your-api-key-here
AZURE_SEARCH_INDEX_NAME=your-index-name

# Optional: Comma-separated list of fields to exclude from search results
# Default: content,content_vector
AZURE_SEARCH_EXCLUDE_FIELDS=content,content_vector,comments,custom_fields

字段排除：

AZURE_SEARCH_EXCLUDE_FIELDS：控制从搜索工具结果中排除哪些字段（语义、混合、文本、筛选）
这 fetch_document 工具总是只排除 content 和 content_vector 字段
如果未设置，则默认为： content,content_vector
根据您的需求进行定制（例如。， content,content_vector 为了最小化排除）

所需Azure资源

Azure人工智能搜索服务：在Azure门户中创建搜索服务
搜索索引：使用您的数据配置索引
API密钥：从Azure门户获取管理员或查询密钥

增强语义搜索的可选功能：

语义配置：启用Azure的语义排序器（推荐但不是必需的）
向量化器：启用基于向量的语义搜索（无需语义配置即可工作）

用法

与MCP检查员一起

使用MCP检查器测试服务器：

npm run inspector

使用克劳德桌面

添加到您的Claude Desktop配置文件中：

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "azure-ai-search": {
      "command": "npx",
      "args": ["@tomgutt/azure-ai-search-mcp"],
      "env": {
        "AZURE_SEARCH_ENDPOINT": "https://your-search-service.search.windows.net",
        "AZURE_SEARCH_API_KEY": "your-api-key-here",
        "AZURE_SEARCH_INDEX_NAME": "your-index-name",
        "AZURE_SEARCH_EXCLUDE_FIELDS": "content,content_vector,comments,custom_fields"
      }
    }
  }
}

与其他MCP客户端

通过stdio运行服务器：

export AZURE_SEARCH_ENDPOINT="https://your-search-service.search.windows.net"
export AZURE_SEARCH_API_KEY="your-api-key-here"
export AZURE_SEARCH_INDEX_NAME="your-index-name"
node build/index.js

可用工具

1. `semantic_search`

执行基于人工智能的语义搜索，理解上下文和含义。使用或不使用语义配置-如果语义配置不可用，将使用矢量器。

参数：

query （字符串，必填）：搜索查询
top （数字，可选）：返回的最大结果数（默认值：30）

退货： 文档摘要中未指定字段 AZURE_SEARCH_EXCLUDE_FIELDS （默认值： content, content_vector，中指定的其他字段 AZURE_SEARCH_EXCLUDE_FIELDS)

例子：

{
  "query": "machine learning algorithms",
  "top": 5
}

2. `hybrid_search`

结合全文和矢量搜索以获得平衡的结果。

参数：

query （字符串，必填）：搜索查询
top （数字，可选）：返回的最大结果数（默认值：30）

退货： 文档摘要中未指定字段 AZURE_SEARCH_EXCLUDE_FIELDS （默认值： content, content_vector，中指定的其他字段 AZURE_SEARCH_EXCLUDE_FIELDS)

例子：

{
  "query": "artificial intelligence trends",
  "top": 30
}

3. `text_search`

传统的基于关键字的文本搜索。

参数：

query （字符串，必填）：搜索查询
top （数字，可选）：返回的最大结果数（默认值：30）

退货： 文档摘要中未指定字段 AZURE_SEARCH_EXCLUDE_FIELDS （默认值： content, content_vector，中指定的其他字段 AZURE_SEARCH_EXCLUDE_FIELDS)

例子：

{
  "query": "data science",
  "top": 30
}

4. `filtered_search`

使用OData筛选器表达式搜索以缩小结果范围。

参数：

query （字符串，必填）：搜索查询
filter （字符串，必需）:OData筛选器表达式
top （数字，可选）：返回的最大结果数（默认值：30）

退货： 文档摘要中未指定字段 AZURE_SEARCH_EXCLUDE_FIELDS （默认值： content, content_vector，中指定的其他字段 AZURE_SEARCH_EXCLUDE_FIELDS)

例子：

{
  "query": "technology",
  "filter": "category eq 'AI' and year ge 2020",
  "top": 30
}

5. `fetch_document`

通过其唯一ID检索特定文档。返回包含所有字段的完整文档。

参数：

documentId （string，必填）：文档的唯一标识符

退货： 包含所有字段的完整文档（仅排除 content 和 content_vector)

例子：

{
  "documentId": "doc-12345"
}

资源

索引架构

访问完整的索引架构，包括字段定义：

统一资源标识符: azure-search://index/{index-name}/schema

返回JSON格式：

字段名称和类型
字段属性（可搜索、可过滤、可排序、可分面）
语义搜索配置

发展

运行测试

测试套件支持运行所有测试或使用自定义查询测试单个工具。

运行所有测试

npm run build  # First time only
npm run test   # Runs all 5 tools with default queries

测试单个工具

语义搜索 （人工智能驱动的上下文理解）：

npm run test semantic "machine learning algorithms"

混合搜索 （结合矢量+文本搜索）：

npm run test hybrid "artificial intelligence trends"

文本搜索 （传统关键字匹配）：

npm run test text "data science"

获取文档 （按ID检索）：

npm run test fetch doc-12345
# or auto-find a document
npm run test fetch

筛选的搜索 （使用OData过滤器）：

npm run test filtered "technology"

获得帮助

npm run test help

测试示例

# Test semantic search with a specific query
npm run test semantic "neural networks and deep learning"

# Test hybrid search for balanced results
npm run test hybrid "cloud computing security best practices"

# Test text search for exact keywords
npm run test text "azure cognitive search"

# Fetch a specific document
npm run test fetch "doc-abc-123"

# Test filtered search (adjust filter based on your schema)
npm run test filtered "AI research papers"

备注：确保你的 .env 在运行测试之前，文件已配置了有效的Azure凭据。

建筑

npm run build

观看模式

npm run watch

向NPM发布

更新版本 在 package.json
构建项目:
```
npm run build
```
本地测试:
```
npm run inspector
```
发布:
```
npm login
npm publish
```

项目结构

azure-ai-search-mcp/
├── src/
│   ├── azure-ai-search/
│   │   └── azure-search-client.ts    # Azure SDK client setup
│   ├── tools/
│   │   ├── semanticSearch.ts         # Semantic search tool
│   │   ├── hybridSearch.ts           # Hybrid search tool
│   │   ├── textSearch.ts             # Text search tool
│   │   ├── fetchDocument.ts          # Document fetch tool
│   │   └── filteredSearch.ts         # Filtered search tool
│   ├── index.ts                      # MCP server implementation
│   └── test.ts                       # Test suite
├── build/                            # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md

运作原理

客户端初始化：服务器使用环境变量中的凭据创建Azure搜索客户端（延迟初始化）
工具注册：每个搜索工具都使用适当的模式在MCP服务器上注册
资源暴露：索引模式作为MCP资源公开，用于自检
查询执行：工具使用Azure搜索SDK执行搜索
响应滤波:
- 搜索工具 返回没有在中指定字段的文档摘要 AZURE_SEARCH_EXCLUDE_FIELDS env 是
- 获取文档 始终返回完整文档（仅排除 content 和 content_vector)
- 字段排除可通过环境变量按部署进行配置

安全说明

API密钥：从不将API密钥提交到版本控制
环境变量：使用环境变量或安全密钥管理
访问控制：在生产环境中使用Azure RBAC和查询密钥（不是管理密钥）
速率限制：注意Azure搜索服务层限制
字段排除：使用 AZURE_SEARCH_EXCLUDE_FIELDS 防止在搜索结果中返回敏感数据
数据隐私：The content 和 content_vector 默认情况下，所有响应中始终排除字段

故障排除

“缺少必需的环境变量”

确保设置了所有三个环境变量：

AZURE_SEARCH_ENDPOINT
AZURE_SEARCH_API_KEY
AZURE_SEARCH_INDEX_NAME

语义搜索配置

语义搜索可以在有或没有显式语义配置的情况下工作：

具有语义配置：使用Azure的语义排序器以获得最佳结果
无语义配置：回到简单搜索，如果配置了矢量器，则可以使用矢量器
如果在索引中配置了矢量器，则不需要进行语义配置

“找不到ID为'xxx'的文档”

文档ID在索引中不存在。首先使用搜索工具查找有效的文档ID。

贡献

欢迎投稿！请随时提交拉取请求。

许可证

麻省理工学院

作者

汤姆·古特曼

使用说明

Azure AI搜索MCP服务器

特性

安装

作为NPM包

来源

配置

环境变量

所需Azure资源

用法

与MCP检查员一起

使用克劳德桌面

与其他MCP客户端

可用工具

1. semantic_search

2. hybrid_search

3. text_search

4. filtered_search

5. fetch_document

资源

索引架构

发展

运行测试

运行所有测试

测试单个工具

获得帮助

测试示例

建筑

观看模式

向NPM发布

项目结构

运作原理

安全说明

故障排除

“缺少必需的环境变量”

语义搜索配置

“找不到ID为'xxx'的文档”

贡献

许可证

作者

链接

相关 MCP

实时文档检索服务

AI持久记忆服务器

Zotero文献库搜索与阅读MCP服务

Qdrant向量搜索MCP服务器

AutoRAG 检索 MCP 服务

本地LLM模型控制协议

1. `semantic_search`

2. `hybrid_search`

3. `text_search`

4. `filtered_search`

5. `fetch_document`