MCP 引导演示：交互式

一个展示具有智能引导功能的模型上下文协议（MCP）的演示，用于交互式数据收集。该项目展示了MCP服务器如何在需要时动态请求客户端的信息。

演示视频

概述

此演示实现了一个餐厅预订系统，展示了MCP的引导特性。服务器可以通过交互提示智能地从客户端请求缺失或无效的数据。

特性

• 智能引导：服务器动态请求缺失参数
• 输入验证：验证日期、人数和其他预订详情
• 错误处理：优雅地处理用户取消和错误
• 多种场景：支持各种预订场景以供测试
• 类型安全：完整的类型提示和Pydantic模式验证

项目结构

mcp-elicitation-example/
├── .gitignore              # Git忽略模式
├── .python-version         # Python版本规范
├── elicitation-server.py   # 预订工具的MCP服务器
├── elicitation-client.py   # 测试用的交互式客户端
├── pyproject.toml          # 项目依赖和配置
├── README.md               # 此文件
└── uv.lock                 # 依赖锁定文件

安装

1. 克隆仓库（如果尚未完成）：

   git clone <repository-url>
   cd mcp--elicitation-example
   

2. 使用uv安装依赖：

   uv sync
   

   这将自动：

   • 使用Python 3.11+创建虚拟环境
   • 从pyproject.toml安装所有依赖
   • 在uv.lock中锁定依赖以实现可重复构建

   注意：无需手动创建或激活虚拟环境 - uv会自动处理！

   替代方案（使用pip）：

   python -m venv venv
   source venv/bin/activate  # 在Windows上：venv\Scripts\activate
   pip install -e .
   

使用方法

启动服务器

在一个终端中启动MCP服务器：

uv run python elicitation-server.py

服务器默认将在http://localhost:8000/mcp启动。

启动客户端

在另一个终端中运行交互式客户端：

uv run python elicitation-client.py

提示：使用uv run可以自动使用项目的虚拟环境，无需手动激活！

演示场景

客户端演示了三个场景：

1. 完全引导：没有初始参数 - 服务器请求所有数据
2. 部分数据：仅提供日期 - 服务器请求人数
3. 无效数据：提供过去的日期 - 服务器验证并请求纠正

工作原理

服务器实现（elicitation-server.py）

• FastMCP服务器：使用FastMCP框架进行简单设置
• Pydantic模式：定义不同输入类型的验证模式
• 引导处理器：通用函数，用于带有验证的数据请求
• 预订餐桌工具：主要工具，协调预订过程

客户端实现（elicitation-client.py）

• 智能回调：解释服务器请求并适当提示用户
• 输入验证：客户端侧验证，带重试逻辑
• 多种场景：测试不同的初始数据组合
• 错误处理：优雅地处理用户取消

关键组件

引导模式

class GetDate(BaseModel):
    date: str = Field(
        description="请输入您的预订日期（YYYY-MM-DD）",
        pattern=r"^\d{4}-\d{2}-\d{2}$"
    )

服务器工具

@mcp.tool()
async def book_table(ctx: Context, date: str = "", party_size: int = 0) -> str:
    """通过智能引导来预订餐桌，针对缺失或无效的数据。"""

客户端回调

async def smart_elicitation_callback(
    context: RequestContext["ClientSession", Any],
    params: types.ElicitRequestParams,
) -> types.ElicitResult | types.ErrorData:

技术细节

依赖项

• mcp[cli]：模型上下文协议SDK
• pydantic：数据验证和设置管理
• anyio：异步I/O库
• asyncio：Python内置的异步框架

验证规则

• 日期格式：必须是YYYY-MM-DD且不能在过去
• 人数：必须在1到20人之间
• 确认：布尔值，可选备注字段

错误处理

• 引导过程中客户端断开连接
• 输入格式无效
• 用户在任何步骤取消操作
• 网络超时和连接错误

示例交互

🍽️ 开始餐桌预订流程...

--- 测试：无参数（全引导）---

--- 服务器请求 ---
消息：请输入您的预订日期：
请输入您的预订日期（YYYY-MM-DD）：2025-07-15

--- 服务器请求 ---
消息：请输入您的预订人数：
请输入人数（1-20）：4

--- 服务器请求 ---
消息：您是否确认于2025年7月15日预订4人的餐桌？
您是否确认此预订？（y/n）：y
是否有特殊要求或备注？（可选）：请安排靠窗的桌子

✅ 结果：✅ 您已成功预订2025年7月15日4人的餐桌。备注：请安排靠窗的桌子

开发

编码风格

项目遵循PEP 8标准，包括：

• 最大行长度：79个字符
• 所有函数的类型提示
• 类和函数的文档字符串
• 一致的命名约定

测试

运行客户端以测试不同场景：

python elicitation-client.py

客户端将自动测试三种场景，并在每个场景之间提示继续。

扩展演示

要添加新的引导类型：

1. 在ElicitationSchema类中定义一个模式
2. 在服务器工具中添加处理逻辑
3. 更新客户端回调以处理新的请求类型
4. 使用客户端测试新功能

故障排除

常见问题

1. 连接被拒绝：确保在启动客户端之前服务器正在运行
2. 端口已被占用：检查是否有其他进程使用8000端口
3. 导入错误：确保所有依赖项都已使用uv sync安装

调试模式

通过修改elicitation-server.py中的日志级别启用调试日志记录：

logging.getLogger("mcp").setLevel(logging.DEBUG)

贡献

1. 分叉仓库
2. 创建功能分支
3. 添加适当的测试后进行更改
4. 确保代码遵循样式指南
5. 提交拉取请求

许可

本项目作为MCP功能演示提供。请参阅MCP SDK许可以获取使用条款。

额外资源

• 模型上下文协议文档
• FastMCP文档
• Pydantic文档

---

此演示展示了MCP引导特性的强大功能，可用于构建能够从用户动态收集信息的交互式、智能工具。