HRD PIS 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
   

2. Masuk ke dalam direktori proyek:

   cd hrd-pis-mcp
   

3. 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

2. 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

3. 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".

4. 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!