Azure 容器应用 - AI & MCP 实验场

本项目展示了如何使用MCP协议与OpenAI、Azure OpenAI和GitHub模型进行交互。它提供了一个简单的终端演示应用程序，该程序与一个待办事项列表代理进行互动。 代理可以访问由MCP服务器提供的工具集。

MCP 组件

当前实现主要包括三个主要组件：

1. MCP 主机：与MCP服务器和语言模型提供商进行交互的主要应用程序。主机实例化一个语言模型提供商，并提供一个终端界面供用户与代理进行交互。
2. MCP 客户端：使用MCP协议与MCP服务器通信的客户端。应用程序提供了两种MCP客户端，分别支持HTTP和SSE（服务器发送事件）协议。
3. MCP 服务器：实现MCP协议并与DocumentDB数据库通信的服务器。应用程序提供了两种MCP服务器实现：一种使用HTTP，另一种使用SSE（服务器发送事件）。
4. 语言模型提供商：例如OpenAI、Azure OpenAI、GitHub模型等，根据MCP主机提供的输入生成响应。
5. 本地DocumentDB：用于存储代理状态和工具的数据库。
6. 工具：代理可以用来执行操作的一组工具，如添加或列出购物清单中的项目。

flowchart TD
    user(("fa:fa-users 用户"))
    host["VS Code, Copilot, LlamaIndex, Langchain..."]
    client[MCP SSE 客户端]
    clientHttp[MCP HTTP 客户端]
    server([MCP SSE 服务器])
    serverHttp([MCP HTTP 服务器])
    agent[代理]
    AzureOpenAI([Azure OpenAI])
    GitHub([GitHub 模型])
    OpenAI([OpenAI])
    
    tools["fa:fa-wrench 工具"]
    db[(本地DocumentDB)]

    user --> hostGroup 
    subgraph hostGroup["MCP 主机"]
        host -.- client & clientHttp & agent
    end
    
    agent -.- AzureOpenAI & GitHub & OpenAI
    
    client a@ ---> |"服务器发送事件"| server
    clientHttp aa@ ---> |"可流式传输的HTTP"| serverHttp

    subgraph container["ACA 容器 (*)"]
      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
    
    %% 样式

    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（服务器发送事件）。MCP主机可以连接到这两种服务器，允许您选择最适合需求的一种。

功能	完成情况
SSE (旧版)	✅
HTTP 流式传输	✅
认证 (基于令牌)	进行中
工具	✅
资源	#3
提示	#4
抽样	#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数据库中。您可以使用VS Code的DocumentDB扩展来探索数据库。

本地开发

要开始这个项目，请按照以下步骤操作：

前提条件

• Node.js 和 npm（版本22或更高）
• Docker（推荐用于运行MCP服务器和Docker中的本地DocumentDB）
• 与OpenAI兼容的端点：
  • OpenAI API密钥
  • 或者，如果您想使用GitHub模型，需要一个GitHub令牌：https://gh.io/models
  • 或者，如果您使用Azure OpenAI，需要有一个Azure OpenAI资源及其相应的端点。

安装

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

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

配置使用的语言模型提供商

此样本支持以下语言模型提供商：

提供商	支持的API
Azure OpenAI	响应API
OpenAI	响应API
GitHub 模型	对话完成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"

# （可选）如果您不使用托管身份，则设置Azure OpenAI API密钥
# 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 模型

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

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

运行MCP服务器

在DevContainer中运行（推荐）

此项目包括一个DevContainer配置，允许您在一个容器化的环境中运行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主机并按照上述“用法”部分描述的方式与语言模型代理进行交互。

在Docker外部运行

1. 首先，在单独的终端中运行MCP服务器：

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

[!注意] 为了演示目的，MCP主机（如下所示）被配置为连接到两个服务器（端口3000和3001）。然而，这不是必需的，您可以选择使用哪个服务器。如果某个服务器不可用，主机将打印错误并继续扫描其他服务器。如果没有可用的服务器，代理将无法使用任何工具。

1. 在单独的终端中运行MCP主机：

npm start --prefix mcp-host

您应该能够使用MCP主机与语言模型代理进行交互。尝试询问有关添加或列出购物清单中的项目的操作。主机将尝试从MCP服务器获取并调用工具。

调试和检查

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

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

调试默认情况下对两个MCP服务器都是开启的。

许可证

本项目根据MIT许可证发布。详情请参阅LICENSE文件。