Primitif MCP: Tools, Resources, dan Prompts

Ketika orang pertama kali mengenal Model Context Protocol, mereka cenderung terpaku pada tools dan mengira itulah semua yang ditawarkan server. Nyatanya spesifikasinya mendefinisikan tiga primitif server, dan perbedaan di antaranya bukan apa yang mereka lakukan melainkan siapa yang memutuskan kapan mereka berjalan. Membuat perbedaan itu benar adalah yang memisahkan server yang dipakai model dengan mulus dari yang meraba-raba.

Penjelasan ini menelusuri ketiga primitif, menunjukkan bagaimana mereka berbeda dalam kode, dan memberi satu aturan sederhana untuk memilih di antaranya ketika Anda merancang sebuah server.

Tiga primitif server

Sebuah server MCP bisa mengekspos tools, resources, dan prompts. Mereka dibedakan oleh control model-nya, yaitu pihak mana dalam percakapan yang diharapkan memutuskan kapan kapabilitas itu dipanggil. Satu gagasan itu menjelaskan sebagian besar cara mereka dimaksudkan untuk dipakai.

Singkatnya:

• Tools dikendalikan model: AI memutuskan untuk memanggilnya, biasanya untuk mengambil aksi atau menjemput sesuatu yang dinamis.
• Resources dikendalikan aplikasi: aplikasi klien memutuskan mana yang dimuat sebagai konteks, masing-masing dialamatkan lewat URI.
• Prompts dikendalikan pengguna: seseorang memilihnya secara sengaja, sering ditampilkan sebagai slash command atau item menu.

Bagaimana mereka berbeda, dalam kode

Perbedaannya paling mudah terlihat ketika Anda mendaftarkan satu dari masing-masing pada sebuah server. Bentuknya mirip, tetapi maksud di balik tiap pendaftaran berbeda, dan klien memperlakukannya secara berbeda sebagai hasilnya.

Di sini ketiganya didaftarkan pada objek server yang sama:

// Tool: model-controlled action the client can invoke
server.tool(
  "create_issue",
  { title: z.string() },
  async ({ title }) => ({
    content: [{ type: "text", text: "Created: " + title }],
  })
);

// Resource: application-controlled context, addressed by a URI
server.resource(
  "readme",
  "file:///project/README.md",
  async (uri) => ({
    contents: [{ uri: uri.href, text: "Project overview..." }],
  })
);

// Prompt: user-controlled template, surfaced as a slash command
server.prompt(
  "summarize",
  { topic: z.string() },
  ({ topic }) => ({
    messages: [
      {
        role: "user",
        content: { type: "text", text: "Summarize " + topic },
      },
    ],
  })
);

Tools secara mendalam

Tools adalah primitif yang paling diandalkan kebanyakan server karena mereka membuat model bisa bertindak. Karena model memanggilnya atas penilaiannya sendiri, mereka memikul tanggung jawab paling besar dan pantas mendapat perhatian paling besar.

• Mereka bisa punya efek samping, dari membaca sebuah rekaman sampai mengubah state, jadi deskripsinya harus menetapkan ekspektasi yang jelas.
• Schema masukan mereka adalah kontraknya; validasi ketat adalah yang menjaga panggilan pilihan model dari melakukan sesuatu yang tak diinginkan.
• Sebuah description yang presisi bukan dokumentasi untuk manusia melainkan instruksi yang diandalkan model untuk memutuskan kapan memanggil.
• Mereka mengembalikan konten yang diumpankan klien kembali ke model, menutup loop sehingga hasilnya bisa menginformasikan langkah berikutnya.

Resources dan prompts

Resources mengekspos data yang bisa dipilih aplikasi untuk ditarik ke konteks, masing-masing diidentifikasi lewat URI seperti jalur berkas atau skema kustom. Mereka dimaksudkan untuk konteks read-only, seperti sebuah dokumen atau berkas konfigurasi, yang diputuskan relevan oleh klien alih-alih dituntut model.

Prompts adalah template yang dapat dipakai ulang dan berparameter yang dipanggil pengguna dengan sengaja. Mereka ideal untuk permintaan umum yang terstruktur, sebuah prompt review kode atau prompt ringkasan, yang ingin Anda tawarkan sebagai titik awal sekali klik alih-alih membuat orang mengetik ulang tiap kali.

Memilih primitif yang tepat

Kebanyakan kesalahan desain datang dari memaksa satu primitif mengerjakan tugas primitif lain. Satu aturan keputusan singkat menjaga server tetap bersih dan dapat diprediksi bagi klien yang memakainya.

• Jika model yang seharusnya memutuskan kapan memanggilnya dan ia mungkin bertindak atau menjemput secara dinamis, jadikan ia tool.
• Jika ia konteks read-only yang dipilih aplikasi, jadikan ia resource dan beri URI yang stabil.
• Jika seseorang seharusnya memicunya secara sengaja sebagai template yang dapat dipakai ulang, jadikan ia prompt.

Ketiga primitif MCP tidak bisa dipertukarkan; masing-masing menjawab pertanyaan berbeda tentang siapa yang memegang kendali. Tools untuk model bertindak, resources untuk aplikasi memasok konteks, dan prompts untuk pengguna memanggil sebuah template. Rancang mengikuti pembagian itu dan server Anda akan terasa jelas bagi tiap klien yang terhubung dengannya.