McpServerPlugin

This MCP Server Plugin for Sylius exposes a Model Context Protocol (MCP) server that enables LLMs (like ChatGPT) to interact with your store through a set of pre-defined tools. Tools include common e-commerce operations such as searching products, fetching product data, managing orders, and performing checkout steps. The server runs the MCP runtime integrated with Sylius, allowing the AI to call these tools in a structured, function-like manner during a conversation. You can access the MCP endpoint either via a standard STDIO transport when running locally through the Symfony console or via HTTP endpoints as configured by the MCP bundle. The HTTP endpoint is typically available at /_mcp and can be consumed by your AI prompts or OpenAI-style tool calls.

To use it with your AI agent, configure a tool in your environment (e.g., OpenAI Playground) that points to http://your-host/_mcp and select the Sylius toolset (the defined server label “Sylius”). The agent will issue tool calls (e.g., search_products, fetch_product, create_order) which the MCP server will map to Sylius API interactions and return structured results for the agent to consume.

Out of the box, the server offers a suite of tools for common storefront tasks, including adding items to orders, completing checkouts, creating orders, fetching orders/products/variants, listing payment and shipping methods, and updating addresses. You can also extend functionality by adding your own tools using PHP classes annotated with the MCP tool attribute, then registering them as services so they become available to the MCP server.

Prerequisites:

• PHP 8.2 or higher
• Sylius 2.1 or higher
• Node.js is not required for the MCP server, which runs via Symfony/PHP in this setup
• Access to composer for PHP dependencies

Installation steps:

1. Require the plugin via Composer:

composer require sylius/mcp-server-plugin

2. If using Symfony Flex, clear the cache after installation:

bin/console cache:clear

3. If not using Symfony Flex, import configuration and routes as described in the plugin documentation:

# config/packages/sylius_mcp_server.yaml
imports:
    - { resource: "@SyliusMcpServerPlugin/config/config.yaml" }

# config/routes.yaml
sylius_mcp_server:
    resource: '@SyliusMcpServerPlugin/config/routes.yaml'

4. Start or prepare your Symfony environment to run the MCP server via the CLI:

# Run the MCP server (STDIO transport)
bin/console mcp:server

5. Verify the HTTP endpoint (if enabled by configuration) at /_mcp for tool calls from your AI agent, and ensure the base API URI is configured as environment variable if you rely on the Sylius API client within the MCP server.

6. Configure the shop API base URI (as needed by the server tools) via environment variable or Symfony parameters, for example SYLIUS_MCP_SERVER_API_SHOP_BASE_URI.

• The MCP Server exposes a set of ready-to-use tools for common Sylius operations. You can extend functionality by adding new tools written as PHP classes annotated with #[McpTool] and exposing them via the service container.
• By default, many tools operate in guest mode; note that fetch_order will return data only for orders without an associated customer account.
• The HTTP endpoint for MCP interactions is typically at /_mcp; ensure your web server and firewall allow traffic to this path when integrating with an external agent.
• The Sylius API base URI is configurable and defaults to http://localhost:8000/api/v2/shop/. Override this using the environment variable SYLIUS_MCP_SERVER_API_SHOP_BASE_URI to point to your real storefront API.
• If you run into CORS or authentication issues, verify that the HTTP client configuration in Sylius is compatible with the MCP server’s transport and that the AI tool is allowed to make requests to the SAP endpoint.
• For production deployments, consider securing access to the MCP endpoint and managing credentials if you expose it to external AI services.