تعریف prompts (Defining prompts)

عنوان اصلی: Defining prompts

هدف یادگیری: تعریف یک MCP prompt: یک template پیام parameterized که کاربر (نه مدل) صریحاً اجرایش می‌کند.

مفاهیم کلیدی: prompts/list، prompts/get، prompt arguments، prompt چندپیامی، embedded resources، UX به‌صورت slash command.

Prompts user-controlled هستند — به‌صورت slash command یا منوی template surface می‌شوند و کاربر انتخاب می‌کند. هر prompt یک name، title و description اختیاری، و فهرستی از arguments (هر کدام با name، description، required) دارد. وقتی با prompts/get فراخوانی می‌شود، server یک آرایه messages از { role, content } برمی‌گرداند — که role می‌تواند user یا assistant باشد و content می‌تواند text، image، audio یا یک embedded resource باشد. promptهای چندپیامی به server اجازه می‌دهند مکالمه را با few-shot example یا یک جفت structured system+user seed کند.

سومین primitive سه‌گانه را کامل می‌کند: - Tools → model-controlled (LLM انتخاب می‌کند) - Resources → app-controlled (host تزریق می‌کند) - Prompts → user-controlled (انسان از طریق slash command انتخاب می‌کند)

مثال عملی — Python (prompt تک‌پیامی و چندپیامی)

from mcp.server.fastmcp.prompts import base

@mcp.prompt(title="Code Review")
def review_code(code: str) -> str:
    return f"Please review this code:\n\n{code}"

@mcp.prompt(title="Debug Assistant")
def debug_error(error: str) -> list:
    return [
        base.UserMessage("I'm seeing this error:"),
        base.UserMessage(error),
        base.AssistantMessage("I'll help debug that."),
    ]

مثال عملی — JSON-RPC خام

{ "jsonrpc": "2.0", "id": 2, "method": "prompts/get",
  "params": { "name": "code_review",
              "arguments": { "code": "def hello():\n    print('world')" } } }

دیاگرام معماری (متنی): کاربر /code_review را تایپ می‌کند. Host فرمی برای argument code نمایش می‌دهد. Host → Server: prompts/get با name + args. Server → Host: یک آرایه messages. Host آن messages را در context مدل تزریق می‌کند و اجازه می‌دهد مدل ادامه دهد.

اشتباهات رایج

• گذاشتن منطق business که state را تغییر می‌دهد در handler یک prompt. promptها متن برمی‌گردانند؛ اگر می‌خواهید عمل کنید، از tool استفاده کنید.
• علامت نزدن argumentهای required. host نمی‌تواند قبل از ارسال validate کند.
• embed کردن resource بزرگ inline به‌جای برگرداندن resource_link — context را هدر می‌دهد.