FoundryAgent-MCP-Stub

概述

此仓库提供了一个轻量级的MCP（模型上下文协议）服务器，该服务器将Azure AI Foundry Agent作为MCP工具公开。 部署后，任何兼容MCP的客户端都可以调用已注册的Foundry Agent作为可流式传输的HTTP MCP服务器。

特性

• 最小化的自包含Python实现（单个server.py文件）。
• 无状态的REST API，将请求转发到Azure AI Foundry Agent。
• 除了官方的Azure AI Foundry Python SDK外，没有其他外部依赖项。

MCP工具信息

MCP工具的名称和描述直接来源于对应的Azure AI Foundry Agent元数据。 请确保您的代理的名称和描述有意义，因为客户端将依靠它们来正确发现和调用工具。

公开的工具如下所示：

{
    "name": "<agent name>",          // 空格被替换为下划线
    "description": "<agent description>",
    "inputSchema": {
        "type": "object",
        "required": ["query"],
        "properties": {
            "query": {
                "type": "string",
                "description": "工具查询",
            }
        }
    }
}

先决条件

1. Python 3.9+（已在开发容器中预安装）
2. 访问Azure AI Foundry Agent
   • Foundry 终结点URL
   • Foundry 代理ID
   • API密钥用于验证传入请求（您管理的任何不透明字符串）

配置

服务器完全通过环境变量进行配置：

变量	描述
AZURE_AI_ENDPOINT	目标AI Foundry的HTTPS终结点（例如：https://<your-resource>.services.ai.azure.com/api/projects/<your-project>）
AZURE_AI_AGENT_ID	您希望公开的代理标识符
API_KEY	客户端必须在x-api-keyHTTP头中发送的值
PORT (可选)	绑定的TCP端口（默认3000）

可以在本地导出这些变量或在容器化时通过docker run ‑e传递它们。

快速开始（本地）

# 0) 登录有效的Azure帐户以访问Azure AI Foundry
az login

# 1) 克隆并安装运行时依赖项
pip install -r requirements.txt

# 2) 配置环境（替换为您真实的值）
export AZURE_AI_ENDPOINT="https://xxx.services.ai.azure.com/api/projects/yyy"
export AZURE_AI_AGENT_ID="agent-123456"
export API_KEY="replace-me"

# 3) 启动服务
python server.py  # 监听于 http://localhost:3000/mcp

在Azure容器应用上运行

包含一个Dockerfile，并且GitHub Actions工作流程会自动构建并将容器镜像发布到GitHub容器注册表（GHCR），作为ghcr.io/hatasaki/foundryagent-mcp-stub:latest。您可以直接将这个预构建的镜像部署到Azure容器应用——无需本地docker build / docker push。

# 0) 登录并选择正确的订阅
az login
az account set --subscription <SUBSCRIPTION_ID>

# （设置环境变量以便重复使用）
export RESOURCE_GROUP="<your-resource-group>"
export YOUR_REGION="<your-region>"

# 1) 部署（初始）最新发布的GHCR镜像

az containerapp up \
  --name foundry-mcp-server \
  --resource-group $RESOURCE_GROUP \
  --location $YOUR_REGION \
  --image ghcr.io/hatasaki/foundryagent-mcp-stub:latest \
  --target-port 3000 \
  --ingress external \
  --env-vars AZURE_AI_ENDPOINT=$AZURE_AI_ENDPOINT \
             AZURE_AI_AGENT_ID=$AZURE_AI_AGENT_ID \
             PORT=3_000

# 1.1) 创建密钥
az containerapp secret set \
  --name foundry-mcp-server \
  --resource-group $RESOURCE_GROUP \
  --secrets api-key=$API_KEY

# 1.2) 设置API_KEY引用密钥（secretref:）
az containerapp update \
  --name foundry-mcp-server \
  --resource-group $RESOURCE_GROUP \
  --set-env-vars API_KEY=secretref:api-key

# 1.3) 启用托管身份
az containerapp identity assign \
  --name foundry-mcp-server \
  --resource-group $RESOURCE_GROUP \
  --system-assigned

# 2) 授予托管身份访问Azure AI Foundry的权限（一次性操作）
PRINCIPAL_ID=$(az containerapp show \
  --name foundry-mcp-server \
  --resource-group $RESOURCE_GROUP \
  --query "identity.principalId" -o tsv)

az role assignment create \
  --assignee $PRINCIPAL_ID \
  --role "Azure AI User" \
  --scope $(az resource show --name <AI_Foundry_Name> --resource-group <FOUNDRY_RESOURCE_GROUP> --resource-type Microsoft.CognitiveServices/accounts --query id --output tsv)

# 3) 验证并检查您的容器应用的入口网关URL
az containerapp show --name foundry-mcp-server --resource-group $RESOURCE_GROUP -o table

# 4) 添加MCP客户端（如VSCode，Azure的MCP客户端）以连接
VSCode mcp.json示例：
{
  "servers": {
    "Foundry MCP server": {
      "type": "http",
      "url": "https://foundry-mcp-server.xxx.<region>.azurecontainerapps.io/mcp",
      "headers": {
        "x-api-key": "<your api key>"
      }
    }
  }
}

免责声明

本软件仅供测试、评估和演示目的使用。它不具备生产就绪性且没有任何形式的保证。自行承担风险使用。该项目未获得微软正式认可。

贡献

本项目采用了微软开源行为准则。更多详情请参阅行为准则FAQ或联系opencode@microsoft.com以获取额外的问题或评论。

许可证

本项目采用MIT许可证。详情请参见LICENSE文件。