Instruckt Laravel Laravel Package

What's new

Database store

Annotations can now be persisted to a database table instead of a flat JSON file. Set INSTRUCKT_STORE=database and run the migration:

php artisan vendor:publish --tag=instruckt-migrations
php artisan migrate

Required for hosted and multi-instance environments.

S3 / remote screenshot storage

Set INSTRUCKT_SCREENSHOT_DISK=s3 (or any configured Laravel disk) to store screenshots on a remote disk. Screenshots are served via temporary signed URLs so they survive deploys.

MCP token authentication

Protect the /instruckt/mcp SSE endpoint with a Bearer token:

INSTRUCKT_MCP_TOKEN=your-secret-token

Then add the header in your .mcp.json:

{
  "instruckt": {
    "url": "https://your-app.com/instruckt/mcp",
    "headers": { "Authorization": "Bearer your-secret-token" }
  }
}

Split middleware config

middleware is now split into api_middleware (annotation CRUD routes) and mcp_middleware (MCP SSE endpoint) for independent control.

MCP error handling fix

instruckt.get_screenshot now returns a proper MCP error response (isError: true) when an annotation has no screenshot or the file is missing, preventing Claude Code from attempting to recover by locating the image via other means.

Upgrade notes

• If you have published the config, re-publish or manually add api_middleware, mcp_middleware, mcp_token, store, and screenshot_disk keys (all have sensible defaults).
• The old middleware key still works but is superseded by api_middleware.

Add Laravel 13 support

Add configurable toolbar tool visibility — hide individual tools (annotate, screenshot, freeze, etc.) via the tools config array. (PR #4 by @JonPurvis)

What's new

• Vite plugin support: instruckt:install now prefers injecting the instruckt/vite plugin into vite.config.* with server: false (Laravel owns the backend), and adds a simple import 'virtual:instruckt' to app.js
• Falls back to legacy JS snippet and Blade component for projects without Vite
• instruckt:uninstall updated to clean up Vite plugin injection, virtual imports, and all legacy injection patterns

What's New

Server-side source resolution

• New SourceResolver class resolves Livewire component names to PHP class files and line numbers using ReflectionClass
• Blade view names resolved to file paths via the view finder
• Store::createAnnotation() automatically enriches annotations with source_file, source_line, class_name, and render_line

Blade view tracking middleware

• New TrackBladeViews middleware injects a JSON script tag listing all rendered Blade views per request
• Works with the npm package's Blade adapter to provide framework context for plain Blade pages (e.g. Livewire starter kit auth pages)

On-demand source resolution endpoint

• New POST /instruckt/resolve-source endpoint for resolving source info on demand

MCP crash fix

• MCP tools no longer use abort() which threw uncaught HttpException in the stdio context
• Store::updateAnnotation() returns null instead of aborting; MCP tools handle gracefully

Install command improvement

• InstallCommand now always includes 'blade' in the adapters list alongside any JS framework adapter

Full Changelog: https://github.com/joshcirre/instruckt-laravel/compare/v0.4.17...v0.4.19

What's Changed

• feat: add instruckt:uninstall command by @joshcirre in https://github.com/joshcirre/instruckt-laravel/pull/2

Full Changelog: https://github.com/joshcirre/instruckt-laravel/compare/v0.4.17...v0.4.18