Mcp Laravel Package

Technical Evaluation

Architecture Fit

• Laravel Native Integration: Built for Laravel 11+, leveraging Laravel’s service container, middleware, and Artisan commands. The package extends Laravel’s core features (e.g., Passport for auth, Bouncer for ACL) without requiring architectural overhauls.
• Modular Design: Tools are decoupled into discrete classes (e.g., CatalogTool, DevToolsTool), enabling selective adoption. The ToolRegistry centralizes tool management, simplifying future extensions.
• MCP Protocol Alignment: Adheres to the Model Context Protocol standard, ensuring compatibility with AI agents (Copilot, Claude, etc.) and future-proofing against protocol updates.
• UnoPim-Specific Optimizations: Tailored for UnoPim’s data model (e.g., cursor-paginated CRUD for products/categories, family/group/attribute management), reducing abstraction overhead.

Integration Feasibility

• Low Friction for UnoPim Users: Designed as a drop-in for UnoPim 1.0+ (Laravel 11+). The mcp:install command handles config publishing, Passport scaffolding (if installed), and cache clearing.
• Dual Transport Support: HTTP (SSE) and stdio transports cater to remote AI agents and local development workflows, respectively. The stdio agent (mcp:start) requires no additional infrastructure.
• Permission Granularity: Tools map to UnoPim’s ACL system (via Bouncer), allowing fine-grained access control. HTTP endpoints default to OAuth2 (Passport), while CLI tools bypass ACL for local dev (configurable).
• Security Hardening: Built-in protections (rate limiting, path traversal guards, command whitelisting) reduce integration risk. Audit logging tracks destructive operations for compliance.

Technical Risk

• Dependency on UnoPim: Assumes UnoPim’s data model (e.g., products, categories, families). Customizations may be needed for non-UnoPim Laravel apps using similar entities.
• AI Agent Compatibility: Relies on MCP protocol adoption by AI tools (e.g., GitHub Copilot, Claude). Limited adoption (2 stars, 0 dependents) may indicate niche use or early-stage tech.
• Performance Overhead: Cursor-paginated tools (e.g., search_products) may introduce latency for large catalogs. Rate limiting (default: 60 req/min) could throttle high-frequency AI queries.
• Skill System Complexity: Dynamic skills (via SKILL.md) add flexibility but require understanding of YAML frontmatter and MCP tool registration. Misconfigured skills could expose security risks.
• Laravel 11+ Requirement: Blocks integration with older Laravel versions without significant refactoring.

Key Questions

1. Use Case Validation:
   • Is the primary goal AI-assisted catalog management (e.g., auto-generating product descriptions) or developer productivity (e.g., CLI-driven plugin scaffolding)?
   • Will the team use HTTP (remote agents) or stdio (local dev) transport, or both?
2. Security Requirements:
   • Are audit logging and rate limiting sufficient, or are additional safeguards (e.g., IP whitelisting) needed?
   • How will ACLs be configured for non-admin users accessing MCP tools?
3. Performance:
   • What are the expected query volumes for cursor-paginated tools (e.g., search_products)? Are there plans to optimize or cache responses?
   • How will the package handle concurrent AI agent requests during peak loads?
4. Extensibility:
   • Are there plans to extend the package with custom tools (e.g., for inventory management) or integrate with other MCP-compatible systems?
   • Will dynamic skills be used, and is the team prepared to maintain SKILL.md files?
5. Maintenance:
   • Who will monitor MCP-related logs and audit trails in production?
   • How will the team handle updates to the MCP protocol or Laravel 11+ dependencies?

Integration Approach

Stack Fit

• Laravel 11+: Native integration with Laravel’s service container, middleware, and Artisan. Leverages Laravel Passport for auth and Bouncer for ACL.
• UnoPim 1.0+: Optimized for UnoPim’s data model (products, categories, families, etc.). Assumes standard UnoPim table structures and relationships.
• PHP 8.2+: Uses modern PHP features (e.g., named arguments, attributes) but avoids experimental syntax.
• AI Agents: Compatible with MCP-supporting tools (Copilot, Claude, Cursor, Windsurf). Requires agent-side configuration (e.g., .vscode/mcp.json).
• Testing: Pest-compatible test suite covers tools, services, and security layers. Can integrate with Laravel’s testing helpers.

Migration Path

1. Pre-Integration:
   • Audit Laravel/UnoPim versions to ensure compatibility (PHP 8.2+, Laravel 11+, UnoPim 1.0+).
   • Review existing ACLs (Bouncer) and Passport setup if HTTP auth is required.
   • Allocate paths for allowed_paths (e.g., base_path(), sys_get_temp_dir()) and skills (base_path('.ai/skills')).
2. Installation:
   • Run composer require unopim/mcp and php artisan mcp:install.
   • Configure config/mcp.php (auth, rate limits, paths) and .env (e.g., MCP_API_AUTH=true).
   • Publish config and clear caches if needed.
3. Transport Setup:
   • HTTP: Configure Passport clients for AI agents. Test SSE endpoint (POST /api/mcp/unopim).
   • stdio: Register the server in AI editor configs (e.g., .vscode/mcp.json).
4. Tool Adoption:
   • Start with core tools (e.g., get_catalog_schema, search_products) for validation.
   • Gradually introduce dynamic skills or custom tools as needed.
5. Security Hardening:
   • Enable audit logging (MCP_AUDIT_LOGGING=true).
   • Adjust rate limits (MCP_RATE_LIMIT) based on expected usage.
   • Restrict allowed_paths to minimize file operation risks.

Compatibility

• UnoPim Customizations: If the catalog schema differs from UnoPim’s defaults (e.g., custom attributes), tools like get_catalog_schema may need extension via ToolRegistry.
• Non-UnoPim Laravel Apps: The package can be adapted for generic Laravel apps by replacing UnoPim-specific queries (e.g., in UnoPimQueryBuilder) with Eloquent or custom logic.
• AI Agent Versions: Ensure agents support MCP protocol (check documentation for Copilot, Claude, etc.). Older agents may require workarounds.
• Legacy Systems: If integrating with non-MCP systems, the HTTP transport can act as a bridge, but stdio tools will be inaccessible.

Sequencing

1. Phase 1: Core Integration (2–4 weeks):
   • Install and configure the package.
   • Test HTTP and stdio transports with a single AI agent (e.g., Copilot).
   • Validate core tools (get_catalog_schema, search_products, dev_tools).
2. Phase 2: Workflow Automation (2–3 weeks):
   • Implement dynamic skills for custom workflows (e.g., SKILL.md for inventory alerts).
   • Integrate with CI/CD (e.g., auto-generate tests via mcp:make test).
3. Phase 3: Security & Scaling (1–2 weeks):
   • Fine-tune ACLs, rate limits, and audit logging.
   • Load-test with simulated AI agent traffic.
4. Phase 4: Expansion (Ongoing):
   • Extend with custom tools or integrate with other MCP services.
   • Monitor performance and adjust caching/rate limits.

Operational Impact

Maintenance

• Configuration Drift: The package publishes config/mcp.php and uses .env variables, reducing manual config errors. However, changes to allowed_paths or rate limits require redeployment.
• Dependency Updates: Laravel 11+ and PHP 8.2+ dependencies may require updates during Laravel minor releases. Monitor unopim/mcp for compatibility patches.
• Skill Management: Dynamic skills (via SKILL.md) add flexibility but require manual maintenance. Document skill ownership and update processes.
• Audit Logs: Enable MCP_AUDIT_LOGGING to track destructive operations (e.g., upsert_products). Logs should be reviewed periodically for anomalies.

Support

• Troubleshooting: The package includes an mcp:inspector command for manual tool testing and a Troubleshooting Guide covering auth, connection, and tool errors.
• Error Handling: Tools return structured errors (e.g., 429 Too Many Requests for rate limits, 403 Forbidden for ACL violations). AI agents should handle these gracefully.
• Documentation: Comprehensive docs cover configuration, tool reference, and [extending the bridge](docs/ext