Ubah Node.js REST API Anda menjadi server MCP yang siap AI – Beragampengetahuan

Pengembangan model bahasa besar (LLM) dan agen AI memerlukan perubahan mendasar dalam cara aplikasi mengekspos fungsionalitasnya. REST API tradisional dirancang untuk komunikasi antar perangkat lunak, mengharuskan pengembang membaca dokumentasi dan menulis kode integrasi khusus. Model Context Protocol (MCP) adalah standar terbuka yang bertujuan untuk memecahkan masalah ini dengan menciptakan antarmuka terpadu yang dapat dibaca mesin sehingga agen kecerdasan buatan dapat menemukan dan berinteraksi secara dinamis.

Artikel ini memberikan panduan komprehensif untuk mengonversi REST API Node.js yang ada ke server MCP menggunakan TypeScript SDK resmi, dengan fokus pada perubahan arsitektur dan kasus penggunaan utama yang dihasilkan oleh konversi ini.

Pergeseran Paradigma: Dari REST ke MCP

REST API biasanya dirancang dengan mempertimbangkan pengembang manusia, mengoptimalkan manajemen sumber daya (operasi CRUD) melalui kata kerja HTTP, variabel jalur, dan format permintaan/respons tertentu.

Sebaliknya, model MCP mengutamakan AI:

Konversi bukanlah pelabuhan langsung; itu adalah abstraksi. Anda dapat menggabungkan logika bisnis Node.js yang ada dengan lapisan MCP, yang mengubah panggilan MCP standar menjadi permintaan REST yang dipahami oleh API Anda.

Langkah 1: Siapkan lingkungan MCP Node.js

Model Context Protocol TypeScript SDK resmi adalah alat inti untuk konversi ini.

1. Inisialisasi proyek dan instal dependensi

Dengan asumsi proyek dasar Node.js (v18+), Anda memerlukan MCP SDK, utilitas untuk validasi permintaan (seperti Zod), dan klien HTTP (seperti axios atau node-fetch) untuk berinteraksi dengan REST API yang ada.

npm init -y
npm install @modelcontextprotocol/sdk zod node-fetch
npm install -D typescript @types/node ts-node

2. Buat instance server MCP

Buat file (seperti mcp-server.ts) untuk menyiapkan instans server dan lapisan transport, seperti StdioServerTransport untuk pengujian lokal atau StreamableHttpServerTransport untuk penerapan jarak jauh.

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

// Instantiate the core MCP server
const server = new McpServer({
    name: "MyNodeAPIServer",
    version: "1.0.0",
    capabilities: { tools: {}, resources: {}, prompts: {} },
});

// The transport handles communication with the LLM client
const transport = new StdioServerTransport();

async function startServer() {
    // [Tool and Resource registration will go here]
    
    await server.connect(transport);
    console.log("MCP Server is running on standard I/O...");
}

startServer().catch(console.error);

Langkah 2: Rencanakan dan tentukan alat MCP

Ini adalah langkah paling kritis. Daripada mengekspos secara membabi buta setiap titik akhir REST, Anda harus mengatur fungsionalitas ke dalam alat dan sumber daya tingkat tinggi yang ramah agen.

1. Rancang alat yang ramah LLM

LLM berkinerja lebih baik menggunakan alat semantik berbasis niat daripada panggilan API tingkat rendah yang terperinci.

• Buruk (berpusat pada REST): get_user_by_id, update_user_name, update_user_email
• Bagus (berpusat pada MCP): manage_user_profile(userId, newName, newEmail)

Pengendali alat MCP harus mengatur beberapa panggilan REST yang diperlukan untuk menyelesaikan satu operasi tingkat tinggi.

2. Menerapkan pengendali alat

Setiap alat memerlukan nama deskriptif, deskripsi bahasa alami LLM yang lengkap, dan skema input/output terstruktur menggunakan Zod.

// Define the schema for the tool's input arguments
const UpdateUserSchema = z.object({
    userId: z.string().describe("The unique ID of the user to update."),
    newEmail: z.string().email().optional().describe("The user's new email address."),
    newSubscriptionPlan: z.enum(['basic', 'premium', 'pro']).optional().describe("The new subscription plan to apply."),
});

server.registerTool(
    "manage_subscription",
    {
        title: "Manage User Subscription and Profile",
        description: "Updates a user's email address and/or changes their subscription plan. Requires the user's ID.",
        argsSchema: UpdateUserSchema,
        outputSchema: z.object({
            status: z.string(),
            updatedFields: z.array(z.string()),
        }),
    },
    async (args) => {
        const { userId, newEmail, newSubscriptionPlan } = args;
        const updatedFields: string[] = [];
        
        // --- REST API CALL Orchestration ---
        const REST_API_BASE = process.env.REST_API_URL;

        if (newEmail) {
            // 1. Call the REST API to update email
            await fetch(`${REST_API_BASE}/users/${userId}/email`, {
                method: 'PUT',
                body: JSON.stringify({ email: newEmail }),
                headers: { 'Content-Type': 'application/json' },
            });
            updatedFields.push('email');
        }

        if (newSubscriptionPlan) {
            // 2. Call the REST API to update subscription
            await fetch(`${REST_API_BASE}/billing/${userId}/plan`, {
                method: 'POST',
                body: JSON.stringify({ plan: newSubscriptionPlan }),
                headers: { 'Content-Type': 'application/json' },
            });
            updatedFields.push('subscriptionPlan');
        }

        // Return a structured response for the LLM
        return {
            status: "Success",
            updatedFields: updatedFields.length > 0 ? updatedFields : ["No changes made."],
        };
    }
);

3. Ciptakan sumber daya untuk konteksnya

Untuk permintaan GET sederhana yang menyediakan konteks (data hanya baca), gunakan ResourceTemplates. Ini memungkinkan LLM memahami data apa yang tersedia tanpa harus menggunakan alat.

server.registerResource(
    "product_catalog_item",
    {
        title: "Product Catalog Item",
        description: "A single item from the product catalog, including price, stock, and description.",
        uriTemplate: "api://my-node-api-mcp/products/{productId}",
        dataSchema: z.object({
            id: z.string(),
            name: z.string(),
            price: z.number(),
            description: z.string(),
        }),
    },
    async (uri) => {
        // Parse the productId from the URI or argument
        const productId = uri.split("
        
        // Call your REST API: GET /products/{productId}
        const response = await fetch(`${process.env.REST_API_URL}/products/${productId}`);
        return await response.json();
    }
);

Langkah 3: Terapkan keamanan dan penanganan kesalahan

Keamanan sangat penting ketika memaparkan fungsionalitas ke agen otonom.

1. Integrasi sertifikasi

Server MCP Anda bertindak sebagai proxy. Klien HTTP internalnya harus menangani otentikasi REST API asli. Hal ini biasanya melibatkan pemuatan kunci API atau token OAuth dengan aman dari variabel lingkungan dan memasukkannya ke dalam header otorisasi panggilan pengambilan atau aksio dalam pengendali alat.

2. Respon kesalahan yang kuat

Agen AI mengandalkan keluaran terstruktur untuk menentukan keberhasilan atau kegagalan suatu operasi. Penangan Anda harus menangkap kesalahan HTTP dari REST API dan mengubahnya menjadi respons kesalahan MCP yang jelas dan terstruktur.

• Buruk: Menampilkan kesalahan HTTP 404 mentah.
• Baik: Mengembalikan keluaran MCP di mana { status: “Kesalahan”, pesan: “Pengguna dengan ID 123 tidak ditemukan dalam database.” }

Kasus penggunaan utama untuk membuka kunci MCP

Konversi ke MCP adalah langkah strategis yang memungkinkan aplikasi berbasis AI jenis baru.

1. Alat pengembangan berbasis AI (kasus penggunaan “kursor”)

Banyak IDE AI modern dan asisten kode (seperti Cursor, GitHub Copilot) menggunakan MCP untuk memungkinkan AI berinteraksi dengan lingkungan pengembangan lokal atau layanan internal.

• Skenario: Pengembang bertanya: “Jalankan tes integrasi untuk modul manajemen pengguna baru.”
• Alat MCP: run_npm_script (nama skrip: string)
• Logika API Node.js: Alat ini dengan aman menjalankan perintah shell seperti npm run test:user-management dengan persetujuan pengguna yang eksplisit.

2. Otomatisasi Dukungan Pelanggan yang Cerdas

Paparkan CRM inti, inventaris, atau API penagihan Anda sebagai alat MCP kepada agen AI internal.

• Skenario: Agen dukungan bertanya kepada AI, “Apa status pesanan pelanggan Alice dan bisakah kami menerapkan diskon 10%?”
• Alat MCP 1 (sumber daya): get_customer_order_history(customerId)
• Alat MCP 2 (Alat): apply_discount_to_order(orderId, persentase)
• Keuntungan: AI secara otomatis menghubungkan panggilan, memperoleh data, dan melakukan tindakan, sehingga tidak memerlukan langkah manual.

3. Alur kerja dinamis dan orkestrasi layanan mikro

Server MCP dapat berfungsi sebagai lapisan abstraksi di atas arsitektur layanan mikro yang luas, memungkinkan LLM mengatur alur kerja multi-langkah yang kompleks menggunakan satu perintah semantik.

• Skenario: LL.M. menerima instruksi untuk “menangani proses orientasi klien baru untuk Jane Doe.”
• Alat MCP: onboard_new_customer (nama, email)

Logika orkestrasi: Pengendali alat secara internal memanggil layanan mikro pengguna (REST POST), layanan penagihan (REST POST), dan layanan email (REST POST) untuk memastikan bahwa seluruh proses bisnis diselesaikan dengan benar. Hal ini membuat integrasi LLM menjadi sederhana dan mudah beradaptasi dengan kompleksitas back-end.

Kesimpulan: Masa depan integrasi AI terstandarisasi

Mengonversi REST API Node.js Anda untuk mendukung MCP adalah investasi untuk mempersiapkan aplikasi Anda di masa depan di era agen AI otonom. Meskipun menggabungkan setiap titik akhir merupakan titik awal yang baik, kekuatan sebenarnya dari MCP dicapai melalui manajemen aktif, alat semantik tingkat tinggi yang dirancang untuk mencerminkan maksud pengguna, bukan struktur API. Proses ini mengubah API Anda dari layanan pertukaran data statis menjadi keahlian dinamis yang dapat dipanggil AI, sehingga sangat memperluas kegunaannya dalam ekosistem agensi