Experimental MCP Service for Azure AI Search

Azure AI Search 实验性 MCP 服务

此实验性 MCP 服务为你提供以下功能：

• 获取服务中的 AI Search 索引列表
• 获取特定 AI Search 服务的架构和配置详情
• 创建新索引
• 更新现有索引
• 对特定 AI Search 索引运行查询
• 创建和更新索引器

项目迁移

此项目最初托管于此处，但团队已将其迁移至官方地址： https://github.com/azure-ai-foundry/mcp-foundry

重要免责声明

我们仍在实现和测试这些功能。

上面介绍的部分工具组尚不可用，但很快就会推出。

我们正在持续为服务添加和升级功能。近期还会添加更多工具。

这些工具能够修改 AI Search 服务中的数据。

请注意，目前所有工具都标记为 experimental，其行为可能会在不事先通知的情况下发生变化。

你应始终检查并验证所有 AI 生成内容的准确性和正确性。

请谨慎操作，并自行承担使用风险。

可用工具

目前，服务提供以下工具：

工具名称	工具组	工具描述
list_index_names	READ_INDEX	从 AI Search Service 获取所有索引名称
list_index_schemas	READ_INDEX	从 AI Search Service 获取所有索引架构
retrieve_index_schema	READ_INDEX	获取特定索引的架构
create_index	WRITE_INDEX	创建新索引
modify_index	WRITE_INDEX	修改现有索引的定义
delete_index	WRITE_INDEX	删除现有索引
add_document	WRITE_DOCUMENTS	向索引添加文档
delete_document	WRITE_DOCUMENTS	从索引中删除文档
query_index	READ_DOCUMENTS	搜索特定索引以获取匹配的文档
get_document_count	READ_DOCUMENTS	返回索引中的文档总数
list_indexers	READ_INDEXER	从 AI Search Service 获取所有索引器名称
get_indexer	READ_INDEXER	从 AI Search Service 获取特定索引器的完整定义
create_indexer	WRITE_INDEXER	在 Search Service 中使用技能、索引和数据源创建新的索引器
delete_indexer	WRITE_INDEXER	根据名称从 AI Search Service 删除索引器
list_data_sources	READ_INDEXER	从 AI Search Service 获取所有数据源名称
get_data_source	READ_INDEXER	获取特定数据源的完整定义
list_skill_sets	READ_INDEXER	从 AI Search Service 获取所有技能集名称
get_skill_set	READ_INDEXER	获取特定技能集的完整定义
fk_fetch_local_file_contents	FETCH_FILE_CONTENTS	获取本地文件路径的内容（示例 JSON、文档等）
fk_fetch_url_contents	FETCH_FILE_CONTENTS	获取 URL 的内容（示例 JSON、文档等）

MCP 服务工具组

我们不希望 MCP Host 被此服务提供的大量工具所淹没。

以下是可用的工具组及其用途：

• READ_OPERATIONS - 用于只读操作的工具
• WRITE_OPERATIONS - 用于创建、修改或删除条目的工具。ALL 的别名
• READ_INDEX - 用于列出和描述服务中索引的工具
• WRITE_INDEX - 用于创建、删除、更新或配置索引的工具
• READ_DOCUMENTS - 用于查询索引以检索文档的工具
• WRITE_DOCUMENTS - 用于添加、更新或删除索引中文档的工具
• WRITE_INDEXERS - 用于配置索引器、数据源和技能集的工具
• READ_INDEXERS - 用于获取数据源、技能集和索引器信息的工具

先决条件

你需要配置一个服务主体，用于向你要交互的 AI Search 服务进行身份验证。你也可以使用具有索引读写权限的 AI Search Key，具体取决于你希望利用该服务的哪些功能。

需要 Python 3.12 或更高版本，并且还需要安装 uv 才能使用该服务。

以下存储库包含一个 Terraform 脚本，可加快 AI Search 服务和服务主体的配置，帮助你快速上手。

安装依赖项

请按照以下链接安装 uv、Python 和包含 MCP 服务的模块

• 安装 uv
• 使用 uv 安装 Python（如有需要）

你可以按如下方式安装 MCP 服务：

uv build

pip install dist/mcp_server_azure_ai_search_preview-0.3.1-py3-none-any.whl 

# If you are running in SSE mode, you can run it as:
uv run -m mcp_server_azure_ai_search_preview --transport sse --envFile .env --host 127.0.0.1 --port 8000

#f you are running it in STDIO mode in Cursor or Claude Desktop, we have an example config below for you to use

环境文件、主机和端口均为可选项。如果未指定，将使用默认值。

你也可以克隆此 git 仓库，并通过此仓库中的 main.py 文件安装服务

MCP 主机中的环境变量配置

如果使用托管标识进行身份验证，需要在 MCP 主机配置中传入环境变量。也可以使用 AI Search API 密钥进行身份验证。

需要指定身份验证方法和搜索终结点。以下是必需的环境变量。

如果使用服务主体进行身份验证，则应配置以下变量：

• AZURE_AUTHENTICATION_METHOD - 默认值为 "api-search-key"
• AZURE_AI_SEARCH_ENDPOINT
• AZURE_TENANT_ID
• AZURE_CLIENT_ID
• AZURE_CLIENT_SECRET

如果使用 API 密钥进行身份验证，则必须配置以下环境变量：

• AZURE_AUTHENTICATION_METHOD - 默认值为 "api-search-key"
• AZURE_AI_SEARCH_ENDPOINT
• AZURE_AUTHENTICATION_METHOD
• AZURE_AI_SEARCH_API_KEY

还可以在配置中指定以逗号分隔的工具组列表，从而筛选返回给 MCP 主机的工具列表。

环境变量	值的数据类型	用途
AZURE_AUTHENTICATION_METHOD	string	服务主体身份验证使用 "service-principal"，基于密钥的访问使用 "api-search-key"。
AZURE_AI_SEARCH_ENDPOINT	string (URL)	指定 Azure AI Search 终结点 URL；用于向服务发送 REST API 请求。
AZURE_TENANT_ID	string	标识用于通过服务主体进行身份验证的 Azure Active Directory (AAD) 租户。
AZURE_CLIENT_ID	string	用于 Azure 身份验证的服务主体（应用注册）的唯一标识符。
AZURE_CLIENT_SECRET	string	服务主体的密钥凭据；用于进行身份验证并从 AAD 获取令牌。
AZURE_AI_SEARCH_API_KEY	string	用于对 Azure AI Search 实例的读写 API 请求进行身份验证；必须妥善保管。
AZURE_AI_SEARCH_API_VERSION	string	要使用的 API 版本。
AZURE_AI_SEARCH_MCP_TOOL_GROUPS	string	以逗号分隔的工具组列表，用于筛选为 MCP 主机检索的工具。

STDIO 模式下的 MCP 主机配置

这是使用 STDIO 传输的 VScode Agent Mode 配置示例。

{
    "inputs": [
        {
            "type": "promptString",
            "id": "AZURE_AI_SEARCH_API_KEY",
            "description": "AZURE_AI_SEARCH_API_KEY",
            "password": true
        },
        {
            "type": "promptString",
            "id": "LOCAL_WORKING_DIRECTORY",
            "description": "Directory where the MCP service Git repo was cloned to",
            "password": false
        }
    ],
    "servers": {

        "ai_search_mcp": {
            "type": "stdio",
            "command": "uv",

            "args": [
                "run",
                "--directory",
                "${input:LOCAL_WORKING_DIRECTORY}",
                "-m",
                "run mcp_server_azure_ai_search_preview"
                "--transport",
                "stdio"
            ],
            "env": {
                "AZURE_AI_SEARCH_MCP_TOOL_GROUPS": "ALL",
                "AZURE_AI_SEARCH_ENDPOINT": "https://{service_name}.search.windows.net",
                "AZURE_AI_SEARCH_API_VERSION": "2025-03-01-preview",
                "AZURE_AUTHENTICATION_METHOD": "api-search-key",
                "AZURE_AI_SEARCH_API_KEY":  "${input:AZURE_AI_SEARCH_API_KEY}"
            }
        }
    }
}

此示例使用自定义环境变量文件来指定 MCP 服务使用的环境变量。

{
    "inputs": [
        {
            "type": "promptString",
            "id": "LOCAL_WORKING_DIRECTORY",
            "description": "Directory where the MCP service Git repo was cloned to",
            "password": false
        }
    ],
    "servers": {

        "ai_search_mcp": {
            "type": "stdio",
            "command": "uv",
            "args": [
                "run",
                "--directory",
                "${input:LOCAL_WORKING_DIRECTORY}",
                "-m",
                "run mcp_server_azure_ai_search_preview"
                "--transport",
                "stdio"
               "--envFile",
                ".env"
            ]
        }
    }
}

此示例使用一个以 SSE 模式运行的 MCP 服务。

# Start up the MCP server first and then specify this config in your `.vscode/mcp.json` file in your VSCODE workspace

uv run -m mcp_server_azure_ai_search_preview --transport sse --envFile .env

{
    "servers": {
        "ai_search_2": {
            "type": "sse",
            "url": "http://localhost:8000/sse"
        }
    }
}

从 Pydantic AI 等 Agent 框架运行

你可以参考此仓库中的示例，了解如何使用 Pydantic AI 这类 Python Agent 框架运行 MCP 客户端。

启动 Python MCP 客户端之前，请确保客户端代码依赖的所有 SSE MCP 服务都已启动并正在运行。