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_ENDPOINTAZURE_SEARCH_API_KEYAZURE_SEARCH_INDEX_NAME
语义搜索配置
语义搜索可以在有或没有显式语义配置的情况下工作：
- 具有语义配置：使用Azure的语义排序器以获得最佳结果
- 无语义配置：回到简单搜索，如果配置了矢量器，则可以使用矢量器
- 如果在索引中配置了矢量器，则不需要进行语义配置
“找不到ID为'xxx'的文档”
文档ID在索引中不存在。首先使用搜索工具查找有效的文档ID。
贡献
欢迎投稿！请随时提交拉取请求。
许可证
麻省理工学院
作者
汤姆·古特曼
链接
-