Superapp MCP Server

MCP Server berbasis TypeScript untuk membaca dokumentasi Swagger/OpenAPI dari Superapp Golang dan mengeksposnya sebagai tools ke AI melalui stdio transport.

Fitur

• get_all_routes: Mengambil semua endpoint API dari Swagger paths.
• get_route_details: Mengambil detail endpoint tertentu (method + path) dan melakukan resolve $ref ke definitions.
• get_data_model: Mengambil schema model tertentu dari definitions.
• Error handling untuk kondisi Swagger tidak bisa diakses.

Prasyarat

• Node.js 18+
• Superapp Golang aktif dan menyediakan Swagger JSON

Default Swagger URL:

http://localhost:8000/swagger/doc.json

Instalasi

npm install

Konfigurasi

1. Salin nilai dari file .env.example.
2. Atur environment variable SWAGGER_URL sesuai endpoint Swagger kamu.

Contoh (PowerShell):

$env:SWAGGER_URL="http://localhost:8000/swagger/doc.json"

Menjalankan Project

Build TypeScript:

npm run build

Jalankan server MCP:

npm start

Setup MCP Client (Dev/Staging/Prod)

Template konfigurasi MCP client sudah disediakan di:

• examples/mcp-servers.template.json (jalankan server dengan Node lokal)
• examples/mcp-servers.docker.template.json (jalankan server dari Docker)

Template final siap copy per client:

• examples/clients/claude-desktop.node.json
• examples/clients/claude-desktop.docker.json
• examples/clients/cursor.node.json
• examples/clients/vscode-copilot.node.json

Langkah pakai:

1. Salin template ke file konfigurasi MCP client yang kamu gunakan.
2. Ubah path args ke lokasi project di mesin masing-masing developer.
3. Sesuaikan nilai SWAGGER_URL per environment (dev/staging/prod).

Tips Windows:

• Gunakan path absolute dengan slash /, contoh: C:/tools/superapp-mcp/build/index.js.

Docker (Praktis untuk Tim)

Build image:

npm run docker:build

Jalankan image secara lokal:

npm run docker:run

Catatan:

• Opsi -i wajib agar stdio MCP tetap terhubung ke client.
• host.docker.internal dipakai agar container bisa mengakses service Swagger di host machine.

Deploy ke Tim Dev

Karena transport MCP kamu berbasis stdio, pola deploy yang disarankan adalah distribusi executable runtime, bukan expose HTTP endpoint terpisah.

Pilihan distribusi:

1. Node distribution (paling sederhana)
   • Simpan project di repo internal.
   • Tiap developer: npm ci, npm run build, lalu pakai template config MCP.
2. Docker distribution (paling konsisten)
   • Build image sekali di CI.
   • Push ke private container registry.
   • Tiap developer menjalankan MCP via command docker run --rm -i ... dari config MCP client.

Checklist rollout tim:

1. Tetapkan URL Swagger per environment.
2. Lock versi package/image.
3. Standarkan template config MCP client.
4. Jalankan smoke test tool get_all_routes setelah setup.
5. Dokumentasikan troubleshooting internal (network, URL, permission).

CI/CD Dasar

Pipeline CI sudah disiapkan di:

• .github/workflows/ci.yml

Yang divalidasi otomatis:

1. Install dependency (npm ci).
2. Typecheck (npm run typecheck).
3. Build TypeScript (npm run build).
4. Build Docker image (docker build ...).

Jika kamu pakai private registry, next step-nya tinggal tambah step login + push image di workflow yang sama.

Scripts

• npm run build: compile TypeScript ke folder build.
• npm start: jalankan MCP server dari build/index.js.
• npm run typecheck: validasi TypeScript tanpa emit output.
• npm run docker:build: build Docker image superapp-mcp:latest.
• npm run docker:run: jalankan MCP server dari Docker image.
• npm run test: placeholder script default.

Struktur Project

• index.ts - entry point MCP server.
• tsconfig.json - konfigurasi TypeScript.
• .env.example - contoh konfigurasi environment.
• .gitignore - file/folder yang diabaikan Git.
• Dockerfile - build image untuk distribusi tim.
• .dockerignore - optimasi konteks build Docker.
• examples/mcp-servers.template.json - template config MCP client (Node).
• examples/mcp-servers.docker.template.json - template config MCP client (Docker).
• examples/clients/*.json - template config final untuk client populer.
• .github/workflows/ci.yml - validasi build/deploy readiness di CI.

Catatan Integrasi MCP

Server menggunakan stdio transport, jadi cocok dijalankan oleh MCP host/client yang mendukung komunikasi proses standard input/output.