AI导哈

MCP服务器与AI代理教学系统

一个基于Jupyter Notebook的交互式教学系统，通过构建MCP服务器和Google ADK AI代理来教授模型上下文协议和AI代理开发。

  • by prashantkul
  • Jupyter Notebook
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 prashantkul/simple-mcp-server

使用说明

🎓 教育MCP服务器演示：客户管理系统

一个交互式的Jupyter笔记本系列，用于教学生如何构建MCP（模型上下文协议）服务器和AI代理。本实践教程演示了如何使用MCP集成和Google ADK构建一个完整的客户管理系统。

📚 这是什么？

该教育资源教授 模型上下文协议（MCP） 和 谷歌代理开发工具包（ADK） 通过实际工作示例：

📓 两本笔记本：

  1. mcp_customer_demo.ipynb -构建MCP服务器

    • 使用Flask创建基于HTTP的MCP服务器
    • 实施6个客户管理工具
    • 学习MCP协议基础（JSON-RPC 2.0、SSE流）
    • 使用MCP检查员进行测试

  2. adk_customer_agent.ipynb -构建AI代理

    • 使用Google ADK创建AI代理
    • 使用MCPToolSet连接到MCP服务器
    • 使用自然语言与客户数据交互
    • 测试对话式人工智能能力
    • 使用部署 adk web 和ngrok供公众访问

完成两个笔记本 了解完整的MCP生态系统：构建服务器并创建使用它们的代理！

🎯 学习目标

通过完成两本笔记本，学生将学习：

MCP服务器（笔记本电脑1）：

  • MCP协议基础 -JSON-RPC 2.0消息结构和SSE流
  • 服务器实现 -使用Flask构建基于HTTP的MCP服务器
  • 工具定义 -使用正确的JSON模式创建MCP工具
  • 数据库集成 -将MCP工具连接到SQLite数据库
  • 测试与调试 -使用MCP Inspector进行交互式测试

谷歌ADK代理（笔记本2）：

  • 代理开发 -使用Google ADK构建人工智能代理
  • MCP工具集集成 -将代理连接到MCP服务器
  • 自然语言处理 -了解用户意图和工具选择
  • 对话式人工智能 -创建用于数据访问的聊天界面
  • 实际应用 -构建实用的人工智能集成系统

✨ 特性

🔧 完成MCP服务器实施（笔记本1）

  • 6个MCP工具 用于客户管理（获取、列出、添加、更新、禁用、激活）
  • 基于Flask的HTTP服务器 支持服务器发送事件（SSE）
  • SQLite数据库 带有样本数据
  • 正确的错误处理 和验证
  • MCP协议合规性 （规范2024-11-05）
  • 自动ngrok隧道 用于生成公共URL
  • MCP检查器集成 -可视化界面测试
  • 10个交互式测试用例 演示协议

🤖 谷歌ADK人工智能代理（笔记本2）

  • 双子动力代理 使用Google ADK框架
  • MCPToolSet集成 -自动发现MCP服务器工具
  • 自然语言接口 -不需要API知识
  • 对话式互动 -与您的数据聊天
  • 10个测试场景 从简单到复杂的查询
  • 错误处理 -巧妙处理边缘案例
  • 系统说明 -可定制的代理行为
  • ADK Web部署 -公共聊天界面 adk web + 吸烟
  • 可共享URL -让其他人与您的代理人聊天

📖 教学设计

  • 分步说明 解释清楚
  • 💡 学习要点 在两本笔记本中
  • 互动演示 举个真实的例子
  • 视觉输出 带彩色终端显示器
  • 代码注释 解释关键概念
  • 架构图 显示系统流程

🚀 快速开始

对于学生：

第1部分：构建MCP服务器

  1. 打开笔记本1：单击顶部的第一个徽章→ mcp_customer_demo.ipynb
  2. 设置ngrok （参见 Ngrok设置 详见下文）
  3. 运行单元格1-11 设置服务器
  4. 运行测试单元14-32 查看MCP协议的运行情况
  5. 复制公共URL 根据输出（例如。， https://xxxx.ngrok.io/mcp)
  6. 使用MCP检查员进行测试：运行 npx @modelcontextprotocol/inspector

第2部分：构建AI代理

  1. 保持笔记本1运行 （MCP服务器必须处于活动状态）
  2. 打开笔记本2：单击第二个徽章→ adk_customer_agent.ipynb
  3. 设置Google API密钥 （笔记本中的说明）
  4. 添加MCP服务器URL Colab的秘密
  5. 运行所有单元格 创建和测试AI代理
  6. 与您的数据聊天 使用自然语言！
  7. （可选）使用ADK Web进行部署：运行部署单元以获取公共聊天UI

对于讲师：

此笔记本可用于：

  • API设计计算机科学课程
  • 涵盖法学硕士集成的AI/ML课程
  • 协议软件工程课程
  • 关于构建人工智能工具的研讨会

持续时间：约30-45分钟完成所有细胞

📋 包含什么

笔记本结构

1. 📚 Introduction & MCP Concepts
2. 🔧 Installation & Setup
3. 🗄️ Database Creation (SQLite)
4. 🛠️ CRUD Functions (Python)
5. 🌐 MCP Server Implementation (Flask + SSE)
6. 🚀 Server Startup (with ngrok)
7. 🧪 Interactive Tests (10 demonstrations)
8. 🔍 MCP Inspector Guide
9. 🎯 Server Management Utilities
10. 📝 Summary & Next Steps

客户管理工具

工具 说明 参数
get_customer 按ID检索客户 customer_id （int）
list_customers 列出所有或筛选的客户 status （可选：“活动”、“禁用”）
add_customer 创建新客户 name （必填）， email, phone （可选）
update_customer 更新客户信息 customer_id （int）， name, email, phone （可选）
disable_customer 停用帐户 customer_id （int）
activate_customer 重新激活帐户 customer_id （int）

🛠️ 技术栈

MCP服务器（笔记本电脑1）：

  • Python 3.9+ -核心语言
  • 烧瓶 -HTTP服务器框架
  • SQLite -嵌入式数据库
  • 服务器发送事件（SSE） -流媒体协议
  • 平罗克 -公共URL隧道
  • JSON-RPC 2.0 -消息协议

ADK代理（笔记本2）：

  • 谷歌ADK -代理开发工具包
  • 双子座2.5闪光灯 -代理情报法学硕士
  • MCP工具集 -MCP服务器集成
  • 流式HTTP连接参数 -HTTP/SSE连接处理

🔍 MCP检验员测试

启动MCP检查器

MCP Inspector是一个CLI工具，为测试MCP服务器提供了一个可视化界面。要启动它：

  1. 在本地计算机上打开终端（不在Colab中）
  2. 运行以下命令：
    npx @modelcontextprotocol/inspector
  3. 这将自动：
    • 下载MCP检查器工具（如果尚未安装）
    • 启动检查器服务器
    • 打开浏览器，进入MCP检查器界面

连接到您的服务器

  1. 启动笔记本电脑中的服务器（Cell 11）
  2. 从输出中复制公共URL（例如。， https://abc123.ngrok.io/mcp)
  3. 在MCP Inspector浏览器界面中：
    • 将URL粘贴到“服务器URL”字段中
    • 点击“连接”
  4. 交互式探索和测试所有6个客户管理工具！

益处

  • 视觉界面 用于测试MCP工具
  • 无需编码 -点击测试
  • 查看完整的协议消息 -非常适合学习
  • 实时测试 -即时反馈
  • 易于调试 -查看请求和响应

📊 数据库模式

CREATE TABLE customers (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT NOT NULL,
    email TEXT,
    phone TEXT,
    status TEXT DEFAULT 'active' CHECK(status IN ('active', 'disabled')),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

样本数据： 10名客户（8名活跃客户，2名残疾客户）

💡 涵盖的关键概念

MCP协议基础

  • JSON-RPC 2.0消息格式
  • 三种核心方法： initialize, tools/list, tools/call
  • 使用JSON模式定义工具
  • 服务器能力协商

服务器发送事件（SSE）

  • 实时流媒体通信
  • SSE消息格式： data: {json}\n\n
  • Flask中的发电机功能
  • 请求上下文管理

错误处理

  • 正确的MCP错误响应
  • 数据库错误处理
  • 输入验证
  • AI有意义的错误消息

🌐 Ngrok设置

适用于MCP服务器（笔记本电脑1）

要启用对MCP服务器的公共访问（使用MCP Inspector进行测试所需），您需要设置ngrok：

1.获取Ngrok认证令牌

  1. 首选 https://ngrok.com
  2. 注册一个免费帐户
  3. 转到您的仪表板并复制您的身份验证令牌

2.向Google Colab Secrets添加令牌

  1. 打开Colab笔记本
  2. 点击 🔑 （秘密） 左侧边栏中的图标
  3. 点击 +添加新密码
  4. 设置：
    • 名字: NGROK_AUTHTOKEN
    • 价值：从ngrok粘贴您的身份验证令牌
  5. 切换 笔记本访问 到ON
  6. 运行Cell 11以使用公共URL启动服务器

3.验证设置

当Cell 11成功运行时，您应该看到：

✅ Ngrok authenticated
✅ Public URL: https://xxxx.ngrok.io
📍 MCP Endpoint: https://xxxx.ngrok.io/mcp

如果您看到关于丢失令牌的警告，请仔细检查：

  • 秘密的名字正是 NGROK_AUTHTOKEN
  • 笔记本访问已启用
  • 添加秘密后，您已重新运行Cell 11

用于ADK Web部署（Colab外部）

如果你想在本地运行ADK Web并通过ngrok公开它：

选项1：使用辅助脚本

# Set environment variables
export GOOGLE_API_KEY="your-google-api-key"
export MCP_SERVER_URL="https://xxxx.ngrok.io/mcp"

# Run with ngrok
python start_adk_with_ngrok.py \
  --agent_path agent.py \
  --ngrok_token YOUR_NGROK_TOKEN

脚本将：

  • 在端口8000上启动ADK web服务器
  • 创建ngrok隧道
  • 显示共享的公共URL

选项2：手动设置

# Terminal 1: Start ADK web
export GOOGLE_API_KEY="your-key"
export MCP_SERVER_URL="https://xxxx.ngrok.io/mcp"
adk web --agent_path agent.py

# Terminal 2: Start ngrok
ngrok http 8000

没有Ngrok

如果你没有设置ngrok：

  • MCP服务器：将在Colab本地工作，但不能与MCP检查员一起测试
  • ADK网站：只能在本地主机上访问(http://127.0.0.1:8000)

🔗 资源

MCP资源：

谷歌ADK资源：

其他资源：

📝 测试总结

看 测试_ SUMMARY.md 详细的测试文档，包括：

  • 所有测试均已完成
  • 发现并修复的问题
  • 组件验证
  • Colab兼容性检查

⚠️ 已知限制（Colab特定）

  • 临时存储：运行时重置时删除数据库
  • 线程持久性：服务器将继续运行，直到运行时重置
  • 本地主机绑定：仅限于Colab环境的直接本地访问
  • 没有坚持：会话之间未保存状态

这些是 刻意为之 出于教育目的，并在笔记本上明确记录。

🤝 贡献

这是一种教育资源。欢迎捐款：

  • 附加练习
  • 错误修复
  • 文档改进
  • 翻译成其他语言
  • 其他MCP示例

📄 许可证

这种教育资源是按原样提供的，用于教学和学习目的。

🙏 致谢

  • Anthropic -对于模型上下文协议规范
  • Flask社区 -对于优秀的web框架
  • 吸烟 -隧道掘进能力
  • 谷歌Colab -免费计算资源

📧 问题或反馈？

在此存储库中打开问题或通过pull请求贡献改进！

快乐学习！ 🚀

最后更新日期：2025-11-10 笔记本版本：v1.0.0

相关 MCP