refactor: susun semula struktur folder — Laravel source ke src/

vendor/laravel/mcp/resources/boost/skills/mcp-development/references/app.md

@@ -0,0 +1,940 @@
+# MCP UI Apps Reference
+
+## Quick Start
+
+`make:mcp-app-resource DashboardApp` generates two files — a PHP registration stub and a Blade view. The entire app lives in the Blade view.
+
+**PHP class** — renders the Blade view. The view name is auto-inferred from the class name (`mcp.<kebab-class-name>`), so the generated stub needs no changes unless you're passing additional server-side data:
+
+```php
+class DashboardApp extends AppResource
+{
+    public function handle(Request $request): Response
+    {
+        return Response::view('mcp.dashboard-app', [
+            'title' => $this->title(),
+        ]);
+    }
+}
+```
+
+**Blade view** — HTML structure + inline JS, everything in one file:
+
+```blade
+<x-mcp::app title="Dashboard App">
+    <x-slot:head>
+        <script type="module">
+        createMcpApp(async (app) => {
+            document.getElementById('run-btn').addEventListener('click', async () => {
+                const result = await app.callServerTool({ name: 'tool-name', arguments: {} });
+                document.getElementById('output').textContent = result.content[0]?.text ?? '';
+            });
+        });
+        </script>
+    </x-slot:head>
+
+    <div id="app">
+        <h1>Dashboard App</h1>
+        <button id="run-btn">Run</button>
+        <p id="output"></p>
+    </div>
+</x-mcp::app>
+```
+
+`createMcpApp` is a global pre-bundled by the package — no npm install, no imports, no Vite required. It handles connection, error handling, and host theming automatically.
+
+---
+
+## Core Concept: Tool + Resource
+
+Every MCP App is built from two parts linked together:
+
+- **Tool** — called by the LLM or host. Returns a text/data response and tells the host which UI resource to render via `_meta.ui.resourceUri`.
+- **AppResource** — serves the self-contained HTML app. The host fetches it after the tool is called and renders it in a sandboxed iframe.
+
+```
+LLM calls Tool
+    └─► Tool response includes _meta.ui.resourceUri → "ui://dashboard-app"
+            └─► Host fetches AppResource at that URI
+                    └─► Host renders HTML in sandboxed iframe
+                            └─► createMcpApp() connects the iframe back to the server
+                                    └─► UI calls app-only tools to load/refresh data
+```
+
+The link is declared once with `#[RendersApp]` on the tool:
+
+```php
+#[RendersApp(resource: DashboardApp::class)]
+class ShowDashboard extends Tool
+{
+    public function handle(Request $request): Response
+    {
+        return Response::text('Dashboard loaded.');
+    }
+}
+```
+
+After that, the host handles fetching and rendering the resource automatically — you never reference the URI by hand.
+
+---
+
+## Architecture Overview
+
+MCP Apps add interactive UI to the Model Context Protocol. The server returns self-contained HTML with all JS/CSS inlined. The host renders it in a sandboxed iframe. Apps communicate back via `createMcpApp()` — a pre-bundled global implementing the MCP UI PostMessage protocol.
+
+```
+┌─────────────────────────────────────────────┐
+│  Host (Claude, ChatGPT, VS Code)            │
+│  ┌───────────────────────────────────────┐  │
+│  │  Sandboxed iframe                     │  │
+│  │  ┌─────────────────────────────────┐  │  │
+│  │  │  Your MCP App (HTML/JS/CSS)     │  │  │
+│  │  │  - Rendered by AppResource       │  │  │
+│  │  │  - Single self-contained HTML   │  │  │
+│  │  │  - Themed via host CSS vars     │  │  │
+│  │  └─────────────────────────────────┘  │  │
+│  └───────────────────────────────────────┘  │
+└──────────────────┬──────────────────────────┘
+                   │ MCP Protocol (JSON-RPC)
+┌──────────────────▼──────────────────────────┐
+│  Laravel MCP Server                         │
+│  - AppResource → self-contained HTML         │
+│  - Tool #[RendersApp] → triggers UI display   │
+│  - resources/read → serves HTML + _meta.ui  │
+└─────────────────────────────────────────────┘
+```
+
+The server automatically advertises `io.modelcontextprotocol/ui` capability when any `AppResource` is registered. The client declares support in `capabilities.extensions["io.modelcontextprotocol/ui"]` during the initialize handshake.
+
+---
+
+## Server-Side
+
+Minimal case — `handle()` renders the Blade view, entire app lives there:
+
+```php
+class DashboardApp extends AppResource
+{
+    public function handle(Request $request): Response
+    {
+        return Response::view('mcp.dashboard-app', [
+            'title' => $this->title(),
+        ]);
+    }
+}
+```
+
+Auto-renders `resources/views/mcp/dashboard-app.blade.php` with `$title` available via `$this->title()`.
+
+Override `handle()` only when passing additional server-side data:
+
+```php
+class AnalyticsDashboard extends AppResource
+{
+    public function handle(Request $request): Response
+    {
+        return Response::view('mcp.analytics-dashboard', [
+            'title' => $this->title(),
+            'metrics' => Metric::latest()->take(10)->get(),
+            'totalUsers' => User::count(),
+        ]);
+    }
+}
+```
+
+`Response::view($view, $data = [], $mergeData = [])` renders a Blade view and returns it as text.
+
+`Response::html($path)` reads an HTML file from disk and returns its content. Relative paths resolve via `resource_path()`:
+
+```php
+class StaticApp extends AppResource
+{
+    public function handle(Request $request): Response
+    {
+        return Response::html('mcp/static-app.html');
+    }
+}
+```
+
+### AppMeta Configuration
+
+The simplest way to configure UI metadata is via the `#[AppMeta]` attribute directly on your resource class:
+
+```php
+use Laravel\Mcp\Server\Attributes\AppMeta;
+use Laravel\Mcp\Server\Ui\Enums\Library;
+use Laravel\Mcp\Server\Ui\Enums\Permission;
+
+#[AppMeta(
+    connectDomains: ['https://api.stripe.com'],
+    permissions: [Permission::Camera, Permission::ClipboardWrite],
+    prefersBorder: true,
+    libraries: [Library::Tailwind, Library::Alpine],
+)]
+class PaymentsResource extends AppResource
+{
+    // ...
+}
+```
+
+For dynamic or computed configuration, override `appMeta()` instead:
+
+```php
+use Laravel\Mcp\Server\Ui\AppMeta;
+
+public function appMeta(): AppMeta
+{
+    return AppMeta::make()
+        ->csp(Csp::make()->connectDomains(config('services.api.domains')))
+        ->permissions(Permissions::make()->allow(Permission::Camera))
+        ->libraries(Library::Tailwind)
+        ->domain('sandbox.example.com');
+}
+```
+
+#### Permission Enum
+
+Use the `Permission` enum for type-safe permission configuration:
+
+```php
+use Laravel\Mcp\Server\Ui\Enums\Permission;
+
+Permission::Camera        // 'camera'
+Permission::Microphone    // 'microphone'
+Permission::Geolocation   // 'geolocation'
+Permission::ClipboardWrite // 'clipboardWrite'
+```
+
+#### Csp
+
+Controls what external domains the iframe can access:
+
+```php
+Csp::make()
+    ->connectDomains(['https://api.example.com'])    // fetch, XHR, WebSocket origins
+    ->resourceDomains(['https://cdn.example.com'])   // images, scripts, fonts, media
+    ->frameDomains(['https://embed.example.com'])    // nested iframe origins
+    ->baseUriDomains(['https://base.example.com']);  // base URI origins
+```
+
+#### Permissions
+
+```php
+Permissions::make()->allow(Permission::Camera, Permission::ClipboardWrite);
+
+Permissions::make()
+    ->camera()
+    ->microphone()
+    ->geolocation()
+    ->clipboardWrite();
+```
+
+Each enabled permission serializes as `"camera": {}` per the MCP spec.
+
+#### AppMeta
+
+```php
+AppMeta::make()
+    ->csp(Csp::make()->connectDomains([...]))
+    ->permissions(Permissions::make()->allow(Permission::Camera))
+    ->libraries(Library::Tailwind, Library::Alpine)
+    ->domain('sandbox.example.com')  // dedicated sandbox origin (OAuth/CORS)
+    ->prefersBorder(false);
+```
+
+`prefersBorder` defaults to `true`. `toArray()` omits null fields and empty nested objects. Library CDN domains are automatically merged into `csp.resourceDomains`.
+
+#### domain
+
+The `domain` field provides a stable origin that external APIs can allowlist for CORS. It is automatically resolved from `config('app.url')` (your `APP_URL` env variable) via `resolvedAppMeta()`, so most apps need no configuration. Override only when a resource needs a different origin:
+
+```php
+#[AppMeta(domain: 'custom.example.com')]
+class PaymentsResource extends AppResource
+{
+    // ...
+}
+```
+
+#### Library Scripts
+
+The `libraries` parameter adds pre-configured CDN scripts to the `<head>` of your app. Available libraries:
+
+```php
+use Laravel\Mcp\Server\Ui\Enums\Library;
+
+Library::Tailwind  // Tailwind CSS CDN + dark mode config
+Library::Alpine    // Alpine.js CDN + x-cloak style
+```
+
+When libraries are specified, the package automatically:
+
+1. Injects the CDN `<script>` tags into the Blade view's `<head>` (after the MCP SDK, before your `<x-slot:head>`)
+2. Merges each library's CDN domains into `csp.resourceDomains` so the host allows loading them
+
+Via attribute:
+
+```php
+#[AppMeta(libraries: [Library::Tailwind])]
+class StyledApp extends AppResource
+{
+    // Tailwind is available in the Blade view — no extra setup
+}
+```
+
+Via fluent builder:
+
+```php
+public function appMeta(): AppMeta
+{
+    return AppMeta::make()
+        ->libraries(Library::Tailwind, Library::Alpine);
+}
+```
+
+---
+
+## View Layer
+
+### `<x-mcp::app>` Blade Component
+
+Renders a complete self-contained HTML document with the MCP SDK inlined. `createMcpApp` is available globally.
+
+```blade
+<x-mcp::app title="Dashboard App">
+    <x-slot:head>
+        <script type="module">
+        createMcpApp(async (app) => {
+            document.getElementById('run-btn').addEventListener('click', async () => {
+                const result = await app.callServerTool({ name: 'tool-name', arguments: {} });
+                document.getElementById('output').textContent = result.content[0]?.text ?? '';
+            });
+        });
+        </script>
+    </x-slot:head>
+
+    <div id="app">
+        <button id="run-btn">Run</button>
+        <p id="output"></p>
+    </div>
+</x-mcp::app>
+```
+
+**Props and slots:**
+
+| Name          | Type          | Description                                          |
+| ------------- | ------------- | ---------------------------------------------------- |
+| `title`       | Prop          | Sets `<title>`. Optional.                            |
+| `head`        | Named slot    | Injected into `<head>` after the inlined SDK script. |
+| Default slot  | Slot          | Body content.                                        |
+| `$attributes` | Attribute bag | Forwarded to `<body>` (e.g. `class="dark"`).         |
+
+The SDK is loaded from the `mcp.sdk` singleton (registered by `McpServiceProvider`) and inlined directly in a `<script>` tag. Library scripts (Tailwind, Alpine) configured via `#[AppMeta]` are injected after the SDK and before the `head` slot.
+
+Publish the component: `php artisan vendor:publish --tag=mcp-views`.
+
+To pass server-side data to JS, embed it as `data-*` attributes:
+
+```blade
+<div id="app" data-users="{{ $users->toJson() }}">
+    ...
+</div>
+```
+
+```js
+const users = JSON.parse(document.getElementById("app").dataset.users);
+```
+
+## Client-Side
+
+This package provides a simple MCP client library to easily work with client interactions.
+
+### createMcpApp
+
+Pre-bundled and inlined automatically — no npm install or imports required.
+
+```js
+createMcpApp(async (app) => {
+    // app is ready — connection established, theming applied
+});
+```
+
+### Tools
+
+#### app.callServerTool()
+
+Accepts an object or positional arguments:
+
+```js
+// Object form
+const result = await app.callServerTool({ name: 'get-analytics', arguments: { dateRange: '7d' } });
+
+// Positional form
+const result = await app.callServerTool('get-analytics', { dateRange: '7d' });
+
+// result structure depends on the server's tool response
+const text = result.content[0]?.text ?? "";
+```
+
+All tool results share a standard structure:
+
+| Property  | Type      | Description                                                               |
+| --------- | --------- | ------------------------------------------------------------------------- |
+| `content` | `Array`   | Content items returned by the tool (each has `type` and `text` or `data`) |
+| `isError` | `boolean` | `true` when the tool returned an error response                           |
+
+Always check `result.isError` before consuming `content`. See [Error Handling](#error-handling) for a full example.
+
+### Resources
+
+#### app.listResources()
+
+```js
+const resources = await app.listResources();
+// or with cursor for pagination
+const resources = await app.listResources("cursor-value");
+// or object form
+const resources = await app.listResources({ cursor: "cursor-value" });
+```
+
+#### app.readResource()
+
+```js
+const resource = await app.readResource("ui://my-resource");
+// or object form
+const resource = await app.readResource({ uri: "ui://my-resource" });
+```
+
+### Messaging
+
+#### app.sendMessage()
+
+Send a message to the model (creates a conversation turn):
+
+```js
+// Object form with structured content
+await app.sendMessage({
+    role: "user",
+    content: [{ type: "text", text: "User submitted the form." }],
+});
+
+// Shorthand — plain string content with optional role (defaults to 'user')
+await app.sendMessage("User submitted the form.");
+await app.sendMessage("System event occurred.", "user");
+```
+
+### Host Context
+
+#### app.getHostContext()
+
+Returns the current host context, including theme and style variables:
+
+```js
+const ctx = app.getHostContext();
+ctx?.theme; // 'light' | 'dark'
+ctx?.styles?.variables; // CSS variable map from host
+ctx?.styles?.css?.fonts; // font CSS from host
+```
+
+#### app.getHostInfo()
+
+```js
+const info = app.getHostInfo();
+```
+
+#### app.getHostCapabilities()
+
+```js
+const caps = app.getHostCapabilities();
+```
+
+### Navigation & Files
+
+#### app.openLink()
+
+```js
+await app.openLink("https://example.com");
+// or object form
+await app.openLink({ url: "https://example.com" });
+```
+
+#### app.downloadFile()
+
+```js
+await app.downloadFile("file contents here");
+// or object form
+await app.downloadFile({ contents: "file contents here" });
+```
+
+### Display
+
+#### app.requestDisplayMode()
+
+```js
+await app.requestDisplayMode("fullscreen");
+// or object form
+await app.requestDisplayMode({ mode: "fullscreen" });
+```
+
+#### app.resize() / app.autoResize()
+
+`resize()` sends a one-time size notification. `autoResize()` uses `ResizeObserver` to continuously notify the host of size changes. It returns a cleanup function that disconnects the observer — useful if you need to stop observing before teardown. The observer is also automatically disconnected on teardown.
+
+```js
+const stopObserving = app.autoResize();
+
+// Later, if needed:
+stopObserving();
+```
+
+### Model Context
+
+#### app.updateModelContext()
+
+```js
+await app.updateModelContext({ key: "value" });
+```
+
+### Lifecycle
+
+#### app.requestTeardown()
+
+Sends a teardown notification to the host.
+
+```js
+app.requestTeardown();
+```
+
+### Logging
+
+#### app.sendLog()
+
+```js
+// Positional form
+await app.sendLog("info", "Processing started", "my-logger");
+
+// Object form
+await app.sendLog({
+    level: "info",
+    data: "Processing started",
+    logger: "my-logger",
+});
+```
+
+### Event Handlers
+
+Register callbacks for host-side events. Tool input/result/cancelled events are queued until a handler is registered, then flushed.
+
+```js
+createMcpApp(async (app) => {
+    app.onToolInput((params) => {
+        /* tool input received */
+    });
+    app.onToolInputPartial((params) => {
+        /* partial tool input */
+    });
+    app.onToolResult((params) => {
+        /* tool result received */
+    });
+    app.onToolCancelled((params) => {
+        /* tool was cancelled */
+    });
+    app.onHostContextChanged((ctx) => {
+        /* theme/styles changed */
+    });
+    app.onTeardown(async () => {
+        /* cleanup before teardown */
+    });
+    app.onCallTool(async (params) => {
+        /* host requests tool call */
+    });
+    app.onListTools(async (params) => {
+        /* host requests tool list */
+    });
+});
+```
+
+---
+
+## Host Theming
+
+`createMcpApp` automatically applies host theming on connect and on context change:
+
+- Sets `data-theme` attribute and `color-scheme` on `<html>`
+- Applies CSS variables from `hostContext.styles.variables` to `:root`
+- Injects font CSS from `hostContext.styles.css.fonts` into a `<style>` tag
+
+The specific CSS variables available depend on the host. Always provide fallback values — use `light-dark()` for theme-aware defaults:
+
+```css
+:root {
+    --color-background-primary: light-dark(#ffffff, #171717);
+    --color-text-primary: light-dark(#171717, #fafafa);
+    --color-text-secondary: light-dark(#525252, #a3a3a3);
+    --color-border-primary: light-dark(#e5e5e5, #404040);
+    --font-sans: system-ui, -apple-system, sans-serif;
+    --border-radius-md: 8px;
+}
+
+body {
+    font-family: var(--font-sans);
+    background: var(--color-background-primary);
+    color: var(--color-text-primary);
+    margin: 0;
+}
+
+.card {
+    background: var(--color-background-secondary);
+    border: 1px solid var(--color-border-primary);
+    border-radius: var(--border-radius-md);
+    padding: 1rem;
+}
+```
+
+---
+
+## Tool-to-UI Linking
+
+### #[RendersApp] Attribute
+
+Associates a Tool with a UI Resource. When the tool is called, the host fetches and renders the linked resource.
+
+```php
+use Laravel\Mcp\Server\Attributes\RendersApp;
+use Laravel\Mcp\Server\Ui\Enums\Visibility;
+
+// Both model and app can call this tool (default)
+#[RendersApp(resource: DashboardApp::class)]
+class ShowDashboard extends Tool { ... }
+
+// Only the app can call this tool (private to the UI)
+#[RendersApp(resource: DashboardApp::class, visibility: [Visibility::App])]
+class RefreshDashboardData extends Tool { ... }
+```
+
+**Visibility:**
+
+The `Visibility` enum (`Laravel\Mcp\Server\Ui\Enums\Visibility`) has two cases: `Model` and `App`. The default is `[Visibility::Model, Visibility::App]`.
+
+| Visibility                             | Model | App | Use case                                               |
+| -------------------------------------- | ----- | --- | ------------------------------------------------------ |
+| `[Visibility::Model, Visibility::App]` | Yes   | Yes | Primary tools that trigger UI display                  |
+| `[Visibility::App]`                    | No    | Yes | Backend actions the UI calls (refresh, save, paginate) |
+| `[Visibility::Model]`                  | Yes   | No  | Model-only tools linked to a UI                        |
+
+### Primary + Private Pattern
+
+```php
+#[RendersApp(resource: DashboardApp::class)]
+class ShowDashboard extends Tool
+{
+    public function handle(Request $request): Response
+    {
+        return Response::text('Dashboard loaded.');
+    }
+}
+
+#[RendersApp(resource: DashboardApp::class, visibility: [Visibility::App])]
+class GetDashboardMetrics extends Tool
+{
+    public function handle(Request $request): Response
+    {
+        return Response::json(Metric::latest()->take(50)->get());
+    }
+}
+```
+
+---
+
+## Testing
+
+```php
+it('returns html content', function () {
+    MyServer::readResource(DashboardApp::class)
+        ->assertSee('<div id="app">');
+});
+
+it('has correct mime type and uri scheme', function () {
+    $resource = new DashboardApp;
+    $data = $resource->toArray();
+
+    expect($data['mimeType'])->toBe('text/html;profile=mcp-app')
+        ->and($data['_meta']['ui'])->toBeArray()
+        ->and($resource->uri())->toStartWith('ui://');
+});
+
+it('configures ui meta correctly', function () {
+    $meta = (new DashboardApp)->resolvedAppMeta();
+
+    expect($meta['csp']['connectDomains'])->toContain('https://api.example.com')
+        ->and($meta['permissions'])->toHaveKey('clipboardWrite');
+});
+
+it('includes ui metadata in tool listing', function () {
+    MyServer::listTools()->assertSee('show-dashboard');
+});
+```
+
+---
+
+## Patterns
+
+### Real-time Polling
+
+Use app-only tools to fetch fresh data at regular intervals from the UI:
+
+```php
+#[RendersApp(resource: MonitorApp::class, visibility: [Visibility::App])]
+class GetMonitorData extends Tool
+{
+    protected string $description = 'Fetch latest monitor metrics';
+
+    public function handle(Request $request): Response
+    {
+        return Response::json([
+            'cpu' => sys_getloadavg()[0],
+            'memory' => memory_get_usage(true),
+            'timestamp' => now()->toISOString(),
+        ]);
+    }
+}
+```
+
+```js
+createMcpApp(async (app) => {
+    async function poll() {
+        const result = await app.callServerTool('get-monitor-data');
+        const data = JSON.parse(result.content[0]?.text ?? '{}');
+        document.getElementById('cpu').textContent = data.cpu;
+    }
+
+    setInterval(poll, 2000);
+    poll();
+});
+```
+
+### Chunked Data Loading
+
+For large datasets, implement pagination via app-only tools:
+
+```php
+#[RendersApp(resource: LogViewerApp::class, visibility: [Visibility::App])]
+class GetLogChunk extends Tool
+{
+    protected string $description = 'Fetch a chunk of log entries';
+
+    public function schema(JsonSchema $schema): array
+    {
+        return [
+            'offset' => $schema->integer()->description('Byte offset to start from')->required(),
+            'limit' => $schema->integer()->description('Max bytes to return'),
+        ];
+    }
+
+    public function handle(Request $request): Response
+    {
+        $request->validate(['offset' => 'required|integer', 'limit' => 'integer']);
+
+        $offset = $request->get('offset');
+        $limit = $request->get('limit', 500_000);
+        $content = Storage::get('logs/app.log');
+        $chunk = substr($content, $offset, $limit);
+
+        return Response::json([
+            'data' => $chunk,
+            'offset' => $offset,
+            'totalBytes' => strlen($content),
+            'hasMore' => ($offset + $limit) < strlen($content),
+        ]);
+    }
+}
+```
+
+### Binary Resource Serving
+
+Deliver images and binary content through MCP resources using `Response::blob()`:
+
+```php
+#[RendersApp(resource: GalleryApp::class, visibility: [Visibility::App])]
+class GetImage extends Tool
+{
+    protected string $description = 'Fetch an image by ID';
+
+    public function handle(Request $request): Response
+    {
+        $request->validate(['id' => 'required|integer']);
+
+        $image = Image::findOrFail($request->get('id'));
+        $data = base64_encode(Storage::get($image->path));
+
+        return Response::blob($data);
+    }
+}
+```
+
+In the client, convert the base64 blob to a data URI for rendering:
+
+```js
+const result = await app.callServerTool('get-image', { id: 42 });
+const blob = result.content[0];
+img.src = `data:${blob.mimeType};base64,${blob.data}`;
+```
+
+### Streaming Argument Previews
+
+Use `onToolInputPartial` to show previews as the model streams tool arguments:
+
+```js
+createMcpApp(async (app) => {
+    app.onToolInputPartial((params) => {
+        try {
+            const partial = JSON.parse(params.arguments);
+            if (partial.query) {
+                document.getElementById("preview").textContent = partial.query;
+            }
+        } catch {
+            // partial JSON — ignore until parseable
+        }
+    });
+
+    app.onToolResult((params) => {
+        const data = JSON.parse(params.result.content[0]?.text ?? "{}");
+        renderResults(data);
+    });
+});
+```
+
+### View State Persistence
+
+Use `localStorage` to preserve UI state across re-renders. For important state, persist server-side via an app-only tool:
+
+```js
+createMcpApp(async (app) => {
+    const STATE_KEY = "dashboard-view-state";
+
+    // Restore from localStorage
+    const saved = JSON.parse(localStorage.getItem(STATE_KEY) || "{}");
+    if (saved.activeTab) selectTab(saved.activeTab);
+
+    // Save on interaction
+    function saveState(state) {
+        localStorage.setItem(STATE_KEY, JSON.stringify(state));
+    }
+
+    // For durable state, persist server-side
+    async function saveServerState(state) {
+        await app.callServerTool('save-dashboard-state', { state: JSON.stringify(state) });
+    }
+});
+```
+
+### Fullscreen Toggling
+
+Switch between inline and fullscreen display modes and react to mode changes:
+
+```js
+createMcpApp(async (app) => {
+    document.getElementById("expand-btn").addEventListener("click", () => {
+        app.requestDisplayMode("fullscreen");
+    });
+
+    app.onHostContextChanged((ctx) => {
+        document.body.classList.toggle(
+            "fullscreen",
+            ctx.displayMode === "fullscreen",
+        );
+    });
+});
+```
+
+### Model Context Updates
+
+Keep the model informed about what the user is viewing so it can provide relevant assistance:
+
+```js
+createMcpApp(async (app) => {
+    async function notifyContext(view, detail) {
+        await app.updateModelContext({
+            currentView: view,
+            detail: detail,
+        });
+    }
+
+    // Notify on tab change
+    document.querySelectorAll(".tab").forEach((tab) => {
+        tab.addEventListener("click", () => {
+            notifyContext(tab.dataset.view, { filters: getActiveFilters() });
+        });
+    });
+
+    // For large payloads, follow up with sendMessage
+    await app.updateModelContext({ currentView: "report", rows: 5000 });
+    await app.sendMessage("The user is viewing a report with 5000 rows.");
+});
+```
+
+### Pause Offscreen Views
+
+Conserve resources by pausing animations and polling when the view is not visible:
+
+```js
+createMcpApp(async (app) => {
+    let pollInterval = null;
+
+    function startPolling() {
+        if (!pollInterval) {
+            pollInterval = setInterval(fetchData, 2000);
+        }
+    }
+
+    function stopPolling() {
+        clearInterval(pollInterval);
+        pollInterval = null;
+    }
+
+    const observer = new IntersectionObserver(([entry]) => {
+        entry.isIntersecting ? startPolling() : stopPolling();
+    });
+
+    observer.observe(document.documentElement);
+    startPolling();
+});
+```
+
+### Error Handling
+
+Return `Response::error()` from tools and use `updateModelContext()` to signal degraded state:
+
+```php
+class ProcessData extends Tool
+{
+    public function handle(Request $request): Response
+    {
+        $request->validate(['input' => 'required|string']);
+
+        if (strlen($request->get('input')) > 10_000) {
+            return Response::error('Input exceeds 10KB limit.');
+        }
+
+        return Response::json(process($request->get('input')));
+    }
+}
+```
+
+```js
+createMcpApp(async (app) => {
+    const result = await app.callServerTool('process-data', { input: value });
+
+    if (result.isError) {
+        document.getElementById("error").textContent =
+            result.content[0]?.text ?? "Unknown error";
+        await app.updateModelContext({
+            state: "error",
+            message: result.content[0]?.text,
+        });
+        return;
+    }
+
+    renderOutput(JSON.parse(result.content[0]?.text ?? "{}"));
+});
+```