README

Empower AI assistants (GitHub Copilot, Claude, Cursor, Windsurf) to interact with your UnoPim catalog, settings, and codebase using the Model Context Protocol (MCP).

The bridge exposes two transports in one package:

Server	Transport	Best for
HTTP Agent	POST /api/mcp/unopim (SSE)	Remote AI assistants, PIM workflows
stdio Agent	php artisan mcp:start unopim-dev	Coding agents (Copilot, Cursor, Claude Code)

Features

• Full Catalog CRUD — Search, get, and upsert products, categories, and attributes with cursor-paginated results and atomic batch operations (up to 50 items per call).
• Catalog Schema Discovery — get_catalog_schema returns filterable fields, supported operators, and pagination info for every entity type.
• Settings Management — Search and upsert channels and locales via unified search_settings / upsert_settings tools.
• Developer Tools — AI-driven file management, safe Artisan/Composer execution, plugin scaffolding, and test generation via the unified dev_tools action tool.
• Dynamic AI Skills — Drop a SKILL.md into .ai/skills/ and it becomes an MCP tool — no code required.
• Security — Production-hardened with Path Traversal protection, Command Whitelisting, Rate Limiting, ACL enforcement, and Audit Logging.
• Comprehensive Test Suite — Unit and feature tests covering all tools, services, and security layers.

📖 Detailed Documentation

• Use Cases: Real-world scenarios for Catalog Managers, Developers, and Business Analysts.
• Development Workflow: How to integrate MCP into your daily coding routine for UnoPim.
• Tool Reference: Every tool with parameters, defaults, permissions, and query operators.
• Configuration: Every config/mcp.php key, the env vars that drive it, and a production checklist.
• Troubleshooting: Fixes for the most common connection, auth, and tool-execution errors.
• UnoPim vs. Akeneo MCP: Why the UnoPim bridge is the superior choice for developers.
• Extending the Bridge: Guide to creating custom "Skills" and implementing new Core Tools.

Requirements

🛠️ Quick Start & Setup

1. Installation

Install the package via composer into your UnoPim root:

composer require unopim/mcp
php artisan mcp:install

2. Basic Configuration

Ensure APP_URL is set in your .env. If you plan to use the HTTP transport (SSE) for remote access, you may need to generate an API token for your user.

3. Usage (The 10-Second Test)

To verify everything is working, run the inspector:

php artisan mcp:inspector unopim-dev

This will launch a web interface where you can test each tool manually.

🔌 Connecting to AI Editors / Agents

Register the MCP server in your editor's config file. Both HTTP and stdio transports are supported.

VS Code / GitHub Copilot — .vscode/mcp.json

{
    "servers": {
        "unopim-dev": {
            "command": "php",
            "args": ["artisan", "mcp:start", "unopim-dev"],
            "cwd": "/path/to/your/unopim"
        },
        "unopim-http": {
            "url": "http://127.0.0.1:8000/api/mcp/unopim",
            "type": "http"
        }
    }
}

Cursor — Preferences > Models > MCP

Add a new MCP server with the following settings:

• Type: command
• Command: php artisan mcp:start unopim-dev

Claude Code

claude mcp add unopim-dev -- php artisan mcp:start unopim-dev

claude.ai — Remote Custom Connector (OAuth)

No manual setup is required — the package registers everything at boot: OAuth discovery + dynamic client registration endpoints, the Passport admin guard binding, a login route alias to the admin login page, and the guard-bridge middleware that maps the Passport token user onto UnoPim's ACL (bouncer()).

1. Make sure Passport keys exist: php artisan passport:keys (skip if already generated).
2. In claude.ai go to Settings > Connectors > Add custom connector.
3. Enter your MCP endpoint: https://your-unopim-host/mcp/unopim.
4. Complete the OAuth flow — you are redirected to the UnoPim admin login, then back to claude.ai.

Tool calls respect the connected admin's ACL permissions.

Windsurf — ~/.windsurf/mcp.json

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

Configuration (config/mcp.php)

mcp:install publishes the config file via the mcp-config tag. The published file mirrors packages/Webkul/MCP/src/Config/mcp.php:

return [
    // Require a Bearer token (Passport `auth:api`) for HTTP MCP endpoints.
    'api_auth' => env('MCP_API_AUTH', true),

    // Max requests per minute per tool per caller (IP for HTTP, "cli" for stdio).
    'rate_limit' => env('MCP_RATE_LIMIT', 60),

    // FileManager / dev-tool jail. Anything outside is rejected.
    'allowed_paths' => [
        base_path(),
        sys_get_temp_dir(),
    ],

    // Log every destructive tool call (upserts, dev_tools mutations).
    'audit_logging' => env('MCP_AUDIT_LOGGING', true),

    // Where SkillLoader looks for SKILL.md files.
    'skills_path' => env('MCP_SKILLS_PATH', base_path('.ai/skills')),

    // Skill registry caching.
    'enable_cache' => env('MCP_ENABLE_CACHE', true),
    'cache_key'    => 'mcp.skills',
    'cache_ttl'    => env('MCP_CACHE_TTL', 3600),

    // Reserved for upcoming media tools.
    'media' => [
        'allowed_extensions' => ['jpg', 'jpeg', 'png', 'gif', 'webp', 'svg', 'pdf', 'csv', 'xlsx'],
        'allowed_mimes'      => [
            'image/jpeg', 'image/png', 'image/gif', 'image/webp', 'image/svg+xml',
            'application/pdf', 'text/csv', 'text/plain',
            'application/vnd.ms-excel',
            'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
        ],
    ],
];

Per-key behavior, env-var mapping, and a production checklist live in docs/configuration.md.

Available Tools

Source of truth: packages/Webkul/MCP/src/Registry/ToolRegistry.php. See docs/tool-reference.md for parameters and permission mapping.

Catalog (13 tools)

Settings (4 tools)

Data Transfer (2 tools)

Developer Tools (6 core + dynamic)

Artisan Commands

MCP Resources & Prompts

Query Operators

All search tools support the following filter operators:

Dynamic Skills

Create a SKILL.md file with YAML frontmatter in .ai/skills/<skill-name>/SKILL.md:

---
name: My Custom Skill
description: Automates a specific workflow
license: MIT
parameters:
  query:
    type: string
    required: true
metadata:
  author: your-name
---

# Instructions

Describe what this skill does and how to use it.

The skill is automatically discovered, cached, and registered as an MCP tool named execute_my_custom_skill.

Security Policy

The UnoPim MCP Bridge implements multi-layer security:

1. Request Authentication: HTTP SSE endpoints default to auth:api (OAuth2 via Laravel Passport).
2. Rate Limiting: Configurable per-minute limit per tool per client IP (default: 60 req/min).
3. Path Traversal Guard: All file operations are jailed within configured allowed_paths with ./.. normalization.
4. Command Whitelisting: Only php artisan and composer base commands are allowed. Shell operators (;, &, |, `, $(), <, >) are blocked.
5. ACL Mapping: Every MCP tool maps to internal UnoPim permissions via bouncer(). CLI bypasses ACL for local development.
6. Audit Logging: All destructive operations (upsert, create, update) are logged with user ID, IP, tool name, and arguments.
7. MIME Validation Config: Media upload restrictions are defined in config/mcp.php for future media tool implementations.

Architecture

packages/Webkul/MCP/
├── src/
│   ├── Config/mcp.php                    # Configuration (auth, rate limits, paths, media)
│   ├── Console/Commands/                  # Artisan commands (install, make, dev, inspector)
│   ├── Contracts/                         # FileManagerInterface, SkillExecutorInterface
│   ├── DevTools/                          # FileManager, CommandRunner, PluginGenerator, TestGenerator
│   ├── Prompts/Catalog/                   # CatalogAnalysisPrompt
│   ├── Providers/MCPServiceProvider.php   # Service registration, route loading
│   ├── Registry/ToolRegistry.php          # Static registry of 25 core tools
│   ├── Resources/Catalog/                 # CatalogSchemaResource
│   ├── Routes/mcp-routes.php             # HTTP endpoint registration (POST /api/mcp/unopim)
│   ├── Servers/
│   │   ├── UnoPimAgentServer.php          # Main MCP server (tools, resources, prompts, skills)
│   │   └── Methods/PimCallTool.php        # Auth, rate limiting, ACL, audit proxy
│   ├── Services/                          # SkillExecutor, SkillLoader, SkillParser, UnoPimQueryBuilder
│   └── Tools/
│       ├── BaseMcpTool.php                # Abstract base with error handling
│       ├── Catalog/                       # 13 catalog tools (schema, products, categories, attributes, families, groups, options)
│       ├── DataTransfer/                  # JobSearchTool, JobExecutionTool
│       ├── Dev/                           # DevToolsTool, RunSkillTool, DynamicSkillTool, AppInfoTool, DatabaseSchemaTool, DatabaseQueryTool, LogReadTool
│       └── Settings/                      # SettingSearchTool, SettingUpsertTool, CurrencySearchTool, CurrencyUpsertTool
├── tests/
│   ├── Pest.php                           # Pest configuration
│   ├── MCPTestCase.php                    # Base test class
│   ├── Unit/                              # 10 unit test files
│   └── Feature/                           # 11 feature test files
├── composer.json
├── README.md
├── CHANGELOG.md
└── LICENSE.md

Testing

Run the full test suite:

cd packages/Webkul/MCP
../../vendor/bin/pest

Or from project root:

./vendor/bin/pest --filter=MCP

The test suite covers:

• Unit tests: FileManager, CommandRunner, PluginGenerator, TestGenerator, SkillParser, SkillLoader, SkillExecutor, UnoPimQueryBuilder, PimCallTool, ToolRegistry
• Feature tests: Catalog CRUD, Settings management, Bulk operations, Security, DevTools integration, Dynamic Skills, Server registration, Artisan commands

License

The MIT License (MIT). See LICENSE.md for details.