Panduan Pemula untuk Menggunakan FastMCP

Landscape Model Bahasa Besar (LLMs) berkembang dengan cepat, bergerak dari sekadar menghasilkan teks sederhana menuju interaksi yang kompleks dengan sistem eksternal dan sumber data. Memfasilitasi interaksi ini memerlukan pendekatan yang terstandarisasi, bahasa umum bagi LLM untuk meminta informasi dan memicu tindakan. Di sinilah Model Context Protocol (MCP) berperan, dirancang sebagai standar universal – sering disamakan dengan "port USB-C untuk AI" – yang memungkinkan komunikasi tanpa hambatan antara LLM dan sumber daya yang mereka butuhkan.

Sementara MCP menyediakan spesifikasi, membangun server dan klien yang mematuhinya dapat melibatkan kode boilerplate yang signifikan dan manajemen protokol. Di sinilah FastMCP bersinar. FastMCP adalah framework tingkat tinggi, Pythonic yang dirancang untuk sangat menyederhanakan pembuatan server dan klien MCP. Ini menangani kompleksitas dasar dari protokol, memungkinkan pengembang untuk fokus pada mendefinisikan alat berharga, sumber data, dan pola interaksi yang ingin mereka ekspos kepada LLM.

💡

Ingin alat Pengujian API yang hebat yang menghasilkan Dokumentasi API yang indah?

Ingin platform terintegrasi, All-in-One untuk Tim Pengembang Anda bekerja sama dengan produktivitas maksimum?

Apidog memenuhi semua permintaan Anda, dan menggantikan Postman dengan harga yang jauh lebih terjangkau!

button

Apa itu Model Context Protocol (MCP)?

Sebelum menyelami lebih dalam tentang FastMCP, penting untuk memahami konsep inti dari MCP itu sendiri. MCP mendefinisikan cara terstandarisasi bagi aplikasi LLM (klien) untuk berinteraksi dengan sistem eksternal (server). Server MCP dapat mengekspos beberapa komponen kunci:

Alat: Ini pada dasarnya adalah fungsi yang dapat diminta oleh LLM untuk dieksekusi oleh server. Anggaplah seperti endpoint POST dalam API tradisional. Mereka melakukan tindakan, berpotensi berinteraksi dengan sistem lain (basis data, API, perangkat keras), dan mengembalikan hasil. Misalnya, sebuah alat dapat mengirim email, melakukan query ke basis data, atau melakukan perhitungan.
Sumber Daya: Ini mengekspos data yang dapat dibaca atau diambil oleh LLM. Mirip dengan endpoint GET, sumber daya menyediakan informasi untuk memperkaya konteks LLM. Ini bisa berupa apa saja mulai dari file konfigurasi dan profil pengguna hingga aliran data waktu nyata.
Prompt: Ini adalah template yang dapat digunakan kembali untuk menyusun interaksi dengan LLM. Mereka membantu membimbing percakapan dan memastikan keluaran yang konsisten untuk tugas tertentu.
Konteks: Server dapat memberikan informasi kontekstual, termasuk instruksi tentang cara terbaik berinteraksi dengan alat dan sumber daya yang tersedia.

MCP bertujuan untuk menciptakan ekosistem yang kuat dan aman di mana LLM dapat dengan andal mengakses dan memanfaatkan kemampuan eksternal.

Mengapa Memilih FastMCP?

Sementara Anda bisa mengimplementasikan spesifikasi MCP secara langsung menggunakan SDK tingkat rendah, FastMCP menawarkan keuntungan yang menarik, terutama bagi pengembang Python:

🚀 Pembangunan Cepat: Antarmukanya yang tingkat tinggi secara signifikan mengurangi jumlah kode yang diperlukan, mempercepat proses pengembangan. Seringkali, mendefinisikan alat atau sumber daya semudah menghias fungsi Python standar.
🍀 Simplicity: FastMCP mengabstraksi rincian kompleks dari pengaturan server, penanganan protokol, tipe konten, dan manajemen kesalahan, meminimalkan boilerplate.
🐍 Pythonic: Dirancang dengan praktik terbaik Python dalam pikiran, terasa alami dan intuitif bagi pengembang yang akrab dengan bahasa ini, memanfaatkan fitur seperti petunjuk tipe dan dekorator.
🔍 Lengkap: FastMCP bertujuan untuk memberikan implementasi komprehensif dari spesifikasi inti MCP, memastikan kompatibilitas dan akses ke potensi penuh protokol.

Versi FastMCP 1 terbukti sangat sukses dan kini terintegrasi ke dalam SDK MCP Python resmi. Versi 2 dibangun di atas fondasi ini, memperkenalkan fitur-fitur canggih yang fokus pada menyederhanakan interaksi server, seperti klien yang fleksibel, proxy server, dan pola komposisi.

Cara Menginstal FastMCP

Mendapatkan FastMCP di lingkungan Python Anda sangatlah mudah. Metode yang direkomendasikan menggunakan uv, penginstal dan resolver paket Python yang cepat.

1. Menggunakan uv (Direkomendasikan):

Jika Anda mengelola dependensi untuk sebuah proyek, tambahkan FastMCP menggunakan:

uv add fastmcp

Atau, instal langsung ke lingkungan Anda:

uv pip install fastmcp

2. Menggunakan pip:

Jika Anda lebih suka menggunakan pip, Anda dapat menginstal FastMCP dengan:

pip install fastmcp

3. Memverifikasi Instalasi:

Setelah instalasi, Anda dapat memverifikasi bahwa FastMCP terinstal dengan benar dan memeriksa versinya, bersama dengan versi SDK MCP yang mendasarinya dan detail lingkungan Python Anda, dengan menjalankan:

fastmcp version

Anda harus melihat output yang mirip dengan ini:

$ fastmcp version

Versi FastMCP:   0.4.2.dev41+ga077727.d20250410
Versi MCP:                                1.6.0
Versi Python:                            3.12.2
Platform:            macOS-15.3.1-arm64-arm-64bit
Jalur root FastMCP:            ~/Developer/fastmcp

4. Menginstal untuk Pengembangan:

Jika Anda berniat untuk berkontribusi pada proyek FastMCP itu sendiri, Anda perlu menyiapkan lingkungan pengembangan:

git clone https://github.com/jlowin/fastmcp.git
cd fastmcp
uv sync

Ini mengkloning repositori, menavigasi ke direktori, dan menggunakan uv sync untuk menginstal semua dependensi yang diperlukan, termasuk alat pengembangan, dalam lingkungan virtual. Anda kemudian dapat menjalankan pengujian menggunakan pytest.

Cara Menggunakan FastMCP: Membangun Server Pertama Anda

Sekarang, mari kita menyelami aspek praktis penggunaan FastMCP.

1. Membuat Instance Server Dasar:

Pusat dari setiap aplikasi FastMCP adalah kelas FastMCP. Anda mulai dengan membuat instance dari kelas ini.

Buat file bernama my_server.py:

# my_server.py
from fastmcp import FastMCP
import asyncio  # Kita akan membutuhkannya nanti untuk klien

# Instansiasi server, berikan nama
mcp = FastMCP(name="Server MCP Pertama Saya")

print("Objek server FastMCP dibuat.")

Konstruktor FastMCP menerima beberapa argumen yang bermanfaat:

name (str, opsional): Nama yang dapat dibaca manusia untuk server Anda (defaultnya adalah "FastMCP"). Berguna untuk identifikasi dalam log atau aplikasi klien.
instructions (str, opsional): Deskripsi yang membimbing klien tentang cara berinteraksi dengan server, menjelaskan tujuannya atau menyoroti fungsionalitas kunci.
lifespan (callable, opsional): Manajer konteks asinkron untuk menangani logika startup dan shutdown server (misalnya, menginisialisasi koneksi basis data).
tags (set[str], opsional): Tag untuk mengkategorikan server itu sendiri.
**settings: Anda dapat meneruskan argumen kata kunci yang sesuai dengan ServerSettings (seperti port, host, log_level) langsung ke konstruktor untuk konfigurasi.

2. Menambahkan Komponen:

Server kosong tidak begitu berguna. Mari kita tambahkan komponen inti MCP.

Menambahkan Alat: Alat adalah fungsi yang diekspos kepada klien. Gunakan dekorator @mcp.tool(). FastMCP menggunakan petunjuk tipe Python untuk mendefinisikan parameter input yang diharapkan dan tipe pengembalian untuk klien.

# my_server.py (lanjutan)
@mcp.tool()
def greet(name: str) -> str:
    """Mengembalikan sapaan sederhana."""
    return f"Halo, {name}!"

@mcp.tool()
def add(a: int, b: int) -> int:
    """Menambahkan dua angka bersama-sama."""
    return a + b

print("Alat 'greet' dan 'add' ditambahkan.")

Menambahkan Sumber Daya: Sumber daya mengekspos data melalui URI. Gunakan dekorator @mcp.resource(), memberikan string URI.

# my_server.py (lanjutan)
APP_CONFIG = {"theme": "dark", "version": "1.1", "feature_flags": ["new_dashboard"]}

@mcp.resource("data://config")
def get_config() -> dict:
    """Menyediakan konfigurasi aplikasi."""
    return APP_CONFIG

print("Sumber daya 'data://config' ditambahkan.")

Menambahkan Template Sumber Daya: Ini seperti sumber daya dinamis di mana bagian URI bertindak sebagai parameter.

# my_server.py (lanjutan)
USER_PROFILES = {
    101: {"name": "Alice", "status": "active"},
    102: {"name": "Bob", "status": "inactive"},
}

@mcp.resource("users://{user_id}/profile")
def get_user_profile(user_id: int) -> dict:
    """Mengambil profil pengguna berdasarkan ID mereka."""
    # {user_id} dari URI secara otomatis diteruskan sebagai argumen
    return USER_PROFILES.get(user_id, {"error": "Pengguna tidak ditemukan"})

print("Template sumber daya 'users://{user_id}/profile' ditambahkan.")

Menambahkan Prompt: Prompt mendefinisikan pola interaksi yang dapat digunakan kembali.

# my_server.py (lanjutan)
@mcp.prompt("summarize")
async def summarize_prompt(text: str) -> list[dict]:
    """Menghasilkan prompt untuk merangkum teks yang diberikan."""
    return [
        {"role": "system", "content": "Anda adalah asisten yang membantu yang terampil dalam merangkum."},
        {"role": "user", "content": f"Silakan ringkas teks berikut:\n\n{text}"}
    ]

print("Prompt 'summarize' ditambahkan.")

3. Menguji Server (Dalam Proses):

Sebelum menjalankan server secara eksternal, Anda dapat menguji komponennya langsung dalam skrip Python yang sama menggunakan Client. Ini berguna untuk pemeriksaan cepat dan pengujian unit.

# my_server.py (lanjutan)
from fastmcp import Client  # Impor klien

async def test_server_locally():
    print("\n--- Menguji Server Secara Lokal ---")
    # Arahkan klien langsung ke objek server
    client = Client(mcp)

    # Klien bersifat asinkron, jadi gunakan manajer konteks asinkron
    async with client:
        # Panggil alat 'greet'
        greet_result = await client.call_tool("greet", {"name": "Pengguna FastMCP"})
        print(f"hasil greet: {greet_result}")

        # Panggil alat 'add'
        add_result = await client.call_tool("add", {"a": 5, "b": 7})
        print(f"hasil add: {add_result}")

        # Baca sumber daya 'config'
        config_data = await client.read_resource("data://config")
        print(f"sumber daya config: {config_data}")

        # Baca profil pengguna menggunakan template
        user_profile = await client.read_resource("users://101/profile")
        print(f"Profil pengguna 101: {user_profile}")

        # Dapatkan struktur prompt 'summarize' (tidak mengeksekusi panggilan LLM di sini)
        prompt_messages = await client.get_prompt("summarize", {"text": "Ini adalah teks."})
        print(f"Struktur prompt ringkasan: {prompt_messages}")

# Jalankan fungsi uji lokal
# asyncio.run(test_server_locally())
# Dihapus untuk saat ini, kita akan fokus pada menjalankan server selanjutnya

Perhatikan penggunaan async dan await. Klien FastMCP beroperasi secara asinkron, memerlukan fungsi async dan menggunakan async with client: untuk mengelola siklus hidup klien.

4. Menjalankan Server:

Untuk membuat server MCP Anda dapat diakses oleh klien eksternal (seperti aplikasi LLM), Anda perlu menjalankannya. Ada dua cara utama:

Eksekusi Python Standar (Direkomendasikan untuk Kompatibilitas):
Tambahkan blok if __name__ == "__main__": berikut ke file my_server.py Anda. Ini adalah praktik standar Python untuk membuat skrip dapat dieksekusi.

# my_server.py (di akhir file)

if __name__ == "__main__":
    print("\n--- Memulai Server FastMCP melalui __main__ ---")
    # Ini memulai server, biasanya menggunakan transport stdio secara default
    mcp.run()

Untuk menjalankan server, eksekusi skrip dari terminal Anda:

python my_server.py

Perintah ini memulai server MCP, mendengarkan koneksi klien menggunakan mekanisme transport stdio (standar input/output) default. Metode ini memastikan server Anda berjalan konsisten untuk berbagai klien yang diharapkan untuk mengeksekusi skrip Python.

Menggunakan CLI FastMCP:
FastMCP menyediakan antarmuka baris perintah untuk menjalankan server, yang menawarkan lebih banyak fleksibilitas dan kontrol, terutama mengenai opsi transport.

# Jalankan server menggunakan stdio (default)
fastmcp run my_server.py:mcp

# Jalankan server menggunakan Server-Sent Events (SSE) pada port 8080
fastmcp run my_server.py:mcp --transport sse --port 8080 --host 0.0.0.0

# Jalankan dengan tingkat log yang berbeda
fastmcp run my_server.py:mcp --transport sse --log-level DEBUG

Poin kunci tentang CLI:

my_server.py:mcp: Menentukan file (my_server.py) dan objek server FastMCP di dalam file tersebut (mcp). Jika Anda menghilangkan :mcp, FastMCP akan mencoba menemukan objek bernama mcp, app, atau server secara otomatis.
Blok if __name__ == "__main__": tidak diperlukan saat menggunakan fastmcp run; CLI langsung menemukan dan menjalankan objek server yang ditentukan.
--transport: Memilih protokol komunikasi (stdio, sse). SSE umum untuk interaksi berbasis web.
--port, --host, --log-level: Mengonfigurasi pengaturan transport dan logging.

5. Berinteraksi dengan Server yang Sedang Berjalan (Klien):

Setelah server Anda berjalan (baik melalui python my_server.py atau fastmcp run), Anda dapat membuat skrip klien terpisah untuk berinteraksi dengannya.

Buat file baru, my_client.py:

# my_client.py
from fastmcp import Client
import asyncio

async def interact_with_server():
    print("--- Membuat Klien ---")

    # Opsi 1: Terhubung ke server yang dijalankan melalui `python my_server.py` (menggunakan stdio)
    # client = Client("my_server.py")

    # Opsi 2: Terhubung ke server yang dijalankan melalui `fastmcp run ... --transport sse --port 8080`
    client = Client("http://localhost:8080")  # Gunakan URL/port yang benar

    print(f"Klien dikonfigurasi untuk terhubung ke: {client.target}")

    try:
        async with client:
            print("--- Klien Terhubung ---")
            # Panggil alat 'greet'
            greet_result = await client.call_tool("greet", {"name": "Klien Jarak Jauh"})
            print(f"hasil greet: {greet_result}")

            # Baca sumber daya 'config'
            config_data = await client.read_resource("data://config")
            print(f"sumber daya config: {config_data}")

            # Baca profil pengguna 102
            profile_102 = await client.read_resource("users://102/profile")
            print(f"Profil pengguna 102: {profile_102}")

    except Exception as e:
        print(f"Terjadi kesalahan: {e}")
    finally:
        print("--- Interaksi Klien Selesai ---")

if __name__ == "__main__":
    asyncio.run(interact_with_server())

Jalankan skrip klien ini saat server berjalan di terminal lain:

python my_client.py

Klien akan terhubung ke server yang sedang berjalan (pastikan target Client(...) cocok dengan cara server berjalan – jalur file untuk stdio, URL untuk sse), mengeksekusi panggilan alat dan pembacaan sumber daya, dan mencetak hasilnya.

6. Konfigurasi Server (ServerSettings):

Anda dapat menyempurnakan perilaku server menggunakan ServerSettings. Pengaturan dapat diterapkan sesuai urutan prioritas:

Argumen kata kunci selama inisialisasi FastMCP (prioritas tertinggi).
Variabel lingkungan (diberi awalan FASTMCP_SERVER_, misalnya, FASTMCP_SERVER_PORT=8888).
Nilai yang dimuat dari file .env di direktori kerja.
Nilai default (prioritas terendah).

Contoh konfigurasi selama inisialisasi:

from fastmcp import FastMCP

mcp_configured = FastMCP(
    name="Server yang Dikonfigurasi",
    port=8080,  # Mengatur port SSE default
    host="127.0.0.1",  # Mengatur host SSE default
    log_level="DEBUG",  # Mengatur tingkat logging
    on_duplicate_tools="warn"  # Peringatan jika alat dengan nama yang sama terdaftar (opsi: 'error', 'warn', 'ignore')
)

# Akses pengaturan melalui atribut .settings
print(f"Port yang Dikonfigurasi: {mcp_configured.settings.port}")  # Output: 8080
print(f"Kebijakan Alat Duplikat: {mcp_configured.settings.on_duplicate_tools}")  # Output: warn

Opsi konfigurasi kunci termasuk host, port, log_level, dan kebijakan untuk menangani nama komponen duplikat (on_duplicate_tools, on_duplicate_resources, on_duplicate_prompts).

Apa Lagi yang Dapat Anda Lakukan dengan FastMCP?

FastMCP juga mendukung kasus penggunaan yang lebih canggih:

Komposisi: Gabungkan beberapa server FastMCP. main.mount("sub", sub_server) membuat tautan langsung, sementara main.import_server(sub_server) menyalin komponen. Ini membantu modularitas.
Proxy: Gunakan FastMCP.from_client(client) untuk membuat instance server FastMCP yang bertindak sebagai proxy untuk server MCP lain (lokal atau jarak jauh). Ini berguna untuk menjembatani transportasi (misalnya, mengekspos server SSE jarak jauh melalui stdio lokal) atau menambahkan frontend yang terpadu.

Kesimpulan

FastMCP secara signifikan menurunkan hambatan untuk membangun aplikasi LLM yang kuat dan sadar konteks dengan menyederhanakan implementasi Model Context Protocol. Desainnya yang Pythonic, fokus pada pengurangan boilerplate, dan set fitur yang komprehensif menjadikannya pilihan yang sangat baik bagi pengembang yang ingin melengkapi LLM dengan alat khusus dan akses data dengan aman dan efisien.

Dengan mengikuti langkah-langkah yang diuraikan di atas – menginstal FastMCP, membuat instance server, menambahkan alat dan sumber daya menggunakan dekorator sederhana, dan menjalankan server – Anda dapat dengan cepat mulai membangun aplikasi Anda sendiri yang mendukung MCP. Apakah Anda membuat alat utilitas sederhana atau integrasi yang kompleks dan intensif data, FastMCP menyediakan fondasi untuk interaksi LLM yang kuat dan skalabel.