Weave Code
UnoPim Model Context Protocol (MCP) bridge for AI-powered catalog interaction.
Frequently asked questions about Mcp
- How do I install and set up the unoPim MCP Bridge in Laravel 11+?
- Run `composer require unopim/mcp` followed by `php artisan mcp:install`. This generates the config file (`config/mcp.php`) and routes. Configure `APP_URL` and `MCP_RATE_LIMIT` in `.env`, then enable the transport (HTTP SSE or stdio) via the config. No additional dependencies beyond UnoPim 1.0+ are required.
- Does this package work with Laravel 10 or older versions?
- No, the package is built for Laravel 11+ and requires PHP 8.2+. It leverages Laravel’s modern features like enums and attributes, so downgrading isn’t supported. If you’re on Laravel 10, consider waiting for a major update or evaluating alternatives like direct HTTP API integrations.
- Can I use this bridge without UnoPim? What if I only need Laravel?
- This package is **hard-coupled** to UnoPim 1.0+ and relies on its repositories (e.g., `ProductRepository`). While you could theoretically abstract UnoPim’s services, the package’s core tools (e.g., `search_products`) are UnoPim-specific. For vanilla Laravel, explore generic MCP bridges or build a custom HTTP API.
- What’s the difference between HTTP SSE and stdio transports? Which should I use?
- HTTP SSE (`POST /api/mcp/unopim`) is for **remote AI agents** (e.g., cloud-based tools) and supports real-time streaming. Stdio (`php artisan mcp:start unopim-dev`) is for **local development** (e.g., Copilot, Cursor) and runs in your terminal. Use SSE for production workflows and stdio for local AI-assisted coding.
- How do I secure the MCP endpoint in production? Are there default protections?
- The package includes built-in security: **Path Traversal Guards** restrict file operations, **Command Whitelisting** blocks shell operators, and **ACL Enforcement** ties tools to UnoPim permissions (e.g., Bouncer). Enable `MCP_RATE_LIMIT` (default: 60 req/min) and audit logging via `config/mcp.php`. For HTTPS, ensure your Laravel app uses TLS.
- What are the performance implications for large catalogs (e.g., 1M+ products)?
- Batch operations (e.g., `upsert_products`) are capped at **50 items per call** to avoid database strain. For large catalogs, use Laravel’s **queue system** or **database transactions** to chunk operations. Ensure UnoPim’s search indexes (e.g., Elasticsearch) are optimized, as the bridge relies on them for `search_products` queries.
- Can I extend the bridge with custom tools or skills? How complex is it?
- Yes! Add **dynamic skills** by dropping a `SKILL.md` in `.ai/skills/`, or extend core tools via PHP classes. The package follows the **open/closed principle**, so you can add tools without modifying the core. Refer to `docs/extending-mcp.md` for step-by-step guides, including permission hooks and schema validation.
- Which AI agents (Copilot, Claude, etc.) are officially supported?
- The bridge is designed for **MCP-compatible agents** like GitHub Copilot, Claude Code, Cursor, and Windsurf. It also includes a **fallback HTTP JSON API** for agents without MCP support. Test compatibility by running `php artisan mcp:start unopim-dev` locally and verifying tool responses in your agent’s CLI.
- How do I handle rate limiting and throttling in production?
- Rate limiting is controlled by `MCP_RATE_LIMIT` (default: 60 requests/minute) in `.env`. For stricter limits, adjust this value or use Laravel’s **throttle middleware** on the `/api/mcp/unopim` route. Monitor usage via Laravel’s logs or integrate with tools like **Sentry** to track abuse patterns.
- What happens if UnoPim 1.1 breaks backward compatibility? Will this package still work?
- The package is tied to UnoPim 1.0+, so breaking changes (e.g., renamed repositories, deprecated services) may require updates. Monitor **UnoPim’s release notes** and the package’s **GitHub issues** for compatibility patches. If needed, fork the package or contact the maintainers for a major version update.
Weaver
How can I help you explore Laravel packages today?