Mcp Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require unopim/mcp
   php artisan mcp:install
   

   This publishes the config file and sets up Passport (if installed).

2. First Use Case:

   • For AI Agents (Copilot, Cursor, etc.): Start the stdio server:

     php artisan mcp:dev
     

     Configure your AI editor (e.g., VS Code .vscode/mcp.json) to use this server.

   • For HTTP Access: Ensure APP_URL is set in .env and test the endpoint:

     curl -X POST http://your-unopim-site/api/mcp/unopim -H "Authorization: Bearer YOUR_TOKEN"
     

3. Quick Test: Run the inspector to verify functionality:

   php artisan mcp:inspector unopim-dev
   

   This launches a web interface to manually test tools.

Implementation Patterns

Daily Workflows

1. Catalog Management:

   • Search and Filter: Use search_products with cursor pagination for large datasets:

     {
       "tool": "search_products",
       "params": {
         "filters": [
           {"field": "status", "operator": "=", "value": "active"},
           {"field": "price", "operator": ">=", "value": 50}
         ],
         "page": 1,
         "per_page": 50
       }
     }
     

   • Batch Updates: Use upsert_products for atomic batch operations (max 50 items):

     {
       "tool": "upsert_products",
       "params": {
         "products": [
           {"sku": "PRD001", "name": "Updated Product", "price": 69.99},
           {"sku": "PRD002", "name": "Another Product", "price": 49.99}
         ]
       }
     }
     

2. Developer Tools:

   • File Operations: Use dev_tools with create_file or update_file actions:

     {
       "tool": "dev_tools",
       "params": {
         "action": "create_file",
         "path": "app/Http/Controllers/ProductController.php",
         "content": "<?php namespace App\\Http\\Controllers; ..."
       }
     }
     

   • Plugin Scaffolding: Generate a plugin skeleton:

     php artisan mcp:make plugin MyCustomPlugin --type=connector
     

3. AI-Assisted Development:

   • Dynamic Skills: Create a SKILL.md in .ai/skills/ to define custom workflows. Example:

     ---
     name: generate_product_test
     description: Generates a Pest test for a product
     parameters:
       sku:
         type: string
         required: true
     ---
     

     Execute it via:

     {
       "tool": "run_skill",
       "params": {
         "skill_name": "generate_product_test",
         "sku": "PRD001"
       }
     }
     

4. Schema Discovery: Use get_catalog_schema to dynamically explore available fields and operators:

   {
     "tool": "get_catalog_schema",
     "params": {
       "entity": "products"
     }
   }
   

Integration Tips

• Leverage Resources: Use catalog-schema resource for AI prompts to guide users in constructing valid queries.
• Rate Limiting: Monitor MCP_RATE_LIMIT (default: 60 requests/minute/tool/IP) to avoid throttling during bulk operations.
• Audit Logging: Enable MCP_AUDIT_LOGGING to track destructive operations for compliance or debugging.
• Security: Restrict allowed_paths in config/mcp.php to prevent path traversal attacks in file operations.

Gotchas and Tips

Pitfalls

1. Rate Limiting:

   • Issue: Rapid-fire requests (e.g., from an AI agent) may hit the default 60 requests/minute limit.
   • Fix: Adjust MCP_RATE_LIMIT in config/mcp.php or implement client-side throttling.

2. Batch Size Limits:

   • Issue: Tools like upsert_products enforce a 50-item limit per call. Exceeding this returns an error.
   • Fix: Split large batches into chunks or use cursor pagination for searches.

3. Path Traversal:

   • Issue: Attempting to access files outside allowed_paths (e.g., /etc/passwd) fails silently or logs an error.
   • Fix: Double-check allowed_paths in config/mcp.php and use absolute paths for file operations.

4. Command Injection:

   • Issue: Malicious input in dev_tools with run_command action may bypass whitelisting.
   • Fix: Ensure dev_tools actions are restricted to trusted commands (e.g., php artisan, composer).

5. ACL Bypass:

   • Issue: CLI tools (e.g., mcp:dev) bypass ACL checks, which may expose sensitive operations.
   • Fix: Use HTTP transport for production and enforce auth:api in config/mcp.php.

6. Skill Caching:

   • Issue: Changes to SKILL.md files aren’t reflected immediately if MCP_ENABLE_CACHE is true.
   • Fix: Clear the cache:

     php artisan cache:clear
     

Debugging

1. Inspector Tool: Use php artisan mcp:inspector to manually test tools and inspect responses. This is invaluable for debugging tool parameters or schema issues.

2. Audit Logs: Check storage/logs/laravel.log for audit entries when MCP_AUDIT_LOGGING is enabled. Look for:

   • MCP_Audit: Tool [tool_name] called by [user_id]@[ip]
   • Errors like MCP_PathTraversalAttempt or MCP_CommandBlocked.

3. Tool Registry: Verify tool availability via:

   php artisan mcp:inspector unopim-dev --list-tools
   

   This lists all registered tools and their parameters.

4. Query Operators:

   • Gotcha: CONTAINS is case-sensitive. Use LOWER() in SQL queries if case-insensitive searches are needed.
   • Tip: Combine operators for complex filters:

     {
       "filters": [
         {"field": "name", "operator": "CONTAINS", "value": "shirt"},
         {"field": "price", "operator": ">", "value": 20},
         {"field": "status", "operator": "IN", "value": ["active", "pending"]}
       ]
     }
     

Extension Points

1. Custom Skills:

   • How: Drop a SKILL.md in .ai/skills/ with YAML frontmatter defining parameters and metadata.
   • Example: Create a skill to auto-generate product descriptions:

     ---
     name: generate_product_descriptions
     description: Generates SEO-friendly descriptions for products
     parameters:
       skus:
         type: array
         required: true
       tone:
         type: string
         enum: ["technical", "casual", "luxury"]
         default: "casual"
     ---
     

   • Trigger: Call via run_skill tool with skill_name: generate_product_descriptions.

2. Override Tools:

   • How: Extend BaseMcpTool or override methods in UnoPimAgentServer to customize behavior.
   • Example: Add a validate_products tool by creating a class in app/MCP/Tools/Catalog/ValidateProductsTool.php and registering it in the service provider.

3. Dynamic Prompts:

   • How: Extend the Prompts directory to add custom analysis prompts (e.g., analyze_product_completeness).
   • Tip: Use the catalog-schema resource to dynamically generate prompt templates.

4. Media Tools:

   • Future-Proofing: Configure allowed_extensions and allowed_mimes in config/mcp.php for upcoming media upload tools.

Configuration Quirks

1. API Authentication:

   • HTTP Transport: Requires auth:api (Passport) by default. Disable with MCP_API_AUTH=false in .env (not recommended for production).
   • CLI Transport: Bypasses auth for local development. Use HTTP transport for production.

2. Skills Path:

   • Default: .ai/skills/. Change via MCP_SKILLS_PATH in .env or config/mcp.php.
   • Tip: Symlink skills across projects to reuse workflows.

3. Rate Limiting:

   • Granularity: Limits are enforced per tool, client IP, and minute window. Adjust `MCP_RATE_LIMIT