Bagaimana Saya Membangun Server MCP yang Terhubung ke Claude Desktop dengan Typescript

Model Context Protocol (MCP) mewakili kemajuan signifikan dalam cara asisten AI berinteraksi dengan alat dan sumber data eksternal. Dikembangkan oleh Anthropic, MCP memungkinkan Claude untuk berkomunikasi dengan mulus dengan server khusus, memungkinkannya mengakses informasi waktu nyata, menjalankan alur kerja yang kompleks, dan berinteraksi dengan API tanpa meninggalkan konteks percakapan. Kemampuan ini mengubah Claude dari LLM mandiri menjadi asisten serbaguna yang dapat memanfaatkan fungsionalitas eksternal sambil mempertahankan koherensi percakapan.

Dalam panduan komprehensif ini, kita akan membahas proses membangun server TypeScript MCP dari awal dan menghubungkannya ke Claude Desktop. Dengan menerapkan integrasi ini, Anda akan memungkinkan Claude untuk melakukan tugas-tugas seperti mengambil data waktu nyata, menjalankan komputasi, atau berinteraksi dengan logika bisnis khusus Anda langsung di dalam percakapan.

Sebelum menyelami implementasi server MCP kita, perlu disebutkan bahwa pilihan alat pengembangan API Anda dapat secara signifikan memengaruhi efisiensi alur kerja Anda.

Meskipun Postman telah lama menjadi standar industri, Apidog telah muncul sebagai alternatif unggul yang sangat melengkapi alur kerja pengembangan modern seperti yang sedang kita bangun.
Tidak seperti keterbatasan Postman dengan API yang sedang dalam pengembangan, Apidog menawarkan sinkronisasi waktu nyata antara spesifikasi dan permintaan API Anda, memastikan dokumentasi dan pengujian Anda secara otomatis tetap terkini seiring dengan evolusi API Anda.
Dengan pembuatan spesifikasi API visual, eksekusi koleksi tanpa batas (dibandingkan dengan batas 25/bulan Postman), dan fitur canggih seperti permintaan yang dibuat secara otomatis dan respons tiruan, Apidog menyederhanakan seluruh siklus hidup API. Kemampuan pengujiannya yang komprehensif, termasuk pembuatan pengujian visual dan pelari yang dihosting sendiri, menjadikannya ideal untuk tim yang menerapkan integrasi kompleks seperti server MCP kita.

Saat kita membangun server TypeScript MCP kita, pertimbangkan bagaimana fitur kolaboratif dan pendekatan yang berfokus pada pengembangan Apidog dapat meningkatkan produktivitas tim Anda dan memastikan API Anda tetap konsisten, teruji dengan baik, dan terdokumentasi secara menyeluruh selama proses tersebut.

button

Memahami Model Context Protocol

Model Context Protocol mendefinisikan cara standar bagi Claude untuk berkomunikasi dengan layanan eksternal. Ketika Claude mengidentifikasi bahwa ia membutuhkan informasi dari sumber eksternal, ia dapat memanggil server MCP melalui permintaan JSON yang diformat khusus. Server memproses permintaan ini dan mengembalikan data yang diminta, yang kemudian dapat dimasukkan oleh Claude ke dalam responsnya.

MCP menawarkan beberapa keuntungan dibandingkan pendekatan integrasi AI tradisional:

Kesadaran kontekstual: Claude mempertahankan riwayat percakapan lengkap saat membuat permintaan
Komunikasi dua arah: Protokol ini mendukung interaksi kompleks antara Claude dan server Anda
Keamanan dan kontrol: Anda menentukan fungsionalitas apa yang akan diekspos dan bagaimana permintaan diproses
Pengalaman yang mulus: Pengguna berinteraksi dengan Claude secara alami tanpa perlu mengetahui tentang integrasi yang mendasarinya

Prasyarat

Sebelum kita mulai membangun server MCP kita, pastikan Anda memiliki yang berikut:

Node.js (v18 atau lebih baru) terinstal
Editor kode seperti Visual Studio Code
Pengetahuan dasar tentang TypeScript
Aplikasi Claude Desktop terinstal
Keakraban dengan Express.js (untuk membangun titik akhir server)

Menyiapkan Proyek TypeScript Anda

Mari kita mulai dengan membuat proyek TypeScript baru untuk server MCP kita:

mkdir claude-mcp-server
cd claude-mcp-server
npm init -y
npm install typescript @types/node ts-node express @types/express cors @types/cors
npx tsc --init

Selanjutnya, perbarui tsconfig.json Anda untuk menyertakan pengaturan ini:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "outDir": "./dist",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

Mengimplementasikan Server MCP

Buat file baru bernama server.ts di direktori root proyek Anda. Ini akan menjadi titik masuk untuk server MCP kita:

import express from 'express';
import cors from 'cors';
import { Request, Response } from 'express';

// Define types for the MCP protocol
interface MCPRequest {
  query: string;
  conversation_id: string;
  request_id: string;
  parameters?: Record<string, any>;
}

interface MCPResponse {
  response: string;
  status: 'success' | 'error';
  error?: string;
}

const app = express();
app.use(cors());
app.use(express.json());

// Health check endpoint
app.get('/health', (req: Request, res: Response) => {
  res.status(200).json({ status: 'healthy' });
});

// MCP endpoint
app.post('/mcp', (req: Request, res: Response) => {
  try {
    const mcpRequest = req.body as MCPRequest;
    console.log('Received MCP request:', JSON.stringify(mcpRequest, null, 2));

    // Process the request based on the query
    const response = processQuery(mcpRequest);
    
    res.status(200).json({
      status: 'success',
      response
    } as MCPResponse);
  } catch (error) {
    console.error('Error processing MCP request:', error);
    res.status(500).json({
      status: 'error',
      error: error instanceof Error ? error.message : 'Unknown error',
      response: 'Sorry, there was an error processing your request.'
    } as MCPResponse);
  }
});

// Function to process different query types
function processQuery(request: MCPRequest): string {
  const { query, parameters } = request;

  // Example query handling - customize this for your use case
  switch (query) {
    case 'getCurrentTime':
      return `The current time is ${new Date().toLocaleTimeString()}`;
    
    case 'getWeather':
      const location = parameters?.location || 'Unknown';
      // In a real app, you would call a weather API here
      return `The weather in ${location} is currently sunny and 72°F`;
    
    case 'calculateSum':
      if (parameters?.numbers && Array.isArray(parameters.numbers)) {
        const sum = parameters.numbers.reduce((a: number, b: number) => a + b, 0);
        return `The sum of the numbers is ${sum}`;
      }
      return 'Invalid parameters for sum calculation';

    default:
      return `Unrecognized query: ${query}`;
  }
}

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`MCP server running on port ${PORT}`);
});

Menjalankan Server MCP Anda

Untuk menjalankan server Anda, jalankan:

npx ts-node server.ts

Server MCP Anda sekarang seharusnya berjalan di port 3000 (atau port yang Anda tentukan).

Menghubungkan ke Claude Desktop

Sekarang server MCP Anda berjalan, Anda perlu mengonfigurasi Claude Desktop untuk terhubung ke sana. Berikut caranya:

Buka aplikasi Claude Desktop
Buka Pengaturan (biasanya di sudut kanan atas)
Navigasi ke bagian "Fitur Eksperimental"
Aktifkan tombol "Model Context Protocol"
Tambahkan titik akhir MCP baru dengan URL http://localhost:3000/mcp
Simpan pengaturan Anda

Claude Desktop sekarang akan dapat berkomunikasi dengan server MCP khusus Anda.

Menguji Integrasi

Untuk menguji server MCP Anda dengan Claude, coba ajukan pertanyaan kepada Claude yang akan memicu kueri spesifik yang telah Anda terapkan. Misalnya:

"Jam berapa sekarang?" (seharusnya memicu kueri getCurrentTime)
"Bagaimana cuaca di San Francisco?" (seharusnya memicu kueri getWeather dengan "San Francisco" sebagai parameter lokasi)
"Bisakah Anda menghitung jumlah 5, 10, 15, dan 20?" (seharusnya memicu kueri calculateSum)

Ketika Claude menyadari bahwa ia membutuhkan informasi eksternal untuk menjawab pertanyaan-pertanyaan ini, ia akan secara otomatis mengirimkan permintaan MCP ke server Anda dan memasukkan respons ke dalam jawabannya.

Memperluas Server MCP Anda

Server dasar yang telah kita bangun hanyalah titik awal. Berikut adalah beberapa ide untuk memperluas fungsionalitasnya:

Tambahkan Autentikasi

Untuk mengamankan server MCP Anda, tambahkan autentikasi:

// Middleware for basic auth
const authenticateMCP = (req: Request, res: Response, next: Function) => {
  const apiKey = req.headers['x-api-key'];
  if (!apiKey || apiKey !== process.env.MCP_API_KEY) {
    return res.status(401).json({
      status: 'error',
      error: 'Unauthorized',
      response: 'Authentication failed'
    });
  }
  next();
};

// Apply middleware to MCP endpoint
app.post('/mcp', authenticateMCP, (req: Request, res: Response) => {
  // Existing handler code
});

Implementasikan Integrasi Database

Hubungkan server MCP Anda ke database untuk mengambil atau menyimpan informasi:

import { MongoClient } from 'mongodb';

// Initialize database connection
const dbClient = new MongoClient('mongodb://localhost:27017');
let db: any;

async function connectToDb() {
  await dbClient.connect();
  db = dbClient.db('mcpDatabase');
  console.log('Connected to database');
}

connectToDb().catch(console.error);

// Add a query handler for database interactions
case 'getUserData':
  if (parameters?.userId) {
    const user = await db.collection('users').findOne({ id: parameters.userId });
    return user ? JSON.stringify(user) : 'User not found';
  }
  return 'Invalid user ID';

Tambahkan Dukungan Webhook

Implementasikan fungsionalitas webhook untuk memberi tahu layanan eksternal:

case 'sendNotification':
  if (parameters?.message && parameters?.destination) {
    // Call external notification service
    await fetch('https://your-webhook-url.com', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ message: parameters.message })
    });
    return `Notification sent to ${parameters.destination}`;
  }
  return 'Invalid notification parameters';

Praktik Terbaik untuk Pengembangan Server MCP

Tangani kesalahan dengan baik: Selalu tangkap pengecualian dan kembalikan pesan kesalahan yang informatif
Implementasikan pencatatan: Catat semua permintaan dan respons untuk debugging dan audit
Gunakan antarmuka TypeScript: Definisikan antarmuka yang jelas untuk semua struktur data
Tetapkan batas waktu: Implementasikan batas waktu permintaan untuk mencegah operasi yang menggantung
Validasi input: Validasi dengan cermat semua parameter input sebelum diproses
Tambahkan pengujian unit: Uji penangan kueri Anda secara menyeluruh untuk memastikan keandalan

Kesimpulan

Membangun server TypeScript MCP membuka kemungkinan menarik untuk memperluas kemampuan Claude. Dengan mengikuti panduan ini, Anda telah menciptakan fondasi untuk mengintegrasikan Claude dengan layanan dan data Anda sendiri. Model Context Protocol memungkinkan pengalaman pengguna yang mulus di mana Claude dapat mengakses informasi eksternal tanpa mengganggu alur percakapan.

Seiring dengan terus berkembangnya MCP, kita dapat mengharapkan integrasi yang lebih canggih antara model bahasa besar dan sistem eksternal. Apakah Anda sedang membangun alat produktivitas, sistem manajemen pengetahuan, atau aplikasi bisnis khusus, MCP menyediakan cara yang ampuh untuk menggabungkan kecerdasan Claude dengan fungsionalitas khusus Anda.

Mulailah menjelajahi kemungkinan dengan memperluas server Anda dengan penangan kueri tambahan yang spesifik untuk kasus penggunaan Anda, dan bagikan pengalaman Anda dengan komunitas pengembang MCP yang berkembang.