使用说明

Python MCP演示

一个演示项目，展示了使用FastMCP的模型上下文协议（MCP）实现，包括stdio和HTTP传输、与LangChain和代理框架的集成以及部署到Azure容器应用程序的示例。

入门

您有几个选项可以设置此项目。最快的入门方法是GitHub Codespace，因为它将为您设置所有工具，但您也可以在本地设置。

GitHub代码空间

您可以使用GitHub Codespace虚拟运行此项目。单击以下按钮之一，在浏览器中打开基于web的VS Code实例：

默认值（Azure OpenAI）：

Ollama（本地型号，需要64GB+内存）：

Ollama Codespace预安装Ollama并拉取 gemma4:e2b 模型和副本 .env.sample.ollama 如你的 .env 文件。请注意，64GB的内存需求将更快地消耗您的代码空间配额。

打开代码空间后，打开终端窗口并继续执行部署步骤。

VS代码开发容器

一个相关的选项是VS代码开发容器，它将使用开发容器扩展:

启动Docker桌面（如果尚未安装，请安装）
打开项目：
在打开的VS Code窗口中，一旦项目文件出现（这可能需要几分钟），打开一个终端窗口。
继续执行部署步骤。

当地环境

如果你没有使用上述选项之一，那么你需要：

确保安装了以下工具：
克隆存储库并打开项目文件夹。
创建一个 Python虚拟环境并激活它。
安装依赖项：
```
uv sync
```
复制 .env-sample 到 .env 并配置您的环境变量：
```
cp .env-sample .env
```
编辑 .env 使用您的API证书。通过设置选择以下提供程序之一 API_HOST:
- azure -Azure OpenAI（需要Azure凭据）
- ollama -支持Responses API的本地Ollama实例
- openai -OpenAI API（需要 OPENAI_API_KEY)

运行本地MCP服务器

该项目包括MCP服务器 servers/ 目录：

文件	描述
服务器/basic_mcp_strio.py	用于VS Code集成的带stdio传输的MCP服务器
服务器/basic_mcp_http.py	端口8000上具有HTTP传输的MCP服务器
servers/deployed_mcp.py	用于Azure部署的MCP服务器，带有Cosmos DB和可选的Keycloak身份验证

本地服务器(basic_mcp_stdio.py 和 basic_mcp_http.py)使用工具实现“费用跟踪器”，将费用添加到CSV文件中。

与GitHub Copilot一起使用

这 .vscode/mcp.json 该文件为GitHub Copilot集成配置MCP服务器：

可用服务器：

费用mcp：用于生产的stdio传输服务器
mcp调试费用：端口5678上带有调试程序的stdio服务器
费用mcp http：HTTP传输服务器位于 http://localhost:8000/mcp。您必须使用手动启动此服务器 uv run servers/basic_mcp_http.py 在使用它之前。

切换服务器：

通过打开聊天面板，选择工具图标，并从列表中选择所需的MCP服务器，配置GitHub Copilot使用的服务器。

示例输入：

使用这样的查询来测试费用MCP服务器：

Log expense for 50 bucks of pizza on my amex today

使用VS代码进行调试

这 .vscode/launch.json 提供调试配置以连接到MCP服务器。

使用GitHub Copilot Chat调试MCP服务器：

在MCP服务器代码中设置断点 servers/basic_mcp_stdio.py
通过启动调试服务器 mcp.json 通过选择进行配置 expenses-mcp-debug
按 Cmd+Shift+D 打开运行和调试
选择“连接到MCP服务器（stdio）”配置
按 F5 或单击播放按钮启动调试器
在GitHub Copilot聊天工具中选择“experts mcp debug”服务器
使用GitHub Copilot Chat触发MCP工具
调试器在断点处暂停

与MCP检查员一起检查

这 MCP检查员是一个用于测试和调试MCP服务器的开发工具。

注：虽然HTTP服务器在技术上可以在代码空间/开发容器中处理端口转发，但MCP检查器和调试器附件的设置并不简单。为了获得具有完整调试功能的最佳开发体验，我们建议在本地运行此项目。

对于stdio服务器：

npx @modelcontextprotocol/inspector uv run servers/basic_mcp_stdio.py

对于HTTP服务器：

启动HTTP服务器：
```
uv run servers/basic_mcp_http.py
```

在另一个终端中，运行检查器：

npx @modelcontextprotocol/inspector http://localhost:8000/mcp

检查员提供了一个web界面，用于：

查看可用的工具、资源和提示
使用自定义参数调用测试工具
检查服务器响应和错误
调试服务器通信

使用Aspire仪表板查看痕迹

您可以使用 .NET Aspire仪表板从MCP服务器查看OpenTetry跟踪、指标和日志。

注： Aspire Dashboard集成仅为HTTP服务器配置(basic_mcp_http.py).

启动Aspire仪表板：
```
docker run --rm -d -p 18888:18888 -p 4317:18889 --name aspire-dashboard \
    mcr.microsoft.com/dotnet/aspire-dashboard:latest
```
Aspire Dashboard在容器端口18889上公开了其OTLP端点。地图 -p 4317:18889 使其在主机的标准OTLP端口4317上可用。

从容器日志中获取仪表板URL和登录令牌：
```
docker logs aspire-dashboard 2>&1 | grep "Login to the dashboard"
```

通过将此添加到您的 .env 文件：

OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

启动HTTP服务器：
```
uv run servers/basic_mcp_http.py
```
查看仪表板：http://localhost:18888

运行本地代理<->MCP

该项目包括示例代理 agents/ 演示如何将AI代理连接到MCP服务器的目录：

文件	描述
agents/agentframework_http.py	Microsoft代理框架与本地Expenses MCP服务器的集成
代理/代理框架_ earn.py	Microsoft代理框架与远程学习MCP服务器的集成
agents/langchainv1_http.py	LangChain代理与本地Expenses MCP服务器
agents/langchainv1_github.py	带远程GitHub MCP的LangChain工具过滤代理（需要 `GITHUB_TOKEN`)

要运行代理，请执行以下操作：

首先启动HTTP MCP服务器：
```
uv run servers/basic_mcp_http.py
```
在另一个终端中，运行代理：
```
uv run agents/agentframework_http.py
```

代理将连接到MCP服务器，并允许您通过聊天界面与费用跟踪工具进行交互。

部署到Azure

此项目可以使用Azure Developer CLI（azd）部署到Azure容器应用程序。部署规定：

Azure容器应用 -同时托管MCP服务器和代理
Azure OpenAI -为代理提供LLM
Azure Cosmos数据库 -存储费用数据
Azure容器注册表 -存储容器图像
日志分析 -监测和诊断

Azure帐户设置

注册一个免费Azure帐户并创建Azure订阅。
检查您是否具有必要的权限：
- 您的Azure帐户必须具有 Microsoft.Authorization/roleAssignments/write 权限，例如基于角色的访问控制管理员, 用户访问管理员，或拥有者.
- 您的Azure帐户还需要 Microsoft.Resources/deployments/write 订阅级别的权限。

使用azd部署

登录到Azure：
```
azd auth login
```
对于GitHub Codespace用户，如果前面的命令失败，请尝试：
```
azd auth login --use-device-code
```
创建新的azd环境：
```
azd env new
```
这将在内部创建一个文件夹 .azure 您的环境名称。
提供和部署资源：
```
azd up
```
它将提示您选择订阅和位置。这将需要几分钟才能完成。
部署完成后，a .env 将创建一个文件，其中包含必要的环境变量，以便在部署的资源上本地运行代理。

成本

定价因地区和使用情况而异，因此无法预测您使用的确切成本。

你可以试试 Azure定价计算器对于资源：

Azure OpenAI服务：S0级，GPT-5.2型号。定价基于代币数量。定价
Azure容器应用：消费层。定价
Azure容器注册表：标准层。定价
Azure Cosmos数据库：无服务器层。定价
日志分析 （可选）：按需付费。成本基于摄入的数据。定价

⚠️ 为了避免不必要的成本，如果应用程序不再使用，请记住通过删除门户中的资源组或运行 azd down.

将部署的MCP服务器与GitHub Copilot一起使用

已部署的MCP服务器的URL在azd环境变量中可用 MCP_SERVER_URL，并写入 .env 部署后创建的文件。

为避免冲突，请停止MCP服务器 mcp.json 并禁用GitHub Copilot聊天工具中的费用MCP服务器。
从VS代码命令面板中选择“MCP:添加服务器”
选择“HTTP”作为服务器类型
根据以下内容输入MCP服务器的URL MCP_SERVER_URL 环境变量。
在GitHub Copilot Chat工具中启用MCP服务器，并使用费用跟踪查询对其进行测试：
```
Log expense for 75 dollars of office supplies on my visa last Friday
```

在本地运行服务器

部署设置了所需的Azure资源（Cosmos DB、Application Insights）后，您还可以在本地针对这些资源运行MCP服务器：

# Run the MCP server
cd servers && uvicorn deployed_mcp:app --host 0.0.0.0 --port 8000

在Azure应用程序洞察中查看跟踪

默认情况下，已部署的MCP服务器启用了OpenTetry跟踪，并将跟踪发送到Azure Application Insights。要打开指标和跟踪的仪表板，请运行：

azd monitor

或者，您可以直接使用Application Insights：

打开Azure门户，导航到部署期间创建的Application Insights资源（名为 <project-name>-appinsights).
在Application Insights中，转到“事务搜索”查看MCP服务器的跟踪。
您可以过滤和分析跟踪以监控性能和诊断问题。

在Logfire中查看痕迹

您还可以在中查看OpenTetry跟踪原木火通过配置MCP服务器以在那里发送跟踪。

创建一个Logfire帐户，并从Logfire仪表板获取您的写入令牌。

设置azd环境变量以启用Logfire：

azd env set OPENTELEMETRY_PLATFORM logfire
azd env set LOGFIRE_TOKEN <your-logfire-write-token>

提供和部署：
```
azd up
```
打开Logfire仪表板查看MCP服务器的跟踪。

通过专用网络部署到Azure

为了演示生产部署的增强安全性，此项目支持使用限制公共访问Azure资源的虚拟网络（ExpressRoute）配置进行部署。

设置这些azd环境变量，为容器应用程序、Cosmos DB和OpenAI资源设置虚拟网络和私有端点：
```
azd env set USE_VNET true
azd env set USE_PRIVATE_INGRESS true
```
日志分析和ACR资源仍将启用公共访问，因此您可以在不需要VPN的情况下部署和监控应用程序。在生产中，您通常也会限制这些。
提供和部署：
```
azd up
```

私人网络的额外费用

当使用ExpressRoute配置时，会配置额外的Azure资源：

虚拟网络：现收现付。成本基于处理的数据。定价
Azure专用DNS解析程序：每月定价、端点和区域。定价
Azure专用端点：每个端点每小时定价。定价

使用Keycloak身份验证部署到Azure

该项目支持使用Keycloak作为身份提供者，使用OAuth 2.0身份验证进行部署，实现 MCP OAuth规范使用动态客户端注册（DCR）。

📺 观看Keycloak集成的演示视频

部署什么

组件	描述
Keycloak容器应用程序	Keycloak 26.6.0，带预配置域
HTTP路由配置	基于规则的路由： `/auth/` → 钥匙斗篷， `/` → MCP服务器
OAuth保护的MCP服务器	FastMCP与Keycloak的JWKS端点进行JWT验证

部署步骤

启用Keycloak身份验证：
```
azd env set MCP_AUTH_PROVIDER keycloak
```

设置Keycloak管理员密码（必填）：

azd env set KEYCLOAK_ADMIN_PASSWORD "YourSecurePassword123!"

可选地自定义领域名称（默认值： mcp):
```
azd env set KEYCLOAK_REALM_NAME "mcp"
```
部署到Azure：
```
azd up
```
这将创建Azure容器应用程序环境，使用预配置的域部署Keycloak，使用OAuth验证部署MCP服务器，并配置基于HTTP路由的路由。

通过检查输出来验证部署：

azd env get-value MCP_SERVER_URL
azd env get-value KEYCLOAK_DIRECT_URL
azd env get-value KEYCLOAK_ADMIN_CONSOLE

访问Keycloak管理控制台以验证域是否已配置：
```
https://<your-mcproutes-url>/auth/admin
```
使用...登录 admin 以及您配置的密码。

将Keycloak OAuth MCP服务器与GitHub Copilot结合使用

Keycloak部署支持动态客户端注册（DCR），这允许VS Code自动注册为OAuth客户端。VS代码重定向URI在Keycloak领域中预先配置。

要将部署的MCP服务器与GitHub Copilot Chat一起使用：

为避免冲突，请停止MCP服务器 mcp.json 并禁用GitHub Copilot聊天工具中的费用MCP服务器。
从VS代码命令面板中选择“MCP:添加服务器”
选择“HTTP”作为服务器类型
输入MCP服务器的URL azd env get-value MCP_SERVER_URL
您应该看到浏览器中打开了Keycloak身份验证屏幕。选择“允许访问”：
使用Keycloak用户登录（例如。， testuser / testpass 对于预配置的演示用户）：
身份验证后，浏览器将重定向回VS Code：
在GitHub Copilot聊天工具中启用MCP服务器：

使用费用跟踪查询进行测试：

Log expense for 75 dollars of office supplies on my visa last Friday

通过检查Cosmos数据库来验证费用是否增加 user-expenses Azure门户中的容器或通过询问GitHub Copilot Chat：
```
Show me my expenses from last week
```

已知限制（演示权衡）

项目	当前	生产建议	为什么
钥匙斗篷模式	`start-dev`	`start` 配置正确	开发模式放宽了安全默认设置
数据库	H2在内存中	PostgreSQL	H2在重启后不会持久化数据
副本	1（由于H2）	多个共享数据库	H2在内存中，无法共享状态
Keycloak访问	公共（直接URL）	仅通过路由进行内部访问	部署后才知道路由URL
DCR	开放（匿名）	需要初始访问令牌	任何客户端都可以在没有身份验证的情况下注册

注： Keycloak必须可公开访问，因为其URL是由Azure动态生成的。令牌颁发者验证需要一个已知的URL，但mcproutes URL在部署后才可用。使用自定义域可以解决此问题。

使用Entra OAuth代理部署到Azure

此项目支持使用FastMCP内置的Azure OAuth代理进行Microsoft Entra ID（Azure AD）身份验证的部署。这是Keycloak的替代方案，它使用Microsoft Entra和Azure租户进行身份管理。

📺 观看Entra集成的演示视频

Entra OAuth部署了什么

组件	描述
Microsoft Entra应用程序注册	在配置过程中自动创建，重定向URI用于本地开发、VS代码和生产
OAuth保护的MCP服务器	用于OAuth身份验证的带AzureProvider的FastMCP
CosmosDB OAuth客户端存储	在服务器重启期间保持OAuth客户端注册

Entra OAuth的部署步骤

启用Entra OAuth代理：

azd env set MCP_AUTH_PROVIDER entra_proxy

设置租户ID，以便在正确的租户中创建应用程序注册：
```
azd env set AZURE_TENANT_ID "<your-tenant-id>"
```
部署到Azure：
```
azd up
```
部署期间：
- 预浸钩：使用客户端密钥创建Microsoft Entra应用程序注册，并将凭据存储在azd环境变量中
- 供应后挂钩：使用部署的服务器URL作为额外的重定向URI更新应用程序注册

通过检查输出来验证部署：

azd env get-value MCP_SERVER_URL
azd env get-value ENTRA_PROXY_AZURE_CLIENT_ID

环境变量

以下环境变量由部署挂钩自动设置：

变量	描述
`ENTRA_PROXY_AZURE_CLIENT_ID`	应用程序注册的客户端ID
`ENTRA_PROXY_AZURE_CLIENT_SECRET`	应用程序注册的客户端密码

然后将其写入 .env 通过后视觉挂钩进行局部开发。

在本地测试Entra OAuth服务器

部署后，您可以在启用OAuth的情况下进行本地测试：

# Run the MCP server
cd servers && uvicorn auth_entra_mcp:app --host 0.0.0.0 --port 8000

服务器将使用OAuth的Entra应用程序注册和CosmosDB进行客户端存储。

使用Entra OAuth MCP服务器和GitHub Copilot

Entra应用程序注册包括以下VS代码的重定向URI：

https://vscode.dev/redirect （VS代码网）
http://127.0.0.1:{33418-33427} （VS Code桌面本地身份验证助手，10个端口）