MCP Reference: dataform.googleapis.com

Il server MCP Dataform fornisce strumenti per interagire con Dataform.

Un server Model Context Protocol (MCP) funge da proxy tra un servizio esterno che fornisce contesto, dati o funzionalità a un modello linguistico di grandi dimensioni (LLM) o a un'applicazione AI. I server MCP connettono le applicazioni di AI a sistemi esterni come database e servizi web, traducendo le loro risposte in un formato che l'applicazione di AI può comprendere.

Configurazione del server

Prima dell'uso, devi abilitare i server MCP e configurare l'autenticazione. Per ulteriori informazioni sull'utilizzo dei server MCP remoti di Google e Google Cloud, consulta la panoramica dei server MCP di Google Cloud.

Endpoint server

Un endpoint di servizio MCP è l'indirizzo di rete e l'interfaccia di comunicazione (di solito un URL) del server MCP che un'applicazione AI (l'host per il client MCP) utilizza per stabilire una connessione sicura e standardizzata. È il punto di contatto per l'LLM per richiedere il contesto, chiamare uno strumento o accedere a una risorsa. Gli endpoint Google MCP possono essere globali o regionali.

Il server MCP dell'API Dataform ha il seguente endpoint MCP globale:

• https://dataform.googleapis.com/mcp

Strumenti MCP

Uno strumento MCP è una funzione o una funzionalità eseguibile che un server MCP espone a un LLM o a un'applicazione AI per eseguire un'azione nel mondo reale.

Strumenti

Il server MCP dataform.googleapis.com dispone dei seguenti strumenti:

Strumenti MCP
list_repositories	Elenca i repository Dataform in un progetto cloud e una località Google Cloud specifici. Il valore parametro parent deve essere nel formato projects/{project_id}/locations/{location}.
create_repository	Crea un nuovo repository Dataform in un progetto Google Cloud e una località specifici. Questo strumento stabilisce la risorsa principale richiesta per tutte le altre risorse di trasformazione, come i risultati della compilazione e le configurazioni del flusso di lavoro. Prima di poter utilizzare qualsiasi altro strumento Dataform MCP, è necessario creare un repository. L'attivazione di questo strumento è il primo passaggio per configurare un progetto Dataform. Il valore parametro parent deve essere nel formato projects/{project_id}/locations/{location}. Il valore parametro repository_id è l'ID da utilizzare per il repository. Ometti il parametro strictActAsChecks per lasciarlo non impostato in un nuovo repository. Tieni presente che per i nuovi progetti vengono applicati controlli act-as rigorosi per impostazione predefinita, pertanto l'esecuzione di un flusso di lavoro in questo repository richiede un account di servizio personalizzato.
commit_repository_changes	Applica un commit Git per registrare lo stato dei file all'interno di un repository Dataform. Questo strumento è destinato principalmente alla gestione di asset a file singolo, come notebook o query salvate, che si trovano direttamente nel repository. Questo strumento non viene utilizzato nei tipici flussi di lavoro della pipeline che richiedono spazi di lavoro. Non utilizzare questo strumento sui repository connessi a un host Git remoto. Per verificare, utilizza lo strumento get_repository. Se è presente il campo git_remote_settings, il repository è connesso a un host remoto e devi utilizzare strumenti basati sullo spazio di lavoro come commit_workspace_changes. Questa azione di commit crea una voce permanente nella cronologia Git interna del repository. Il valore parametro name deve essere nel formato projects/{project_id}/locations/{location}/repositories/{repository}.
read_repository_file	Restituisce i contenuti di un file all'interno di un repository Dataform. Questo strumento non è destinato allo sviluppo di pipeline standard. È destinato all'interazione diretta con il repository, in genere per la gestione di asset a file singolo come notebook o query salvate. Non utilizzare questo strumento sui repository connessi a un host Git remoto. Per verificare, utilizza lo strumento get_repository. Se è presente il campo git_remote_settings, il repository è connesso a un host remoto e devi utilizzare lo strumento read_file per leggere il file da un workspace. Il valore parametro name si riferisce al repository e deve essere nel formato projects/{project_id}/locations/{location}/repositories/{repository}. Il valore parametro path deve essere relativo alla radice del repository. Non utilizzare directory traversal, ad esempio ... Utilizza lo strumento query_repository_directory_contents per ottenere percorsi di file validi.
query_repository_directory_contents	Restituisce i contenuti di una determinata directory del repository Dataform. Questo strumento viene utilizzato principalmente per elencare e gestire le risorse a file singolo direttamente nel repository. Non utilizzare questo strumento sui repository connessi a un host Git remoto. Per verificare, utilizza lo strumento get_repository. Se è presente il campo git_remote_settings, il repository è connesso a un host remoto e devi utilizzare lo strumento query_directory_contents per elencare una directory del workspace. Il valore parametro name fa riferimento al repository nel formato projects/{project_id}/locations/{location}/repositories/{repository}. Il valore parametro path deve essere relativo alla radice del repository. Non utilizzare directory traversal, ad esempio ... Se il campo viene lasciato vuoto, viene utilizzata la radice del repository.
list_workflow_configs	Elenca le configurazioni del flusso di lavoro in un determinato repository Dataform. Il valore parametro parent deve essere nel formato projects/{project_id}/locations/{location}/repositories/{repository}.
get_workflow_config	Recupera una singola configurazione del flusso di lavoro Dataform. Il valore parametro name deve essere nel formato projects/{project_id}/locations/{location}/repositories/{repository}/workflowConfigs/{workflow_config}.
create_workflow_config	Crea una nuova configurazione del workflow in un determinato repository Dataform. Il valore parametro parent deve essere nel formato projects/{project_id}/locations/{location}/repositories/{repository}. workflow_config_id è l'ID della configurazione del workflow. Una configurazione del flusso di lavoro associa un ReleaseConfig a una pianificazione e a un'identità. ReleaseConfig determina quale codice viene compilato, mentre questo strumento determina quando viene eseguito il codice e quale account di servizio lo esegue. Prerequisito: devi prima creare un ReleaseConfig utilizzando lo strumento create_release_config. Il valore parametro workflow_config.release_config è obbligatorio e la richiesta non va a buon fine senza. Le chiamate del workflow create da questa configurazione del workflow vengono eseguite con un account di servizio personalizzato. Per specificare questo account di servizio, imposta il valore parametro invocationConfig.serviceAccount. Se omesso, le invocazioni tornano a utilizzare service_account del repository. Il account di servizio non può essere l'agente di servizio Dataform predefinito. Il account di servizio deve disporre delle autorizzazioni necessarie per eseguire il flusso di lavoro e l'utente deve essere autorizzato ad agire come l'account selezionato. Questa autorizzazione viene in genere concessa tramite il ruolo IAM Utente service account (roles/iam.serviceAccountUser), che può essere concesso al account di servizio stesso o al progetto che lo contiene.
update_workflow_config	Aggiorna le proprietà di una configurazione del flusso di lavoro Dataform esistente, ad esempio la pianificazione dell'esecuzione (cron), la configurazione della release associata o gli override di chiamata. Le modifiche apportate a cron_schedule vengono applicate immediatamente a tutte le esecuzioni pianificate future. Il valore parametro name deve essere nel formato projects/{project_id}/locations/{location}/repositories/{repository}/workflowConfigs/{workflow_config}. Il valore parametro workflow_config.release_config è strettamente necessario per ogni aggiornamento. Utilizza lo strumento get_workflow_config per leggere la configurazione attuale del workflow e includi il relativo valore release_config nella richiesta di aggiornamento. Le chiamate del workflow create da questa configurazione del workflow vengono eseguite con un account di servizio personalizzato. Per specificare questo account di servizio, imposta il valore parametro invocationConfig.serviceAccount. Se omesso, le invocazioni tornano a utilizzare service_account del repository. Il account di servizio non può essere l'agente di servizio Dataform predefinito. Il account di servizio deve disporre delle autorizzazioni necessarie per eseguire il flusso di lavoro e l'utente deve essere autorizzato ad agire come il account di servizio selezionato. Questa autorizzazione viene in genere concessa tramite il ruolo IAM Utente service account (roles/iam.serviceAccountUser), che può essere concesso al account di servizio stesso o al progetto che lo contiene.
list_release_configs	Elenca le configurazioni della release in un determinato repository Dataform. Il valore parametro parent deve essere nel formato projects/{project_id}/locations/{location}/repositories/{repository}.
get_release_config	Recupera una singola configurazione della release Dataform. Il valore parametro name deve essere nel formato projects/{project_id}/locations/{location}/repositories/{repository}/releaseConfigs/{release_config}.
create_release_config	Crea una nuova configurazione di release in un determinato repository Dataform. Il valore parametro parent deve essere nel formato projects/{project_id}/locations/{location}/repositories/{repository}. release_config_id è l'ID definito dall'utente per la configurazione della release. Se l'utente non specifica un ID, genera un ID breve e descrittivo utilizzando lettere minuscole, numeri e trattini in base alla sua richiesta. Ometti il valore parametro release_config.cron_schedule per i repository ospitati da Google. Per verificare, utilizza lo strumento get_repository. Se il campo git_remote_settings non è presente, il repository è ospitato da Google. Per pianificare la pipeline, imposta la pianificazione utilizzando lo strumento create_workflow_config.
update_release_config	Aggiorna una configurazione di rilascio Dataform esistente, che funge da modello per la compilazione automatica del codice. Gli aggiornamenti a campi come git_commitish modificano la modalità di generazione dei risultati di compilazione futuri, ma non alterano retroattivamente gli asset CompilationResult esistenti. Ometti il valore parametro release_config.cron_schedule durante l'aggiornamento dei repository ospitati da Google. Per verificare, utilizza lo strumento get_repository. Se il campo git_remote_settings non è presente, il repository è ospitato da Google. Per pianificare la pipeline, imposta o aggiorna la pianificazione utilizzando gli strumenti create_workflow_config o update_workflow_config. Il valore parametro name deve essere nel formato projects/{project_id}/locations/{location}/repositories/{repository}/releaseConfigs/{release_config}.
create_compilation_result	Crea un nuovo risultato di compilazione Dataform in un progetto Google Cloud e una località specifici. Questo strumento compila i file .sqlx in SQL eseguibile. Gli agenti devono sapere che le modifiche successive al codice non vengono riflesse in questo risultato, a meno che non venga attivata una nuova compilazione. Il valore parametro parent deve essere nel formato projects/{project_id}/locations/{location}/repositories/{repository}. Gli agenti possono convalidare l'SQL compilato esaminando le risorse CompilationResultAction e potenzialmente utilizzando uno strumento BigQuery per una prova generale. È necessario un risultato di compilazione valido prima di attivare una chiamata manuale del flusso di lavoro utilizzando lo strumento create_workflow_invocation. Prerequisito: crea un repository utilizzando lo strumento create_repository prima di chiamare lo strumento create_compilation_result.
list_workflow_invocations	Elenca le chiamate del workflow in un determinato repository Dataform. Il valore parametro parent deve essere nel formato projects/{project_id}/locations/{location}/repositories/{repository}.
create_workflow_invocation	Crea una nuova chiamata del workflow in un determinato repository Dataform. Il valore parametro parent deve essere nel formato projects/{project_id}/locations/{location}/repositories/{repository}. È obbligatorio specificare il valore parametro compilation_result o workflow_config. Se utilizzi compilation_result, il valore parametro deve essere nel formato projects/{project_id}/locations/{location}/repositories/{repository}/compilationResults/{compilation_result}. Se utilizzi workflow_config, il valore parametro deve essere nel formato projects/{project_id}/locations/{location}/repositories/{repository}/workflowConfigs/{workflow_config}. Prerequisito: per attivare una chiamata, devi prima creare un compilation_result utilizzando lo strumento create_compilation_result o un workflow_config utilizzando lo strumento create_workflow_config. Non puoi attivare una chiamata direttamente dal codice del repository non elaborato. L'invocazione del workflow viene eseguita con un account di servizio determinato dall'origine di compilazione: Se utilizzi compilation_result, imposta il valore parametro invocationConfig.serviceAccount. Se omesso, viene utilizzato il valore predefinito service_account del repository. Se utilizzi workflow_config, non impostare il parametro invocationConfig. L'invocazione viene eseguita automaticamente con il account di servizio configurato in quella configurazione del workflow. Il account di servizio non può essere l'agente di servizio Dataform predefinito. Il account di servizio deve disporre delle autorizzazioni necessarie per eseguire il flusso di lavoro e l'utente deve essere autorizzato ad agire come il account di servizio selezionato. Questa autorizzazione viene in genere concessa tramite il ruolo Utente service account (roles/iam.serviceAccountUser), che può essere concesso al account di servizio stesso o al progetto che lo contiene.
cancel_workflow_invocation	Richiedi l'arresto controllato di una chiamata workflow Dataform in esecuzione. Questo strumento invia un segnale di annullamento al flusso di lavoro in esecuzione. Tuttavia, i singoli job BigQuery, le creazioni di tabelle o le asserzioni già completati nell'ambito di questo flusso di lavoro non verranno ripristinati. Il valore parametro name deve essere nel formato projects/{project_id}/locations/{location}/repositories/{repository}/workflowInvocations/{workflow_invocation}.
get_compilation_result	Recupera un singolo risultato di compilazione di Dataform. Il valore parametro name deve essere nel formato projects/{project_id}/locations/{location}/repositories/{repository}/compilationResults/{compilation_result}.
query_compilation_actions	Restituisce le azioni del risultato della compilazione per un determinato risultato della compilazione di Dataform. Il valore parametro name deve essere nel formato projects/{project_id}/locations/{location}/repositories/{repository}/compilationResults/{compilation_result}.
query_workflow_invocation_actions	Restituisce le azioni di chiamata del workflow per una determinata chiamata del workflow Dataform. Queste azioni rappresentano i singoli job BigQuery, le creazioni di tabelle o le asserzioni che compongono il flusso di lavoro. Il valore parametro name deve essere nel formato projects/{project_id}/locations/{location}/repositories/{repository}/workflowInvocations/{workflow_invocation}.
get_workflow_invocation	Recupera una singola chiamata del workflow Dataform. Il valore parametro name deve essere nel formato projects/{project_id}/locations/{location}/repositories/{repository}/workflowInvocations/{workflow_invocation}.
list_workspaces	Elenca i workspace di sviluppo in un determinato repository Dataform. Utilizza questo strumento per scoprire gli spazi di lavoro esistenti prima di eseguire operazioni sui file (utilizzando strumenti come read_file o write_file) o di eseguire il commit del codice (utilizzando uno strumento come commit_workspace_changes). Il valore parametro parent deve essere nel formato projects/{project_id}/locations/{location}/repositories/{repository}.
get_workspace	Recupera un singolo workspace di sviluppo Dataform. Il valore parametro name deve essere nel formato projects/{project_id}/locations/{location}/repositories/{repository}/workspaces/{workspace}. Se non conosci il nome esatto dello spazio di lavoro, utilizza lo strumento list_workspaces per trovarlo.
create_workspace	Crea un nuovo workspace di sviluppo in un determinato repository Dataform. Un workspace è un checkout isolato e modificabile del repository. Utilizza uno spazio di lavoro quando devi creare o rivedere il codice della pipeline in più file e convalidarlo prima di eseguirne il commit. Modifica i file nello spazio di lavoro con gli strumenti write_file e remove_file, registra il risultato con lo strumento commit_workspace_changes e pubblica le modifiche di cui è stato eseguito il commit nel repository con lo strumento push_git_commits. Non utilizzare lo strumento commit_repository_changes per lo sviluppo di pipeline standard. Questo strumento scrive direttamente nel repository, è destinato solo ad asset a file singolo come notebook o query salvate e non funziona con i repository collegati a un host Git remoto. Prerequisito: il repository principale deve esistere. Il valore parametro parent deve essere nel formato projects/{project_id}/locations/{location}/repositories/{repository}. Il valore parametro workspace_id è l'ID da utilizzare per lo spazio di lavoro. Il valore parametro workspace contiene lo spazio di lavoro da creare.
query_directory_contents	Restituisce i contenuti di una determinata directory all'interno di un workspace Dataform. Utilizza questo strumento per scoprire i percorsi dei file validi prima di chiamare gli strumenti read_file o write_file. Il valore parametro workspace deve essere nel formato projects/{project_id}/locations/{location}/repositories/{repository}/workspaces/{workspace}. Il valore parametro path è il percorso relativo alla directory dalla radice del workspace. Non utilizzare directory traversal, ad esempio ... Se omesso, viene utilizzata la radice dello spazio di lavoro.
search_files	Trova file e directory in un workspace Dataform che corrispondono a un filtro di ricerca. Utilizza questo strumento anziché elencare in modo ricorsivo le directory con lo strumento query_directory_contents quando individui un file per nome o estensione in un repository di grandi dimensioni. Il valore parametro workspace deve essere nel formato projects/{project_id}/locations/{location}/repositories/{repository}/workspaces/{workspace}. Il valore parametro filter limita i risultati. Il filtro è supportato solo per il campo path (ad esempio, path="*.sqlx" o path="definitions/model.sqlx").
read_file	Restituisce i contenuti di un file all'interno di un workspace Dataform, incluse le modifiche non commit. Utilizza questo strumento per leggere il file workflow_settings.yaml del workspace, che contiene le impostazioni di compilazione della pipeline, come il set di dati BigQuery predefinito, la località predefinita e la versione di Dataform Core. Questo file si trova nella directory principale della pipeline, che non è necessariamente la radice dello spazio di lavoro, in quanto un repository può contenere diverse pipeline in sottodirectory. Individua il file con lo strumento search_files. Per leggere un file di cui è stato eseguito il commit direttamente dal repository senza uno spazio di lavoro, utilizza lo strumento read_repository_file. Tieni presente che read_repository_file funziona solo sui repository non connessi a un host Git remoto. Il valore parametro workspace deve essere nel formato projects/{project_id}/locations/{location}/repositories/{repository}/workspaces/{workspace}. Il valore parametro path è il percorso relativo al file dalla radice del workspace. Non utilizzare directory traversal, ad esempio ... I percorsi validi possono essere ottenuti utilizzando gli strumenti query_directory_contents o search_files. Il valore parametro revision seleziona facoltativamente una revisione Git specifica del file. Se omesso, viene restituito lo stato attuale non sottoposto a commit del file.
write_file	Scrivi i contenuti di un file all'interno di un workspace Dataform, creando il file se non esiste. Il valore parametro contents fornito sostituisce l'intero file, quindi leggi i contenuti attuali con lo strumento read_file prima di apportare una modifica parziale. Le modifiche rimangono non eseguite finché non viene chiamato lo strumento commit_workspace_changes. Il valore parametro workspace deve essere nel formato projects/{project_id}/locations/{location}/repositories/{repository}/workspaces/{workspace}. Il valore parametro path è il percorso relativo al file dalla radice del workspace. Non utilizzare directory traversal, ad esempio ... Il valore parametro contents deve essere una stringa codificata in base64 contenente il contenuto del file.
remove_file	Elimina un file all'interno di un workspace Dataform. L'eliminazione rimane non confermata finché non viene chiamato lo strumento commit_workspace_changes. Il valore parametro workspace deve essere nel formato projects/{project_id}/locations/{location}/repositories/{repository}/workspaces/{workspace}. Il valore parametro path è il percorso relativo al file dalla radice del workspace. Non utilizzare directory traversal, ad esempio ... I percorsi dei file validi possono essere ottenuti utilizzando gli strumenti query_directory_contents o search_files.
make_directory	Crea una directory all'interno di un workspace Dataform, incluse le directory padre mancanti. Il valore parametro workspace deve essere nel formato projects/{project_id}/locations/{location}/repositories/{repository}/workspaces/{workspace}. Il valore parametro path è il percorso relativo alla directory dalla radice del workspace. Non utilizzare directory traversal, ad esempio ...
commit_workspace_changes	Registra un commit Git per le modifiche non eseguite in un workspace Dataform. Il commit rimane locale al workspace finché non viene pubblicato con lo strumento push_git_commits. Per impostazione predefinita, viene eseguito il commit di tutte le modifiche di cui non è stato eseguito il commit. Per eseguire il commit solo di un sottoinsieme di file, fornisci il valore parametro paths. Il valore parametro name deve essere nel formato projects/{project_id}/locations/{location}/repositories/{repository}/workspaces/{workspace}. Il valore parametro author identifica l'autore Git registrato per il commit. Sono necessari sia author.name che author.email_address. Fornisci i valori che identificano l'utente per conto del quale viene eseguito il commit. Non utilizzare segnaposto, perché vengono scritti nella cronologia Git. Il valore parametro commit_message è il messaggio del commit.
push_git_commits	Esegui il push delle modifiche di cui è stato eseguito il commit di un workspace Dataform nel git remote del repository. Prerequisito: devi eseguire il commit delle modifiche allo spazio di lavoro utilizzando lo strumento commit_workspace_changes prima di eseguire il push. Le modifiche non eseguite rimangono locali e non vengono inviate. Se prevedi di utilizzare lo strumento create_release_config, devi prima eseguire il push dei commit. Una configurazione della release risolve il relativo git_commitish rispetto al repository Git remoto, quindi un ramo o un commit che esiste solo nello spazio di lavoro locale non è visibile. Il valore parametro name deve essere nel formato projects/{project_id}/locations/{location}/repositories/{repository}/workspaces/{workspace}. Il valore parametro remote_branch è il ramo remoto a cui eseguire il push. Se omesso, un workspace con la gestione dei branch abilitata esegue il push nel branch attualmente estratto e qualsiasi altro workspace esegue il push nel branch predefinito configurato del repository.
get_repository	Recupera un singolo repository Dataform, incluse le impostazioni Git remote, gli override di compilazione dello spazio di lavoro e l'account di servizio predefinito. Utilizza questo strumento per controllare il campo git_remote_settings e determinare come interagire con il repository. Se è presente il campo git_remote_settings, il repository è connesso a un host Git remoto, il che significa che devi utilizzare strumenti basati sullo spazio di lavoro per lo sviluppo di pipeline, come create_workspace o commit_workspace_changes. Se il campo non è presente, il repository è ospitato da Google. In questo caso, puoi comunque utilizzare gli spazi di lavoro per lo sviluppo della pipeline. Gli strumenti di repository diretti come commit_repository_changes non sono consigliati, a meno che tu non gestisca asset a file singolo. Il valore parametro name deve essere nel formato projects/{project_id}/locations/{location}/repositories/{repository}. Se non conosci il nome esatto del repository, utilizza lo strumento list_repositories per trovarlo.
update_repository	Aggiorna le proprietà di un repository Dataform esistente, ad esempio le impostazioni Git remote, gli override di compilazione del workspace o il account di servizio predefinito. Prerequisito: utilizza lo strumento get_repository per leggere lo stato attuale del repository prima dell'aggiornamento. Se il valore parametro update_mask viene omesso, tutti i campi modificabili vengono sovrascritti con i valori forniti nel valore parametro repository. Per modificare solo campi specifici senza cancellare gli altri, elenca questi campi in update_mask. Il valore parametro repository.name deve essere nel formato projects/{project_id}/locations/{location}/repositories/{repository}.
create_folder	Crea una nuova cartella Dataform in un progetto cloud e una località Google Cloud specifici. Le cartelle organizzano i repository Dataform in una gerarchia. La creazione di una cartella non comporta lo spostamento di alcun repository al suo interno. Per inserire un repository all'interno di una cartella, imposta il valore parametro containing_folder quando utilizzi lo strumento create_repository. Non tentare di spostare un repository esistente in una cartella utilizzando lo strumento update_repository. Una volta creato un repository, il relativo campo containing_folder non può essere modificato utilizzando gli strumenti MCP. Il valore parametro parent deve essere nel formato projects/{project_id}/locations/{location}. Il valore parametro folder.display_name è obbligatorio e specifica il nome descrittivo della cartella.

Ottenere le specifiche dello strumento MCP

Per ottenere le specifiche dello strumento MCP per tutti gli strumenti in un server MCP, utilizza il metodo tools/list. L'esempio seguente mostra come utilizzare curl per elencare tutti gli strumenti e le relative specifiche attualmente disponibili nel server MCP.

Richiesta curl
curl --location 'https://dataform.googleapis.com/mcp' \ --header 'content-type: application/json' \ --header 'accept: application/json, text/event-stream' \ --data '{ "method": "tools/list", "jsonrpc": "2.0", "id": 1 }'