PHPackages unopim/mcp - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Security](/categories/security) 4. / 5. unopim/mcp ActiveLaravel-library[Security](/categories/security) unopim/mcp ========== UnoPim Model Context Protocol (MCP) bridge for AI-powered catalog interaction. v1.0.0(1mo ago)2131MITPHPPHP ^8.2 Since Apr 22Pushed 1mo agoCompare [ Source](https://github.com/unopim/unopim-mcp)[ Packagist](https://packagist.org/packages/unopim/mcp)[ RSS](/packages/unopim-mcp/feed)WikiDiscussions main Synced 1w ago READMEChangelog (1)Dependencies (4)Versions (2)Used By (0) UnoPim MCP Bridge ================= [](#unopim-mcp-bridge) Empower AI assistants (GitHub Copilot, Claude, Cursor, Windsurf) to interact with your UnoPim catalog, settings, and codebase using the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/). > The bridge exposes **two transports in one package**: > > ServerTransportBest 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 -------- [](#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 ------------------------ [](#-detailed-documentation) - **[Use Cases](docs/use-cases.md)**: Real-world scenarios for Catalog Managers, Developers, and Business Analysts. - **[Development Workflow](docs/development-workflow.md)**: How to integrate MCP into your daily coding routine for UnoPim. - **[Tool Reference](docs/tool-reference.md)**: Every tool with parameters, defaults, permissions, and query operators. - **[Configuration](docs/configuration.md)**: Every `config/mcp.php` key, the env vars that drive it, and a production checklist. - **[Troubleshooting](docs/troubleshooting.md)**: Fixes for the most common connection, auth, and tool-execution errors. - **[UnoPim vs. Akeneo MCP](docs/comparison-and-benefits.md)**: Why the UnoPim bridge is the superior choice for developers. - **[Extending the Bridge](docs/extending-mcp.md)**: Guide to creating custom "Skills" and implementing new Core Tools. Requirements ------------ [](#requirements) RequirementVersionPHP8.2+UnoPim1.0+Laravel11.0+--- 🛠️ Quick Start & Setup -------------------------- [](#️-quick-start--setup) ### 1. Installation [](#1-installation) Install the package via composer into your UnoPim root: ``` composer require unopim/mcp php artisan mcp:install ``` ### 2. Basic Configuration [](#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) [](#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 ----------------------------------- [](#-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` [](#vs-code--github-copilot--vscodemcpjson) ``` { "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` [](#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-code) ``` claude mcp add unopim-dev -- php artisan mcp:start unopim-dev ``` ### Windsurf — `~/.windsurf/mcp.json` [](#windsurf--windsurfmcpjson) ``` { "servers": { "unopim-dev": { "command": "php", "args": ["artisan", "mcp:start", "unopim-dev"], "cwd": "/path/to/your/unopim" } } } ``` --- Configuration (`config/mcp.php`) -------------------------------- [](#configuration-configmcpphp) `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](docs/configuration.md)**. --- Available Tools --------------- [](#available-tools) Source of truth: `packages/Webkul/MCP/src/Registry/ToolRegistry.php`. See [docs/tool-reference.md](docs/tool-reference.md) for parameters and permission mapping. ### Catalog (13 tools) [](#catalog-13-tools) ToolDescription`get_catalog_schema`Returns filterable fields, operators, and pagination info per entity.`search_products`Cursor-paginated product search with filters (max 100 per page).`get_product`Fetch full product details by ID or SKU with relationships and completeness.`upsert_products`Batch create/update products (max 50 per call, atomic transaction).`search_categories`Cursor-paginated category search with filters.`upsert_categories`Batch create/update categories (max 50 per call, atomic transaction).`search_attributes`Cursor-paginated attribute search with filters.`upsert_attributes`Batch create/update attributes (max 50 per call, atomic transaction).`search_attribute_options`Cursor-paginated search across attribute options.`search_families`Search attribute families.`upsert_families`Batch create/update attribute families.`search_attribute_groups`Search attribute groups.`upsert_attribute_groups`Batch create/update attribute groups.### Settings (4 tools) [](#settings-4-tools) ToolDescription`search_settings`Search channels or locales (pass `type`: `channels` or `locales`).`upsert_settings`Create/update channels or locales (max 50 per call).`search_currencies`Search currencies with filters.`upsert_currencies`Batch create/update currencies (max 50 per call).### Data Transfer (2 tools) [](#data-transfer-2-tools) ToolDescription`search_jobs`Search import/export job instances by `code`, `type`, `entity_type`, `action`.`get_job_execution`Fetch a single job execution (JobTrack) by ID with status, counts, and errors.### Developer Tools (6 core + dynamic) [](#developer-tools-6-core--dynamic) ToolDescription`dev_tools`Unified action tool with 6 actions: `create_file`, `read_file`, `update_file`, `run_command`, `generate_plugin`, `generate_test`.`run_skill`Execute a predefined skill from `.ai/skills/` by name.`get_app_info`Inspect the host app — Laravel/PHP versions, environment, installed packages.`get_database_schema`Introspect tables, columns, and relationships. Pass a `table` to scope.`run_database_query`Execute a read-only SQL query against the configured connection.`read_logs`Tail entries from `storage/logs/laravel.log` (and named log channels).Dynamic SkillsEach `SKILL.md` under `mcp.skills_path` is auto-registered as `execute_`.### Artisan Commands [](#artisan-commands) CommandDescription`php artisan mcp:install`Run Passport scaffolding (if installed), publish `config/mcp.php`, and clear caches.`php artisan mcp:make plugin [--type=connector|core-extension|generic]`Scaffold a complete UnoPim plugin.`php artisan mcp:make test `Generate a Pest test skeleton for a class.`php artisan mcp:dev`Alias for `mcp:start unopim-dev` — starts the stdio server for local coding agents.`php artisan mcp:start `Start an MCP server over stdio (provided by `laravel/mcp`).`php artisan mcp:inspector `Launch the MCP Inspector against a stdio handle (e.g. `unopim-dev`) or HTTP path (e.g. `mcp/unopim`).### MCP Resources & Prompts [](#mcp-resources--prompts) NameTypeDescription`catalog-schema`ResourceHigh-level catalog summary (product, category, attribute counts).`analyze-catalog`PromptGuided catalog analysis (completeness, consistency, optimization).--- Query Operators --------------- [](#query-operators) All search tools support the following filter operators: OperatorDescriptionExample`=`Equals`{"field": "status", "operator": "=", "value": "active"}``!=`Not equals`{"field": "type", "operator": "!=", "value": "bundle"}``IN`In list`{"field": "type", "operator": "IN", "value": ["simple", "configurable"]}``NOT IN`Not in list`{"field": "id", "operator": "NOT IN", "value": [1, 2]}``CONTAINS`Like %value%`{"field": "name", "operator": "CONTAINS", "value": "shirt"}``STARTS WITH`Like value%`{"field": "sku", "operator": "STARTS WITH", "value": "PRD"}``ENDS WITH`Like %value`{"field": "sku", "operator": "ENDS WITH", "value": "001"}``>`Greater than`{"field": "price", "operator": ">", "value": 100}``