Skip to content

ecomyseo/prestashop_skills / prestashop_psmcpserver

prestashop_psmcpserver

Verified

Make any PrestaShop module expose its business logic to AI agents through the official PrestaShop MCP Server (ps_mcp_server). Covers the discovery contract, a Composer-free PSR-4 autoloader, and ready-to-use templates for Tools, Resources, Resource Templates and Prompts.

PrestaShop MCP Server integration (ps_mcp_server)

Use this skill when a module must expose MCP elements (Tools / Resources / Prompts) to AI agents (Claude, ChatGPT, Gemini, MCP Inspector) via the official ps_mcp_server module. Reference module: ecom_desestimiento (its src/Mcp/ classes follow this skill exactly).

How ps_mcp_server discovers your module (the contract)

  1. Your main module class declares compliance:
    public function isMcpCompliant() { return true; }
    
    On its hooks/discovery, ps_mcp_server calls Module::getInstanceByName(...) on every installed module, checks method_exists($m,'isMcpCompliant') && $m->isMcpCompliant(), and registers compliant module IDs in ps_mcp_server's mcp_modules_registered table.
  2. For each registered module it scans the directory {module}/src (recursive, *.php, excludes index.php).
  3. For every file it tokenizes the namespace+class, runs class_exists($fqcn, true) (autoload!), then new ReflectionClass(...) and reads public methods for the attributes: #[PsMcpTool], #[PsMcpResource], #[PsMcpResourceTemplate], #[PsMcpPrompt].
  4. The module name is deduced from the file path /modules/{name}/..., not from the namespace. So your namespace can be anything; the files just have to live under modules/{your_module}/src/.
  5. Technical names are auto-prefixed: {module}-{toolName} and must be ≤ 64 chars total (longer = silently skipped).

Requirements: PrestaShop 8.2+, PHP 8.1+.

CRITICAL: Composer-free autoloading

The discoverer loads classes by reflection (class_exists(..., true)), not require_once. If your project forbids Composer (manual loading only), register a tiny SPL autoloader in the main module constructor. It is active during discovery because ps_mcp_server instantiates your module (getInstanceById) right before scanning.

public function __construct()
{
    // ... name, version, etc ...
    parent::__construct();
    self::registerMcpAutoload();
    // ... displayName, etc ...
}

public static function registerMcpAutoload()
{
    static $registered = false;
    if ($registered) { return; }
    $registered = true;

    spl_autoload_register(static function ($class) {
        $prefix = 'Vendor\\MyModule\\';                  // your namespace prefix
        $len = strlen($prefix);
        if (strncmp($class, $prefix, $len) !== 0) { return; }
        $relative = substr($class, $len);
        $file = _PS_MODULE_DIR_ . 'my_module/src/' . str_replace('\\', '/', $relative) . '.php';
        if (is_file($file)) { require_once $file; }
    });
}

If you DO use Composer, a composer.json PSR-4 autoload + committed vendor/autoload.php works too — then you can skip the SPL autoloader.

Attribute reference (exact signatures)

Ps* attributes live in PrestaShop\Module\PsMcpServer\Server\Attributes\ and extend the mcp/sdk ones:

  • #[PsMcpTool(?string $name, ?string $title, ?string $description, ?ToolAnnotations $annotations, ?array $icons, ?array $meta, ?array $outputSchema)]
  • #[PsMcpResource(string $uri, ?string $name, ?string $description, ?string $mimeType, ?int $size, ?Annotations $annotations, ...)]
  • #[PsMcpResourceTemplate(string $uriTemplate, ?string $name, ?string $description, ?string $mimeType, ...)]
  • #[PsMcpPrompt(?string $name, ?string $title, ?string $description, ?array $icons, ?array $meta)]
  • #[PsMcpSchema(?array $properties, ?array $required, ?string $type, ?array $items, ...)] — describes tool inputs.
  • PsMcpToolAnnotations(?string $title, ?bool $readOnlyHint, ?bool $destructiveHint, ?bool $idempotentHint, ?bool $openWorldHint)

GOTCHA: PsMcpToolAnnotations is NOT a standalone attribute

PsMcpToolAnnotations extends ToolAnnotations (it is not marked #[\Attribute]). Pass it inside the element attribute via the annotations: argument, using PHP 8.1 "new in initializers":

#[PsMcpTool(name: 'x', description: '...', annotations: new PsMcpToolAnnotations(readOnlyHint: true, destructiveHint: false))]

Do not write #[PsMcpToolAnnotations(...)] as its own method attribute — it is ignored and risks reflection errors.

Templates

Put each class in {module}/src/Mcp/ (or any subfolder of src/). Always guard with _PS_VERSION_ and require your own service classes at the top (loaded when the class is autoloaded inside PrestaShop). The use PrestaShop\Module\PsMcpServer\... lines are just aliases — they only resolve when ps_mcp_server reflects the class, so the file is safe to autoload even if ps_mcp_server is absent (attributes are evaluated only at reflection time).

Tool (read-only example)

namespace Vendor\MyModule\Mcp;

use PrestaShop\Module\PsMcpServer\Server\Attributes\PsMcpSchema;
use PrestaShop\Module\PsMcpServer\Server\Attributes\PsMcpTool;
use PrestaShop\Module\PsMcpServer\Server\Attributes\PsMcpToolAnnotations;
use PrestaShop\Module\PsMcpServer\Server\Exceptions\PsMcpToolCallException;

if (!defined('_PS_VERSION_')) { exit; }
require_once _PS_MODULE_DIR_ . 'my_module/classes/MyService.php';

class MyTools
{
    #[PsMcpTool(
        name: 'do_something',                       // becomes my_module-do_something
        description: 'Clear, explicit description for the AI. Say what it returns and when to use it.',
        annotations: new PsMcpToolAnnotations(readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false)
    )]
    #[PsMcpSchema(
        properties: [
            'orderId' => ['type' => 'integer', 'description' => 'Numeric order ID.'],
        ],
        required: ['orderId']
    )]
    public function doSomething(int $orderId = 0): array
    {
        if ($orderId <= 0) {
            throw new PsMcpToolCallException('orderId must be a positive integer.', 1);
        }
        $order = new \Order($orderId);
        if (!\Validate::isLoadedObject($order)) {
            throw new PsMcpToolCallException('Order not found.', 1);
        }
        return ['id' => (int) $order->id, 'reference' => (string) $order->reference];
    }
}

Rules: method params must match schema property names. Use core classes fully-qualified (\Order, \Configuration, \Validate, \Db). Validate inputs; keep results bounded; mark read-only tools readOnlyHint: true.

Resource (markdown or JSON)

use PrestaShop\Module\PsMcpServer\Server\Attributes\PsMcpResource;
use PrestaShop\Module\PsMcpServer\Server\Attributes\PsMcpToolAnnotations;
use PrestaShop\Module\PsMcpServer\Server\Exceptions\PsMcpResourceReadException;

class MyResources
{
    #[PsMcpResource(
        uri: 'mymodule://policy',
        name: 'My module policy',
        description: 'Stable knowledge the AI can read.',
        mimeType: 'application/json',
        annotations: new PsMcpToolAnnotations(readOnlyHint: true, destructiveHint: false)
    )]
    public function getPolicy(): array
    {
        try {
            return ['days' => (int) \Configuration::get('MYMODULE_DAYS')];
        } catch (\Throwable $e) {
            throw new PsMcpResourceReadException('Failed: ' . $e->getMessage(), 1);
        }
    }
}

Return a string for text/markdown resources, an array for application/json.

Resource Template (dynamic URI, RFC 6570)

#[PsMcpResourceTemplate(
    uriTemplate: 'mymodule://order/{id}',
    name: 'Order by ID',
    description: 'Returns an order by its numeric ID.',
    mimeType: 'application/json',
    annotations: new PsMcpToolAnnotations(readOnlyHint: true, destructiveHint: false)
)]
public function getOrder(int $id): array { /* ... */ }

Prompt

use PrestaShop\Module\PsMcpServer\Server\Attributes\PsMcpPrompt;
use PrestaShop\Module\PsMcpServer\Server\Exceptions\PsMcpPromptGetException;

class MyPrompts
{
    #[PsMcpPrompt(name: 'assistant', description: 'Prime the AI to use this module tools.')]
    public function assistant(): string
    {
        return "You are an assistant for ... Use the tools 'my_module-do_something' and the resource 'mymodule://policy'.";
    }
}

Prompt method parameters become prompt arguments (use the docblock @param for their descriptions; required if no default value).

Error handling

Wrap failures so the AI receives a clean message:

ElementException
ToolPsMcpToolCallException($message, $exitCode)
Resource / TemplatePsMcpResourceReadException(...)
PromptPsMcpPromptGetException(...)

Activation / testing

  1. Install + enable ps_mcp_server and your module.
  2. Force discovery: open ps_mcp_server config, or delete its .mcp/cache directory.
  3. Verify with the MCP Inspector or a connected AI client (token / OAuth).
  4. Tools/resources/prompts appear named {module}-{name}.

Checklist (copy for each module)

  • isMcpCompliant(): true in the main module class.
  • SPL autoloader registered in __construct (or Composer PSR-4) for your src/ namespace.
  • MCP classes under {module}/src/... with if (!defined('_PS_VERSION_')) exit; and index.php in every folder (it is excluded from scanning).
  • #[PsMcpTool] + #[PsMcpSchema] on each tool method; annotations: passed INSIDE #[PsMcpTool(...)].
  • Names ≤ 64 chars with the {module}- prefix; descriptions explicit and consistent.
  • Inputs validated; outputs bounded; read-only tools flagged.
  • Errors wrapped in the PsMcp*Exception classes.
  • Degrades silently when ps_mcp_server is absent (nothing loads your src/Mcp classes).

Notes / gotchas learned

  • The discoverer reflects classes; if your class can't be autoloaded it is skipped silently — the SPL autoloader is the usual culprit when nothing appears.
  • index.php files in src/ are skipped by the scanner (notName('index.php')), so they don't break discovery.
  • Keep tool logic in your existing service classes and call them from the MCP class — do not duplicate business rules.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall