# MCP and Filament Blueprint (Jabali Panel)

Last updated: 2026-02-12

This document is an internal developer blueprint for working on Jabali Panel with:

- MCP tooling (Model Context Protocol) for fast, version-correct introspection and docs.
- Filament (Admin + User panels) conventions and project-specific UI rules.

## Goals

- Keep changes consistent with the existing architecture and UI.
- Prefer version-specific documentation and project-aware inspection.
- Avoid UI regressions by following Filament-native patterns.
- Keep privileged operations isolated behind the agent.

## MCP Tooling Blueprint

Jabali is set up to be worked on with MCP tools. Use them to reduce guesswork and prevent version drift.

### 1) Laravel Boost (Most Important)

Laravel Boost MCP gives application-aware tools (routes, config, DB schema, logs, and version-specific docs).

Use it when:
- You need to confirm route names/paths and middleware.
- You need to confirm the active config (not just what you expect in `.env`).
- You need the DB schema or sample records to understand existing behavior.
- You need version-specific docs for Laravel/Livewire/Filament/Tailwind.

Preferred workflow:
- `application-info` to confirm versions and installed packages.
- `list-routes` to find the correct URL, route names, and panel prefixes.
- `get-config` for runtime config values.
- `database-schema` and `database-query` (read-only) to verify tables and relationships.
- `read-log-entries` / `last-error` to confirm the active failure.
- `search-docs` before implementing anything that depends on framework behavior.

Project rule of thumb:
- Before making a structural change in the panel, list relevant routes and key config values first.

### 2) Jabali Docs MCP Server

The repository includes `mcp-docs-server/` which exposes project docs as MCP resources/tools.

What it is useful for:
- Quick search across `README.md`, `AGENT.md`, and changelog content.
- Pulling a specific section by title.

This is not a runtime dependency of the panel. It is a developer tooling layer.

### 3) Frontend and Quality MCPs

Use these to audit and reduce UI/HTML/CSS regressions:

- `css-mcp`:
  - Analyze CSS quality/complexity.
  - Check browser compatibility for specific CSS features.
  - Pull MDN docs for CSS properties/selectors when implementing UI.
- `stylelint`:
  - Lint CSS where applicable (note: Filament pages should not use custom CSS files).
- `webdev-tools`:
  - Prettier formatting for snippets.
  - `php -l` lint for PHP syntax.
  - HTML validation for standalone HTML.

Security rule:
- Do not send secrets (tokens, passwords, private keys) into any tool query.

## Filament Blueprint (How Jabali Panels Are Built)

Jabali has two Filament panels:

- Admin panel: server-wide operations.
- User panel ("Jabali" panel): tenant/user operations.

High-level structure:
- `app/Filament/Admin/*` for admin.
- `app/Filament/Jabali/*` for user.

### Pages vs Resources

Default decision:
- Use a Filament Resource when the UI is primarily CRUD around an Eloquent model.
- Use a Filament Page when the UI is a dashboard, a multi-step wizard, or merges multiple concerns into a single screen.

### Project UI Rules (Strict)

These rules exist to keep the UI consistent and maintainable:

- Use Filament native components for layout and UI.
- Avoid raw HTML layout in Filament pages.
- Avoid custom CSS for Filament pages.
- Use Filament tables for list data.

Practical mapping:
- Layout: `Filament\Schemas\Components\Section`, `Grid`, `Tabs`, `Group`.
- Actions: `Filament\Actions\Action`.
- List data: `HasTable` / `InteractsWithTable` or `EmbeddedTable`.

### Tabs + Tables Gotcha

There is a known class of issues when a table is nested incorrectly inside schema Tabs.

Rule of thumb:
- Prefer `EmbeddedTable::make()` in schema layouts.
- Avoid mounting tables inside `View::make()` within `Tabs::make()` unless you know the action mounting behavior is preserved.

### Translations and RTL

Jabali uses JSON-based translations.

Rules:
- Use the English string as the translation key: `__('Create Domain')`.
- Do not introduce dotted translation keys like `__('domain.create')`.
- Ensure UI reads correctly in RTL locales (Arabic/Hebrew).

### Privileged Operations (Agent Boundary)

The Laravel app is the control plane. Privileged system operations are executed by the root-level agent.

Key points:
- The agent is `bin/jabali-agent`.
- The panel should call privileged operations through the Agent client service (not by shelling out directly).
- Keep all path and input validation strict before an agent call.

## Filament Blueprint Planning (Feature Specs)

When writing an implementation plan for a Filament feature, use Filament Blueprint planning docs as a checklist.

Reference:
- `vendor/filament/blueprint/resources/markdown/planning/overview.md`

At minimum, a plan should specify:
- Data model changes (tables, columns, indexes, relationships).
- Panel placement (Admin vs User) and navigation.
- Page/Resource decisions.
- Authorization model (policies/guards).
- Background jobs (for long-running operations).
- Audit logging events.
- Tests (Feature tests for endpoints and Livewire/Filament behaviors).

## Development Checklist (Per Feature)

- Confirm the correct panel and route prefix.
- List routes and verify config assumptions (Boost tools).
- Follow Filament-native components (no custom HTML/CSS in Filament pages).
- Use tables for list data.
- Keep agent boundary intact for privileged operations.
- Add or update tests and run targeted test commands.