MCP Framework Demo

MCP框架演示：一台服务器，三个框架

一个10分钟的现场编码演示，展示了如何使用一个单一的MCP（模型上下文协议）服务器，被三个不同的AI编排框架所利用：AutoGen、Semantic Kernel（语义内核）和Microsoft Agent Framework（MAF，微软代理框架）。

🎯 项目目的

一次编写，随处可用。 这个演示证明，MCP提供了一个通用的工具接口，该接口能够在不同的AI编排框架之间无缝工作，无需对服务器进行任何修改。

• 一个MCP服务器将数据库操作暴露为标准化工具
• 三个框架AutoGen、Semantic Kernel 和 MAF 使用相同的工具
• 不同的哲学观每个框架都展示了其独特的编排方法

🏗️ 建筑学

┌─────────────────────────────────────────────────────────┐
│                    MCP Server (stdio)                   │
│                                                          │
│  Tools:                                                  │
│    • query_tasks  → Get all tasks from SQLite DB        │
│    • update_task  → Update task status                  │
│                                                          │
└────────────────────┬────────────────────────────────────┘
                     │
        ┌────────────┼────────────┐
        │            │            │
        ▼            ▼            ▼
   ┌─────────┐  ┌─────────┐  ┌─────────┐
   │ AutoGen │  │   SK    │  │   MAF   │
   └─────────┘  └─────────┘  └─────────┘
   
   Multi-Agent    Planning    Unified +
   Conversation   Decomp.     Checkpoints

📋 前提条件

• Python 3.10+（或“Python 3.10及以上版本”） （推荐使用 Python 3.11+）
• Anthropic API密钥 （致克劳德·莎士比亚十四行诗第4首）
• SQLite3 （通常预装在 macOS/Linux 上）

🚀 快速入门

1. 克隆并设置

# Clone the repository
cd mcp-framework-demo

# Run setup script (will prompt for API key)
chmod +x setup.sh
./setup.sh

# The script will:
# - Create virtual environment
# - Install dependencies
# - Set up database
# - Prompt for Anthropic API key (stored in .env)

# Activate virtual environment
source venv/bin/activate

注如果在设置过程中跳过输入API密钥，您可以手动将其添加到 .env 文件：

# Get your key from: https://console.anthropic.com/settings/keys
ANTHROPIC_API_KEY=sk-ant-your-actual-key-here

2. 启动MCP服务器

在 第一航站楼:

cd 01-mcp-server
python server.py

服务器静默运行，等待stdio连接。

3. 运行框架演示

AutoGen 演示（航站楼2）

cd 02-autogen
python demo.py

它所展示的对话式多智能体协同。一个任务规划器（TaskPlanner）智能体分析数据库并提出更新建议，而一个执行器（Executor）智能体则执行这些操作。

语义内核演示（3号航站楼）

cd 03-semantic-kernel
python demo.py

它所显示的确定性规划与步骤分解。SK的规划器将目标分解为一系列顺序步骤，并以可预测的方式执行它们。

MAF 试运行（4号航站楼）

cd 04-maf
python demo.py

它所显示的统一的方法结合对话与规划，加上生产级别的检查点机制以确保持久性和恢复能力。

📊 演示时间线

🔍 每个框架所展示的内容

AutoGen：对话式编排

• 模式多个专用代理（任务规划器+执行器）
• 沟通轮流对话
• 优势通过智能体协作实现灵活、创造性的问题解决
• 用例需要谈判和授权的复杂情境

任务“审查所有待处理任务，并将API部署标记为进行中”

语义核：规划与分解

• 模式单步骤执行规划器
• 交流确定性计划创建 → 顺序执行
• 优势可预测、可审计的工作流程，步骤清晰
• 用例需要可靠性和可审计性的企业场景

任务“获取所有待处理任务，然后将任务1更新为‘已完成’”

MAF：具有持久性的统一框架

• 模式；图案将AutoGen的智能体与增强的编排功能相结合
• 沟通灵活（既适用于对话也适用于规划）
• 优势生产就绪的检查点机制、暂停/恢复、容错能力
• 用例长期运行的工作流、人工参与的审批流程、分布式系统

任务“将所有待办任务标记为进行中”

🎓 重点总结

1. 通用工具接口MCP 提供了一种可在不同框架间通用的标准协议
2. 无需服务器修改相同 server.py 支持所有三个框架
3. 框架专业化每个框架都具有独特的编排优势
4. 生产就绪MAF在统一模型的基础上增加了企业功能（检查点机制、持久性）
5. 开发者之选选择符合您编排需求的框架

📁 项目结构

mcp-framework-demo/
├── .github/instructions/          # Detailed implementation guides
├── 01-mcp-server/
│   ├── server.py                  # MCP server (stdio protocol)
│   └── seed.sql                   # Database seed data
├── 02-autogen/
│   ├── demo.py                    # AutoGen multi-agent demo
│   └── expected_output.txt        # Sample output
├── 03-semantic-kernel/
│   ├── demo.py                    # Semantic Kernel planning demo
│   └── expected_output.txt        # Sample output
├── 04-maf/
│   ├── demo.py                    # MAF convergence demo
│   └── expected_output.txt        # Sample output
├── requirements.txt               # Python dependencies
├── setup.sh                       # Setup script
├── .env.example                   # Environment template
├── .gitignore                     # Git exclusions
└── README.md                      # This file

🧪 测试与验证

验证MCP服务器

# Check database
sqlite3 01-mcp-server/tasks.db "SELECT * FROM tasks"

# Inspect MCP tools (requires mcp CLI)
mcp inspect stdio python 01-mcp-server/server.py

预期的数据库状态

使用AutoGen之后任务1 → in-progress\ 在语义核之后任务1 → completed\ 在MAF之后任务2 → in-progress

验证MAF检查点

# Check checkpoint file was created
cat 04-maf/checkpoints/demo-run-1.json

🔗 框架文档

• MCP协议https://modelcontextprotocol.io/（该网址可直接作为中文表述，无需翻译，但若要说明其含义，可表述为：“这是一个名为‘Model Context Protocol’的网站，网址为https://modelcontextprotocol.io/”）
• AutoGenhttps://microsoft.github.io/autogen/（中文可表述为：“微软GitHub上的Autogen项目页面”）
• 语义内核https://learn.microsoft.com/en-us/semantic-kernel/ 的中文翻译可以是：“微软官方学习平台 - 语义核心（Semantic Kernel）文档”
• Microsoft Agent 框架https://github.com/microsoft/autogen（MAF 文档）

🛠️ 故障排除

“ModuleNotFoundError: 没有名为 'mcp' 的模块”

确保您已激活虚拟环境并安装了依赖项：

source venv/bin/activate
pip install -r requirements.txt

ANTHROPIC_API_KEY 未设置

创建一个 .env 从模板中获取文件并添加您的API密钥：

cp .env.example .env
# Edit .env and add your key

macOS上的SSL证书错误

如果您遇到SSL证书验证错误，演示中包含一种解决方法：

ssl._create_default_https_context = ssl._create_unverified_context

这仅用于演示目的，不应在生产代码中使用。此问题通常是由于 macOS 上的 Python 无法找到系统证书所引起的。

“数据库被锁定”或连接错误

确保只有一个MCP服务器实例在运行。数据库支持并发读取，但可能在多个写入器的情况下出现问题。

框架演示卡住或没有输出

在另一个终端中验证MCP服务器是否正在运行。框架通过stdio与服务器进程进行通信。

📝 许可证

这是一个用于教育目的的演示项目。

🙏 致谢

该系统旨在展示模型上下文协议（Model Context Protocol）的强大功能以及现代人工智能框架的不同编排方法。