PinisiDev MCP Light

HTTP API gateway untuk konsistensi output coding agent (Claude Code, Codex, Kimi Code, Antigravity IDE). MCP tidak panggil LLM — coding agent panggil LLM sendiri pakai key/subscription user. MCP cuma transform prompt + validate response.

Fitur

| Fitur | Deskripsi | |---|---| | Feature Codes | Prefix prompt dengan NF:, BF:, DA:, AS: untuk auto-apply mode + workflow | | Interactive CLI | pinisi-light ask — transform tanpa curl, ramah developer pemula | | Preset Workflows | 4 workflow auto-created saat init (new-feature, bug-fix, deep-analyze, audit-system) | | Mode Lock | Setiap workflow bisa define mode default (SNR_CODE/JNR_CODE/SNR_DB/ORC) | | Prompt Compactor | Heuristic regex: strip greeting, dedup, truncate >4000 token | | Token Budget Gate | Auto-reject prompt > 8000 token | | Output Validator | Similarity check ≥80% vs golden output, dengan structure fallback | | Cache + State Hash | Cache key include hash CURRENT_STATE.md — edit state = auto-miss | | Memory Bridge | .ai/ folder jadi single source of truth untuk semua coding agent | | Auto-Commit | pinisi-light commit atau POST /commit — commit otomatis per file dengan pesan minimal-token | | Persona Injection | 4 mode: SNR_CODE, JNR_CODE, SNR_DB, ORC — inject otomatis ke finalPrompt |

Quick Start

# 1. Install
git clone <repo> && cd pinisi-mcp-light
npm install

# 2. Build
cp .env.example .env
npm run build

# 3. Start dengan PM2
# Cara A: pakai config CJS (paling kompatibel)
pm2 start ecosystem.config.cjs

# Cara B: command langsung (tanpa config file)
pm2 start dist/server.js --name pinisi-light

# 4. Save PM2 config
pm2 save
pm2 startup

Catatan PM2: Kalau ecosystem.config.js (ESM) error, gunakan ecosystem.config.cjs (CommonJS) atau command langsung.

Deploy ke Server Sendiri (Self-Host)

Kalau ingin deploy MCP Light untuk tim sendiri:

# 1. Clone & install
git clone <repo> && cd pinisi-mcp-light
npm install
npm run build

# 2. Set environment (opsional)
cp .env.example .env
# Edit .env — default PORT=3000, DB_PATH=data/pinisi-light.db

# 3. Deploy dengan PM2
pm2 start ecosystem.config.cjs
pm2 save
pm2 startup

# 4. Setup reverse proxy (Nginx)
# Lihat contoh config di bawah

# 5. Setup SSL (Certbot)
sudo certbot --nginx -d light.yourdomain.com

Contoh Nginx Config:

server {
    listen 80;
    server_name light.yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Tim developer menggunakan server self-host:

# Set env var ke server production
export PINISI_SERVER_URL=https://light.yourdomain.com

# Init project
npx pinisi-light init
# Masukkan server URL saat wizard, atau biarkan default localhost untuk local dev

Cara Penggunaan

1. Inisialisasi Project

cd /path/to/your-project
npx pinisi-light init

Wizard akan:

• Bootstrap .ai/ folder (WORKER_BRIEF, CURRENT_STATE, ISSUE, CC_LOG, dll)
• Install adapter untuk agent yang dipilih (Claude Code, Codex, Kimi CLI, Antigravity)
• Auto-create 4 preset workflow: new-feature (NF), bug-fix (BF), deep-analyze (DA), audit-system (AS)
• Register project ke SQLite

2. Transform dengan Feature Code (Cara Termudah)

A. Via Interactive CLI (rekomendasi untuk pemula):

npx pinisi-light ask
# Prompt: NF: buat fitur login dengan JWT
# → auto-detect NF → mode SNR_CODE → workflow new-feature
# → tampilkan finalPrompt, tinggal copy ke LLM

B. Via curl (advanced):

curl -X POST http://localhost:3000/transform \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "my-project",
    "agent": "claude",
    "prompt": "NF: buat fitur login dengan JWT",
    "projectPath": "/path/to/project"
  }'

C. Full cycle manual:

# Step 1: Transform
curl -X POST http://localhost:3000/transform \
  -d '{"projectId":"x","agent":"claude","prompt":"NF: buat fitur X","projectPath":"/project"}'
# → {transformId, finalPrompt, tokenEstimate}

# Step 2: Copy finalPrompt ke LLM Anda (Claude/Kimi/Codex)

# Step 3: Validate response (opsional)
curl -X POST http://localhost:3000/validate \
  -d '{"transformId":"uuid","response":"<output LLM>"}'

3. Feature Codes Reference

| Kode | Arti | Mode | Kapan Dipakai | |---|---|---|---| | NF: | New Feature | SNR_CODE | Buat fitur baru, implementasi kompleks | | BF: | Bug Fix | JNR_CODE | Fix bug, quick patch, execute-only | | DA: | Deep Analyze | SNR_CODE | Audit code, analisis performa, review | | AS: | Audit System | SNR_DB | Scan security, review DB/schema |

Contoh:

# New Feature → mode SNR_CODE
curl -d '{"projectId":"x","agent":"claude","prompt":"NF: buat forgot password"...}'

# Bug Fix → mode JNR_CODE
curl -d '{"projectId":"x","agent":"claude","prompt":"BF: fix null pointer"...}'

# Deep Analyze → mode SNR_CODE
curl -d '{"projectId":"x","agent":"claude","prompt":"DA: kenapa query lambat"...}'

# Audit System → mode SNR_DB
curl -d '{"projectId":"x","agent":"claude","prompt":"AS: cek security auth"...}'

4. Ganti Mode Manual

Kalau tidak pakai feature code, mode wajib di-set manual:

curl -X POST http://localhost:3000/transform \
  -d '{"projectId":"x","mode":"SNR_DB","agent":"claude","prompt":"add migration","projectPath":"/project"}'

| Mode | Kapan Dipakai | |---|---| | SNR_CODE | Task kompleks, review, arsitektur | | JNR_CODE | Task simpel, quick fix, execute-only | | SNR_DB | Perubahan database, migration | | ORC | Breakdown task besar ke sub-task |

5. Workflow CRUD

# Buat workflow dengan mode + feature code
curl -X POST http://localhost:3000/workflow \
  -d '{
    "projectId": "my-project",
    "name": "deploy",
    "steps_json": "[\"git pull\", \"npm build\"]",
    "mode": "JNR_CODE",
    "feature_code": "BF"
  }'

# List workflows
curl http://localhost:3000/workflow/my-project

# Detail workflow
curl http://localhost:3000/workflow/my-project/deploy

6. Auto-Commit (Perubahan Model)

Setelah model selesai membuat/mengubah file, commit otomatis dengan pesan minimal-token:

# Via CLI (auto-detect dari git status)
npx pinisi-light commit
# → Committed a1b2c3d: chore: 3f (1c 2u)

# Via API — batch commit per file list
curl -X POST http://localhost:3000/commit \
  -H "Content-Type: application/json" \
  -d '{
    "projectPath": "/path/to/project",
    "mode": "batch",
    "files": [
      {"path": "src/auth.ts", "action": "create"},
      {"path": "src/login.ts", "action": "update"}
    ]
  }'

# Via API — auto-detect dari git status
curl -X POST http://localhost:3000/commit \
  -H "Content-Type: application/json" \
  -d '{"projectPath": "/path/to/project", "mode": "auto"}'

Mode commit: | Mode | Behaviour | |---|---| | per-file | 1 commit per file, pesan: create: src/foo.ts | | batch | 1 commit untuk semua file, pesan: chore: 3f (1c 2u) | | auto | Detect dari git status --porcelain, lalu batch commit |

7. Arsipkan CC_LOG

# Mingguan ritual: arsipkan log lama
curl -X POST http://localhost:3000/compact \
  -d '{"projectId":"my-project","projectPath":"/path/to/project"}'

8. Golden Output

npx pinisi-light golden add
# Wizard tanya: project path, workflow name, model source, golden output

9. Token Status

curl "http://localhost:3000/token-status?projectId=my-project&since=2026-05-01T00:00:00Z"

Token Budget Gate

Prompt yang terlalu panjang / "halu" (>8000 token) di-reject otomatis:

{
  "statusCode": 413,
  "error": "Prompt too large",
  "tokenEstimate": 12000,
  "suggestion": "Split task into smaller pieces or use shorter prompt."
}

Solusi: pakai feature code (NF/BF/DA/AS) atau pecah task jadi lebih kecil.

CLI Commands

npx pinisi-light init          # Initialize project + preset workflows
npx pinisi-light ask           # Interactive transform (no curl!)
npx pinisi-light commit        # Auto-commit staged changes (minimal messages)
npx pinisi-light golden add    # Add golden output
npx pinisi-light install <agent>  # Install single agent adapter

API Reference

POST /transform

Transform prompt sebelum kirim ke LLM.

Request:

{
  "projectId": "my-project",
  "mode": "SNR_CODE",
  "agent": "claude",
  "prompt": "NF: buat login",
  "projectPath": "/abs/path/to/project",
  "workflowName": "deploy"
}

Response:

{
  "transformId": "uuid",
  "finalPrompt": "<persona + context + task>",
  "tokenEstimate": 1234,
  "goldenPath": "/path/.ai/workflows/deploy.golden.md",
  "cacheHit": false,
  "warnings": []
}

POST /validate

Validasi response LLM (opsional).

Request:

{
  "transformId": "uuid",
  "response": "<output dari LLM>"
}

Response:

{
  "score": 0.85,
  "passed": true,
  "reason": "matched-golden",
  "suggestion": null
}

POST /compact

Arsipkan CC_LOG lama ke DB + update CURRENT_STATE.

Request:

{
  "projectId": "my-project",
  "projectPath": "/abs/path/to/project"
}

POST /workflow

Buat custom workflow dengan mode & feature_code.

Request:

{
  "projectId": "my-project",
  "name": "deploy",
  "steps_json": "[\"git pull\", \"npm build\"]",
  "mode": "JNR_CODE",
  "feature_code": "BF"
}

GET /workflow/:projectId

List workflows.

GET /workflow/:projectId/:name

Detail workflow.

POST /commit

Auto-commit file perubahan model dengan pesan minimal-token.

Request:

{
  "projectPath": "/abs/path/to/project",
  "mode": "batch",
  "files": [
    {"path": "src/auth.ts", "action": "create"},
    {"path": "src/login.ts", "action": "update"}
  ]
}

Response:

{
  "mode": "batch",
  "commits": [
    {"hash": "a1b2c3d", "message": "chore: 2f (1c 1u)"}
  ]
}

GET /token-status

Statistik token transform.

Query: ?projectId=my-project&since=2026-05-01T00:00:00Z

GET /health

Healthcheck.

Integrasi per Coding Agent

Prinsip: MCP Light adalah prompt processor. Dia tidak memanggil LLM — kamu (coding agent) yang memanggil LLM. Jadi enforcement ada di sisi agent: adapter file + habit.

Claude Code

Claude Code (terutama versi desktop/IDE) bisa membaca file di .claude/agents/*.md sebagai system instructions.

1. Install adapter:

   npx pinisi-light init
   # Install Claude Code? y

2. File .claude/agents/pinisi-light.md sudah berisi instruksi wajib. Claude Code akan membacanya setiap sesi.

3. Workflow wajib sebelum setiap prompt:

   # Transform dulu
   npx pinisi-light transform \
     --prompt "NF: buat fitur login" \
     --agent claude --project-id my-project --project-path .
   
   # Copy finalPrompt ke Claude Code
   # Setelah selesai → auto-commit
   npx pinisi-light commit

Codex (OpenAI Codex CLI)

Codex CLI tidak punya auto-read context file. Solusi: wrapper script atau manual curl.

1. Install adapter:

   npx pinisi-light init
   # Install Codex? y

2. File .codex/agents/pinisi-light.md berisi instruksi. Copy-paste ke Codex sebagai system instruction, atau baca sebelum sesi.

3. Workflow wajib (gunakan pinisi-light transform sebagai pre-processor):

   # 1. Transform
   final=$(npx pinisi-light transform --raw \
     --prompt "BF: fix null pointer" \
     --agent codex --project-id my-project --project-path .)
   
   # 2. Pipe ke Codex (atau copy-paste manual)
   echo "$final" | codex
   
   # 3. Auto-commit setelah selesai
   npx pinisi-light commit

Kimi Code CLI

Kimi CLI membaca folder .kimi/ sebagai context. File .kimi/pinisi-light.md otomatis tersedia sebagai reference.

1. Install adapter:

   npx pinisi-light init
   # Install Kimi CLI? y

2. Workflow wajib (sama seperti Codex — CLI-based jadi pakai wrapper):

   # 1. Transform
   final=$(npx pinisi-light transform --raw \
     --prompt "DA: analisis performa query" \
     --agent kimi --project-id my-project --project-path .)
   
   # 2. Copy ke clipboard atau pipe ke Kimi
   echo "$final" | xclip -selection clipboard
   # lalu paste ke Kimi CLI
   
   # 3. Auto-commit setelah selesai
   npx pinisi-light commit

Antigravity IDE

Antigravity IDE membaca .antigravity/ folder. Instruksi di .antigravity/pinisi-light.md tersedia sebagai context.

1. Install adapter:

   npx pinisi-light init
   # Install Antigravity IDE? y

2. Baca file .antigravity/pinisi-light.md sebelum mulai sesi di IDE.

3. Workflow wajib (IDE-based, lebih fleksibel):

   # Transform via CLI
   npx pinisi-light transform --raw \
     --prompt "NF: buat dashboard admin" \
     --agent antigravity --project-id my-project --project-path .
   # Copy finalPrompt, paste ke chat IDE
   
   # Setelah selesai coding → auto-commit
   npx pinisi-light commit

🎯 Shortcut: Shell Alias (Rekomendasi)

Agar workflow benar-benar "wajib" dan tidak terlewat, buat shell alias:

# ~/.bashrc atau ~/.zshrc
alias plx='pinisi-light transform --project-id my-project --project-path .'
alias plc='pinisi-light commit'

Penggunaan:

# Transform + copy ke clipboard
plx --agent kimi --prompt "NF: buat fitur X" --raw | xclip -selection clipboard
# lalu paste ke agent

# Setelah selesai
plc

Troubleshooting

| Masalah | Penyebab | Solusi | |---|---|---| | better-sqlite3 native error | Node.js version mismatch | npm rebuild | | Wizard install 0 agent | Tidak pencet y/n di confirm | Re-run, ketik y untuk agent yang dipilih | | 404 saat validate | transformId salah | Pastikan transformId dari response /transform | | 410 Gone | Session expired (>1 jam) | Ulangi /transform | | 413 Prompt too large | Prompt > 8000 token | Pakai feature code (NF/BF/DA/AS) atau pecah task | | score < 0.8 | Golden mismatch | Edit golden file atau ganti model | | cacheHit selalu false | CURRENT_STATE.md berubah | Normal — auto-invalidate | | Workflow FK error | Project belum terdaftar | Jalankan pinisi-light init dulu | | Cannot open database | Folder data/ belum ada | Fixed — auto-create folder saat init DB |

Stack

• TypeScript ESM + Fastify
• better-sqlite3 (sync, no ORM)
• zod (validasi)
• tiktoken (estimasi token)
• string-similarity (output validator)
• commander + @inquirer/prompts (CLI wizard)
• vitest (test)
• PM2 (deploy)

Test

npm test        # vitest run
npm run build   # tsc + copy schema.sql

Changelog

Lihat CHANGELOG.md untuk riwayat lengkap.

Highlights:

• v0.2.0 — Auto-Commit (pinisi-light commit, POST /commit), pesan minimal-token per file
• v0.1.3 — Feature Codes (NF/BF/DA/AS), pinisi-light ask, Token Budget Gate, Workflow Mode Lock
• v0.1.2 — Token Status, Workflow CRUD + Injection
• v0.1.1 — CLI Wizard (init, install, golden), Adapter Templates
• v0.1.0 — Skeleton, Core API, Prompt Compactor, Validator, Memory Bridge, Persona Modes