HRD-PIS MCP Server

📋 Prasyarat Sistem

Sebelum memulai, pastikan sistem Anda sudah terinstal:

1. Node.js (Minimal versi 18)
2. Git (Untuk cloning repositori)
3. Aplikasi terminal (Command Prompt/PowerShell untuk Windows, atau Terminal bawaan untuk Mac/Linux).
4. Claude Desktop (Jika ingin menjalankan tahap integrasi AI).

🚀 Langkah 1: Instalasi Proyek

1. Buka terminal Anda dan clone repositori ini ke komputer lokal:

   git clone https://github.com/Rashqueee/hrd-pis-mcp.git

1. Masuk ke dalam direktori proyek:

   cd hrd-pis-mcp

1. Instal seluruh dependensi yang dibutuhkan (termasuk MCP SDK dan TypeScript):

   npm install

🔑 Langkah 2: Mendapatkan Token Autentikasi API

Server ini membutuhkan Bearer Token untuk dapat berkomunikasi dengan backend HRD-PIS. Token ini diambil melalui proses otentikasi Basic (Base64). Ikuti langkah ini dengan teliti:

A. Ubah Kredensial ke Base64 Ubah format username:password Anda menjadi format Base64 menggunakan terminal:

• Pengguna Mac/Linux:

  echo -n "username_anda:password_anda" | base64

• Pengguna Windows (PowerShell):

   [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("username_anda:password_anda"))

(Catat teks acak hasil perintah di atas, misalnya: `YnVkaXNhbnRvc28...`)

B. Tembak API Login Jalankan perintah curl berikut di terminal untuk melakukan login. Pastikan flag -D - disertakan agar terminal menampilkan Response Header:

curl -s -D - -X POST \
  https://api-profile-plus.pisdev.my.id/auth/login \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <MASUKKAN_HASIL_BASE64_DI_SINI>"

C. Ambil Token Lihat hasil keluaran di terminal. Abaikan pesan success di bagian bawah, dan cari baris ini di bagian atas (Header): authorization: Bearer xxxxx... Salin teks tersebut. Ini adalah HRD_API_TOKEN Anda.

🏗️ Langkah 3: Build Proyek

Karena proyek ini ditulis dengan TypeScript, Anda harus melakukan kompilasi (build) menjadi JavaScript sebelum bisa dijalankan.

Jalankan perintah berikut di terminal (berada di dalam folder hrd-pis-mcp):

npm run build

Catatan: Perintah ini akan otomatis menghapus sisa kompilasi lama dan membuat folder `build/` baru yang siap pakai.

🛠️ Langkah 4: Pengujian Lokal (MCP Inspector)

Sebelum dipasang ke Claude Desktop, uji coba tools Anda menggunakan MCP Inspector (antarmuka web resmi dari Anthropic).

Jalankan perintah di bawah ini dengan mengganti <TOKEN_ANDA> menggunakan token dari Langkah 2:

Untuk Pengguna Mac/Linux (Bash/Zsh):

HRD_BASE_URL="https://api-profile-plus.pisdev.my.id" HRD_API_TOKEN="<TOKEN_ANDA>" npx @modelcontextprotocol/inspector node build/index.js

Untuk Pengguna Windows (PowerShell):

$env:HRD_BASE_URL="https://api-profile-plus.pisdev.my.id"; $env:HRD_API_TOKEN="<TOKEN_ANDA>"; npx @modelcontextprotocol/inspector node build/index.js

Setelah perintah berjalan, terminal akan menampilkan tautan (misal: http://localhost:5173). Buka tautan tersebut di browser Anda untuk melakukan testing pada 16 tools yang tersedia secara manual.

(Tekan `Ctrl + C` di terminal untuk mematikan Inspector jika sudah selesai).

🤖 Langkah 5: Pemasangan Permanen di Claude Desktop

Jika pengujian lokal berhasil, pasangkan server ini ke Claude Desktop agar AI bisa menggunakannya secara otonom.

1. Cari Absolute Path Proyek Anda:

Dapatkan alamat direktori lengkap menuju file index.js hasil build Anda.

• Contoh Mac: /Users/namauser/projects/hrd-pis-mcp/build/index.js
• Contoh Win: C:\Users\namauser\projects\hrd-pis-mcp\build\index.js

1. Buka File Konfigurasi Claude:

• macOS: Buka terminal dan jalankan open ~/Library/Application\ Support/Claude/claude_desktop_config.json
• Windows: Buka File Explorer dan tuju ke %APPDATA%\Claude\claude_desktop_config.json

1. Masukkan Konfigurasi:

Isi file JSON tersebut dengan format berikut:

   {
     "mcpServers": {
       "hrd-pis": {
         "command": "node",
         "args": [
           "<MASUKKAN_PATH_ABSOLUT_ANDA_DI_SINI>"
         ],
         "env": {
           "HRD_BASE_URL": "https://api-profile-plus.pisdev.my.id",
           "HRD_API_TOKEN": "<MASUKKAN_TOKEN_ANDA_DI_SINI>"
         }
       }
     }
   }

⚠️ Penting untuk Windows: Anda wajib mengubah garis miring terbalik tunggal (\) pada path menjadi ganda (\\). Contoh: "C:\\Users\\nama\\projects\\hrd-pis-mcp\\build\\index.js".

1. Restart Claude Desktop:

Tutup aplikasi Claude Desktop sepenuhnya (Quit), lalu buka kembali.

Buka obrolan baru, klik ikon Tools (palu) di kolom obrolan, dan Anda sudah bisa mulai memberikan perintah terkait HRD-PIS kepada Claude!