Azure Container Apps - AI & MCP Playground

Azure Container Apps - AI 与 MCP Playground

本项目展示了如何将 MCP 协议与 OpenAI、Azure OpenAI 和 GitHub Models 搭配使用。项目提供了一个简单的演示终端应用，可与 TODO 列表 Agent 交互。 该 Agent 可使用 MCP 服务提供的一组工具。

MCP 组件

当前实现由三个主要组件组成：

1. MCP Host：与 MCP 服务和大模型提供商交互的主应用。Host 会实例化一个大模型提供商，并提供终端界面，供用户与 Agent 交互。
2. MCP Client：使用 MCP 协议与 MCP 服务通信的客户端。该应用提供两个 MCP 客户端，分别支持 HTTP 和 SSE（Server-Sent Events）协议。
3. MCP Server：实现 MCP 协议并与 DocumentDB 数据库通信的服务。该应用提供两种 MCP 服务实现：一种使用 HTTP，另一种使用 SSE（Server-Sent Events）。
4. 大模型提供商：基于 MCP Host 的输入生成响应的语言模型提供商（例如 OpenAI、Azure OpenAI、GitHub Models）。
5. DocumentDB Local：用于存储 Agent 和工具状态的数据库。
6. 工具：Agent 可用于执行操作的一组工具，例如在购物清单中添加或列出项目。

flowchart TD
    user(("fa:fa-users User"))
    host["VS Code, Copilot, LlamaIndex, Langchain..."]
    client[MCP SSE Client]
    clientHttp[MCP HTTP Client]
    server([MCP SSE Server])
    serverHttp([MCP HTTP Server])
    agent[Agent]
    AzureOpenAI([Azure OpenAI])
    GitHub([GitHub Models])
    OpenAI([OpenAI])
    
    tools["fa:fa-wrench Tools"]
    db[(DocumentDB Local)]

    user --> hostGroup 
    subgraph hostGroup["MCP Host"]
        host -.- client & clientHttp & agent
    end
    
    agent -.- AzureOpenAI & GitHub & OpenAI
    
    client a@ ---> |"Server Sent Events"| server
    clientHttp aa@ ---> |"Streamable HTTP"| serverHttp

    subgraph container["ACA Container (*)"]
      server -.- tools
      serverHttp -.- tools
      tools -.- add_todo 
      tools -.- list_todos
      tools -.- complete_todo
      tools -.- delete_todo
    end

    add_todo b@ --> db
    list_todos c@--> db
    complete_todo d@ --> db
    delete_todo e@ --> db
    
    %% styles

    classDef animate stroke-dasharray: 9,5,stroke-dashoffset: 900,animation: dash 25s linear infinite;
    classDef highlight fill:#9B77E8,color:#fff,stroke:#5EB4D8,stroke-width:2px
    
    class a animate
    class aa animate
    class b animate
    class c animate
    class d animate
    class e animate

    class container highlight

MCP 服务支持的功能和能力

此演示应用提供两种 MCP 服务实现：一种使用 HTTP，另一种使用 SSE（Server-Sent Events）。MCP Host 可以连接到这两种服务，让你可以选择最适合需求的一种。

功能	已完成
SSE（旧版）	✅
HTTP 流式传输	✅
AuthN（基于令牌）	wip
工具	✅
资源	#3
提示词	#4
Sampling	#5

快速开始（使用 Docker）

若要使用 Docker 开始本项目，请按以下步骤操作：

1. 克隆仓库：

git clone https://github.com/Azure-Samples/azure-container-apps-ai-mcp.git
cd azure-container-apps-ai-mcp

2. 启动 Docker 容器：

docker-compose up

3. 使用 VS Code 内置的 MPC 支持访问 MCP 服务，参见 ./.vscode/mcp.json。所有数据都会持久化到 DocumentDB Local 数据库中。你可以使用 VS Code extension for DocumentDB 浏览数据库。

本地开发

若要开始本项目，请按以下步骤操作：

先决条件

• Node.js 和 npm（版本 22 或更高）
• Docker（建议用于运行 MCP 服务和 Docker 中的 DocumentDB Local）
• 一个兼容 OpenAI 的端点：
  • 一个 OpenAI API 密钥
  • 或者，如果要使用 GitHub 模型，则需要一个 GitHub 令牌：https://gh.io/models
  • 或者，如果使用 Azure OpenAI，则需要拥有一个 Azure OpenAI resource 和对应的端点。

安装

1. 克隆仓库。
2. 安装依赖项：

npm install --prefix mcp-host
npm install --prefix mcp-server-http
npm install --prefix mcp-server-sse

配置要使用的大模型提供商

此示例支持以下大模型提供商：

提供商	支持的 API
Azure OpenAI	Responses API
OpenAI	Responses API
GitHub Models	ChatCompletion API

Azure OpenAI

说明

在本地的 Docker 容器中运行时，不支持使用托管标识访问 Azure OpenAI。你可以不使用 Docker，直接在本地运行代码；也可以使用其他身份验证方式，例如通过 AZURE_OPENAI_API_KEY 进行密钥身份验证。

要使用 Azure 托管标识进行无密钥身份验证，需要在 .env 文件中设置 AZURE_OPENAI_ENDPOINT 环境变量：

AZURE_OPENAI_ENDPOINT="https://<ai-foundry-openai-project>.openai.azure.com"
MODEL="gpt-4.1"

# (optional) Set the Azure OpenAI API key if you are not using Managed Identity
# AZURE_OPENAI_API_KEY=your_azure_openai_api_key

并确保使用 Azure CLI 登录 Azure 帐户，然后按照说明选择订阅：

az login

OpenAI

要使用 OpenAI API，需要在 .env 文件中设置 OPENAI_API_KEY 密钥：

OPENAI_API_KEY=your_openai_api_key
MODEL="gpt-5"

GitHub Models

要使用 GitHub 模型，需要在 .env 文件中设置 GITHUB_TOKEN：

GITHUB_TOKEN=your_github_token
MODEL="openai/gpt-5"

运行 MCP 服务

在 DevContainer 中运行（推荐）

此项目包含 DevContainer 配置，可让你在容器化环境中运行 MCP 服务。推荐使用这种方式运行 MCP 服务，因为它可以确保所有依赖项都已正确安装和配置。

在 DevContainer 中打开项目后，可以按照下方的 Docker 部分运行 MCP 服务。

在 Docker 中运行

你可以使用提供的 Docker Compose 文件，在 Docker 容器中运行两个 MCP 服务。这适用于测试和开发。操作步骤如下：

1. 确保你的计算机已安装 Docker。在终端中输入 docker compose，检查是否已安装 Docker Compose。
2. 进入项目根目录，运行以下命令来构建并启动容器：

docker compose up -d --build

此命令会构建并启动 HTTP 和 SSE MCP 服务，以及 DocumentDB 数据库容器。

3. 在另一个终端中运行以下命令，以访问 MCP 主机终端：

docker exec -it mcp-host bash

4. 在容器内，你可以运行 MCP 主机，并按照上方“用法”部分中的说明与大模型 Agent 交互。

在 Docker 外部运行

1. 首先，在不同的终端中运行 MCP 服务：

npm start --prefix mcp-server-http
npm start --prefix mcp-server-sse

说明

为了演示，MCP 主机（见下文）配置为连接两个服务（端口 3000 和 3001）。但这不是必需的，你可以选择要使用的服务。如果某个服务不可用，主机会打印错误，并继续扫描其他服务。如果没有可用服务，Agent 将无法使用任何工具。

1. 在另一个终端中运行 MCP 主机：

npm start --prefix mcp-host

你应该可以使用 MCP 主机与大模型 Agent 交互。试着询问如何在购物清单中添加或列出条目。随后，主机会尝试从 MCP 服务获取并调用工具。

调试与检查

你可以使用 DEBUG 环境变量为 MCP 主机启用详细日志记录：

DEBUG=mcp:* npm start --prefix mcp-host

默认情况下，两个 MCP 服务都已启用调试。

许可证

此项目基于 MIT License 许可。详情请参阅 LICENSE 文件。