Instruckt Laravel Laravel Package

Technical Evaluation

Architecture Fit

• MCP Integration: Aligns well with Laravel’s MCP (Model Composition Pattern) ecosystem, enabling seamless AI agent interaction (e.g., Claude Code, Copilot). Leverages Laravel’s native MCP support for structured feedback loops.
• Visual Feedback Layer: Adds a browser-based annotation tool (via Blade/Vite) that bridges human input (visual markup) with AI processing (structured markdown). Complements existing Laravel tooling (e.g., Livewire, Blade) without disrupting core logic.
• Modular Design: Decouples frontend (Vite/Blade) from backend (API routes, JSON storage), reducing coupling risk. Configurable adapters (livewire, blade) allow targeted integration.
• AI-Centric: Optimized for AI-driven development workflows, where human feedback is ingested as structured data for agents. Fits into AI-assisted coding pipelines (e.g., pair programming, code reviews).

Integration Feasibility

• Low Friction: Zero-config install (composer require + artisan command) handles Vite setup, MCP detection, and Blade toolbar injection. Minimal manual intervention required.
• Backend API: Exposes /instruckt endpoint for annotation storage/retrieval. Uses Laravel’s JSON file storage (configurable) or can be extended to databases (e.g., Eloquent).
• Frontend Integration: Vite plugin injects a Blade toolbar component and JS SDK. Works with existing Livewire/Blade apps without rewrites.
• MCP Tools: Automatically registers tools for detected AI agents (e.g., instruckt.annotate(), instruckt.listAnnotations()). Requires laravel/mcp (optional but recommended).

Technical Risk

• Vite Dependency: Requires Vite 5+ (Laravel 11/12 default). Apps using older build tools (e.g., Webpack, Mix) may need migration.
• MCP Compatibility: MCP tools must align with agent capabilities (e.g., Copilot’s tool schema). Misalignment could break AI integration.
• Storage Backend: Defaults to JSON files (scalability limits). Custom storage (e.g., database) requires manual setup.
• Blade/Livewire Adapters: Limited to these frameworks. Inertia/Alpine.js users may need custom adapters.
• AI Agent Support: Only pre-configured for Claude Code, Cursor, Codex, OpenCode, Copilot. Emerging agents may need manual MCP tool registration.

Key Questions

1. AI Workflow Alignment:
   • How will annotations feed into your AI agent’s decision-making? (e.g., code generation, debugging)
   • Are there existing MCP tools in your stack that conflict with instruckt?
2. Storage Scalability:
   • Will JSON file storage suffice, or is a database (e.g., Eloquent) needed for large-scale annotations?
3. Frontend Compatibility:
   • Does your app use Vite 5+? If not, what’s the migration path?
   • Are you using Livewire/Blade? If not, can adapters be extended?
4. Security:
   • How will annotation data be validated/sanitized before AI processing?
   • Are there RBAC requirements for annotation access?
5. Performance:
   • Could real-time annotation sync (via MCP) impact AI agent latency?
6. Uninstall Cleanup:
   • What’s the rollback plan if instruckt is removed post-integration?

Integration Approach

Stack Fit

• Laravel 11/12: Native support for MCP, Vite, and Blade. No major conflicts.
• PHP 8.2+: Required for MCP and modern Laravel features. Aligns with current stack.
• Frontend:
  • Vite 5+: Mandatory for the instruckt plugin. If using Laravel Mix/Webpack, migrate to Vite first.
  • Blade/Livewire: Primary adapters. Inertia/Alpine.js users must implement custom adapters.
• AI Agents: Optimized for Copilot, Claude Code, Cursor. Test with your primary agent(s).

Migration Path

1. Pre-Integration:
   • Audit vite.config.js for Vite 5+ compatibility.
   • Verify laravel/mcp is installed if using MCP tools.
   • Backup existing annotation systems (if any).
2. Installation:

   composer require joshcirre/instruckt-laravel --dev
   php artisan instruckt:install
   

   • Review published config (config/instruckt.php) for customizations.
3. Configuration:
   • Update vite.config.js with instruckt plugin (provided by install command).
   • Add import 'virtual:instruckt' to your JS entry point.
   • Configure MCP tools in app/Models/Agent.php (if using custom agents).
4. Testing:
   • Verify Blade toolbar appears in dev tools.
   • Test annotation creation/editing in the browser.
   • Validate MCP tools work with your AI agent (e.g., php artisan mcp:test).
5. Post-Integration:
   • Extend storage backend if needed (e.g., replace JSON with Eloquent).
   • Add annotation validation/sanitization middleware.

Compatibility

Sequencing

1. Phase 1: Core Integration (1–2 days)
   • Install package, configure Vite/Blade, test toolbar.
   • Validate MCP tools with AI agent.
2. Phase 2: Storage Customization (0.5–1 day)
   • Extend storage to database if needed (e.g., Annotation model).
3. Phase 3: Workflow Integration (1–3 days)
   • Hook annotations into AI workflows (e.g., trigger agent on save).
   • Add validation/security layers.
4. Phase 4: Testing & Rollout (1–2 weeks)
   • Test with real AI agents and user feedback.
   • Monitor performance (e.g., annotation sync latency).

Operational Impact

Maintenance

• Package Updates:
  • Monitor joshcirre/instruckt-laravel for breaking changes (e.g., MCP schema updates).
  • Vite plugin updates may require config adjustments.
• Dependency Management:
  • laravel/mcp and Vite versions must stay aligned.
  • JSON storage may need cleanup scripts for large volumes.
• Customizations:
  • Storage backend extensions (e.g., Eloquent) require maintenance.
  • MCP tools for unsupported agents need updates.

Support

• Debugging:
  • Use php artisan instruckt:debug (if available) or check storage/logs/instruckt.log.
  • Vite dev tools to inspect annotation payloads.
• Common Issues:
  • MCP Tool Failures: Verify agent supports the tool schema.
  • Toolbar Not Loading: Check Vite plugin config and JS imports.
  • Storage Limits: JSON files may bloat; migrate to database if needed.
• Documentation:
  • Limited but clear README. May need internal runbooks for:
    • Annotation data structure.
    • MCP tool debugging.
    • Vite plugin troubleshooting.

Scaling

• Storage:
  • JSON: Not scalable for >10K annotations. Replace with Eloquent + database.
  • Database: Add indexes on user_id, timestamp for query performance.
• Performance:
  • Real-Time Sync: MCP tool calls may add latency. Batch annotations if needed.
  • Frontend: Toolbar should be lightweight; test with large Blade templates.
• Concurrency:
  • JSON storage is file-locking; database avoids race conditions.
  • AI agent tool calls should be idempotent.

Failure Modes