Tutorial MCP Server TypeScript: Hubungkan Database ke AI

Model Context Protocol (MCP) menjadi standar komunikasi antara AI agent dan sumber data eksternal. Dibandingkan dengan integrasi API tradisional, MCP memungkinkan LLM menemukan dan menggunakan tool secara dinamis tanpa hardcoded prompt. Artikel ini akan membimbingmu membangun MCP server pertama menggunakan TypeScript dan menghubungkannya ke database PostgreSQL.

Projek ini cocok untuk developer yang ingin memahami arsitektur MCP dan menerapkannya dalam sistem production. Kita akan menggunakan official SDK dari Anthropic dan memastikan server berjalan via stdio transport yang kompatibel dengan Claude Desktop maupun MCP client lainnya.

Apa itu Model Context Protocol?

MCP adalah protokol terbuka yang memungkinkan AI assistant mengakses data lokal maupun remote secara aman. Konsepnya mirip dengan LSP (Language Server Protocol), tapi fokus pada penyediaan konteks dan tool untuk AI. Dengan MCP, developer bisa mengekspos file system, database, API internal, atau bahkan hardware sebagai resource yang bisa di-query LLM.

Protokol ini mendefinisikan tiga komponen utama: resources (data yang bisa dibaca LLM), tools (aksi yang bisa dieksekusi), dan prompts (template interaksi). Setiap komponen dideskripsikan dengan schema JSON sehingga LLM tahu persis cara menggunakannya.

Persiapan Environment

Sebelum mulai coding, pastikan environment sudah siap. Kamu memerlukan Node.js versi 18 atau lebih tinggi, PostgreSQL running lokal, dan package manager npm atau pnpm. Buat direktori baru dan inisialisasi projek TypeScript:

mkdir mcp-postgres-server
cd mcp-postgres-server
npm init -y
npm install @modelcontextprotocol/sdk zod pg
npm install -D typescript @types/node

Konfigurasi tsconfig.json dengan target ES2022 dan module CommonJS karena MCP SDK masih mengandalkan module format tersebut untuk stdio transport:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "CommonJS",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true
  }
}

Langkah 1: Definisikan Schema dengan Zod

MCP menggunakan schema untuk menjelaskan parameter tool kepada LLM. Kita akan gunakan Zod karena integrasinya native dengan TypeScript dan memberikan type safety yang kuat. Buat file src/schema.ts:

import { z } from 'zod';

export const QueryArgsSchema = z.object({
  sql: z.string().describe('Query SQL yang valid untuk PostgreSQL'),
  params: z.array(z.string()).optional().describe('Parameter query')
});

export const TableSchema = z.object({
  tableName: z.string().describe('Nama tabel yang ingin dijelaskan')
});

Schema ini akan diterjemahkan ke dalam JSON Schema yang dipahami LLM. Field describe sangat penting karena menjadi instruksi natural language bagi model untuk mengisi parameter dengan benar.

Langkah 2: Implementasi Server Core

Buat file src/server.ts sebagai entry point. Di sini kita inisialisasi Server instance dari SDK dan mendaftarkan capability yang didukung:

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/server/index.js';

const server = new Server(
  { name: 'postgres-mcp-server', version: '1.0.0' },
  { capabilities: { tools: {} } }
);

Transport stdio dipilih karena merupakan cara paling universal untuk MCP client mengkomunikasikan dengan server. Claude Desktop, Cursor, dan client lainnya secara default mencari executable yang berkomunikasi via stdin/stdout.

Langkah 3: Daftarkan Tool List

Tiap kali client memulai koneksi, ia akan meminta daftar tool yang tersedia. Kita tangani dengan handler ListToolsRequestSchema:

server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: 'query_database',
        description: 'Jalankan query SELECT pada PostgreSQL',
        inputSchema: {
          type: 'object',
          properties: {
            sql: { type: 'string', description: 'Query SQL SELECT' },
            params: { type: 'array', items: { type: 'string' } }
          },
          required: ['sql']
        }
      },
      {
        name: 'describe_table',
        description: 'Dapatkan struktur kolom dari tabel tertentu',
        inputSchema: {
          type: 'object',
          properties: {
            tableName: { type: 'string', description: 'Nama tabel' }
          },
          required: ['tableName']
        }
      }
    ]
  };
});

Langkah 4: Implementasi Handler Tool

Bagian ini adalah core logic. Ketika LLM memutuskan untuk menggunakan tool, client akan mengirim request CallTool yang perlu kita proses:

import { Pool } from 'pg';

const pool = new Pool({ connectionString: process.env.DATABASE_URL });

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  if (name === 'query_database') {
    const { sql, params = [] } = args as any;
    const result = await pool.query(sql, params);
    return {
      content: [{ type: 'text', text: JSON.stringify(result.rows, null, 2) }]
    };
  }

  if (name === 'describe_table') {
    const { tableName } = args as any;
    const result = await pool.query(
      `SELECT column_name, data_type FROM information_schema.columns WHERE table_name = $1`,
      [tableName]
    );
    return {
      content: [{ type: 'text', text: JSON.stringify(result.rows, null, 2) }]
    };
  }

  throw new Error(`Tool tidak dikenal: ${name}`);
});

Pastikan selalu validasi input dan gunakan parameterized query untuk mencegah SQL injection. Meskipun LLM yang memanggil tool, client tetap bisa dipakai oleh user yang tidak berwenang jika tidak diamankan dengan baik.

Langkah 5: Kompilasi dan Koneksi ke Client

Terakhir, compile TypeScript dan jalankan server. Tambahkan script di package.json:

{
  "scripts": {
    "build": "tsc",
    "start": "node dist/server.js"
  }
}

Jalankan npm run build lalu tes server dengan cara menjalankan executable langsung. Untuk menghubungkan ke Claude Desktop, tambahkan konfigurasi di file claude_desktop_config.json:

{
  "mcpServers": {
    "postgres": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-postgres-server/dist/server.js"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost/dbname"
      }
    }
  }
}

Restart Claude Desktop dan AI sekarang bisa melihat struktur database serta menjalankan query sesuai kebutuhan analisis.

Kesimpulan

Membangun MCP server tidak serumit yang dibayangkan. Dengan TypeScript dan SDK official, kita bisa mengekspos resource internal ke AI agent dalam waktu kurang dari satu jam. Protokol ini membuka kemungkinan integrasi yang lebih dalam antara LLM dan infrastruktur yang sudah ada.

Untuk eksplorasi lebih lanjut, pertimbangkan menambahkan resource read-only, implementasi caching, atau autentikasi berbasis token. Dokumentasi lengkap MCP tersedia di modelcontextprotocol.io.

Source gambar: Unsplash. Referensi tutorial: MCP Quickstart Server.

Tutorial MCP Server dengan TypeScript: Hubungkan Database ke AI Agent