Prompt'lar

Prompt, kullanıcının seçtiği bir mesaj şablonudur.

Araçlar model içindir. Prompt ise tam tersi: kullanıcı istemcisindeki bir menüden (bir slash komutu, bir düğme) birini seçer, argümanlarını doldurur ve ortaya çıkan mesajlar sanki kendisi yazmış gibi konuşmaya eklenir.

Metni döndüren bir fonksiyonun üzerine @mcp.prompt() koyarak bir prompt tanımlarsınız.

İlk prompt'unuz

from mcp.server import MCPServer

mcp = MCPServer("Code Helper")


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

SDK, bir araçtan okuduğu aynı üç şeyi okur:

• Ad, fonksiyonun adıdır: review_code.
• İstemcinin gösterdiği açıklama docstring'dir: Review a piece of code.
• Argümanlar parametrelerden gelir. code için varsayılan değer yok, bu yüzden zorunludur.

Bir istemci prompts/list çağrısından şunu alır:

{
  "name": "review_code",
  "description": "Review a piece of code.",
  "arguments": [
    {"name": "code", "required": true}
  ]
}

Burada JSON Schema yok. Prompt argümanları adlandırılmış dize değerlerinden oluşan düz bir listedir: bir modelin kurduğu bir veri yükü değil, bir insanın doldurduğu bir form.

Şablonu işleme

İstemci, argümanları geçirerek şablonu prompts/get ile işler. Fonksiyonunuz çalışır ve döndürdüğünüz str tek bir kullanıcı mesajına dönüşür:

{
  "description": "Review a piece of code.",
  "messages": [
    {
      "role": "user",
      "content": {
        "type": "text",
        "text": "Please review this code:\n\ndef add(a, b): return a + b"
      }
    }
  ],
  "resultType": "complete"
}

Bir prompt'un tüm yaşamı bu: adıyla listelenir, istendiğinde işlenir, sohbete bırakılır.

mcp.shared.exceptions.MCPError: Internal server error

Deneyin

Sunucuyu MCP Inspector ile çalıştırın:

uv run mcp dev server.py

Prompts sekmesini açın ve review_code'u seçin. Inspector, tek bir zorunlu code alanı olan bir form çizer. Doldurun, işleyin; geriye tam olarak yukarıdaki kullanıcı mesajı döner.

Birden fazla mesaj

Bir kod incelemesi tek bir mesajdır. Bir hata ayıklama oturumu ise bir konuşmadır ve bir prompt bu konuşmanın tamamının temelini atabilir.

str yerine bir mesaj listesi döndürün:

from mcp.server import MCPServer
from mcp.server.mcpserver.prompts.base import AssistantMessage, Message, UserMessage

mcp = MCPServer("Code Helper")


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


@mcp.prompt()
def debug_error(error: str) -> list[Message]:
    """Start a debugging conversation."""
    return [
        UserMessage("I'm seeing this error:"),
        UserMessage(error),
        AssistantMessage("I'll help debug that. What have you tried so far?"),
    ]

• UserMessage ve AssistantMessage, mcp.server.mcpserver.prompts.base modülünden gelir. Onlara bir str verin, sizin için TextContent içine sararlar. Rol, sınıfın adıdır.
• Message ortak temel sınıflarıdır. Dönüş tür açıklaması olarak onu kullanın.

debug_error işlendiğinde artık sırasıyla üç mesaj üretilir:

{
  "description": "Start a debugging conversation.",
  "messages": [
    {"role": "user", "content": {"type": "text", "text": "I'm seeing this error:"}},
    {"role": "user", "content": {"type": "text", "text": "TypeError: 'int' object is not iterable"}},
    {
      "role": "assistant",
      "content": {"type": "text", "text": "I'll help debug that. What have you tried so far?"}
    }
  ],
  "resultType": "complete"
}

Sonuncusuna dikkat edin. Bir assistant turunu önceden doldurmak, yönlendirmeyi kullanıcıya yazdırmadan modelin bir sonraki yanıtını yönlendirmenin yoludur.

Başlıklar ve argüman açıklamaları

review_code bir etiket değil, bir fonksiyon adıdır. İstemciye düğmeye koyacak daha iyi bir şey verin ve formun kendini açıklaması için her argümanı tanımlayın:

from typing import Annotated

from pydantic import Field

from mcp.server import MCPServer

mcp = MCPServer("Code Helper")


@mcp.prompt(title="Code review")
def review_code(
    code: Annotated[str, Field(description="The code to review.")],
    language: Annotated[str, Field(description="The language the code is written in.")] = "python",
) -> str:
    """Review a piece of code."""
    return f"Please review this {language} code:\n\n{code}"

• title="Code review" insan tarafından okunabilir addır; tıpkı bir aracın title'ı gibi.
• Annotated[str, Field(description=...)], Araçlar sayfasının bir aracın parametrelerini açıklamak için kullandığı kalıbın aynısıdır. Burada açıklama bir şemaya değil, argümanın üzerine düşer.
• language için bir varsayılan değer var, bu yüzden artık zorunlu değildir.

prompts/list girdisi artık bir istemcinin iyi bir form çizmek için ihtiyaç duyduğu her şeyi taşır:

{
  "name": "review_code",
  "title": "Code review",
  "description": "Review a piece of code.",
  "arguments": [
    {"name": "code", "description": "The code to review.", "required": true},
    {"name": "language", "description": "The language the code is written in.", "required": false}
  ]
}

Özet

• Bir fonksiyonun üzerindeki @mcp.prompt() onu bir prompt yapar. Ad fonksiyondan, açıklama docstring'den gelir.
• Prompt'lar kullanıcı denetimindedir: istemci bunları listeler, kullanıcı birini seçer ve argümanları doldurur.
• Argümanlar adlandırılmış dizelerden oluşan düz bir listedir (şema yok). Varsayılanı olan bir parametre isteğe bağlıdır.
• Bir str döndürün, tek bir kullanıcı mesajına dönüşür. Çok turlu bir konuşmanın temelini atmak için UserMessage / AssistantMessage listesi döndürün.
• title= ve Field(description=...), bir istemcinin arayüzüne koyduğu şeylerdir.
• Eksik bir zorunlu argüman isteğin tamamını başarısız kılar. Prompt'a özgü bir hata sonucu yoktur.

Bir prompt'un (veya bir kaynak şablonunun) argümanları için sunucu tarafı otomatik tamamlama Tamamlamalar sayfasındadır.