Servizio di accesso MCP API Merchant (alpha)

Utilizza il servizio di accesso al 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 flussi di lavoro automatizzati.

Panoramica

Il servizio di accesso MCP dell'API Merchant fornisce un ponte standardizzato e sicuro per LLM, agenti e assistenti alla programmazione per creare e orchestrare nuove esperienze agentiche e flussi di lavoro 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 sola lettura e di scrittura limitata per risolvere casi d'uso come:

  • Diagnosi e correzione delle mancate approvazioni dei prodotti
  • Generazione di report sul rendimento e approfondimenti
  • Revisione dell'attivazione dei miglioramenti automatici
  • Creazione e recupero delle origini dati

Controlli di accesso e sicurezza

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

  • Autenticazione: l'esecuzione dello strumento è regolata dall'autenticazione standard dell'API Merchant, che richiede le credenziali OAuth 2.0 o del service account. Ti consigliamo di utilizzare le credenziali con i diritti di accesso più restrittivi possibili.
  • Sicurezza di esecuzione: sebbene la visibilità dello strumento non sia limitata per il rilevamento agentico, l'esecuzione dello strumento è limitata alle tue credenziali API specifiche.
  • Misure di salvaguardia: per motivi di sicurezza, 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).

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 sperimentare prima utilizzando un account di test o un account non live prima di utilizzare questi strumenti in un ambiente di produzione live.

Quota condivisa

Il servizio di accesso MCP dell'API Merchant condivide lo stesso pool di quote delle chiamate API Merchant standard. L'esecuzione degli 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 le azioni di scrittura. Ti consigliamo vivamente di configurare esplicitamente il client per il filtro degli strumenti integrato 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:

  • Recuperare lo stato dettagliato e il contesto dei report per prodotti specifici utilizzando i nomi delle risorse esatti.
  • Elencare e cercare più prodotti.
  • Eseguire query su metriche sul rendimento, stati dei prodotti e approfondimenti su prodotti più apprezzati, insight sul prezzo, scenario competitivo e dati e analisi degli affiliati di YouTube Shopping.
  • Identificare i problemi a livello di account che influiscono sulla visibilità dei prodotti o sulla partecipazione al programma.
  • Elencare, creare, recuperare e controllare lo stato di caricamento delle origini dati.
  • Elencare i motivi aggregati delle mancate approvazioni dei prodotti nell'inventario.
  • Esaminare le impostazioni di miglioramento automatico per articoli, immagini e spedizione.
  • Controllare 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 framework dell'agente personalizzato.

La configurazione locale del servizio di accesso MCP dell'API Merchant richiede un service account. L'OAuth dell'utente standard non è supportato per questa esecuzione locale headless. Devi creare un service account, scaricare il file JSON della chiave privata e fornire il percorso insieme all'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 nella Antigravity documentazione.

{
    "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 flussi di lavoro automatizzati, prendi in considerazione i seguenti scenari:

Scenario 1: diagnosi e correzione delle 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 l'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, inclusa una lista 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, suggerendoti come risolverla (ad esempio, aggiornando le informazioni sul prezzo).

Scenario 2: revisione dell'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 immagini, articoli e spedizione.
  3. L'agente conferma che i miglioramenti della spedizione sono attivi o spiega come attivarli se sono disattivati.

Scenario 3: generazione di report sul rendimento e approfondimenti

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

Prompt dell'utente:

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

Comportamento dell'agente con MCP:

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

Scenario 4: creazione e recupero delle origini dati

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

Prompt dell'utente:

"Crea un'origine dati supplementare denominata 'price-updates' 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 della risorsa univoco.
  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 l'avanzamento del caricamento e confermare lo stato di elaborazione riuscita degli articoli.

Strumenti e descrizioni MCP

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

Strumento MCP Descrizione
get_product_by_name Recupera le informazioni sul prodotto per un determinato commerciante utilizzando il nome della risorsa del prodotto esatto. 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 Esegue 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 i dettagli, consulta la guida ai report.
list_data_sources Elenca le origini dati disponibili per un determinato commerciante.
get_data_source Recupera 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 Recupera lo stato dell'ultimo caricamento 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 Recupera le impostazioni di miglioramento automatico, inclusi gli aggiornamenti degli articoli, i miglioramenti delle immagini e i miglioramenti della spedizione.