Azure AI Foundry+MCP+APIM演示

✅ MCP服务器状态：工作\ 🔐 身份验证：托管身份（必需）

⚠️ 重要：已在Azure AI Foundry上禁用API密钥身份验证。此应用程序现在使用 Azure托管身份 用于所有身份验证。看管理_身份_移民.md 有关设置说明。

此仓库展示了一个完整的 端到端自动化部署 通过GitHub Actions部署的具有模型上下文协议（MCP）功能的AI代理。

🏗️ 建筑

┌─────────────────────────────────────────────────────────────────────┐
│                         GitHub Actions CI/CD                        │
│  ┌───────────────────────────────────────────────────────────────┐  │
│  │ 1. Deploy MCP Server to Azure App Service                    │  │
│  │ 2. Configure APIM Gateway                                     │  │
│  │ 3. Grant Service Principal Permissions                        │  │
│  │ 4. Create/Update AI Agent with MCP Tools                      │  │
│  └───────────────────────────────────────────────────────────────┘  │
│                              ↓                                      │
└──────────────────────────────┼──────────────────────────────────────┘
                               ↓
    ┌──────────────────────────────────────────────────────────┐
    │              Azure AI Foundry Project                    │
    │  ┌────────────────────────────────────────────────────┐  │
    │  │        AI Agent (document-analysis-agent)          │  │
    │  │        Model: gpt-4o-mini                          │  │
    │  │        Tools: MCP Server Connection                │  │
    │  └──────────────┬─────────────────────────────────────┘  │
    └─────────────────┼────────────────────────────────────────┘
                      │ MCP Protocol (SSE)
                      ↓
    ┌─────────────────────────────────────────────────────────┐
    │          Azure API Management (Optional)                │
    │          Security, Rate Limiting, Monitoring            │
    └──────────────┬──────────────────────────────────────────┘
                   │
                   ↓
    ┌─────────────────────────────────────────────────────────┐
    │          MCP Server (Azure App Service)                 │
    │          https://mcp-server-app-*.azurewebsites.net     │
    │  ┌────────────────────────────────────────────────────┐ │
    │  │  MCP Tools:                                        │ │
    │  │  • list_documents   - List uploaded documents      │ │
    │  │  • get_document     - Retrieve document content    │ │
    │  │  • search_documents - Search across documents      │ │
    │  │  • upload_document  - Upload new documents         │ │
    │  └────────────────────────────────────────────────────┘ │
    └─────────────────────────────────────────────────────────┘

🔐 身份验证和授权流程

GitHub Actions Workflow
    ↓ Uses credentials from GitHub Secrets
Service Principal (github-deployer)
    ├─ Role: Contributor (Subscription)
    │  └─ Can deploy resources, manage App Services, APIM
    │
    └─ Roles on AI Project Resource:
       ├─ Azure AI User
       │  └─ Data action: Microsoft.CognitiveServices/*
       │     └─ Includes: agents/write (create agents)
       │
       └─ Cognitive Services OpenAI Contributor
          └─ Data action: Microsoft.CognitiveServices/accounts/OpenAI/*
             └─ Includes: Use OpenAI models

✨ 特性

✅ 全自动部署 -推送到主分支→ 一切都会自动部署\ ✅ 文档上传与分析 -上传TXT/CSV文件或粘贴文本\ ✅ MCP协议支持 -完整模型上下文协议实现\ ✅ Azure AI代理集成 -使用MCP工具自动创建代理\ ✅ APIM网关 -安全的API管理和监控\ ✅ 权限管理 -自动服务主体角色分配\ ✅ CI/CD管道 -完整的基础设施即代码

快速开始

先决条件

Azure人工智能铸造项目 -创建一个https://ai.azure.com
Azure订阅 -具有参与者访问权限的活动Azure订阅
服务主体 -用于GitHub操作身份验证
GitHub存储库 -分叉或克隆此仓库

1.创建Azure服务主体

# Create service principal for GitHub Actions
az ad sp create-for-rbac --name "github-deployer" \
  --role contributor \
  --scopes /subscriptions/ \
  --sdk-auth

# Output will be JSON - save this for GitHub Secrets

2.授予其他权限

服务负责人需要在您的AI Foundry项目中担任其他角色：

# Set variables
SUBSCRIPTION_ID=""
RESOURCE_GROUP=""
AI_PROJECT_RESOURCE=""
SERVICE_PRINCIPAL_ID=""

# Get resource ID
RESOURCE_ID=$(az resource show \
  --name "$AI_PROJECT_RESOURCE" \
  --resource-group "$RESOURCE_GROUP" \
  --resource-type "Microsoft.CognitiveServices/accounts" \
  --query id -o tsv)

# Grant Azure AI User role (for agent creation)
az role assignment create \
  --assignee "$SERVICE_PRINCIPAL_ID" \
  --role "Azure AI User" \
  --scope "$RESOURCE_ID"

# Grant OpenAI Contributor role (for model access)
az role assignment create \
  --assignee "$SERVICE_PRINCIPAL_ID" \
  --role "Cognitive Services OpenAI Contributor" \
  --scope "$RESOURCE_ID"

3.配置GitHub机密

首选设置 → 秘密与变量 → 行动并添加：

秘密名称	描述	示例	必填	备注
`AZURE_CREDENTIALS`	步骤1中的服务主体JSON	`{"clientId":"...","clientSecret":"..."}`	✅ 是	对于GitHub Actions部署
`AI_PROJECT_RESOURCE_GROUP`	您的AI项目的资源组	`AI-RG`	✅ 是
`AI_PROJECT_NAME`	AI Foundry项目资源名称	`my-project-resourcev2`	✅ 是	资源名称，不是显示名称
`FOUNDRY_ENDPOINT`	Azure AI Foundry模型端点	`https://...openai.azure.com/`	✅ 是
`FOUNDRY_API_KEY`	Azure AI Foundry API密钥	`sk-...`	❌ 没有	可选的 -如果未设置，则使用托管身份

备注：web应用程序使用 管理身份 用于向AI Foundry进行身份验证。这 FOUNDRY_API_KEY 是可选的，仅用于向后兼容性。对于生产，建议完全删除这个秘密。

备注：AI_PROJECT_NAME通常是 资源名称 （通常以 -resourcev2)，而不是项目显示名称。

4.更新工作流变量（可选）

编辑 .github/workflows/deploy.yml 自定义：

env:
  AZURE_RESOURCE_GROUP: ai-mcp-rg          # Where MCP server will be deployed
  LOCATION: westeurope                      # Azure region
  WEBAPP_NAME: mcp-server-app-  # Must be globally unique
  APIM_NAME: mcp-apim-          # Must be globally unique
  AI_AGENT_NAME: document-analysis-agent    # Name for your AI agent

5.部署

git add .
git commit -m "Configure for my Azure environment"
git push origin main

GitHub Actions管道将自动：

✅ 将MCP服务器部署到Azure应用服务
✅ 创建/配置APIM网关
✅ 授予服务主体权限（如果需要）
✅ 等待权限传播（2分钟）
✅ 使用配置的MCP工具创建AI代理

6.验证部署

~5-10分钟后，检查：

MCP 服务器: https://.azurewebsites.net/mcp/sse
AI 代理: https://ai.azure.com → 您的项目→ 代理→ document-analysis-agent

🔄 CI/CD管道详细信息

GitHub操作工作流(.github/workflows/deploy.yml)自动化整个部署：

管道阶段

┌─────────────────────────────────────────────────────────────────┐
│ Stage 1: Infrastructure Setup                                  │
├─────────────────────────────────────────────────────────────────┤
│ • Create Azure Resource Group                                  │
│ • Deploy Azure App Service Plan                                │
│ • Deploy Azure App Service (for MCP server)                    │
│ • Configure App Service settings                               │
└─────────────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────────┐
│ Stage 2: MCP Server Deployment                                 │
├─────────────────────────────────────────────────────────────────┤
│ • Build Node.js application                                    │
│ • Deploy to App Service                                        │
│ • Configure environment variables (FOUNDRY_ENDPOINT, etc.)     │
└─────────────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────────┐
│ Stage 3: API Management (Optional)                             │
├─────────────────────────────────────────────────────────────────┤
│ • Create/Update APIM instance                                  │
│ • Import OpenAPI specification                                 │
│ • Configure backend services                                   │
└─────────────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────────┐
│ Stage 4: Permission Management                                 │
├─────────────────────────────────────────────────────────────────┤
│ • Grant "Azure AI User" role (for agents/write)                │
│ • Grant "Cognitive Services OpenAI Contributor" role           │
│ • Wait 2 minutes for permission propagation                    │
└─────────────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────────┐
│ Stage 5: AI Agent Creation                                     │
├─────────────────────────────────────────────────────────────────┤
│ • Discover AI Foundry project endpoint                         │
│ • Initialize Azure AI Projects SDK client                      │
│ • Create agent with MCP tool configuration:                    │
│   {                                                             │
│     "type": "mcp",                                              │
│     "server_label": "document_mcp_server",                     │
│     "server_url": "https://.../mcp/sse"                        │
│   }                                                             │
│ • Configure agent with instructions and model (gpt-4o-mini)    │
└─────────────────────────────────────────────────────────────────┘

关键脚本

脚本	目的
`.github/scripts/get_project_endpoint.sh`	从资源名称中发现AI Foundry项目端点
`.github/scripts/grant_permissions.sh`	向服务负责人授予所需角色
`.github/scripts/create_agent.py`	使用Azure AI项目SDK创建AI代理

管道故障排除

问题：代理创建过程中出现拒绝权限错误\ 解决方案：确保服务主体具有“Azure AI用户”角色（请参阅步骤2）

问题：找不到项目终结点\ 解决方案：验证 AI_PROJECT_NAME 是 资源名称 （查看Azure门户→ 资源）

问题：MCP服务器没有响应\ 解决方案：检查Azure门户中的应用服务日志→ 应用服务→ 日志流

🧪 测试你的AI代理

部署后，在Azure AI Foundry中测试您的代理：

开放式Azure AI Foundry: https://ai.azure.com
导航到您的项目
点击“代理” 在左侧边栏中
打开“文档分析代理”
开始聊天 并尝试以下命令：

You: "List available documents"
Agent: [Uses list_documents MCP tool to show documents]

You: "Upload this text: Azure AI is amazing..."
Agent: [Uses upload_document MCP tool]

You: "What documents do I have?"
Agent: [Uses list_documents MCP tool]

You: "Tell me about the Azure AI document"
Agent: [Uses get_document MCP tool and summarizes]

📊 MCP服务器端点

部署的MCP服务器公开了以下端点：

端点	方法	描述
`/mcp/sse`	GET	模型上下文协议SSE端点（由AI代理使用）
`/session`	POST	创建新文档会话
`/session/{sid}/upload`	POST	将文档上传到会话
`/session/{sid}/query`	POST	查询会话中的文档
`/`	GET	用于测试的简单web UI

🔍 了解组件

服务负责人（github部署者）

A. 服务主体 是用于访问Azure资源的自动化工具（如GitHub Actions）的标识。它具有以下权限：

角色	范围	目的
贡献者	订阅	部署资源、管理应用服务、APIM
Azure AI用户	AI项目资源	创建/管理AI代理（包括 `agents/write`)
认知服务OpenAI贡献者	AI项目资源	使用OpenAI模型

人工智能铸造项目与资源

重要区别:

AI项目名称：您在中看到的显示名称https://ai.azure.com（例如。， davidsr-ai-project)
资源名称：实际的Azure资源名称（例如。， davidsr-ai-project-resourcev2)

GitHub行动需要 资源名称 （通常以 -resourcev2 或 -resource).

MCP工具配置格式

代理使用此JSON结构连接到您的MCP服务器：

{
  "type": "mcp",
  "server_label": "document_mcp_server",
  "server_url": "https://mcp-server-app-*.azurewebsites.net/mcp/sse"
}

备注: server_label 和 server_url 必须位于顶层，而不是嵌套在 mcp 钥匙。

📚 额外资源

端点

/session → 创建新会话。
/session/{sid}/upload → 上传文本文档。
/session/{sid}/query → 提问或总结。

AI Foundry MCP Gw Emeagbb

快速接入

详细介绍