Azure-Samples/snippy

Snippy는 GitHub Copilot과 같은 AI 어시스턴트와 통합되는 MCP (Model Context Protocol) 도구를 구축하는 방법을 보여주는 Azure Functions 기반의 레퍼런스 애플리케이션입니다. 이 프로젝트는 Azure Functions가 전통적인 API 역할과 동시에 AI 어시스턴트가 발견하고 사용할 수 있는 MCP 호환 도구 역할을 수행하는 현대적인 서버리스 AI 애플리케이션 아키텍처를 선보입니다.

이 시스템은 멀티 에이전트 워크플로우를 오케스트레이션하기 위해 Durable Task Scheduler를 사용하며, 의미론적 코드 검색을 위해 벡터 인덱싱이 포함된 Cosmos DB를, 임베딩(embeddings) 및 LLM 기능을 위해 Azure OpenAI를 사용합니다. 이 프로젝트는 재현 가능한 azd 인프라를 제공하며, azd up 명령어를 통해 전체 스택을 배포할 수 있고 로컬 Docker 기반 에뮬레이터와 Azure 클라우드 서비스 모두에서 작동합니다.

중요 보안 공지: 이 저장소는 학습 및 데모 목적으로 설계되었습니다. 철저한 보안 검토 없이 프로덕션 환경에 배포하지 마십시오. 최소한 다음 사항을 수행해야 합니다:

• 연결 문자열(connection strings)을 Managed Identity + Azure Key Vault로 교체
• Private Endpoints 또는 서비스 태그(service-tags)를 통해 Azure 서비스에 대한 네트워크 액세스 제한
• GitHub 비밀값 스캐닝(secret-scanning) 및 CI 보안 도구 활성화

기능 • 실습 튜토리얼 • 시작하기 • 가이드라인

MCP 도구 통합 – Azure Functions를 AI 어시스턴트가 발견할 수 있는 MCP 도구로 노출
Microsoft Agent Framework를 사용한 Durable Agents – 자동 대화 기록 관리가 포함된 ChatAgent를 사용하여 상태 유지(stateful) AI 에이전트 구축
멀티 에이전트 오케스트레이션 (Multi-Agent Orchestration) – fan-out/fan-in 패턴과 함께 Durable Task Scheduler를 사용하여 특화된 에이전트(DeepWiki, CodeStyle)를 조정
Cosmos DB DiskANN 기반 벡터 검색 – Azure OpenAI 임베딩 및 저지연 벡터 인덱싱을 사용한 의미론적 코드 검색
모니터링 및 관찰 가능성 (Monitoring & Observability) – DTS 대시보드(로컬은 localhost:8082, 클라우드는 Azure 포털)를 사용하여 오케스트레이션을 실시간으로 추적
원클릭 배포 – azd up

Functions, Cosmos DB, Azure OpenAI 및 DTS를 포함한 전체 인프라를 프로비저닝(Provisioning)하고 배포합니다.Codespaces & Dev Containers – 브라우저 또는 로컬 VS Code에서 완전히 구성된 개발 환경을 제공합니다.

도구 이름	목적
save_snippet	시맨틱 검색 (Semantic Search)을 위해 벡터 임베딩 (Vector Embeddings)과 함께 코드 스니펫을 저장
get_snippet	고유 이름을 통해 이전에 저장된 코드 스니펫을 검색
code_style	저장된 스니펫으로부터 언어별 코드 스타일 가이드를 생성
deep_wiki	코드 스니펫을 분석하여 포괄적인 위키(Wiki) 문서를 생성
generate_comprehensive_documentation	딥 위키(Deep Wiki)와 스타일 가이드를 생성하기 위해 멀티 에이전트 워크플로 (Multi-agent workflow)를 오케스트레이션

Snippy가 처음이신가요? 애플리케이션 전체를 처음부터 구축할 수 있도록 안내하는 포괄적인 **실습 랩 튜토리얼 (Hands-on lab tutorial)**로 시작해 보세요:

튜토리얼 범위:

단계별 구현 – 상세한 설명과 함께 전체 애플리케이션을 구축합니다코드 리뷰 연습 – MCP 도구, Durable Agents, 그리고 벡터 검색 (Vector search) 패턴을 이해합니다로컬 개발 – Docker 기반 에뮬레이터를 사용하여 설정 및 테스트를 진행합니다Azure 배포 – azd를 사용하여 프로덕션 환경에 프로비저닝 및 배포합니다멀티 에이전트 오케스트레이션 (Multi-agent orchestration) – DTS 대시보드를 통해 복잡한 워크플로를 모니터링합니다엔드 투 엔드 (End-to-end) 테스트 – REST Client, GitHub Copilot 및 MCP 도구를 사용하여 테스트합니다

추가 리소스:

• 빠른 참조 (Quick Reference) – 필수 명령 및 일반 작업
• 문제 해결 가이드 (Troubleshooting Guide) – 일반적인 문제에 대한 해결책

Azure Functions, MCP 도구 또는 AI 에이전트 개발이 처음이더라도, 이 랩은 실습 경험과 함께 구조화된 학습 경로를 제공합니다.

• 리소스를 생성할 수 있는 권한이 있는 Azure 구독
• azd CLI 설치됨
• 개발 환경 선택:
  GitHub Codespaces(가장 빠름, 로컬 설정 불필요)VS Code Dev Containers(Docker Desktop 필요)로컬 개발(Python 3.11, Node 18+, Azure Functions Core Tools v4 필요)

GitHub Codespaces 사용 시:

위의 "Open in GitHub Codespaces" 배지를 클릭한 다음, 다음을 실행하세요:

azd auth login --use-device-code
azd up

Dev Containers 또는 로컬 환경 사용 시:

azd init --template Azure-Samples/snippy
azd auth login
azd up

azd up 명령은 다음을 수행합니다:

• Azure 지역(region) 선택 요청 (eastus 또는 swedencentral 권장) - 모든 리소스(Functions, Cosmos DB, Azure OpenAI, DTS) 프로비저닝 (Provisioning)
• 인증을 위한 Azure AD 앱 등록(app registration) 생성
• 애플리케이션 코드 배포

완료되면 Function App URL과 MCP 엔드포인트(endpoint)가 표시됩니다. 로컬 개발, 에뮬레이터를 사용한 테스트 및 오케스트레이션(orchestrations) 모니터링에 대한 자세한 지침은 튜토리얼을 참조하세요.

Azure OpenAI 모델 지원은 지역(region)마다 다릅니다. [여기]에서 가용성을 확인하고 모든 Azure 리소스에 대해 동일한 지역을 선택하세요. eastus 및 swedencentral이 좋은 기본 선택지입니다.

Snippy는 안전한 서비스 간 인증(service-to-service authentication)을 위해 사용자 할당 관리 ID (User-Assigned Managed Identity)를 사용합니다. 인프라는 다음과 같이 구성됩니다:

적절한 RBAC 역할이 부여된 Function App의 사용자 할당 관리 ID (User-Assigned Managed Identity):

• Cosmos DB 데이터 기여자 (Data Contributor)
• Storage Blob 데이터 소유자 (Data Owner) 및 Queue 데이터 기여자 (Data Contributor)
• Application Insights 모니터링 메트릭 게시자 (Monitoring Metrics Publisher)
• Azure AI 프로젝트 개발자 (Project Developer)

프로덕션 배포를 위해 다음을 권장합니다:

• Private Endpoints + VNet 통합을 통한 인바운드 트래픽 제한
• 서비스 엔드포인트(service endpoints) 및 방화벽 규칙(firewall rules)과 같은 네트워크 보안 기능 활성화

표준 fork → branch → PR 워크플로우를 따릅니다. 커밋 메시지에는 Conventional Commits (feat:, fix:)를 사용하세요.

MIT © Microsoft Corporation