Servizio di accesso MCP API Merchant (alpha)

Utilizza il servizio di accesso Model Context Protocol (MCP) dell'API Merchant per ottenere l'accesso autorizzato ai dati e agli approfondimenti di Merchant Center per creare nuove esperienze agentiche e workflow automatizzati.

Panoramica

Il servizio di accesso MCP dell'API Merchant fornisce un ponte standardizzato e sicuro per LLM, agenti e assistenti di codifica per creare e orchestrare nuove esperienze agentiche e workflow automatizzati basati sui dati di Merchant Center.

In particolare, consente l'accesso autorizzato ai dati di Merchant Center e ai report e agli approfondimenti generati da Google per eseguire operazioni di lettura e scrittura limitate per gestire casi d'uso quali:

  • Diagnostica e correggi le mancate approvazioni dei prodotti
  • Generare report sul rendimento e approfondimenti
  • Esaminare l'attivazione dei miglioramenti automatici
  • Creare e recuperare le origini dati

Controlli di sicurezza e accesso

Il servizio di accesso MCP dell'API Merchant è progettato con una priorità per la sicurezza:

  • Autenticazione: l'esecuzione dello strumento è regolata dall'autenticazione API Merchant standard, che richiede le credenziali OAuth 2.0 o del service account. Ti consigliamo di utilizzare credenziali con i diritti di accesso più restrittivi possibili.
  • Sicurezza di esecuzione: sebbene la visibilità degli strumenti non sia limitata per l'individuazione agente, l'esecuzione degli strumenti è limitata alle tue credenziali API specifiche.
  • Salvaguardie: gli strumenti sono rigorosamente limitati alle operazioni di sola lettura e agli strumenti di scrittura a basso rischio (ad esempio, la creazione di origini dati) come misura di sicurezza.

Considerazioni importanti

Il servizio di accesso MCP dell'API Merchant è una versione alpha; il suo ambito e le sue funzionalità verranno ampliati e potrebbero cambiare.

Prima di iniziare, esamina le seguenti limitazioni e best practice:

Modifiche e release

Le modifiche possono essere apportate senza preavviso e verranno pubblicate nelle note di rilascio.

Test sicuri

Ti consigliamo di fare prima degli esperimenti utilizzando un account di prova o un account non attivo prima di utilizzare questi strumenti in un ambiente di produzione attivo.

Quota condivisa

Il servizio di accesso MCP dell'API Merchant condivide lo stesso pool di quote delle chiamate standard dell'API Merchant. L'esecuzione di agenti può esaurire rapidamente la quota, soprattutto per i recuperi delle origini dati. Ti consigliamo vivamente di utilizzare un account di test per evitare interruzioni del servizio di produzione.

Filtro e sicurezza degli strumenti

In futuro verranno aggiunte nuove funzionalità, in particolare azioni di scrittura. Ti consigliamo vivamente di configurare esplicitamente il client per il filtraggio degli strumenti integrati anziché esporre l'intero set di strumenti.

Riepilogo delle funzionalità disponibili

Puoi utilizzare il servizio di accesso MCP dell'API Merchant per eseguire le seguenti azioni in modo agentico:

  • Recupera lo stato dettagliato e il contesto dei report per prodotti specifici utilizzando i nomi esatti delle risorse.
  • Elenca e cerca più prodotti.
  • Metriche sul rendimento delle query, stati dei prodotti e insight sui prodotti più apprezzati, insight sui prezzi, scenario competitivo e dati e analisi per gli affiliati di YouTube Shopping.
  • Identifica i problemi a livello di account che influiscono sulla visibilità dei prodotti o sulla partecipazione al programma.
  • Elenca, crea, recupera e controlla lo stato di caricamento delle origini dati.
  • Elenca i motivi aggregati delle disapprovazioni dei prodotti nel tuo inventario.
  • Esamina le impostazioni di miglioramento automatico per articoli, immagini e spedizione.
  • Controlla le regioni attive, i requisiti non soddisfatti e lo stato di partecipazione per programmi Merchant Center specifici.

Per iniziare

Per connettere l'IDE, l'assistente alla programmazione o l'agente al servizio di accesso MCP dell'API Merchant, aggiorna le impostazioni del client MCP. Ad esempio, aggiorna il file mcp.json per Google Agent Studio, Claude Desktop, Antigravity, Visual Studio Code o il tuo framework di agenti personalizzato.

La configurazione del servizio di accesso MCP dell'API Merchant locale richiede un service account. L'OAuth utente standard non è supportato per questa esecuzione locale headless. Devi creare un service account, scaricare il relativo file JSON della chiave privata e fornire il percorso insieme al tuo ID Merchant Center specifico come argomenti.

Per istruzioni dettagliate su come creare e scaricare un service account, consulta la guida ai service account.

Configurazione client

Configurazioni:

Antigravity

Segui le istruzioni riportate nella documentazione di Antigravity.

{
    "mcpServers": {
        "merchant-data-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@google/merchant-data-mcp",
                "--credentials",
                "/path/to/your/service-account-file.json"
            ]
        }
    }
}

Claude Desktop

Segui le istruzioni nella documentazione di Claude Desktop.

{
    "mcpServers": {
        "merchant-data-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@google/merchant-data-mcp",
                "--credentials",
                "/path/to/your/service-account-file.json"
            ]
        }
    }
}

Scenari di utilizzo di esempio

Per illustrare come puoi sfruttare il servizio di accesso MCP dell'API Merchant per creare esperienze agentiche e workflow automatizzati, considera i seguenti scenari:

Scenario 1: diagnosticare e correggere le mancate approvazioni dei prodotti

Vuoi capire perché un prodotto specifico non viene visualizzato nei risultati della Ricerca Google.

Prompt dell'utente:

"Perché il mio prodotto con ID offerta "offer123" non è stato approvato?"

Comportamento dell'agente con MCP:

  1. L'agente chiama list_products o get_product_by_name per individuare lo stato del prodotto.
  2. Il server MCP restituisce lo stato del prodotto, incluso un elenco di issues (ad esempio "Formato del prezzo errato" o "Valore di spedizione mancante").
  3. L'agente analizza i problemi e ti spiega la causa principale, suggerendo come risolverli (ad esempio, aggiornando le informazioni sul prezzo).

Scenario 2: esamina l'attivazione dei miglioramenti automatici

Vuoi verificare se i miglioramenti automatici della spedizione sono attivi.

Prompt dell'utente:

"I miglioramenti automatici della spedizione sono attivi?"

Comportamento dell'agente con MCP:

  1. L'agente chiama get_automatic_improvements per recuperare le impostazioni a livello di account.
  2. Il server MCP restituisce la configurazione che mostra lo stato dei miglioramenti di immagine, articolo e spedizione.
  3. L'agente conferma che i miglioramenti alla spedizione sono attivi o spiega come attivarli se sono disattivati.

Scenario 3: genera report e approfondimenti sul rendimento

Vuoi controllare rapidamente il rendimento recente senza navigare nell'interfaccia utente di Merchant Center.

Prompt dell'utente:

"Mostrami i miei 5 prodotti con il rendimento migliore in base ai clic della settimana scorsa".

Comportamento dell'agente con MCP:

  1. L'agente crea una query Merchant Center Query Language (MCQL) che ha come target la tabella product_performance_view, ordinata per clicks DESC e limitata a 5.
  2. L'agente chiama report_search con la query creata.
  3. Il server MCP esegue la query sul database di reporting live e restituisce le righe.
  4. L'agente formatta i risultati in una tabella Markdown pulita.

Scenario 4: crea e recupera le origini dati

Vuoi aggiungere una nuova origine dati per caricare gli aggiornamenti dei prodotti.

Prompt dell'utente:

"Crea un'origine dati supplementare denominata "aggiornamenti-prezzo" per il mio account commerciante."

Comportamento dell'agente con MCP:

  1. L'agente chiama create_data_source con le impostazioni specificate per registrare il nuovo feed.
  2. Il server MCP crea l'origine dati e restituisce il relativo nome univoco della risorsa.
  3. L'agente chiama fetch_data_source per attivare il download e l'elaborazione del file associato.
  4. L'agente chiama get_file_upload per monitorare lo stato di avanzamento del caricamento e confermare lo stato di elaborazione riuscita degli elementi.

Strumenti MCP e descrizioni

Il servizio di accesso MCP dell'API Merchant espone i seguenti strumenti al tuo agente:

Strumento MCP Descrizione
get_product_by_name Recupera le informazioni sul prodotto per un determinato commerciante utilizzando il nome esatto della risorsa del prodotto. Restituisce lo stato dettagliato del prodotto contenente il contesto dei report e i potenziali problemi a livello di prodotto.
list_products Elenca o cerca più prodotti per un determinato commerciante. Restituisce lo stato dettagliato del prodotto contenente il contesto dei report e i potenziali problemi a livello di prodotto per più prodotti.
report_search Esegui query sulle tabelle dei report per recuperare le metriche sul rendimento dei prodotti, gli stati dei prodotti, gli insight sul prezzo e lo scenario competitivo. Per maggiori dettagli, consulta la guida ai report.
list_data_sources Elenca le origini dati disponibili per un determinato commerciante.
get_data_source Visualizza i dettagli di un'origine dati specifica.
create_data_source Crea una nuova origine dati per un determinato commerciante.
fetch_data_source Recupera ed elabora il file associato a un'origine dati per un determinato commerciante.
get_file_upload Visualizza lo stato dell'ultimo caricamento di file per una determinata origine dati.
list_accounts Elenca gli account per un determinato utente.
list_account_issues Elenca i problemi a livello di account per un determinato commerciante per identificare i problemi a livello di account.
list_programs Elenca i programmi per un determinato commerciante, inclusi lo stato di partecipazione, le regioni attive e i requisiti non soddisfatti.
list_aggregate_product_statuses Elenca i problemi aggregati a livello di prodotto per monitorare lo stato generale dei dati di prodotto.
get_automatic_improvements Ottieni le impostazioni per i miglioramenti automatici, inclusi aggiornamenti degli articoli, miglioramenti delle immagini e miglioramenti della spedizione.