base-api-scramble-mcp 1.0.0

package/README.md

@@ -0,0 +1,140 @@
+# 🚀 Base API Scramble — MCP Server
+
+MCP (Model Context Protocol) server yang expose seluruh dokumentasi **base-api-scramble** sebagai knowledge base untuk AI (Claude, Cursor, Copilot, dll).
+
+Dengan MCP ini, AI langsung paham:
+- Arsitektur & flow request project
+- Konvensi wajib (UUID, Queryable, ApiResponse)
+- Cara pakai artisan `gc` & `gc:from-migration`
+- Pattern Model / Query Class / Controller / FormRequest
+- FileService, Export Excel, Auth endpoints, dsb.
+
+---
+
+## 📦 Struktur
+
+```
+base-api-mcp/
+├── index.js          ← MCP Server utama
+├── package.json
+├── docs/             ← Copy dari base-api-scramble/docs/
+│   ├── starting_point.md
+│   ├── AI-GUIDE-COMPLETE.md
+│   ├── STRUCTURE.md
+│   ├── README.md
+│   ├── EXCEL-EXPORT-SERVICE.md
+│   ├── EXPORT-DATA-PROVIDERS.md
+│   ├── EXPORT-TEMPLATES.md
+│   ├── LARAVEL-API-TEST.md
+│   └── MAKE-EXPORT-EXCEL-COMMAND.md
+└── README.md
+```
+
+---
+
+## 🛠 Tools yang Tersedia
+
+| Tool | Deskripsi |
+|---|---|
+| `get_starting_point` | Kickoff guide: quick start, stack, konvensi — **mulai dari sini** |
+| `get_architecture` | Arsitektur lengkap, flow, pattern code |
+| `get_structure` | Struktur direktori project |
+| `get_conventions` | Aturan wajib: Model, Migration, Query, Controller, Route |
+| `get_commands` | Referensi artisan gc commands + field type mapping |
+| `get_api_response_format` | Format JSON response + semua method ApiResponse |
+| `get_query_params` | Semua query parameter (search, filter, sort, include, dll) |
+| `get_file_service` | Cara upload/delete file dengan FileService |
+| `get_export_guide` | Excel export system (PhpSpreadsheet + Data Provider) |
+| `get_auth_endpoints` | Endpoint auth, RBAC, file management bawaan |
+| `list_docs` | Daftar semua file doc yang tersedia |
+| `get_doc` | Baca isi lengkap 1 file doc |
+| `search_docs` | Full-text search di semua docs |
+
+---
+
+## ⚙️ Setup
+
+### 1. Install dependencies (sudah dilakukan)
+```bash
+cd /Users/sunarta25/gotra/CLI/base-api-mcp
+npm install
+```
+
+### 2. Tambahkan ke Claude Desktop
+
+Edit file: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "base-api-scramble": {
+      "command": "node",
+      "args": ["/Users/sunarta25/gotra/CLI/base-api-mcp/index.js"]
+    }
+  }
+}
+```
+
+> Jika sudah ada `mcpServers` lain, cukup tambahkan key `"base-api-scramble"` di dalam object yang sudah ada.
+
+### 3. Restart Claude Desktop
+
+Tutup & buka kembali Claude Desktop. MCP server akan aktif otomatis.
+
+---
+
+## ⚙️ Setup Cursor
+
+Edit `.cursor/mcp.json` di root project atau `~/.cursor/mcp.json` untuk global:
+
+```json
+{
+  "mcpServers": {
+    "base-api-scramble": {
+      "command": "node",
+      "args": ["/Users/sunarta25/gotra/CLI/base-api-mcp/index.js"]
+    }
+  }
+}
+```
+
+---
+
+## 🔄 Update Docs
+
+Jika docs di `base-api-scramble` diupdate, sync ulang dengan:
+
+```bash
+cp -r /Users/sunarta25/gotra/base-api-scramble/docs/* \
+      /Users/sunarta25/gotra/CLI/base-api-mcp/docs/
+```
+
+---
+
+## 🧪 Test Manual
+
+```bash
+cd /Users/sunarta25/gotra/CLI/base-api-mcp
+npm start
+```
+
+Server berjalan via **stdio** — digunakan oleh Claude/Cursor secara otomatis.
+
+---
+
+## 💡 Cara Pakai di Claude
+
+Setelah setup, Claude bisa langsung pakai tools ini. Contoh prompt:
+
+```
+Gunakan get_starting_point untuk memahami project, lalu buatkan module Product
+dengan fields: name, price, stock, image (file), category (relasi).
+```
+
+```
+Cari informasi tentang FileService menggunakan search_docs
+```
+
+```
+Tampilkan semua endpoint auth yang tersedia menggunakan get_auth_endpoints
+```

package/docs/AI-GUIDE-COMPLETE.md

@@ -0,0 +1,372 @@
+# AI GUIDE — Laravel Base API (Query Pattern + Scramble)
+
+**Stack:** Laravel 10.x · PHP 8.1+ · UUID primary keys
+**Path:** `~/gotra/base-api-scramble`
+
+**Core Dependencies:**
+| Package | Version | Purpose |
+|---|---|---|
+| Laravel Sanctum | ^3.3 | Auth (Bearer token) |
+| Spatie Permission | ^6.13 | RBAC |
+| Spatie QueryBuilder | ^6.3 | Filtering/sorting/includes |
+| Spatie Activity Log | ^4.9 | Audit trail |
+| Dedoc Scramble + Pro | ^0.12.35 + ^0.7.18 | Auto OpenAPI docs |
+
+---
+
+## ARCHITECTURE
+
+```
+FormRequest → Controller → Query Class → Model (Queryable trait) → ApiResponse
+```
+
+**5 core components:**
+1. **Query Class** (`App\Queries\*`) — extends Spatie QueryBuilder, defines `allowedFilters` & `allowedIncludes`
+2. **Queryable Trait** (`App\Traits\Queryable`) — auto-generates filters/sorts/fields from DB columns, provides `scopeSearch`
+3. **Controller** (`App\Http\Controllers\Api\V1\*`) — uses `baseQuery()` + ApiResponse methods
+4. **ApiResponse Trait** (`App\Helpers\ApiResponse`) — standardized JSON output
+5. **FileService** (`App\Services\FileService`) — upload/compress/delete files
+
+---
+
+## TWO WORKFLOWS
+
+### A. Migration-First (complex / AI-generated schema)
+```
+AI generates migration → User saves file → php artisan gc:from-migration {table} → php artisan migrate
+```
+
+### B. Fields-First (simple / quick)
+```
+php artisan gc {Model} --fields=field:type,... → php artisan migrate
+```
+
+**Decision logic:**
+- User menyebut "migration" OR schema kompleks → Workflow A
+- Fields < 5 dan jelas → Workflow B
+- Tidak jelas / > 5 fields → `gc:wizard {Model}`
+
+---
+
+## COMMANDS REFERENCE
+
+```bash
+# Fields-first
+php artisan gc Product --fields=name:string,price:decimal,stock:integer,image:file
+php artisan gc Product --fields=name,price:decimal --belongsTo=Category,Brand
+
+# Migration-first
+php artisan gc:from-migration products   # table name (plural)
+
+# Interactive
+php artisan gc:wizard Product
+
+# Extras
+php artisan gc Product --fields=name,price --preview    # preview only
+php artisan gc Product --fields=name,price --migration  # migration only
+php artisan gc:help
+php artisan migrate
+```
+
+---
+
+## FIELD TYPE MAPPING
+
+Auto-detect dari nama field (ID/EN):
+
+| Field | Type | Field | Type |
+|---|---|---|---|
+| nama, name, title, judul | `string` | gambar, image, photo, foto, file, dokumen | `file` |
+| deskripsi, description, content | `text` | is_*, aktif, published | `boolean` |
+| harga, price, cost, biaya | `decimal` | *_at, tanggal, date | `datetime` |
+| stok, stock, quantity, jumlah | `integer` | slug | `string` |
+
+**Indonesian → English:** nama→name, harga→price, stok→stock, gambar→image, foto→photo, deskripsi→description, judul→title, konten→content, tanggal→date, aktif→is_active
+
+---
+
+## GENERATED FILES (6 files)
+
+```
+app/
+├── Models/Product.php                         # HasUuids, Queryable, $fillable, $appends, $searchable
+├── Queries/ProductQuery.php                   # extends QueryBuilder, allowedFilters, allowedIncludes
+├── Http/Controllers/Api/V1/ProductController.php  # CRUD + FileService
+├── Http/Requests/Api/V1/ProductStoreRequest.php
+├── Http/Requests/Api/V1/ProductUpdateRequest.php
+database/migrations/xxxx_create_products_table.php
+# routes/api_v1.php — Route::apiResource('products', ProductController::class) auto-added
+```
+
+---
+
+## PATTERN REFERENCE
+
+### Model
+```php
+class Product extends Model
+{
+    use HasFactory, HasUuids, Queryable;
+
+    protected $fillable = ['name', 'price', 'stock', 'image', 'category_id'];
+    protected $appends  = ['image_url'];            // for file fields
+    protected array $searchable = ['name'];          // columns for ?search=
+    protected array $relationIncludes = ['category']; // for ?include=
+
+    public function category() { return $this->belongsTo(Category::class); }
+
+    public function getImageUrlAttribute()
+    {
+        return $this->image ? asset('uploads/products/' . $this->image) : null;
+    }
+}
+```
+
+### Query Class
+```php
+class ProductQuery extends QueryBuilder
+{
+    public function __construct()
+    {
+        parent::__construct(Product::query());
+        $this
+            ->allowedIncludes([AllowedInclude::relationship('category')])
+            ->allowedFilters([
+                AllowedFilter::exact('id'),
+                AllowedFilter::partial('name'),
+                AllowedFilter::exact('category_id'),
+            ]);
+    }
+}
+```
+
+### Controller
+```php
+class ProductController extends Controller
+{
+    private FileService $fileService;
+    public function __construct() { $this->fileService = new FileService(); }
+
+    // index — uses baseQuery() which reads request() internally
+    public function index(IndexRequest $request)
+    {
+        return $this->responseData(
+            $this->baseQuery(new ProductQuery()),
+            'Product retrieved successfully'
+        );
+    }
+
+    // show
+    public function show(Product $product)
+    {
+        return $this->responseSuccess($product, 'Product retrieved successfully');
+    }
+
+    // store
+    public function store(ProductStoreRequest $request)
+    {
+        $data = $request->validated();
+        if ($request->hasFile('image')) {
+            $file = $this->fileService->saveFileComplete(
+                file: $request->file('image'),
+                folder: 'products',
+                fileName: 'product_' . time(),
+                is_compressed: true,
+            );
+            $data['image'] = $file['name'];
+        }
+        return $this->responseCreated(Product::create($data), 'Product created successfully');
+    }
+
+    // update
+    public function update(ProductUpdateRequest $request, Product $product)
+    {
+        $data = $request->validated();
+        if ($request->input('image') == null && $product->image) {
+            $this->fileService->deleteFile(folder: 'products', fileName: $product->image);
+            $data['image'] = '';
+        }
+        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 successfully');
+    }
+
+    // destroy
+    public function destroy(Product $product)
+    {
+        if ($product->image) $this->fileService->deleteFile(folder: 'products', fileName: $product->image);
+        $product->delete();
+        return $this->responseDeleted('Product deleted successfully');
+    }
+}
+```
+
+### FormRequest (with Scramble PHPDoc)
+```php
+public function rules(): array
+{
+    return [
+        /** @example iPhone 14 Pro */
+        'name'        => 'required|string|max:255',
+        /** @example 15000000 */
+        'price'       => 'required|numeric|min:0',
+        /** @example 50 */
+        'stock'       => 'required|integer|min:0',
+        /** Product image JPG/PNG max 20MB. @example (binary) */
+        'image'       => 'nullable|file|mimes:jpg,jpeg,png|max:20480',
+        /** @example 550e8400-e29b-41d4-a716-446655440000 */
+        'category_id' => 'required|exists:categories,id',
+    ];
+}
+```
+
+---
+
+## API QUERY PARAMETERS
+
+```
+# Via baseQuery() — Controller level
+?search=keyword              # searches $searchable columns (LIKE %keyword%)
+?sort_by=price               # column to sort
+?sort_order=asc|desc         # default: desc
+?paginate=20                 # items per page (triggers pagination)
+?first=1                     # return first record only
+
+# Via Spatie QueryBuilder — Query Class level
+?filter[name]=iPhone         # exact/partial filter (as defined in Query class)
+?filter[category_id]=uuid
+?include=category            # relations in $relationIncludes
+?include=category,brand
+?sort=-price                 # Spatie sort: prefix - for desc
+?fields[products]=id,name,price
+
+# Combined example
+GET /api/v1/products?search=phone&filter[category_id]=uuid&sort_by=price&sort_order=asc&paginate=15&include=category
+```
+
+---
+
+## API RESPONSE METHODS & FORMAT
+
+```php
+$this->responseSuccess($data, $message, $statusCode = 200)
+$this->responseData($data, $message)    // auto-detects paginator → adds pagination key
+$this->responseCreated($data, $message) // 201
+$this->responseDeleted($message)        // 200, data: null
+$this->responseError($message, $code = 400)
+```
+
+**Standard:** `{ success, message, code, data }`
+**Paginated:** adds `pagination: { current_page, from, to, total, per_page, last_page, next_page, prev_page, path }`
+
+---
+
+## MIGRATION TEMPLATE (Workflow A)
+
+```php
+// Save as: database/migrations/2024_xx_xx_create_products_table.php
+return new class extends Migration {
+    public function up(): void {
+        Schema::create('products', function (Blueprint $table) {
+            $table->uuid('id')->primary();
+            $table->string('name');
+            $table->decimal('price', 10, 2);
+            $table->integer('stock');
+            $table->string('image')->nullable();
+            $table->foreignUuid('category_id')->constrained()->cascadeOnDelete();
+            $table->timestamps();
+        });
+    }
+    public function down(): void { Schema::dropIfExists('products'); }
+};
+```
+
+**Then:** `php artisan gc:from-migration products && php artisan migrate`
+
+**gc:from-migration auto-detects:**
+- All column types → `$fillable`, validation rules
+- `foreignUuid` / `foreignId` → `belongsTo` + `$relationIncludes`
+- File-like field names → FileService integration + `$appends` accessor
+- `->nullable()` → `nullable` validation rule
+
+---
+
+## FILE SERVICE
+
+```php
+// Upload with compression
+$file = $this->fileService->saveFileComplete(
+    file: $request->file('image'),
+    folder: 'products',           // stored in storage/app/{folder}/ (or S3: filemanager/{folder}/)
+    fileName: 'product_' . time(),
+    is_compressed: true,          // Imagick compression (jpg/jpeg/png/webp only)
+);
+$data['image'] = $file['name'];   // returns ['name' => 'slugged-name-xxxx.ext', ...]
+
+// Delete
+$this->fileService->deleteFile(folder: 'products', fileName: $product->image);
+```
+
+---
+
+## AI RULES
+
+**ALWAYS:**
+- Translate Indonesian field names to English
+- Use `uuid('id')->primary()` — no auto-increment
+- Include `php artisan migrate` after gc command
+- Use `gc:from-migration {table}` (plural table name) for existing migrations
+- Add `@example` PHPDoc in FormRequests for Scramble docs
+- `baseQuery(new XxxQuery())` — ONE argument only
+
+**NEVER:**
+- Generate CRUD code manually — always use gc commands
+- Use `id()->primary()` (use `uuid`)
+- Skip explaining `?search`, `?filter[]`, `?include=` capabilities
+- Suggest `gc:wizard` when fields are clear and < 5
+
+**Model name rules:** Singular PascalCase (`Product`, `CategoryItem`), table = plural snake_case (auto)
+
+---
+
+## QUICK EXAMPLES
+
+```bash
+# Simple
+php artisan gc Product --fields=name,price:decimal,stock:integer && php artisan migrate
+
+# With file
+php artisan gc Product --fields=name,price:decimal,image:file && php artisan migrate
+
+# With relations
+php artisan gc Product --fields=name,price:decimal,image:file --belongsTo=Category,Brand && php artisan migrate
+
+# From existing migration
+php artisan gc:from-migration products && php artisan migrate
+
+# Complex / unclear
+php artisan gc:wizard Product
+```
+
+---
+
+## SCRAMBLE DOCS
+
+Auto-generated from PHPDoc + FormRequest rules + route definitions.
+Access: `http://your-app.test/docs/api`
+
+Controller PHPDoc pattern:
+```php
+/**
+ * Get list of products
+ * @response array{success: true, code: 200, message: "...", data: Product[], pagination?: array{...}}
+ */
+public function index(IndexRequest $request) { ... }
+```