Mcp Laravel Package

Technical Evaluation

Architecture Fit

• Laravel Native Integration: The package is purpose-built for Laravel 11+ and UnoPim, leveraging Laravel’s service providers, Artisan commands, and Passport for authentication. This ensures seamless integration with existing Laravel ecosystems (e.g., middleware, queues, caching).
• 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, ensuring compatibility with AI agents (Copilot, Claude, etc.) and future-proofing against protocol updates.
• Security-by-Design: Hardened against common vulnerabilities (path traversal, command injection) with configurable ACLs, rate limiting, and audit logging. Leverages Laravel Passport for HTTP auth, reducing custom security overhead.

Integration Feasibility

• UnoPim Dependency: Tightly coupled with UnoPim 1.0+, requiring alignment with its data models (e.g., Product, Attribute, Family). Pre-integration validation of UnoPim schema compatibility is critical.
• Laravel 11+ Requirement: May necessitate PHP/Laravel upgrades, especially if the target system uses older versions (e.g., Laravel 10). Composer dependencies (e.g., laravel/mcp) must align with the host environment.
• Artisan Command Overhead: Introduces 6 new Artisan commands (e.g., mcp:install, mcp:dev), which may require CLI access permissions and could conflict with existing commands.
• Database Introspection: Tools like get_database_schema and run_database_query assume direct database access. Compatibility with custom query builders or ORMs (e.g., Eloquent) must be tested.

Technical Risk

• AI Agent Dependency: Relies on external AI tools (e.g., GitHub Copilot) for full functionality. Internal teams without AI integration may see limited value.
• Performance Impact:
  • Rate Limiting: Default 60 req/min per tool per client may throttle high-frequency AI queries. Adjustments to config/mcp.php may be needed.
  • Batch Operations: Atomic upserts (max 50 items) could strain database transactions for large catalogs. Testing with production-scale data is essential.
• Security Misconfiguration: Incorrect allowed_paths or rate_limit settings could expose the system to abuse. Audit logging (MCP_AUDIT_LOGGING) must be enabled in production.
• Dynamic Skills Complexity: Custom SKILL.md files introduce runtime parsing overhead and potential skill conflicts. Validation of skill YAML syntax and parameter types is required.

Key Questions

1. Use Case Alignment:
   • Is the primary goal AI-assisted catalog management (e.g., Copilot for PIM workflows) or internal tooling (e.g., CLI-driven operations)?
   • Will the HTTP SSE endpoint be exposed to external AI agents, or is stdio-only usage sufficient?
2. UnoPim Customization:
   • Are there custom UnoPim extensions (e.g., plugins, attributes) that require MCP tool overrides or new skills?
   • How does the package handle UnoPim’s multi-tenancy if applicable?
3. Performance:
   • What are the expected query volumes for search_products/search_categories? Are cursor-paginated results feasible for large datasets?
   • How will the dev_tools (e.g., run_command) impact server resources during peak usage?
4. Security:
   • Are there existing Laravel Passport clients configured for auth:api? If not, additional setup is required.
   • Should MCP_API_AUTH be disabled for internal stdio usage, or is token-based auth mandatory?
5. Maintenance:
   • Who will manage SKILL.md files and dynamic tools? Is there a governance process for skill approval?
   • How will the package be updated alongside UnoPim and Laravel versions?

Integration Approach

Stack Fit

• Laravel 11+: Native support for Laravel’s service container, routing, and Passport. No major framework conflicts expected.
• UnoPim 1.0+: Direct integration with UnoPim’s Eloquent models (Product, Attribute, etc.). Custom UnoPim plugins may require MCP tool extensions.
• PHP 8.2+: Leverages modern PHP features (e.g., enums, attributes) but avoids breaking changes. Composer autoloading is optimized.
• AI Agents: Compatible with MCP-supporting editors (Copilot, Cursor, Claude) via stdio/HTTP. Non-MCP agents will require custom adapters.

Migration Path

1. Pre-Integration:
   • Audit Laravel/UnoPim versions. Upgrade if necessary (e.g., PHP 8.2+, Laravel 11).
   • Backup config/ and storage/logs/ directories.
   • Review existing Artisan commands for naming conflicts (e.g., mcp:dev vs. custom dev: commands).
2. Installation:

   composer require unopim/mcp
   php artisan mcp:install
   

   • Publishes config/mcp.php (merge with existing configs if needed).
   • Sets up Passport scaffolding (if installed).
3. Configuration:
   • Update .env:

     MCP_API_AUTH=true
     MCP_RATE_LIMIT=120  # Adjust based on expected load
     MCP_AUDIT_LOGGING=true
     

   • Configure allowed_paths in config/mcp.php to restrict file operations.
4. Testing:
   • Run the inspector to validate tools:

     php artisan mcp:inspector unopim-dev
     

   • Test critical workflows (e.g., upsert_products, dev_tools).
5. AI Agent Setup:
   • Configure editors (VS Code, Cursor) with stdio/HTTP endpoints (see README).
   • Example for Copilot:

     // .vscode/mcp.json
     {
       "servers": {
         "unopim-dev": {
           "command": "php",
           "args": ["artisan", "mcp:dev"],
           "cwd": "/path/to/unopim"
         }
       }
     }
     

Compatibility

• Existing Tools:
  • Laravel Passport: Required for HTTP auth. If not installed, run composer require laravel/passport and php artisan passport:install.
  • Queue Workers: Tools like upsert_products use queues for batch operations. Ensure queue workers (e.g., Redis, database) are running.
  • File System: dev_tools requires write access to allowed_paths. Test with a staging environment first.
• UnoPim Customizations:
  • Override tools by extending UnoPimAgentServer or registering custom skills in .ai/skills/.
  • Example custom skill:

    # .ai/skills/validate-catalog/SKILL.md
    ---
    name: validate-catalog
    description: Checks product completeness and consistency
    parameters:
      family_id:
        type: integer
        required: true
    ---
    

Sequencing

1. Phase 1: Core Integration (2–4 weeks):
   • Install and configure MCP.
   • Test catalog tools (search_products, upsert_products) with a subset of data.
   • Validate security settings (ACLs, rate limiting).
2. Phase 2: AI Agent Onboarding (1–2 weeks):
   • Configure editors (Copilot, Cursor) with stdio/HTTP endpoints.
   • Develop prompts/resources (e.g., catalog-schema) for AI-assisted workflows.
3. Phase 3: Advanced Features (2–3 weeks):
   • Implement custom skills for niche use cases.
   • Extend dev_tools for CI/CD or plugin scaffolding.
   • Optimize batch operations for large datasets.
4. Phase 4: Production Rollout:
   • Enable audit logging and monitoring.
   • Train teams on MCP tools and AI integration.

Operational Impact

Maintenance

• Configuration Management:
  • Centralized in config/mcp.php with .env overrides. Use Laravel’s config caching (php artisan config:cache) in production.
  • Monitor MCP_RATE_LIMIT and adjust based on AI agent usage patterns.
• Skill Maintenance:
  • Dynamic skills (SKILL.md) require version control and peer review. Document skill ownership and update processes.
  • Cache invalidation: Clear mcp.skills cache (php artisan cache:forget mcp.skills) after skill updates.
• Dependency Updates:
  • Monitor unopim/mcp and laravel/mcp for breaking changes. Test upgrades in staging before production.

Support

• Troubleshooting:
  • Use php artisan mcp:inspector for interactive tool testing.
  • Check `storage/logs/laravel