MS docs MCP agents

Microsoft Docs MCP代理-双框架PoC

一个FastAPI应用程序，演示了两个AI代理框架（Microsoft agent Framework和LangGraph）与 完全MCP集成 通过Azure OpenAI访问Microsoft Learn文档。

概述

该项目展示了一个AI代理框架的比较平台，允许用户在Microsoft agent Framework（MAF）和LangGraph之间切换，以查看不同框架如何处理针对Microsoft文档的相同查询。

两个代理都具有完整的MCP（模型上下文协议）集成 使用Microsoft Learn MCP Server，提供对Microsoft官方文档的实时访问。

特性

MCP支持双代理框架

微软代理框架（MAF）

• ✅ 完全MCP集成 通过 MCPStreamableHTTPTool
• ✅ 实时文档访问 微软学习
• ✅ 综合响应 有引用和例子
• ✅ 原生MCP支持 内置于框架中

LangGraph

• ✅ 完全MCP集成 通过 langchain-mcp-adapters
• ✅ 实时文档访问 微软学习
• ✅ 结构化响应 附有详细解释
• ✅ 基于工具的体系结构 具有自动MCP工具转换功能

交互式用户界面

• 在代理之间切换 -一键切换框架
• 视觉徽章 -明确指出哪种试剂产生了每个响应（MAF/LangGraph）
• Markdown渲染 -带有标题、代码块、列表和链接的漂亮格式
• 响应式设计 -专业的微软主题界面

技术特性

• 使用Jinja2进行服务器端渲染
• 实时降价到HTML转换
• 两个框架的MCP服务器集成
• 视觉反馈错误处理
• 健康检查端点
• 干净、可维护的代码结构

建筑

User Browser
    ↓
FastAPI (Port 8000)
    ↓
    ├─→ Microsoft Agent Framework → Azure OpenAI → MCP Server → Microsoft Learn Docs
    └─→ LangGraph → Azure OpenAI → MCP Server → Microsoft Learn Docs

先决条件

• Python 3.11+
• 已部署模型的Azure OpenAI资源（建议使用gpt-4o-mini）
• 用于MCP服务器访问的互联网连接

安装

1.克隆存储库

git clone https://github.com/josephazar/MS_docs_mcp_agents.git
cd MS_docs_mcp_agents

2.创建虚拟环境

python3.11 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3.安装依赖项

pip install -r requirements.txt

4.配置环境变量

复制示例环境文件并使用您的凭据进行更新：

cp .env.example .env

编辑 .env 并添加您的Azure OpenAI凭据：

AZURE_OPENAI_ENDPOINT=https://your-resource-name.openai.azure.com
AZURE_OPENAI_API_KEY=your-api-key-here
AZURE_OPENAI_API_VERSION=2024-12-01-preview
AZURE_OPENAI_DEPLOYMENT_NAME=gpt-4o-mini

运行应用程序

启动服务器

# Make sure virtual environment is activated
source venv/bin/activate

# Run the application
python app.py

或者直接使用uvicorn：

uvicorn app:app --host 0.0.0.0 --port 8000

访问应用程序

打开浏览器并导航到：

• 应用： http://localhost:8000
• 健康检查： http://localhost:8000/health

用法

1. 选择代理框架 -单击“Microsoft代理框架”或“LangGraph”按钮
2. 输入你的问题 -键入有关Microsoft技术的问题
3. 提交 -点击“询问客服”以获得回复
4. 查看结果 -查看带有代理徽章的格式化响应

查询示例

• “什么是Azure函数，如何创建一个？”
• “如何使用Azure CLI将web应用部署到Azure应用服务？”
• “什么是Azure Kubernetes服务？”
• “解释Azure容器实例”
• “如何创建Azure SQL数据库？”

API终点

GET /

带有代理切换和查询表单的主页

POST /query

向Microsoft代理框架提交查询

• 表单参数： query_text （字符串）
• 退货： 来自MCP的带有MAF答案的HTML响应

POST /query-langgraph

向LangGraph代理提交查询

• 表单参数： query_text （字符串）
• 退货： 来自MCP的带有LangGraph答案的HTML响应

GET /health

健康检查端点

• 退货： 带有代理初始化状态的JSON

项目结构

MS_docs_mcp_agents/
├── app.py                           # Main FastAPI application
├── langgraph_agent.py               # LangGraph agent with MCP integration
├── templates/
│   └── index.html                  # Jinja2 template with toggle UI
├── static/                         # Static files directory
├── .env.example                    # Example environment variables
├── .gitignore                      # Git ignore rules
├── requirements.txt                # Python dependencies
├── README.md                       # This file
└── MCP_INTEGRATION_SUCCESS.md      # MCP integration test results

使用的技术

后端

• 快速API -现代web框架
• Uvicorn -ASGI服务器
• Microsoft代理框架 -具有原生MCP支持的AI代理编排
• LangGraph -基于图的代理框架
• LangChain -LLM应用框架
• langchain mcp适配器 -LangChain/LangGraph的MCP集成
• 降价2 -Markdown到HTML的转换

AI/ML

• Azure OpenAI -语言模型提供者（gpt-4o-mini）
• Microsoft学习MCP服务器 -实时文档访问

前端

• Jinja2 -模板引擎
• HTML5/CSS3 -现代网络标准
• JavaScript -交互式切换功能

MCP集成详细信息

Microsoft代理框架

from agent_framework import MCPStreamableHTTPTool

mcp_server = MCPStreamableHTTPTool(
    name="Microsoft Learn MCP",
    url="https://learn.microsoft.com/api/mcp",
)

agent = ChatAgent(
    chat_client=chat_client,
    name="DocsAgent",
    instructions="..."
)

result = await agent.run(query, tools=mcp_server)

LangGraph

from langchain_mcp_adapters.client import MultiServerMCPClient
from langchain.agents import create_agent

client = MultiServerMCPClient({
    "microsoft_learn": {
        "transport": "streamable_http",
        "url": "https://learn.microsoft.com/api/mcp",
    }
})

tools = await client.get_tools()
agent = create_agent(llm, tools, system_prompt="...")
result = await agent.ainvoke({"messages": [...]})

比较：MAF与LangGraph（均具有全MCP）

配置

环境变量

所有配置都是通过环境变量完成的 .env 文件：

• AZURE_OPENAI_ENDPOINT -您的Azure OpenAI端点URL
• AZURE_OPENAI_API_KEY -你的Azure OpenAI API密钥
• AZURE_OPENAI_API_VERSION -API版本（默认：2024-12-01预览）
• AZURE_OPENAI_DEPLOYMENT_NAME -您部署的模型名称

MCP服务器

Microsoft Learn MCP服务器可在以下网址公开访问：

• 端点： https://learn.microsoft.com/api/mcp
• 运输： 流式HTTP
• 身份验证： 无需
• 文档： 完整的Microsoft学习文档

故障排除

代理未响应

• 在中验证Azure OpenAI凭据 .env
• 检查部署名称是否与您的Azure资源匹配
• 确保MCP服务器的互联网连接

MCP连接错误

• 验证MCP服务器是否可访问：https://learn.microsoft.com/api/mcp
• 检查防火墙设置
• 确保 streamable_http 传输配置正确

导入错误

• 确认虚拟环境已激活
• 重新安装软件包： pip install -r requirements.txt
• 检查Python版本（需要3.11以上）

端口已在使用中

• 更改端口 app.py 或使用： uvicorn app:app --port 8001

环境变量未加载

• 确保 .env 文件存在于项目根目录中
• 检查文件权限
• 如果需要，手动导出变量

演出

• 启动时间： 约2-3秒
• MAF查询响应时间： 约10-15秒（包括MCP呼叫和LLM处理）
• LangGraph查询响应时间： 约8-12秒（包括MCP呼叫和LLM处理）
• MCP服务器响应： 快速可靠
• UI渲染： 瞬间
• 切换响应： 立即

发展

添加新功能

1. 复刻仓库
2. 创建要素分支
3. 进行更改
4. 用两种试剂进行彻底测试
5. 提交拉取请求

代码风格

• 遵循PEP 8指南
• 在适当的情况下使用类型提示
• 将文档字符串添加到函数中
• 保持功能集中和小型化
• 使用两个代理框架进行测试

测试

手动测试

1. 启动应用程序
2. 在MAF和LangGraph之间切换
3. 提交测试查询
4. 验证MCP集成是否正常工作
5. 检查标记渲染
6. 确认响应来自Microsoft Learn文档

示例测试查询

• Azure 函数
• Azure应用服务
• Azure Kubernetes服务
• Azure容器实例
• Azure SQL数据库

许可证

本项目按原样提供，用于演示和教育目的。

贡献

欢迎投稿！请随时提交拉取请求。

支持

有关问题和疑问，请在GitHub上打开问题。

致谢

• Microsoft代理框架团队
• LangGraph和LangChain社区
• Azure OpenAI团队
• Microsoft学习文档团队
• 模型上下文协议（MCP）规范的拟人化

相关资源

• Microsoft代理框架文档
• LangGraph文档
• 模型上下文协议（MCP）
• LangChain MCP适配器
• Azure OpenAI服务