ecomyseo/prestashop_skills / prestashop_psmcpserver
prestashop_psmcpserver
VerifiedMake 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)
- Your main module class declares compliance:
On its hooks/discovery,public function isMcpCompliant() { return true; }ps_mcp_servercallsModule::getInstanceByName(...)on every installed module, checksmethod_exists($m,'isMcpCompliant') && $m->isMcpCompliant(), and registers compliant module IDs inps_mcp_server'smcp_modules_registeredtable. - For each registered module it scans the directory
{module}/src(recursive,*.php, excludesindex.php). - For every file it tokenizes the namespace+class, runs
class_exists($fqcn, true)(autoload!), thennew ReflectionClass(...)and reads public methods for the attributes:#[PsMcpTool],#[PsMcpResource],#[PsMcpResourceTemplate],#[PsMcpPrompt]. - 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 undermodules/{your_module}/src/. - 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:
| Element | Exception |
|---|---|
| Tool | PsMcpToolCallException($message, $exitCode) |
| Resource / Template | PsMcpResourceReadException(...) |
| Prompt | PsMcpPromptGetException(...) |
Activation / testing
- Install + enable
ps_mcp_serverand your module. - Force discovery: open
ps_mcp_serverconfig, or delete its.mcp/cachedirectory. - Verify with the MCP Inspector or a connected AI client (token / OAuth).
- Tools/resources/prompts appear named
{module}-{name}.
Checklist (copy for each module)
-
isMcpCompliant(): truein the main module class. - SPL autoloader registered in
__construct(or Composer PSR-4) for yoursrc/namespace. - MCP classes under
{module}/src/...withif (!defined('_PS_VERSION_')) exit;andindex.phpin 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*Exceptionclasses. - Degrades silently when
ps_mcp_serveris absent (nothing loads yoursrc/Mcpclasses).
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.phpfiles insrc/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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 471k | Updated | Claude CodeCodex | Verified | Install |
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |