MCP Elicitation Example

MCP激发演示：交互式

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

演示视频

![IMAGE ALT TEXT HERE]()

概述

该演示实现了一个餐厅餐桌预订系统，演示了MCP的启发式功能。服务器可以通过交互式提示智能地向客户端请求丢失或无效的数据。

特性

• 智能启发式：服务器动态请求缺少参数
• 输入验证：验证日期、派对规模和其他预订详细信息
• 错误处理：妥善处理用户取消和错误
• 多个场景：支持各种预订场景进行测试
• 类型安全：完整类型提示和Pydantic模式验证

项目结构

mcp-elicitation-example/
├── .gitignore              # Git ignore patterns
├── .python-version         # Python version specification
├── elicitation-server.py   # MCP server with booking tool
├── elicitation-client.py   # Interactive client for testing
├── pyproject.toml          # Project dependencies and configuration
├── README.md              # This file
└── uv.lock                # Dependency lock file

安装

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

   git clone 
   cd mcp-elicitation-example

1. 使用uv安装依赖项:

   uv sync

这将自动：

- 使用Python 3.11创建虚拟环境+ - 从安装所有依赖项 pyproject.toml - 锁定依赖项 uv.lock 用于可重复构建

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

替代方案（使用pip）:

   python -m venv venv
   source venv/bin/activate  # On 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="Enter the date for your booking (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:
    """Book a table with intelligent elicitation for missing or invalid data."""

客户端回调

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

技术细节

依赖项

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

验证规则

• 日期格式：必须是YYYY-MM-DD，而不是过去的
• 聚会规模：必须在1到20人之间
• 确认：带可选注释字段的布尔值

错误处理

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

交互示例

🍽️  Starting table booking process...

--- Testing: No arguments (full elicitation) ---

--- Server Request ---
Message: Please enter the date for your booking:
Enter the date for your booking (YYYY-MM-DD): 2025-07-15

--- Server Request ---
Message: Please enter the party size for your booking:
Enter the number of people (1-20): 4

--- Server Request ---
Message: Please confirm your booking for 4 people on 2025-07-15.
Do you want to confirm this booking? (y/n): y
Any special requests or notes? (optional): Window table please

✅ Result: ✅ Your table for 4 people on 2025-07-15 has been booked. Notes: Window table please

发展

代码的风格

该项目遵循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的启发功能在构建交互式智能工具方面的强大功能，这些工具可以动态地从用户那里收集信息。*