Come creare i miei strumenti MCP?

Gli sviluppatori di moduli possono creare i propri strumenti per esporre la funzionalità del loro modulo alle applicazioni IA, o per esporre funzionalità native PrestaShop oltre a ciò che offrono gli strumenti predefiniti.

Per creare i tuoi strumenti per PrestaShop MCP Server, dichiara il tuo modulo come compatibile con MCP e definisci i tuoi strumenti personalizzati usando attributi PHP.

Indici dei contenuti

1. Dichiarare il tuo modulo come compatibile con MCP

Per far sapere a PrestaShop MCP Server che il tuo modulo include strumenti MCP, dichiaralo come compatibile con MCP aggiungendo il metodo isMcpCompliant() alla tua classe modulo principale:

<?php

class Ps_MySuperModule extends Module
{
    // Questo metodo permette a ps_mcp_server di scoprire i tuoi strumenti
    public function isMcpCompliant()
    {
        return true;
    }
}

?>

2. Implementare i tuoi strumenti MCP

Usa gli attributi PHP-MCP McpTool e Schema per dichiarare la tua funzione come uno strumento MCP. I tuoi strumenti saranno automaticamente scoperti e resi disponibili.

Per maggiori informazioni sugli attributi PHP-MCP, visita la documentazione PHP-MCP.

Esempio:

<?php

class MySuperTool
{
    // esempio di uno strumento per recuperare prodotti dal database
    #[PhpMcp\\Server\\Attributes\\McpTool(
        name: 'update_prestashop_product_by_id',
        description: 'Aggiorna una descrizione prodotto per il suo ID nel negozio PrestaShop'
    )]
    #[PhpMcp\\Server\\Attributes\\Schema(
        properties: [
            'productId' => ['type' => 'integer', 'description' => 'ID del prodotto'],
        ],
        required: ['productId']
    )]
    public function getProducts(int $langId): array {
        return Product::getProducts($langId, 0, 100, 'id_product', 'ASC');
    }
}

?>

Linee guida per strumenti efficaci

Queste linee guida ti aiuteranno a progettare strumenti che gli agenti possano comprendere e utilizzare per completare attività complesse.

1. Descrivi i tuoi strumenti in modo chiaro e conciso

Definisci chiaramente e in modo conciso lo scopo e il comportamento di ogni strumento. Questo aiuta i modelli IA a comprendere la funzionalità dello strumento e usarlo correttamente.

Esempio:

#[PhpMcp\\Server\\Attributes\\McpTool(
    name: 'search_product_by_name',
    description: 'Cerca un prodotto nel negozio solo per nome. Questa ricerca usa corrispondenza fuzzy. I risultati sono ordinati per rilevanza. '
)]
#[PhpMcp\\Server\\Attributes\\Schema(
    properties: [
        'searchTerms' => ['type' => 'string', 'description' => 'Termini di ricerca da cercare nei nomi dei prodotti. Diversi termini possono essere forniti come una lista separata da punto e virgola.'],
        'language' => ['type' => 'integer', 'description' => 'Lingua per eseguire la ricerca. Di default, la lingua preferita.']
    ],
    required: ['productId']
)]

In questo esempio, il nome e la descrizione dello strumento non lasciano dubbi sull'uso dello strumento. Il campo searchTerms mostra anche come un agente può essere guidato per utilizzare appieno i tuoi strumenti.

2. Usa vocabolario coerente

Usa vocabolario coerente in tutto il tuo server MCP per aiutare gli agenti a connettere i tuoi strumenti e pianificare flussi di lavoro complessi usando più strumenti insieme. Questo include parametri, messaggi di errore e altri termini tecnici.

3. Valida i tuoi input

Valida gli input dei tuoi strumenti usando l'annotazione #[Schema()] fornita da PHP-MCP per assicurarti che siano corretti e coerenti.

4. Esegui controlli di coerenza

Dopo aver validato i parametri, assicurati che gli agenti facciano richieste ragionevoli al tuo strumento. Questo include:

• Limitare la dimensione dei risultati e la complessità delle richieste
• Applicare i permessi
• Verificare contenuti inappropriati quando l'IA genera testo o immagini
• Rilevare comportamenti erratici, come un agente bloccato in un loop

Per più linee guida su come scrivere strumenti MCP efficaci, visita la Guida allo sviluppo MCP.

Debug

PrestaShop MCP Server memorizza i registri, la cache e i file di configurazione nella cartella .mcp. I file .logs vengono creati quando il parametro del modulo MCP Abilita registri è impostato su true.

Per forzare una nuova scansione delle posizioni, elimina .cache.json.

Usa l'ispettore MCP per verificare che il tuo server funzioni e validare che i tuoi strumenti MCP funzionino correttamente.

Dipendenze

• php-mcp/server - Libreria server PHP MCP
• php-mcp/client - Libreria client PHP MCP

Documentazione

• Specifica del protocollo MCP: modelcontextprotocol.io
• Libreria PHP MCP: PHP-MCP