Snippy

Snippy 是一个基于 Azure Functions 的参考应用，演示如何构建可与 GitHub Copilot 等 AI 助手集成的 MCP（Model Context Protocol）工具。它展示了现代无服务器 AI 应用架构：Azure Functions 既可作为传统 API，也可作为 AI 助手能够发现和使用的 MCP 兼容工具。

该系统使用 Durable Task Scheduler 编排多 Agent 工作流，使用 支持向量索引的 Cosmos DB 进行语义代码搜索，并使用 Azure OpenAI 提供嵌入和大模型能力。项目附带可复现的 azd 基础设施——azd up 可部署整个技术栈，并支持基于本地 Docker 的模拟器和 Azure 云服务。

重要安全提示 此仓库仅供学习和演示。未经全面的安全审查，请勿将其部署到生产环境。至少应执行以下操作：

• 将连接字符串替换为 托管标识 + Azure Key Vault
• 通过专用终结点或服务标记限制对 Azure 服务的网络访问
• 启用 GitHub 密钥扫描和 CI 安全工具

功能 • 实验教程 • 入门 • 指南

---

功能

• MCP 工具集成 – 将 Azure Functions 公开为 AI 助手可发现的 MCP 工具
• 使用 Microsoft Agent Framework 的持久化 Agent – 使用 ChatAgent 构建有状态 AI Agent，并自动管理对话历史记录
• 多 Agent 编排 – 使用 Durable Task Scheduler 和扇出/扇入模式协调专用 Agent（DeepWiki、CodeStyle）
• Cosmos DB DiskANN 向量搜索 – 使用 Azure OpenAI 嵌入和低延迟向量索引进行语义代码检索
• 监控与可观测性 – 使用 DTS 仪表板实时跟踪编排（本地地址为 localhost:8082，云端使用 Azure 门户）
• 一键部署 – azd up 可预配并部署完整基础设施，包括 Functions、Cosmos DB、Azure OpenAI 和 DTS
• Codespaces 和 Dev Containers – 在浏览器或本地 VS Code 中使用完全配置好的开发环境

工具矩阵

工具名称	用途
save_snippet	保存代码片段及其向量嵌入，以便进行语义搜索
get_snippet	按唯一名称检索先前保存的代码片段
code_style	根据保存的代码片段生成特定语言的代码风格指南
deep_wiki	通过分析代码片段创建全面的 Wiki 文档
generate_comprehensive_documentation	编排多 Agent 工作流，生成详细的 Wiki 和风格指南

---

实验教程

刚开始使用 Snippy？请从我们的全面动手实验教程开始，跟着教程从零开始构建整个应用：

📚 Snippy 教程：构建 AI 增强型代码片段管理器

教程涵盖：

• 分步实现 – 通过详细说明构建完整应用
• 代码审查练习 – 了解 MCP 工具、持久化 Agent 和向量搜索模式
• 本地开发 – 使用基于 Docker 的模拟器进行设置和测试
• Azure 部署 – 使用 azd 配置资源并部署到生产环境
• 多 Agent 编排 – 使用 DTS 仪表板监控复杂工作流
• 端到端测试 – 使用 REST Client、GitHub Copilot 和 MCP 工具进行测试

其他资源：

• 快速参考 – 常用命令和任务
• 故障排除指南 – 常见问题的解决方案

无论你是刚开始接触 Azure Functions、MCP 工具还是 AI Agent 开发，本实验都能通过动手实践为你提供结构化的学习路径。

开始使用

先决条件

• 具有创建资源权限的 Azure 订阅
• 已安装 azd CLI
• 选择你的开发环境：
  • GitHub Codespaces（速度最快，无需本地设置）
  • VS Code Dev Containers（需要 Docker Desktop）
  • 本地开发（需要 Python 3.11、Node 18+、Azure Functions Core Tools v4）

部署到 Azure

使用 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 区域（建议选择 eastus 或 swedencentral）
• 配置所有资源（Functions、Cosmos DB、Azure OpenAI、DTS）
• 创建用于身份验证的 Azure AD 应用注册
• 部署应用代码

完成后，将显示 Function App URL 和 MCP 端点。有关本地开发、使用模拟器测试和监控编排的详细说明，请参阅教程。

---

指引

区域可用性

Azure OpenAI 模型支持因区域而异。请在此处确认可用性，并为所有 Azure 资源选择同一个区域。eastus 和 swedencentral 是不错的默认选择。

安全性

Snippy 使用用户分配的托管标识进行安全的服务到服务身份验证。基础设施配置如下：

• Function App 上的用户分配的托管标识，并分配适当的 RBAC 角色：
  • Cosmos DB 数据贡献者
  • Storage Blob 数据所有者和 Queue 数据贡献者
  • Application Insights 监视指标发布者
  • Azure AI 项目开发者

对于生产部署，我们建议：

• 使用 Private Endpoints + VNet 集成限制入站流量
• 启用服务终结点和防火墙规则等网络安全功能

---

贡献

采用标准的 fork → branch → PR 工作流。在提交消息中使用 Conventional Commits（feat:、fix:）。

---

许可证

MIT © Microsoft Corporation