Getting Started

Minimal Steps

Installation:
```
composer require unopim/mcp
php artisan mcp:install
```
This publishes the config file and sets up Passport (if installed).

First Use Case:

For local AI integration (Copilot, Cursor, etc.):
```
php artisan mcp:dev
```
Then configure your AI editor to use the unopim-dev stdio server (see README.md).

For remote AI access (HTTP/SSE): Ensure APP_URL is set in .env and test with:

curl -X POST http://your-unopim-site.test/api/mcp/unopim \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"action": "get_catalog_schema"}'

Quick Test: Run the MCP Inspector to manually test tools:
```
php artisan mcp:inspector unopim-dev
```
This launches a web UI where you can interactively call any MCP tool.

Implementation Patterns

Daily Workflows

1. Catalog Management

Searching Products: Use search_products with cursor pagination for large datasets:

{
  "action": "search_products",
  "filters": [
    {"field": "status", "operator": "=", "value": "active"},
    {"field": "price", "operator": ">=", "value": 50}
  ],
  "limit": 50,
  "cursor": null
}

Tip: Always check get_catalog_schema first to confirm available fields and operators.

Batch Upserts: Use upsert_products for bulk updates (max 50 items per call):

{
  "action": "upsert_products",
  "products": [
    {"sku": "PRD001", "name": "Updated Product", "price": 99.99},
    {"sku": "PRD002", "name": "New Product", "price": 49.99}
  ]
}

Workflow: Export products from a spreadsheet → Transform to JSON → Upsert via MCP.

2. Developer Workflows

File Management: Use dev_tools with create_file or update_file actions:

{
  "action": "dev_tools",
  "tool": "create_file",
  "params": {
    "path": "app/Services/NewService.php",
    "content": "<?php namespace App\\Services; class NewService { ... }"
  }
}

Safety: Files are created within allowed_paths (configured in config/mcp.php).

Plugin Scaffolding: Generate a new plugin skeleton:
```
php artisan mcp:make plugin MyConnector --type=connector
```
- Integration: The generated plugin follows UnoPim’s conventions and can be extended via MCP tools.
Test Generation: Auto-generate Pest tests for a class:
```
php artisan mcp:make test App\\Services\\ProductService ProductServiceTest
```
- Use Case: Rapidly scaffold tests for new or modified services.

3. AI-Assisted Development

Dynamic Skills: Create a SKILL.md in .ai/skills/ to define custom workflows. Example:
```
---
name: generate-product-mock
description: Generates a mock product based on a description
parameters:
  description:
    type: string
    required: true
---
```
- Execution: The skill becomes available as execute_generate_product_mock in your AI editor.

Database Introspection: Use get_database_schema to explore tables:

{
  "action": "get_database_schema",
  "table": "products"
}

Follow-up: Use run_database_query to execute read-only queries:

{
  "action": "run_database_query",
  "query": "SELECT * FROM products WHERE price > 100 LIMIT 10"
}

4. Settings Management

Search/Update Channels:

{
  "action": "search_settings",
  "type": "channels",
  "filters": [{"field": "code", "operator": "CONTAINS", "value": "web"}]
}

Upsert:

{
  "action": "upsert_settings",
  "type": "channels",
  "settings": [{"code": "new_channel", "name": "New Channel", "enabled": true}]
}

Integration Tips

AI Editor Configuration:
- For VS Code/GitHub Copilot, use the stdio transport (php artisan mcp:dev).
- For remote AI tools, use the HTTP endpoint (/api/mcp/unopim) with SSE.
Rate Limiting:
- Adjust MCP_RATE_LIMIT in .env (default: 60 requests/minute per tool per client).
- Monitor logs for 429 Too Many Requests errors.
Security:
- Enable MCP_API_AUTH (default: true) to require API tokens for HTTP endpoints.
- Restrict allowed_paths in config/mcp.php to sandbox file operations.
Audit Logging:
- Enable MCP_AUDIT_LOGGING to log destructive operations (e.g., upsert_products).
- Review logs in storage/logs/laravel.log for compliance or debugging.
Dynamic Skills:
- Place SKILL.md files in .ai/skills/ to extend functionality without code changes.
- Skills are auto-discovered and cached (TTL: 1 hour by default).

Gotchas and Tips

Pitfalls

Path Traversal:
- Issue: Attempting to access files outside allowed_paths (e.g., /etc/passwd) will fail with a 403 Forbidden.
- Fix: Ensure allowed_paths in config/mcp.php includes only trusted directories (e.g., base_path(), sys_get_temp_dir()).
Command Injection:
- Issue: The dev_tools action blocks shell operators (;, &, |, etc.) and restricts commands to php artisan and composer.
- Fix: If you need custom commands, extend the CommandRunner service or use run_database_query for SQL-based operations.
Rate Limiting:
- Issue: Exceeding MCP_RATE_LIMIT (default: 60/min) returns 429 Too Many Requests.
- Fix: Adjust the limit in .env or implement exponential backoff in your client.
ACL Bypass:
- Issue: CLI tools (e.g., mcp:dev) bypass ACL checks for local development.
- Fix: Disable mcp:dev in production or restrict access via config/mcp.php.
Cursor Pagination:
- Issue: Forgetting to pass the cursor in subsequent search_* calls may return duplicate or incomplete results.
- Fix: Always use the cursor field from the previous response:
```
{
  "data": [...],
  "cursor": "eyJzY29wZSI6I..."
}
```
Batch Size Limits:
- Issue: upsert_* tools enforce a 50-item limit per call.
- Fix: Split large batches into chunks or use a loop in your client code.
Skill Discovery:
- Issue: Dynamic skills (SKILL.md) may not update immediately if caching is enabled.
- Fix: Clear the cache with php artisan cache:clear or adjust MCP_CACHE_TTL.

Debugging

Tool Errors:
- Check storage/logs/laravel.log for detailed error messages.
- Use the mcp:inspector to test tools interactively.
HTTP Endpoint Issues:
- Verify APP_URL and MCP_API_AUTH in .env.
- Ensure the auth:api middleware is properly configured (requires Passport).
stdio Transport:
- If the AI editor fails to connect, check:
  - The unopim-dev server is running (php artisan mcp:dev).
  - The working directory (cwd) in the editor config matches your UnoPim root.
Permission Denied:
- For ACL errors, verify the user has the required permissions in UnoPim’s Bouncer system.
- Use get_app_info to inspect the current user’s permissions:
```
{
  "action": "get_app_info"
}
```

Extension Points

Custom Tools:
- Extend the `

Mcp Laravel Package