Laravel Vurb Laravel Package

Getting Started

• Confirm prerequisites before installing: PHP 8.2+, Laravel 11/12/13, and Node.js with npx available. The bridge daemon runs Vurb.ts as a managed Node process, so a PHP-only environment is not sufficient.
• Install with composer require vinkius-labs/laravel-vurb, then run php artisan vurb:install. Inspect the generated config first — this is where the tool registry, bridge settings, middleware, and governance defaults will live. Also review the generated llms.txt and SKILL.md; they are the package’s built-in AI-agent integration surface.
• Start the server with php artisan vurb:serve and connect an MCP client to the local endpoint. Treat this as a local development server first; do not expose it publicly until auth, tenancy, and redaction are configured.
• First use case: expose one read-only tool, such as “list recent orders for the authenticated user.” Give it a small, stable input schema and a presenter that returns only allowlisted fields. Add DLP redaction for email/phone before testing with a real MCP client.
• Look first at the generated tool examples, the presenter layer, and the middleware pipeline. These are the day-to-day extension points; the bridge daemon should mostly be infrastructure you configure once.

Implementation Patterns

• Model each MCP capability as a dedicated tool class with a single responsibility. Register tools explicitly in config or a service provider, and keep input schemas stable and JSON-serializable.
• Use presenters as the contract between Eloquent models and MCP clients. Never return raw models or full attribute sets. Version presenters when response shapes change so agent prompts do not silently break.
• Put authentication, tenant scoping, and rate limiting in middleware. MCP clients are another entry point into your app, not a trusted internal caller. Reuse Laravel auth/Sanctum where possible.
• Apply DLP redaction at the presenter or middleware boundary using allowlists. Redaction should be deterministic and covered by tests, especially for nested relations and free-text fields.
• Use FSM state gates for multi-step or destructive operations. Require an explicit confirmation state before writes, record transitions, and make gate failures observable.
• Emit structured observability events for tool name, tenant, latency, redaction counts, and failures. Sample high-volume tools rather than logging every payload.
• In development, let vurb:serve auto-manage the bridge daemon. In production, disable auto-spawn and run the Vurb.ts bridge under your normal process supervisor, or run the artisan process with an explicit restart policy.
• Test tool classes directly as Laravel features, and mock the bridge for protocol-level tests. Disable the bridge daemon in test environments to avoid orphaned Node processes.
• Prefer extending through custom middleware, presenters, and state gates over forking the package. The package’s breadth is useful only if your app keeps its own domain boundaries clear.

Gotchas and Tips

• The Node/npx dependency is real. npx may fetch Vurb.ts at runtime; pin the bridge version, pre-install dependencies in CI and production images, and avoid network access during boot.
• The auto-managed bridge can spawn duplicate Node processes under Octane, queue workers, or repeated test runs. Disable auto-management anywhere the app is not actively serving MCP traffic.
• Clear config and route caches after changing the tool registry or middleware pipeline. Silent tool discovery failures are usually stale cache or a registration typo.
• MCP tool schemas must remain simple JSON. Avoid closures, resources, Carbon objects, circular Eloquent relations, and provider-specific types in tool inputs and presenter outputs.
• DLP redaction is not authorization. Enforce policies and tenant scoping before tool execution; redaction only limits what leaves the tool.
• Bridge failures can surface as generic tool errors. Check bridge stderr, confirm the Node process is running, and add health logging around vurb:serve.
• Laravel 13 support may arrive ahead of the wider package ecosystem. Pin framework and package versions in composer.json and test upgrades deliberately.
• llms.txt and SKILL.md may be regenerated by the installer. Decide whether to commit them or ignore them, and avoid hand-editing without a generator or review step.
• Observability can leak sensitive payloads if you log raw tool arguments or responses. Redact before logging and sample aggressively.
• Main extension points are the config, tool registry, middleware pipeline, presenters, FSM state gates, and bridge process settings. Keep customizations there rather than patching vendor code.