Azure-Samples/snippy

Snippy · Intelligent Code-Snippet Service with MCP Tools

Snippy is an Azure Functions-based reference application that demonstrates how to build MCP (Model Context Protocol) tools that integrate with AI assistants like GitHub Copilot. The sample implements an intelligent code-snippet service featuring:

• MCP Tool Integration – expose Azure Functions as discoverable tools for AI assistants
• Durable Agents – create stateful AI agents using Microsoft Agent Framework with automatic state management
• Multi-Agent Orchestration – coordinate DeepWiki and CodeStyle agents using Durable Task Scheduler
• Vector Search – semantic retrieval using Cosmos DB DiskANN with Azure OpenAI embeddings
• Monitoring & Observability – track orchestrations in real-time with DTS dashboard (local & cloud)

The project ships with reproducible azd infrastructure, so azd up will stand up the entire stack – Functions, Cosmos DB, Azure OpenAI, and Durable Task Scheduler – in a single command.

Important Security Notice This repository is intended for learning and demonstration purposes. Do not deploy it to production without a thorough security review. At a minimum you should:

• Swap connection strings for Managed Identity + Azure Key Vault
• Restrict network access to Azure services via Private Endpoints or service‑tags
• Enable GitHub secret‑scanning and CI security tools

Features • Architecture • Getting Started • Guidance

Recent Updates

• Durable Task Scheduler (DTS) integration for cloud orchestration and monitoring
• DTS dashboard scripts: Quickly generate monitoring URLs for Azure deployments (scripts/get-dts-dashboard-url.sh and .ps1)
• Multi-agent orchestration: Coordinate DeepWiki and CodeStyle agents with Durable Functions
• Enhanced monitoring: View orchestration state in local DTS emulator or Azure DTS dashboard

Features

• MCP Tool Integration – expose Azure Functions as discoverable MCP tools for AI assistants
• Durable Agents with Microsoft Agent Framework – build stateful AI agents using ChatAgent with automatic conversation history management
• Multi-Agent Orchestration – coordinate specialized agents (DeepWiki, CodeStyle) using Durable Task Scheduler with fan-out/fan-in patterns
• Vector Search on Cosmos DB DiskANN – semantic code retrieval using Azure OpenAI embeddings and low-latency vector indexing
• Monitoring & Observability – track orchestrations in real-time using DTS dashboard (localhost:8082 local, Azure portal for cloud)
• One-click Deploy – azd up provisions and deploys complete infrastructure including Functions, Cosmos DB, Azure OpenAI, and DTS
• Codespaces & Dev Containers – fully configured development environment in your browser or local VS Code

Tool Matrix

Architecture Diagram

Getting Started

You can run Snippy in GitHub Codespaces, VS Code Dev Containers, or your local environment. The fastest path is Codespaces.

Snippy requires an Azure region that supports text‑embedding‑3‑small (or a compatible embeddings model) and Azure AI Agents. The azd workflow prompts you for a region; we recommend eastus for best availability.

GitHub Codespaces

1. Click Open in Codespaces above (first badge) – the container build may take a few minutes.

2. When the terminal appears, sign in:

   azd auth login --use-device-code
   

3. Launch the stack:

   azd up
   

4. Once deployment completes, copy the printed MCP URL and open GitHub Copilot Chat → Agent mode to try commands like “Save this snippet as hello‑world”.

VS Code Dev Containers

Prerequisites: Docker Desktop + the Dev Containers extension.

1. Click the Dev Containers badge (second badge) or run Remote‑Containers: Open Repository in Container from VS Code.

2. Sign in and launch as shown for Codespaces:

   azd auth login
   azd up
   

Local Environment

Prerequisites

• azd CLI
• Python 3.11 + uv
• Node 18+ (for Functions Core Tools)
• Azure Functions Core Tools v4 (npm i -g azure-functions-core-tools@4 --unsafe-perm)

Quickstart

# 1. Clone & init
azd init --template Azure-Samples/snippy

# 2. Sign in
azd auth login

# 3. Provision & deploy
azd up

The CLI will automatically:

• Create an Azure AD app registration for OAuth authentication
• Provision all Azure resources (Functions, Cosmos DB, OpenAI, etc.)
• Deploy the application code

The CLI prints the Function App URL, MCP endpoint and system key when finished. To remove all resources later:

azd down --purge

Note: The first run automatically creates an Azure AD app registration with OAuth2 scope access_as_user for authentication.

Local Development with Emulators

For local development, Snippy uses the Durable Task Scheduler (DTS) emulator and Azurite for storage.

With Docker (Recommended)

The easiest way to run both emulators:

# Start both emulators
docker compose up -d

# Generate local.settings.json from your Azure environment
./scripts/generate-settings.sh

# Run the Functions app
```mermaid
flowchart LR
  subgraph mcphosts["MCP Hosts & Clients (Your Computer)"]
    Host["Host (VS Code / IDE)"]
    Client["Client (GitHub Copilot)"]
  end
  Host --"MCP Protocol"--> Client
  Client --"Tool Discovery"--> FunctionApp["Function App (MCP Server)"]
  FunctionApp --"Orchestrate"--> DTS["Durable Task Scheduler"]
  DTS --"Agent Calls"--> Agents["Durable Agents<br/>DeepWiki · CodeStyle"]
  FunctionApp --"Vector Search"--> CosmosDB
  Agents --"Vector Search"--> CosmosDB
  FunctionApp --"Embeddings"--> OpenAI["Azure OpenAI"]
  Agents --"LLM Calls"--> OpenAI
  DTS --"Dashboard"--> User["Developer/Monitor"]

Monitoring & Orchestration

• Local development: Monitor orchestrations at http://localhost:8082/ when using the DTS emulator
• Azure deployment: Use the DTS dashboard scripts to generate monitoring URLs:
  • Bash: ./scripts/get-dts-dashboard-url.sh
  • PowerShell: .\scripts\get-dts-dashboard-url.ps1
• View multi-agent orchestration execution, including DeepWiki and CodeStyle agent calls
• Track tool invocations, state transitions, and execution timelines

To switch back to DTS when Docker becomes available:

```bash
./scripts/switch-storage-backend.sh dts

For detailed setup instructions and troubleshooting, see .

Guidance

Region Availability

Azure OpenAI model support varies by region. Verify availability here and choose the same region for all Azure resources. eastus and swedencentral are good default choices.

Security

Snippy uses User-Assigned Managed Identity for secure service-to-service authentication. The infrastructure is configured with:

• User-Assigned Managed Identity on the Function App with appropriate RBAC roles:
  • Cosmos DB Data Contributor
  • Storage Blob Data Owner and Queue Data Contributor
  • Application Insights Monitoring Metrics Publisher
  • Azure AI Project Developer

For production deployments, we recommend:

• Restrict inbound traffic with Private Endpoints + VNet integration
• Enable network security features like service endpoints and firewall rules

Contributing

Standard fork → branch → PR workflow. Use Conventional Commits (feat:, fix:) in commit messages.

License

MIT © Microsoft Corporation