base-api-scramble-mcp 1.0.0

package/index.js

@@ -0,0 +1,968 @@
+#!/usr/bin/env node
+
+/**
+ * MCP Server — Base API Scramble
+ * Laravel API Knowledge Base untuk AI (Claude, Cursor, Copilot, dll)
+ *
+ * Tools:
+ *  - get_starting_point      → Kickoff guide, quick start, stack, konvensi wajib
+ *  - get_architecture        → Arsitektur lengkap, flow request, pattern CRUD
+ *  - get_structure           → Struktur direktori project
+ *  - search_docs             → Full-text search di semua docs
+ *  - get_doc                 → Baca 1 doc file lengkap
+ *  - list_docs               → Daftar semua docs yang tersedia
+ *  - get_conventions         → Konvensi & aturan wajib (model, migration, controller, dll)
+ *  - get_commands            → Referensi artisan gc commands
+ *  - get_api_response_format → Format response API standar
+ *  - get_query_params        → Query parameter yang tersedia
+ *  - get_file_service        → Cara pakai FileService (upload/delete file)
+ *  - get_export_guide        → Excel export system
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { readFileSync, existsSync, readdirSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+// ─────────────────────────────────────────────
+// Resolve docs path
+// ─────────────────────────────────────────────
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DOCS_PATH = join(__dirname, "docs");
+
+// ─────────────────────────────────────────────
+// Helper: baca file doc
+// ─────────────────────────────────────────────
+function readDoc(filename) {
+  const filePath = join(DOCS_PATH, filename);
+  if (!existsSync(filePath)) {
+    return `❌ File tidak ditemukan: ${filename}`;
+  }
+  return readFileSync(filePath, "utf-8");
+}
+
+// ─────────────────────────────────────────────
+// Helper: list semua doc files
+// ─────────────────────────────────────────────
+function listDocFiles() {
+  if (!existsSync(DOCS_PATH)) return [];
+  return readdirSync(DOCS_PATH).filter((f) => f.endsWith(".md"));
+}
+
+// ─────────────────────────────────────────────
+// Helper: search di semua docs
+// ─────────────────────────────────────────────
+function searchDocs(query) {
+  const files = listDocFiles();
+  const queryLower = query.toLowerCase();
+  const results = [];
+
+  for (const file of files) {
+    const content = readDoc(file);
+    const lines = content.split("\n");
+    const matches = [];
+
+    lines.forEach((line, idx) => {
+      if (line.toLowerCase().includes(queryLower)) {
+        // ambil context 1 baris sebelum & sesudahnya
+        const from = Math.max(0, idx - 1);
+        const to = Math.min(lines.length - 1, idx + 1);
+        matches.push({
+          line: idx + 1,
+          context: lines.slice(from, to + 1).join("\n"),
+        });
+      }
+    });
+
+    if (matches.length > 0) {
+      results.push({
+        file,
+        match_count: matches.length,
+        matches: matches.slice(0, 5), // max 5 matches per file
+      });
+    }
+  }
+
+  return results;
+}
+
+// ─────────────────────────────────────────────
+// Buat MCP Server
+// ─────────────────────────────────────────────
+const server = new McpServer({
+  name: "base-api-scramble",
+  version: "1.0.0",
+});
+
+// ══════════════════════════════════════════════
+// TOOL: get_starting_point
+// ══════════════════════════════════════════════
+server.tool(
+  "get_starting_point",
+  "Dapatkan kickoff guide lengkap: quick start, tech stack, arsitektur, konvensi wajib, dan langkah memulai project baru dari base-api-scramble. GUNAKAN INI PERTAMA KALI saat mulai kerja di project ini.",
+  {},
+  async () => {
+    const content = readDoc("starting_point.md");
+    return {
+      content: [
+        {
+          type: "text",
+          text: content,
+        },
+      ],
+    };
+  }
+);
+
+// ══════════════════════════════════════════════
+// TOOL: get_architecture
+// ══════════════════════════════════════════════
+server.tool(
+  "get_architecture",
+  "Dapatkan panduan arsitektur lengkap: flow request, 5 core components, dua workflow (Migration-First & Fields-First), pattern Model/Query/Controller/FormRequest, dan aturan AI. Ideal untuk memahami cara membuat fitur baru.",
+  {},
+  async () => {
+    const content = readDoc("AI-GUIDE-COMPLETE.md");
+    return {
+      content: [
+        {
+          type: "text",
+          text: content,
+        },
+      ],
+    };
+  }
+);
+
+// ══════════════════════════════════════════════
+// TOOL: get_structure
+// ══════════════════════════════════════════════
+server.tool(
+  "get_structure",
+  "Dapatkan struktur direktori lengkap project base-api-scramble: semua folder, file penting, dan penjelasannya.",
+  {},
+  async () => {
+    const content = readDoc("STRUCTURE.md");
+    return {
+      content: [
+        {
+          type: "text",
+          text: content,
+        },
+      ],
+    };
+  }
+);
+
+// ══════════════════════════════════════════════
+// TOOL: list_docs
+// ══════════════════════════════════════════════
+server.tool(
+  "list_docs",
+  "Tampilkan daftar semua file dokumentasi yang tersedia di knowledge base ini.",
+  {},
+  async () => {
+    const files = listDocFiles();
+
+    const descriptions = {
+      "starting_point.md":
+        "Kickoff guide: quick start, tech stack, konvensi, langkah project baru",
+      "AI-GUIDE-COMPLETE.md":
+        "Panduan AI lengkap: arsitektur, pattern code, commands, aturan AI",
+      "STRUCTURE.md": "Struktur direktori lengkap seluruh project",
+      "README.md": "Overview project dengan contoh workflow dan fitur",
+      "EXCEL-EXPORT-SERVICE.md": "Dokumentasi Excel export service (PhpSpreadsheet)",
+      "EXPORT-DATA-PROVIDERS.md": "Pattern Data Provider untuk export Excel",
+      "EXPORT-TEMPLATES.md": "Template Excel: multi-sheet, multi-table, styling",
+      "LARAVEL-API-TEST.md": "Panduan testing Laravel API",
+      "MAKE-EXPORT-EXCEL-COMMAND.md": "Command generator untuk Excel export",
+    };
+
+    const list = files
+      .map((f) => {
+        const desc = descriptions[f] || "Dokumentasi tambahan";
+        return `• **${f}** — ${desc}`;
+      })
+      .join("\n");
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: `# Daftar Dokumentasi Base API Scramble\n\nTotal: ${files.length} files\n\n${list}\n\n---\nGunakan tool \`get_doc\` dengan nama file untuk membaca isi lengkapnya.`,
+        },
+      ],
+    };
+  }
+);
+
+// ══════════════════════════════════════════════
+// TOOL: get_doc
+// ══════════════════════════════════════════════
+server.tool(
+  "get_doc",
+  "Baca isi lengkap dari satu file dokumentasi. Gunakan list_docs terlebih dahulu untuk melihat file yang tersedia.",
+  {
+    filename: z
+      .string()
+      .describe(
+        'Nama file doc yang ingin dibaca. Contoh: "EXCEL-EXPORT-SERVICE.md"'
+      ),
+  },
+  async ({ filename }) => {
+    const content = readDoc(filename);
+    return {
+      content: [
+        {
+          type: "text",
+          text: content,
+        },
+      ],
+    };
+  }
+);
+
+// ══════════════════════════════════════════════
+// TOOL: search_docs
+// ══════════════════════════════════════════════
+server.tool(
+  "search_docs",
+  "Cari keyword/topik di semua file dokumentasi. Berguna untuk menemukan informasi spesifik tentang fitur, class, atau konvensi tertentu.",
+  {
+    query: z
+      .string()
+      .describe(
+        'Keyword yang dicari. Contoh: "FileService", "baseQuery", "uuid", "gc:from-migration"'
+      ),
+  },
+  async ({ query }) => {
+    const results = searchDocs(query);
+
+    if (results.length === 0) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `❌ Tidak ditemukan hasil untuk: "${query}"\n\nCoba keyword lain atau gunakan \`list_docs\` untuk melihat topik yang tersedia.`,
+          },
+        ],
+      };
+    }
+
+    const totalMatches = results.reduce((acc, r) => acc + r.match_count, 0);
+    let output = `# Hasil Pencarian: "${query}"\n\nDitemukan **${totalMatches} baris** di **${results.length} file**\n\n---\n\n`;
+
+    for (const result of results) {
+      output += `## 📄 ${result.file} (${result.match_count} match)\n\n`;
+      for (const match of result.matches) {
+        output += `**Baris ${match.line}:**\n\`\`\`\n${match.context}\n\`\`\`\n\n`;
+      }
+      output += "---\n\n";
+    }
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: output,
+        },
+      ],
+    };
+  }
+);
+
+// ══════════════════════════════════════════════
+// TOOL: get_conventions
+// ══════════════════════════════════════════════
+server.tool(
+  "get_conventions",
+  "Dapatkan konvensi & aturan wajib project: cara buat Model (UUID + Queryable), Migration, Query Class, Controller, FormRequest, dan Route. Gunakan ini sebelum membuat kode baru.",
+  {},
+  async () => {
+    const text = `# Konvensi & Pattern Wajib — Base API Scramble
+
+## ⚡ Flow Request
+\`\`\`
+Request → Route → FormRequest (validasi) → Controller → Query Class → Model → ApiResponse
+\`\`\`
+
+---
+
+## 1. Model
+- **WAJIB** pakai \`HasUuids\` (UUID sebagai primary key, BUKAN auto-increment)
+- **WAJIB** pakai \`Queryable\` trait
+
+\`\`\`php
+use App\\Traits\\Queryable;
+use Illuminate\\Database\\Eloquent\\Concerns\\HasUuids;
+
+class NamaModel extends Model
+{
+    use HasFactory, HasUuids, Queryable;
+
+    protected $fillable = ['field1', 'field2'];
+    protected $searchable = ['field1'];            // kolom untuk ?search=
+    protected $relationIncludes = ['relation1'];   // relasi untuk ?include=
+}
+\`\`\`
+
+---
+
+## 2. Migration
+- **WAJIB** pakai UUID primary key
+
+\`\`\`php
+Schema::create('table_name', function (Blueprint $table) {
+    $table->uuid('id')->primary();
+    $table->string('name');
+    $table->foreignUuid('parent_id')->constrained('parents')->cascadeOnDelete();
+    $table->timestamps();
+});
+\`\`\`
+
+---
+
+## 3. Query Class
+- Lokasi: \`app/Queries/NamaModelQuery.php\`
+- Extends \`QueryBuilder\` dari Spatie
+
+\`\`\`php
+class NamaModelQuery extends QueryBuilder
+{
+    public function __construct()
+    {
+        parent::__construct(NamaModel::query());
+        $this
+            ->allowedIncludes([AllowedInclude::relationship('relation1')])
+            ->allowedFilters([
+                AllowedFilter::exact('id'),
+                AllowedFilter::partial('name'),
+            ]);
+    }
+}
+\`\`\`
+
+---
+
+## 4. Controller
+- Extends \`Controller\` (sudah include \`ApiResponse\` + \`baseQuery()\`)
+- \`baseQuery()\` menerima **1 argumen** saja: instance Query class
+
+\`\`\`php
+class NamaModelController extends Controller
+{
+    public function index(IndexRequest $request)
+    {
+        return $this->responseData(
+            $this->baseQuery(new NamaModelQuery()),
+            'NamaModel retrieved successfully'
+        );
+    }
+
+    public function show(NamaModel $namaModel)
+    {
+        return $this->responseSuccess($namaModel, 'NamaModel retrieved successfully');
+    }
+
+    public function store(NamaModelStoreRequest $request)
+    {
+        $model = NamaModel::create($request->validated());
+        return $this->responseCreated($model, 'NamaModel created successfully');
+    }
+
+    public function update(NamaModelUpdateRequest $request, NamaModel $namaModel)
+    {
+        $namaModel->update($request->validated());
+        return $this->responseSuccess($namaModel, 'NamaModel updated successfully');
+    }
+
+    public function destroy(NamaModel $namaModel)
+    {
+        $namaModel->delete();
+        return $this->responseDeleted('NamaModel deleted successfully');
+    }
+}
+\`\`\`
+
+---
+
+## 5. FormRequest
+- Gunakan \`@example\` PHPDoc agar Scramble auto-generate contoh di API docs
+
+\`\`\`php
+public function rules(): array
+{
+    return [
+        /** @example John Doe */
+        'name'  => 'required|string|max:255',
+        /** @example john@example.com */
+        'email' => 'required|email|unique:users,email',
+    ];
+}
+\`\`\`
+
+---
+
+## 6. Route
+- Tambahkan di \`routes/api_v1.php\` di dalam group \`auth:sanctum\`
+
+\`\`\`php
+Route::apiResource('nama-model', Controllers\\NamaModelController::class);
+\`\`\`
+
+---
+
+## 7. Naming Convention
+| Item | Convention | Contoh |
+|---|---|---|
+| Model | Singular PascalCase | \`ProductCategory\` |
+| Table | Plural snake_case (auto) | \`product_categories\` |
+| Controller | \`{Model}Controller\` | \`ProductCategoryController\` |
+| Query | \`{Model}Query\` | \`ProductCategoryQuery\` |
+| Request | \`{Model}StoreRequest\` | \`ProductCategoryStoreRequest\` |
+| Route | Kebab plural | \`product-categories\` |
+
+---
+
+## ❌ JANGAN PERNAH
+- Generate CRUD manual — **selalu gunakan \`gc\` command**
+- Pakai \`id()->primary()\` — harus \`uuid('id')->primary()\`
+- Pass lebih dari 1 argumen ke \`baseQuery()\`
+- Buat migration tanpa UUID primary key
+`;
+
+    return {
+      content: [{ type: "text", text }],
+    };
+  }
+);
+
+// ══════════════════════════════════════════════
+// TOOL: get_commands
+// ══════════════════════════════════════════════
+server.tool(
+  "get_commands",
+  "Referensi lengkap artisan GC commands: gc, gc:from-migration, gc:wizard. Beserta contoh penggunaan dan field type mapping.",
+  {},
+  async () => {
+    const text = `# Artisan GC Commands — Referensi Lengkap
+
+## Perintah Utama
+
+\`\`\`bash
+# ─── Fields-First ─────────────────────────────────────────────
+php artisan gc Product --fields="name,price:decimal,stock:integer"
+php artisan gc Product --fields="name,price:decimal,image:file" --belongsTo="Category,Brand"
+php artisan gc Product --fields="name,price:decimal" --hasMany="Review"
+
+# ─── Migration-First (Recommended untuk schema kompleks) ───────
+php artisan gc:from-migration products     # ← nama tabel (plural)
+
+# ─── Interactive Wizard ────────────────────────────────────────
+php artisan gc:wizard Product
+
+# ─── Extras ───────────────────────────────────────────────────
+php artisan gc Product --fields="name,price" --preview     # preview tanpa generate
+php artisan gc Product --fields="name,price" --migration   # generate migration only
+php artisan gc:help
+
+# ─── Setelah generate ─────────────────────────────────────────
+php artisan migrate
+\`\`\`
+
+---
+
+## File yang di-Generate (6 files)
+\`\`\`
+app/Models/Product.php
+app/Queries/ProductQuery.php
+app/Http/Controllers/Api/V1/ProductController.php
+app/Http/Requests/Api/V1/ProductStoreRequest.php
+app/Http/Requests/Api/V1/ProductUpdateRequest.php
+database/migrations/xxxx_create_products_table.php
+routes/api_v1.php  ← route ditambah otomatis
+\`\`\`
+
+---
+
+## Field Type Mapping (auto-detect dari nama field)
+
+| Nama Field | Type |
+|---|---|
+| nama, name, title, judul | \`string\` |
+| deskripsi, description, content, konten | \`text\` |
+| harga, price, cost, biaya | \`decimal\` |
+| stok, stock, quantity, jumlah | \`integer\` |
+| gambar, image, photo, foto, file, dokumen | \`file\` |
+| is_*, aktif, active, published | \`boolean\` |
+| *_at, tanggal, date | \`datetime\` |
+| slug | \`string\` |
+
+**Tersedia juga:** \`string\`, \`text\`, \`integer\`/\`int\`, \`decimal\`/\`float\`, \`boolean\`/\`bool\`, \`date\`, \`datetime\`, \`file\`/\`image\`
+
+---
+
+## Decision Logic
+
+- User sebut "migration" ATAU schema > 5 field → **Workflow A** (\`gc:from-migration\`)
+- Fields < 5 dan jelas → **Workflow B** (\`gc\`)
+- Tidak jelas / butuh guidance → \`gc:wizard\`
+
+---
+
+## Contoh Cepat
+
+\`\`\`bash
+# Simple product
+php artisan gc Product --fields="name,price:decimal,stock:integer" && php artisan migrate
+
+# Product dengan file upload & relasi
+php artisan gc Product --fields="name,price:decimal,image:file" --belongsTo="Category,Brand" && php artisan migrate
+
+# Dari migration yang sudah ada
+php artisan gc:from-migration products && php artisan migrate
+
+# Indonesian fields (auto-translate)
+php artisan gc Produk --fields="nama,harga:decimal,stok:integer,gambar:file"
+# → name, price, stock, image
+\`\`\`
+`;
+
+    return {
+      content: [{ type: "text", text }],
+    };
+  }
+);
+
+// ══════════════════════════════════════════════
+// TOOL: get_api_response_format
+// ══════════════════════════════════════════════
+server.tool(
+  "get_api_response_format",
+  "Dapatkan format response API standar (ApiResponse trait) beserta semua method yang tersedia dan contoh output JSON-nya.",
+  {},
+  async () => {
+    const text = `# API Response Format — Base API Scramble
+
+## Methods Tersedia
+
+\`\`\`php
+// Di dalam Controller:
+$this->responseSuccess($data, $message, $statusCode = 200)
+$this->responseData($data, $message)      // auto-detect paginator → tambah key pagination
+$this->responseCreated($data, $message)   // status 201
+$this->responseDeleted($message)          // status 200, data: null
+$this->responseError($message, $code = 400)
+\`\`\`
+
+---
+
+## Format JSON
+
+### ✅ Success (responseSuccess)
+\`\`\`json
+{
+  "success": true,
+  "message": "Product retrieved successfully",
+  "code": 200,
+  "data": { "id": "uuid", "name": "iPhone 14" }
+}
+\`\`\`
+
+### ✅ Created (responseCreated)
+\`\`\`json
+{
+  "success": true,
+  "message": "Product created successfully",
+  "code": 201,
+  "data": { "id": "uuid", "name": "iPhone 14" }
+}
+\`\`\`
+
+### ✅ Paginated (responseData dengan paginator)
+\`\`\`json
+{
+  "success": true,
+  "message": "Products retrieved successfully",
+  "code": 200,
+  "data": [ { "id": "uuid", "name": "iPhone 14" } ],
+  "pagination": {
+    "current_page": 1,
+    "from": 1,
+    "to": 10,
+    "total": 50,
+    "per_page": 10,
+    "last_page": 5,
+    "next_page": 2,
+    "prev_page": null,
+    "path": "http://localhost:8000/api/v1/products"
+  }
+}
+\`\`\`
+
+### ✅ Deleted (responseDeleted)
+\`\`\`json
+{
+  "success": true,
+  "message": "Product deleted successfully",
+  "code": 200,
+  "data": null
+}
+\`\`\`
+
+### ❌ Error (responseError)
+\`\`\`json
+{
+  "success": false,
+  "message": "Validation failed",
+  "code": 422
+}
+\`\`\`
+
+---
+
+## Lokasi File
+\`app/Helpers/ApiResponse.php\`
+`;
+
+    return {
+      content: [{ type: "text", text }],
+    };
+  }
+);
+
+// ══════════════════════════════════════════════
+// TOOL: get_query_params
+// ══════════════════════════════════════════════
+server.tool(
+  "get_query_params",
+  "Dapatkan daftar lengkap query parameter yang tersedia di semua endpoint index: search, filter, sort, include, paginate, dan cara penggunaannya.",
+  {},
+  async () => {
+    const text = `# Query Parameters — Base API Scramble
+
+Semua endpoint \`index\` otomatis support parameter berikut:
+
+## Parameter Lengkap
+
+| Parameter | Contoh | Keterangan |
+|---|---|---|
+| \`search\` | \`?search=keyword\` | Full-text search di kolom \`$searchable\` model |
+| \`filter[kolom]\` | \`?filter[name]=john\` | Filter per kolom (exact/partial sesuai Query class) |
+| \`filter[status]\` | \`?filter[status]=active\` | Filter exact |
+| \`sort_by\` | \`?sort_by=name\` | Kolom untuk sorting |
+| \`sort_order\` | \`?sort_order=asc\` | \`asc\` atau \`desc\` (default: \`desc\`) |
+| \`include\` | \`?include=category,brand\` | Eager load relasi (dari \`$relationIncludes\`) |
+| \`paginate\` | \`?paginate=20\` | Items per page (aktifkan pagination) |
+| \`paginate=false\` | \`?paginate=false\` | Ambil semua data tanpa pagination |
+| \`page\` | \`?page=2\` | Nomor halaman |
+| \`first\` | \`?first=true\` | Ambil hanya 1 data pertama |
+| \`fields[model]\` | \`?fields[products]=id,name\` | Pilih kolom yang dikembalikan |
+
+---
+
+## Contoh Kombinasi
+
+\`\`\`
+GET /api/v1/products?search=iphone&filter[category_id]=uuid&sort_by=price&sort_order=asc&paginate=15&include=category
+
+GET /api/v1/users?search=john&filter[status]=active&include=roles,permissions&paginate=25
+
+GET /api/v1/products?paginate=false    # semua data, tanpa pagination
+
+GET /api/v1/products?first=true        # hanya 1 data pertama
+\`\`\`
+
+---
+
+## Sumber Parameter
+
+| Parameter | Dihandle oleh |
+|---|---|
+| \`search\`, \`sort_by\`, \`sort_order\`, \`paginate\`, \`first\` | \`baseQuery()\` di Controller (via \`Queryable\` trait) |
+| \`filter[]\`, \`include\`, \`sort\`, \`fields[]\` | Spatie QueryBuilder di Query class |
+
+---
+
+## Default Behaviour
+- Pagination default: **10 per page**
+- Sort default: **created_at DESC**
+- Tanpa \`?paginate\`: data dikembalikan tanpa pagination (array biasa)
+`;
+
+    return {
+      content: [{ type: "text", text }],
+    };
+  }
+);
+
+// ══════════════════════════════════════════════
+// TOOL: get_file_service
+// ══════════════════════════════════════════════
+server.tool(
+  "get_file_service",
+  "Panduan cara menggunakan FileService untuk upload file dengan kompresi otomatis, delete file, dan integrasi ke Controller.",
+  {},
+  async () => {
+    const text = `# FileService — Panduan Upload & Delete File
+
+## Lokasi
+\`app/Services/FileService.php\`
+
+---
+
+## Upload File (saveFileComplete)
+
+\`\`\`php
+use App\\Services\\FileService;
+
+class ProductController extends Controller
+{
+    private FileService $fileService;
+
+    public function __construct()
+    {
+        $this->fileService = new FileService();
+    }
+
+    public function store(ProductStoreRequest $request)
+    {
+        $data = $request->validated();
+
+        if ($request->hasFile('image')) {
+            $file = $this->fileService->saveFileComplete(
+                file: $request->file('image'),
+                folder: 'products',              // disimpan di storage/app/products/
+                fileName: 'product_' . time(),   // nama file (tanpa ekstensi)
+                is_compressed: true,             // kompresi otomatis (jpg/jpeg/png/webp)
+            );
+            $data['image'] = $file['name'];      // simpan nama file ke DB
+        }
+
+        return $this->responseCreated(Product::create($data), 'Product created');
+    }
+}
+\`\`\`
+
+**Return value \`saveFileComplete()\`:**
+\`\`\`php
+[
+    'name' => 'product_1234567890.jpg',   // nama file yang disimpan
+    'path' => '/storage/products/...',    // path lengkap
+    'size' => 204800,                     // ukuran dalam bytes
+]
+\`\`\`
+
+---
+
+## Delete File
+
+\`\`\`php
+// Hapus 1 file
+$this->fileService->deleteFile(
+    folder: 'products',
+    fileName: $product->image    // nama file yang tersimpan di DB
+);
+\`\`\`
+
+---
+
+## Update File (pattern lengkap)
+
+\`\`\`php
+public function update(ProductUpdateRequest $request, Product $product)
+{
+    $data = $request->validated();
+
+    // Case 1: Field image di-set null → hapus file lama
+    if ($request->input('image') == null && $product->image) {
+        $this->fileService->deleteFile(folder: 'products', fileName: $product->image);
+        $data['image'] = '';
+    }
+
+    // Case 2: Ada file baru → hapus lama, simpan baru
+    if ($request->hasFile('image')) {
+        if ($product->image) {
+            $this->fileService->deleteFile(folder: 'products', fileName: $product->image);
+        }
+        $file = $this->fileService->saveFileComplete(
+            file: $request->file('image'),
+            folder: 'products',
+            fileName: 'product_' . time(),
+            is_compressed: true,
+        );
+        $data['image'] = $file['name'];
+    }
+
+    $product->update($data);
+    return $this->responseSuccess($product, 'Product updated');
+}
+\`\`\`
+
+---
+
+## Accessor untuk URL (di Model)
+
+\`\`\`php
+protected $appends = ['image_url'];
+
+public function getImageUrlAttribute(): ?string
+{
+    return $this->image
+        ? asset('uploads/products/' . $this->image)
+        : null;
+}
+\`\`\`
+
+---
+
+## Storage Support
+- **Local:** \`storage/app/{folder}/\`
+- **S3:** \`filemanager/{folder}/\` (konfigurasi di \`.env\`)
+
+---
+
+## Kompresi Otomatis
+- Menggunakan **Imagick**
+- Support: \`jpg\`, \`jpeg\`, \`png\`, \`webp\`
+- Aktifkan: \`is_compressed: true\`
+`;
+
+    return {
+      content: [{ type: "text", text }],
+    };
+  }
+);
+
+// ══════════════════════════════════════════════
+// TOOL: get_export_guide
+// ══════════════════════════════════════════════
+server.tool(
+  "get_export_guide",
+  "Panduan sistem Excel export: BaseExport, Data Provider pattern, template multi-sheet/multi-table, dan konfigurasi di config/export_info.php.",
+  {},
+  async () => {
+    // Coba baca dari docs dulu, fallback ke summary
+    const files = ["EXCEL-EXPORT-SERVICE.md", "EXPORT-DATA-PROVIDERS.md"];
+    let content = "";
+
+    for (const f of files) {
+      const doc = readDoc(f);
+      if (!doc.startsWith("❌")) {
+        content += `\n\n---\n# ${f}\n\n${doc}`;
+      }
+    }
+
+    if (!content) {
+      content = `# Excel Export System — Base API Scramble
+
+## Overview
+System export Excel menggunakan **PhpSpreadsheet** dengan pattern **Data Provider**.
+
+## Komponen Utama
+- \`app/Exports/BaseExport.php\` — Abstract base class
+- \`app/Services/ExcelExportService.php\` — Service layer
+- \`config/export_info.php\` — Konfigurasi styling & metadata
+- Data Provider pattern (interface-based)
+
+## Generate Export Module
+\`\`\`bash
+php artisan make:export-excel NamaModule
+\`\`\`
+
+Gunakan \`get_doc\` dengan \`EXCEL-EXPORT-SERVICE.md\` untuk dokumentasi lengkap.
+`;
+    }
+
+    return {
+      content: [{ type: "text", text: content }],
+    };
+  }
+);
+
+// ══════════════════════════════════════════════
+// TOOL: get_auth_endpoints
+// ══════════════════════════════════════════════
+server.tool(
+  "get_auth_endpoints",
+  "Daftar endpoint autentikasi dan RBAC yang sudah tersedia: login, logout, profile, role, permission management.",
+  {},
+  async () => {
+    const text = `# Endpoint Bawaan — Base API Scramble
+
+## Authentication (Sanctum)
+| Method | Endpoint | Keterangan |
+|---|---|---|
+| POST | \`/api/v1/login\` | Login, dapat Bearer token |
+| POST | \`/api/v1/logout\` | Logout (auth required) |
+| GET | \`/api/v1/me\` | Profile user yang sedang login |
+| PUT | \`/api/v1/me\` | Update profile |
+| PUT | \`/api/v1/change-password\` | Ganti password |
+
+**Default credentials:**
+| Email | Password |
+|---|---|
+| \`admin@gmail.com\` | \`password\` |
+| \`dev@gotrasoft.com\` | \`gotradev\` |
+
+---
+
+## Role & Permission (Spatie RBAC)
+| Method | Endpoint | Keterangan |
+|---|---|---|
+| GET/POST/PUT/DELETE | \`/api/v1/role\` | CRUD Role |
+| GET/POST/PUT/DELETE | \`/api/v1/permission\` | CRUD Permission |
+| POST | \`/api/v1/user-role/attach\` | Assign role ke user |
+| POST | \`/api/v1/user-role/detach\` | Lepas role dari user |
+| POST | \`/api/v1/user-role/sync-roles\` | Sync roles user |
+| POST | \`/api/v1/user-role/sync-users\` | Sync users role |
+| POST | \`/api/v1/role-permission/attach\` | Assign permission ke role |
+| POST | \`/api/v1/role-permission/detach\` | Lepas permission dari role |
+| POST | \`/api/v1/role-permission/sync-permissions\` | Sync permissions role |
+| POST | \`/api/v1/role-permission/sync-roles\` | Sync roles permission |
+
+---
+
+## File Management
+| Method | Endpoint | Keterangan |
+|---|---|---|
+| GET/POST/PUT/DELETE | \`/api/v1/file\` | CRUD File (soft-delete) |
+| GET/POST/PUT/DELETE | \`/api/v1/folder\` | CRUD Folder |
+| POST | \`/api/v1/file/restore/{id}\` | Restore file yang di-soft-delete |
+
+---
+
+## Activity Log
+| Method | Endpoint | Keterangan |
+|---|---|---|
+| GET | \`/api/v1/log-activity\` | Lihat semua audit log |
+
+---
+
+## API Docs
+- **Scramble:** \`http://localhost:8000/docs/api\`
+- **Base URL:** \`http://localhost:8000/api/v1\`
+
+---
+
+## Headers Wajib
+\`\`\`
+Authorization: Bearer {token}
+Content-Type: application/json
+Accept: application/json
+\`\`\`
+`;
+
+    return {
+      content: [{ type: "text", text }],
+    };
+  }
+);
+
+// ─────────────────────────────────────────────
+// Start server
+// ─────────────────────────────────────────────
+const transport = new StdioServerTransport();
+await server.connect(transport);