Azure AI Agent & Search

Pesquise conteúdo usando o Azure AI Agent Service e o Azure AI Search.

Documentação

Azure AI Agent Service + Azure AI Search MCP Server

Um servidor Model Context Protocol (MCP) que permite ao Claude Desktop pesquisar seu conteúdo usando os serviços de IA do Azure. Escolha entre o Azure AI Agent Service (com pesquisa de documentos e pesquisa na web) ou a integração direta com o Azure AI Search.

demo

Visão Geral

Este projeto fornece duas implementações de servidor MCP para conectar o Claude Desktop aos recursos de pesquisa do Azure:

Implementação do Azure AI Agent Service (Recomendada) - Usa o poderoso Azure AI Agent Service para fornecer:
- Ferramenta Azure AI Search - Pesquise seus documentos indexados com resultados aprimorados por IA
- Ferramenta Bing Web Grounding - Pesquise na web com citações de fontes
Implementação Direta do Azure AI Search - Conecta-se diretamente ao Azure AI Search com três métodos:
- Pesquisa por Palavras-chave - Correspondências lexicais exatas
- Pesquisa Vetorial - Similaridade semântica usando embeddings
- Pesquisa Híbrida - Combinação de pesquisas por palavras-chave e vetorial

Recursos

Pesquisa Aprimorada por IA - O Azure AI Agent Service otimiza os resultados de pesquisa com processamento inteligente
Múltiplas Fontes de Dados - Pesquise tanto seus documentos privados quanto a web pública
Citações de Fontes - Os resultados de pesquisa na web incluem citações das fontes originais
Implementação Flexível - Escolha entre o Azure AI Agent Service ou a integração direta com o Azure AI Search
Integração Perfeita com Claude - Todos os recursos de pesquisa acessíveis pela interface do Claude Desktop
Personalizável - Fácil de estender ou modificar o comportamento da pesquisa

Links Rápidos

Requisitos

Python: Versão 3.10 ou superior
Claude Desktop: Versão mais recente
Recursos do Azure:
- Serviço Azure AI Search com um índice contendo dados de texto vetorizados
- Para o Agent Service: Projeto de IA do Azure com conexões do Azure AI Search e Bing
Sistema Operacional: Windows ou macOS (instruções fornecidas para Windows, mas adaptáveis)

Implementação do Azure AI Agent Service (Recomendada)

Guia de Configuração

Diretório do Projeto:

mkdir mcp-server-azure-ai-search
cd mcp-server-azure-ai-search

Crie um Arquivo .env:

echo "PROJECT_CONNECTION_STRING=your-project-connection-string" > .env
echo "MODEL_DEPLOYMENT_NAME=your-model-deployment-name" >> .env
echo "AI_SEARCH_CONNECTION_NAME=your-search-connection-name" >> .env
echo "BING_CONNECTION_NAME=your-bing-connection-name" >> .env
echo "AI_SEARCH_INDEX_NAME=your-index-name" >> .env

Configure o Ambiente Virtual:

uv venv
.venv\Scripts\activate
uv pip install "mcp[cli]" azure-identity python-dotenv azure-ai-projects

Use o script azure_ai_agent_service_server.py para integração com o Azure AI Agent Service.

Configuração do Azure AI Agent Service

Antes de usar a implementação, você precisa:

Crie um Projeto de IA do Azure:
- Acesse o Portal do Azure e crie um novo Projeto de IA do Azure
- Anote a string de conexão do projeto e o nome da implantação do modelo
Crie uma Conexão do Azure AI Search:
- No seu Projeto de IA do Azure, adicione uma conexão ao seu serviço Azure AI Search
- Anote o nome da conexão e o nome do índice
Crie uma Conexão de Pesquisa na Web do Bing:
- No seu Projeto de IA do Azure, adicione uma conexão ao serviço Bing Search
- Anote o nome da conexão
Autentique-se com o Azure:
```
az login
```

Configurando o Claude Desktop

{
  "mcpServers": {
    "azure-ai-agent": {
      "command": "C:\\path\\to\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\azure_ai_agent_service_server.py"],
      "env": {
        "PROJECT_CONNECTION_STRING": "your-project-connection-string",
        "MODEL_DEPLOYMENT_NAME": "your-model-deployment-name",
        "AI_SEARCH_CONNECTION_NAME": "your-search-connection-name",
        "BING_CONNECTION_NAME": "your-bing-connection-name",
        "AI_SEARCH_INDEX_NAME": "your-index-name"
      }
    }
  }
}

Observação: Substitua os placeholders de caminho pelos caminhos reais do seu projeto.

Implementação Direta do Azure AI Search

Para aqueles que preferem a integração direta com o Azure AI Search sem o Agent Service:

Crie um Arquivo .env diferente:

echo "AZURE_SEARCH_SERVICE_ENDPOINT=https://your-service-name.search.windows.net" > .env
echo "AZURE_SEARCH_INDEX_NAME=your-index-name" >> .env
echo "AZURE_SEARCH_API_KEY=your-api-key" >> .env

Instale as Dependências:

uv pip install "mcp[cli]" azure-search-documents==11.5.2 azure-identity python-dotenv

Use o script azure_search_server.py para integração direta com o Azure AI Search.

Configure o Claude Desktop:

{
  "mcpServers": {
    "azure-search": {
      "command": "C:\\path\\to\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\azure_search_server.py"],
      "env": {
        "AZURE_SEARCH_SERVICE_ENDPOINT": "https://your-service-name.search.windows.net",
        "AZURE_SEARCH_INDEX_NAME": "your-index-name",
        "AZURE_SEARCH_API_KEY": "your-api-key"
      }
    }
  }
}

Testando o Servidor

Reinicie o Claude Desktop para carregar a nova configuração
Procure o ícone de ferramentas MCP (ícone de martelo) no canto inferior direito do campo de entrada
Experimente consultas como:
- "Pesquise informações sobre IA no meu índice do Azure Search"
- "Pesquise na web os últimos avanços em LLMs"
- "Encontre informações sobre redes neurais usando pesquisa híbrida"

Solução de Problemas

Servidor Não Aparece:
- Verifique os logs do Claude Desktop (localizados em %APPDATA%\Claude\logs\mcp*.log no Windows)
- Verifique os caminhos de arquivo e as variáveis de ambiente na configuração
- Teste executar o servidor diretamente: python azure_ai_agent_service_server.py ou uv run python azure_ai_agent_service_server.py
Problemas com o Azure AI Agent Service:
- Certifique-se de que seu Projeto de IA do Azure está configurado corretamente
- Verifique se as conexões existem e estão configuradas corretamente
- Verifique seu status de autenticação do Azure

Personalizando Seu Servidor

Modifique as Instruções das Ferramentas: Ajuste as instruções fornecidas a cada agente para alterar como eles processam consultas
Adicione Novas Ferramentas: Use o decorador @mcp.tool() para integrar ferramentas adicionais
Personalize a Formatação das Respostas: Edite como as respostas são formatadas e retornadas ao Claude Desktop
Ajuste os Parâmetros de Pesquisa na Web: Modifique a ferramenta de pesquisa na web para focar em domínios específicos

Licença

Este projeto está licenciado sob a Licença MIT.