Azure AI 에이전트 서비스 + Azure AI 검색 MCP 서버

Claude Desktop이 Azure AI 서비스를 사용하여 콘텐츠를 검색할 수 있도록 하는 MCP(모델 컨텍스트 프로토콜) 서버입니다. Azure AI Agent 서비스(문서 검색 및 웹 검색 모두 포함) 또는 Azure AI Search 직접 통합 중에서 선택하세요.

개요

이 프로젝트는 Claude Desktop을 Azure 검색 기능과 연결하기 위한 두 가지 MCP 서버 구현을 제공합니다.

1. Azure AI Agent 서비스 구현(권장) - 강력한 Azure AI Agent 서비스를 사용하여 다음을 제공합니다.
   • Azure AI 검색 도구 - AI가 강화한 결과로 인덱싱된 문서 검색
   • Bing 웹 기반 도구 - 출처 인용을 통한 웹 검색
2. Azure AI Search 직접 구현 - 다음 세 가지 방법을 사용하여 Azure AI Search에 직접 연결합니다.
   • 키워드 검색 - 정확한 어휘 일치
   • 벡터 검색 - 임베딩을 사용한 의미적 유사성
   • 하이브리드 검색 - 키워드 검색과 벡터 검색의 조합

특징

• AI 강화 검색 - Azure AI Agent Service는 지능형 처리를 통해 검색 결과를 최적화합니다.
• 여러 데이터 소스 - 개인 문서와 공개 웹을 모두 검색하세요
• 출처 인용 - 웹 검색 결과에는 원본 출처에 대한 인용이 포함됩니다.
• 유연한 구현 - Azure AI Agent 서비스 또는 직접 Azure AI Search 통합 중에서 선택
• 원활한 Claude 통합 - 모든 검색 기능은 Claude Desktop 인터페이스를 통해 접근 가능합니다.
• 사용자 정의 가능 - 검색 동작을 쉽게 확장하거나 수정할 수 있습니다.

빠른 링크

• Azure AI 검색 시작하기
• Azure AI 에이전트 서비스 빠른 시작

요구 사항

• Python: 버전 3.10 이상
• Claude Desktop: 최신 버전
• Azure 리소스:
  • 벡터화된 텍스트 데이터를 포함하는 인덱스가 있는 Azure AI Search 서비스
  • 에이전트 서비스의 경우: Azure AI 검색 및 Bing 연결이 있는 Azure AI 프로젝트
• 운영 체제: Windows 또는 macOS(Windows에 대한 지침이 제공되지만 조정 가능)

Azure AI 에이전트 서비스 구현(권장)

설정 가이드

1. 프로젝트 디렉토리:지엑스피1
2. .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
3. 가상 환경 설정:
   uv venv .venv\Scripts\activate uv pip install "mcp[cli]" azure-identity python-dotenv azure-ai-projects
4. Azure AI Agent Service와 통합하려면 azure_ai_agent_service_server.py 스크립트를 사용하세요 .

Azure AI 에이전트 서비스 설정

구현을 사용하기 전에 다음이 필요합니다.

1. Azure AI 프로젝트 만들기:
   • Azure Portal로 이동하여 새 Azure AI 프로젝트를 만듭니다.
   • 프로젝트 연결 문자열과 모델 배포 이름을 기록하세요.
2. Azure AI 검색 연결 만들기:
   • Azure AI 프로젝트에서 Azure AI Search 서비스에 대한 연결을 추가합니다.
   • 연결 이름과 인덱스 이름을 기록하세요.
3. Bing 웹 검색 연결 만들기:
   • Azure AI 프로젝트에서 Bing Search 서비스에 대한 연결을 추가합니다.
   • 연결 이름을 확인하세요
4. Azure로 인증:
   az login

Claude Desktop 구성

참고: 경로 자리 표시자를 실제 프로젝트 경로로 바꾸세요.

Azure AI 직접 검색 구현

에이전트 서비스 없이 Azure AI Search를 직접 통합하는 것을 선호하는 경우:

1. 다른 .env 파일을 만듭니다.
   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
2. 종속성 설치:
   uv pip install "mcp[cli]" azure-search-documents==11.5.2 azure-identity python-dotenv
3. Azure AI Search와 직접 통합하려면 azure_search_server.py 스크립트를 사용하세요 .
4. 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" } } } }

서버 테스트

1. 새 구성을 로드하려면 Claude Desktop을 다시 시작하세요.
2. 입력 필드의 오른쪽 하단에 있는 MCP 도구 아이콘(망치 아이콘)을 찾으세요.
3. 다음과 같은 쿼리를 시도해 보세요.
   • "Azure Search 인덱스에서 AI에 대한 정보를 검색하세요"
   • "LLM의 최신 동향을 웹에서 검색하세요"
   • "하이브리드 검색을 사용하여 신경망에 대한 정보 찾기"

문제 해결

• 서버가 나타나지 않습니다:
  • Claude Desktop 로그 확인(Windows의 %APPDATA%\Claude\logs\mcp*.log 에 위치)
  • 구성에서 파일 경로 및 환경 변수를 확인하세요.
  • 서버를 직접 실행해 보세요: python azure_ai_agent_service_server.py 또는 uv run python azure_ai_agent_service_server.py
• Azure AI 에이전트 서비스 문제:
  • Azure AI 프로젝트가 올바르게 구성되었는지 확인하세요.
  • 연결이 존재하고 올바르게 구성되었는지 확인하십시오.
  • Azure 인증 상태를 확인하세요

서버 사용자 지정

• 도구 지침 수정: 각 에이전트에게 제공된 지침을 조정하여 쿼리 처리 방식을 변경합니다.
• 새 도구 추가: @mcp.tool() 데코레이터를 사용하여 추가 도구를 통합합니다.
• 응답 형식 사용자 지정: 응답이 Claude Desktop으로 반환되는 형식을 편집합니다.
• 웹 검색 매개변수 조정: 특정 도메인에 초점을 맞추도록 웹 검색 도구를 수정합니다.

특허

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다.