1. Prompts #

本章主要介绍如何使用 MCP 的 Prompt 机制，包括定义不同形式的 Prompt 返回值，以及客户端如何获取和解析 Prompt 消息。你将学会：

• 如何使用 @mcp.prompt() 定义不同形式的 Prompt 返回值；
• 客户端如何获取和解析 Prompt 消息；
• 如何使用 Prompt 进行多轮对话。

2. 服务器 #

新建 C:\mcp-project\prompts_server.py：

# 文件名：prompts_server.py
# 本文件演示如何使用 @mcp.prompt() 定义多种返回形式的 Prompt

# 导入 FastMCP 高层服务器
from mcp.server.fastmcp import FastMCP

# 导入基础消息类型（如 UserMessage、AssistantMessage 等）
from mcp.server.fastmcp.prompts import (
    base,
)

# 创建 FastMCP 服务器实例，名称为 "Prompts Server"，客户端可见
mcp = FastMCP(name="Prompts Server")

# 一、定义返回字符串的 Prompt（最简单形式）


# 使用装饰器注册为 Prompt，函数参数会自动成为可配置参数
@mcp.prompt()
def greet_user(name: str, style: str = "friendly") -> str:
    # 文档字符串：根据姓名与风格生成问候提示词（字符串形式）。
    """根据姓名与风格生成问候提示词（字符串形式）。"""
    # 定义不同风格的提示语
    styles: dict[str, str] = {
        "friendly": "请用温暖、友好的语气写一段问候",
        "formal": "请用正式、专业的语气写一段问候",
        "casual": "请用轻松、随意的语气写一段问候",
    }
    # 根据 style 参数选择提示语，拼接姓名，返回完整提示字符串
    return f"{styles.get(style, styles['friendly'])}，对象是名为 {name} 的用户。"


# 二、定义返回消息列表的 Prompt（更灵活，适合多轮引导）


# 使用装饰器注册为 Prompt，并设置标题为“调试助手”
@mcp.prompt(title="调试助手")
def debug_assistant(error: str) -> list[base.Message]:
    # 文档字符串：返回一组消息，用于引导调试对话（消息列表形式）。
    """返回一组消息，用于引导调试对话（消息列表形式）。"""
    # 构造多条消息，包含用户和助手角色
    return [
        base.UserMessage("我遇到了如下错误："),  # 用户先描述问题
        base.UserMessage(error),  # 用户补充错误详情
        base.AssistantMessage(
            "我将帮助你定位问题。请提供你已尝试的步骤、相关代码片段，以及你所期望的结果。"
        ),  # 助手引导用户补充信息
    ]


# 主入口：以 stdio 方式运行服务器
if __name__ == "__main__":
    mcp.run(transport="stdio")

要点：

• `@mcp.prompt()` 会根据函数参数自动生成 Prompt 的参数定义（用于客户端填充）。
• 返回值可为：
  • 字符串（会自动转为单条文本消息）
  • 字典/消息对象/消息列表（如 base.UserMessage、base.AssistantMessage 列表）
• 可选参数 title/description 可用于改善客户端显示体验。

3. 客户端 #

新建 C:\mcp-project\test_client_prompts.py：

# 导入异步IO库，用于支持异步编程
import asyncio

# 导入os库，用于处理文件和路径操作
import os

# 从mcp模块导入客户端会话、Stdio服务器参数和类型定义
from mcp import ClientSession, StdioServerParameters, types

# 从mcp.client.stdio导入stdio客户端工厂方法
from mcp.client.stdio import stdio_client


# 定义辅助函数，用于打印Prompt消息内容
def print_prompt_messages(tag: str, prompt: types.GetPromptResult) -> None:
    # 定义一个字符串列表用于存储每条消息的内容
    lines: list[str] = []
    # 遍历Prompt返回的所有消息
    for msg in prompt.messages:
        # 获取消息的角色（如user、assistant等）
        role = msg.role
        # 获取消息的内容
        content = msg.content
        # 如果内容是文本类型，则直接打印文本
        if isinstance(content, types.TextContent):
            lines.append(f"({role}) {content.text}")
        # 否则打印内容类型
        else:
            lines.append(f"({role}) <非文本内容：{type(content).__name__}>")
    # 打印所有消息内容
    print(f"[{tag}]\n" + "\n".join(lines))


# 定义主异步函数
async def main() -> None:
    # 计算服务器脚本的绝对路径
    base_dir = os.path.dirname(os.path.abspath(__file__))
    server_path = os.path.join(base_dir, "prompts_server.py")

    # 配置以stdio方式启动服务器的参数
    server_params = StdioServerParameters(
        command="python",
        args=[server_path],
        env={},
    )

    # 建立到stdio服务器的连接，并创建客户端会话
    async with stdio_client(server_params) as (read, write):
        # 创建MCP客户端会话
        async with ClientSession(read, write) as session:
            # 完成初始化握手
            await session.initialize()

            # 列出所有已注册的Prompt
            prompts = await session.list_prompts()
            print("[Prompts]", [p.name for p in prompts.prompts])

            # 获取greet_user Prompt，传入参数name和style
            prompt_greet = await session.get_prompt(
                "greet_user", arguments={"name": "Alice", "style": "friendly"}
            )
            # 打印greet_user Prompt的消息内容
            print_prompt_messages("greet_user", prompt_greet)

            # 获取debug_assistant Prompt，传入错误文本参数
            prompt_debug = await session.get_prompt(
                "debug_assistant",
                arguments={"error": "IndexError: list index out of range"},
            )
            # 打印debug_assistant Prompt的消息内容
            print_prompt_messages("debug_assistant", prompt_debug)


# 判断是否为主模块入口
if __name__ == "__main__":
    # 在事件循环中运行主异步函数
    asyncio.run(main())

说明：

• list_prompts() 返回可用 Prompt 的名称与描述，客户端可供用户选择。
• get_prompt(name, arguments=...) 返回 GetPromptResult，其中的 messages 可直接用于驱动后续与 LLM 的对话逻辑。

4. 运行与验证 #

cd C:\mcp-project
call .venv\Scripts\activate
python test_client_prompts.py

预期输出：

[Prompts] ['greet_user', 'debug_assistant']
[greet_user]
(user) 请用温暖、友好的语气写一段问候，对象是名为 Alice 的用户。
[debug_assistant]
(user) 我遇到了如下错误：
(user) IndexError: list index out of range
(assistant) 我将帮助你定位问题。请提供你已尝试的步骤、相关代码片段，以及你所期望的结果。

若输出与示例相近，表示你已掌握 Prompt 的基础用法与客户端侧的获取与解析。