MCP Reference: dataform.googleapis.com

Dataform MCP 伺服器提供與 Dataform 互動的工具。

Model Context Protocol (MCP) 伺服器可做為代理伺服器，在外部服務與大型語言模型 (LLM) 或 AI 應用程式之間傳遞脈絡、資料或功能。MCP 伺服器可將 AI 應用程式連結至資料庫和 Web 服務等外部系統，並將系統回覆轉換成 AI 應用程式可理解的格式。

伺服器設定

您必須先啟用 MCP 伺服器並設定驗證，才能使用這項功能。如要進一步瞭解如何使用 Google 和 Google Cloud 遠端 MCP 伺服器，請參閱 Google Cloud MCP 伺服器總覽。

伺服器端點

MCP 服務端點是 MCP 伺服器的網路位址和通訊介面 (通常是網址)，AI 應用程式 (MCP 用戶端的主機) 會使用這個端點建立安全標準連線。這是 LLM 請求情境、呼叫工具或存取資源的聯絡點。Google MCP 端點可以是全域或區域。

Dataform API MCP 伺服器具有下列全域 MCP 端點：

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

MCP 工具

MCP 工具是 MCP 伺服器向 LLM 或 AI 應用程式公開的函式或可執行功能，可在現實世界中執行動作。

工具

dataform.googleapis.com MCP 伺服器提供下列工具：

MCP 工具
list_repositories	列出指定 Google Cloud 雲端專案和位置中的 Dataform 存放區。 parent 參數值的格式必須為 projects/{project_id}/locations/{location}。
create_repository	在指定的 Google Cloud 雲端專案和位置中，建立新的 Dataform 存放區。 這個工具會建立所有其他轉換資產 (例如編譯結果和工作流程設定) 所需的根資源。您必須先建立存放區，才能使用任何其他 Dataform MCP 工具。啟用這項工具是設定 Dataform 專案的第一步。 parent 參數值的格式必須為 projects/{project_id}/locations/{location}。 repository_id 參數值是存放區要使用的 ID。 如要在新存放區中保留未設定的 strictActAsChecks 參數，請省略該參數。請注意，新專案預設會強制執行嚴格的「以…身分執行」檢查，因此在這個存放區中執行工作流程時，需要使用自訂服務帳戶。
commit_repository_changes	套用 Git 提交，記錄 Dataform 存放區中的檔案狀態。 這項工具主要用於管理直接位於存放區中的單一檔案資產，例如筆記本或已儲存的查詢。在需要工作區的典型管道工作流程中，不會使用這項工具。 請勿在連線至遠端 Git 主機的存放區中使用這項工具。如要驗證，請使用 get_repository 工具。如果存在 git_remote_settings 欄位，表示存放區已連線至遠端主機，您必須改用 commit_workspace_changes 等工作區工具。 這項提交動作會在存放區的內部 Git 記錄中建立永久項目。 name 參數值的格式必須為 projects/{project_id}/locations/{location}/repositories/{repository}。
read_repository_file	傳回 Dataform 存放區內檔案的內容。 這個工具不適用於標準管道開發作業。這個介面適用於直接與存放區互動，通常用於管理單一檔案資產，例如筆記本或已儲存的查詢。 請勿在連線至遠端 Git 主機的存放區中使用這項工具。如要驗證，請使用 get_repository 工具。如果存在 git_remote_settings 欄位，表示存放區已連線至遠端主機，您必須改用 read_file 工具從工作區讀取檔案。 name 參數值是指存放區，且格式必須為 projects/{project_id}/locations/{location}/repositories/{repository}。 path 參數值必須相對於存放區根目錄。請勿使用目錄遍歷，例如 ..。使用 query_repository_directory_contents 工具取得有效檔案路徑。
query_repository_directory_contents	傳回指定 Dataform 存放區目錄的內容。 這項工具主要用於直接在存放區中列出及管理單一檔案資產。 請勿在連線至遠端 Git 主機的存放區中使用這項工具。如要驗證，請使用 get_repository 工具。如果存在 git_remote_settings 欄位，表示存放區已連線至遠端主機，您必須改用 query_directory_contents 工具列出工作區目錄。 name 參數值會以 projects/{project_id}/locations/{location}/repositories/{repository} 格式參照存放區。 path 參數值必須相對於存放區根目錄。請勿使用目錄遍歷，例如 ..。如果留空，系統會使用存放區根目錄。
list_workflow_configs	列出指定 Dataform 存放區中的工作流程設定。 parent 參數值的格式必須為 projects/{project_id}/locations/{location}/repositories/{repository}。
get_workflow_config	擷取單一 Dataform 工作流程設定。 name 參數值的格式必須為 projects/{project_id}/locations/{location}/repositories/{repository}/workflowConfigs/{workflow_config}。
create_workflow_config	在指定的 Dataform 存放區中建立新的工作流程設定。 parent 參數值的格式必須為 projects/{project_id}/locations/{location}/repositories/{repository}。 workflow_config_id 是工作流程設定的 ID。 工作流程設定會將 ReleaseConfig 與時間表和身分配對。ReleaseConfig 會決定要編譯的程式碼，而這項工具會決定該程式碼的執行時間和執行程式碼的服務帳戶。 事前準備：您必須先使用 create_release_config 工具建立 ReleaseConfig。您必須提供 workflow_config.release_config 參數值，否則要求會失敗。 透過這項工作流程設定建立的工作流程調用作業，會以自訂服務帳戶執行。如要指定這個服務帳戶，請設定 invocationConfig.serviceAccount 參數值。如果省略此欄位，系統會改用存放區的 service_account。服務帳戶不得為預設的 Dataform 服務代理程式。服務帳戶必須具備執行工作流程的必要權限，且使用者必須獲得授權，才能以所選帳戶身分執行作業。這項授權通常是透過「服務帳戶使用者」(roles/iam.serviceAccountUser) IAM 角色授予，可授予服務帳戶本身或包含該服務帳戶的專案。
update_workflow_config	更新現有 Dataform 工作流程設定的屬性，例如執行排程 (cron)、相關聯的發布版本設定或叫用覆寫。 修改 cron_schedule後，所有日後排定的執行作業都會立即套用變更。 name 參數值的格式必須為 projects/{project_id}/locations/{location}/repositories/{repository}/workflowConfigs/{workflow_config}。 每次更新都必須提供 workflow_config.release_config 參數值。使用 get_workflow_config 工具讀取目前的工作流程設定，並在更新要求中加入其 release_config 值。 透過這項工作流程設定建立的工作流程調用作業，會以自訂服務帳戶執行。如要指定這個服務帳戶，請設定 invocationConfig.serviceAccount 參數值。如果省略此欄位，系統會改用存放區的 service_account。服務帳戶不得為預設的 Dataform 服務代理程式。服務帳戶必須具備執行工作流程的必要權限，且使用者必須獲得授權，才能以所選服務帳戶的身分執行作業。這項授權通常是透過「服務帳戶使用者」(roles/iam.serviceAccountUser) IAM 角色授予，可授予服務帳戶本身或包含該服務帳戶的專案。
list_release_configs	列出指定 Dataform 存放區中的版本設定。 parent 參數值的格式必須為 projects/{project_id}/locations/{location}/repositories/{repository}。
get_release_config	擷取單一 Dataform 發布版本設定。 name 參數值的格式必須為 projects/{project_id}/locations/{location}/repositories/{repository}/releaseConfigs/{release_config}。
create_release_config	在指定的 Dataform 存放區中建立新的發布設定。 parent 參數值的格式必須為 projects/{project_id}/locations/{location}/repositories/{repository}。 release_config_id 是使用者定義的版本設定 ID。如果使用者未指定 ID，請根據要求，使用小寫英文字母、數字和連字號，產生簡短的描述性 ID。 如果是 Google 代管的存放區，請省略 release_config.cron_schedule 參數值。如要驗證，請使用 get_repository 工具。如果缺少 git_remote_settings 欄位，存放區會由 Google 代管。如要排定管道執行時間，請使用 create_workflow_config 工具設定時間表。
update_release_config	更新現有的 Dataform 版本設定，做為自動編譯程式碼的範本。 更新 git_commitish 等欄位會影響日後編譯結果的產生方式，但不會追溯變更現有的 CompilationResult 資產。 更新由 Google 代管的存放區時，請省略 release_config.cron_schedule 參數值。如要驗證，請使用 get_repository 工具。如果缺少 git_remote_settings 欄位，存放區會由 Google 代管。如要排定管道，請使用 create_workflow_config 或 update_workflow_config 工具設定或更新排程。 name 參數值的格式必須為 projects/{project_id}/locations/{location}/repositories/{repository}/releaseConfigs/{release_config}。
create_compilation_result	在指定的 Google Cloud 雲端專案和位置中，建立新的 Dataform 編譯結果。 這項工具會將 .sqlx 檔案編譯為可執行的 SQL。代理程式需要知道，除非觸發新的編譯，否則後續的程式碼變更不會反映在這個結果中。 parent 參數值的格式必須為 projects/{project_id}/locations/{location}/repositories/{repository}。 代理程式可以檢查 CompilationResultAction 資源，驗證編譯後的 SQL，並視需要使用 BigQuery 工具進行模擬測試。 使用 create_workflow_invocation 工具觸發手動工作流程調用前，必須先取得有效的編譯結果。 必要條件：請先使用 create_repository 工具建立存放區，再呼叫 create_compilation_result 工具。
list_workflow_invocations	列出指定 Dataform 存放區中的工作流程叫用。 parent 參數值的格式必須為 projects/{project_id}/locations/{location}/repositories/{repository}。
create_workflow_invocation	在指定的 Dataform 存放區中，建立新的工作流程叫用。 parent 參數值的格式必須為 projects/{project_id}/locations/{location}/repositories/{repository}。 compilation_result 或 workflow_config 參數值為必填項。 如果使用 compilation_result，參數值必須採用 projects/{project_id}/locations/{location}/repositories/{repository}/compilationResults/{compilation_result} 格式。 如果使用 workflow_config，參數值必須採用 projects/{project_id}/locations/{location}/repositories/{repository}/workflowConfigs/{workflow_config} 格式。 先決條件：如要觸發叫用，請先使用 create_compilation_result 工具建立 compilation_result，或使用 create_workflow_config 工具建立 workflow_config。您無法直接從原始存放區程式碼觸發叫用。 工作流程呼叫會以服務帳戶執行，該帳戶取決於編譯來源： 如果使用 compilation_result，請設定 invocationConfig.serviceAccount 參數值。如果省略這個值，系統會使用存放區的預設 service_account。 如果使用 workflow_config，請勿設定 invocationConfig 參數。系統會自動以該工作流程設定中設定的服務帳戶執行呼叫。 服務帳戶不得為預設的 Dataform 服務代理程式。服務帳戶必須具備執行工作流程的必要權限，且使用者必須獲得授權，才能以所選服務帳戶的身分執行作業。這項授權通常是透過「服務帳戶使用者」角色 (roles/iam.serviceAccountUser) 授予，可授予服務帳戶本身或包含該帳戶的專案。
cancel_workflow_invocation	要求安全終止正在執行的 Dataform 工作流程叫用。 這項工具會將取消信號傳送至正在執行的工作流程。不過，如果工作流程中已完成任何 BigQuery 工作、資料表建立作業或斷言，系統不會還原這些項目。 name 參數值的格式必須為 projects/{project_id}/locations/{location}/repositories/{repository}/workflowInvocations/{workflow_invocation}。
get_compilation_result	擷取單一 Dataform 編譯結果。 name 參數值的格式必須為 projects/{project_id}/locations/{location}/repositories/{repository}/compilationResults/{compilation_result}。
query_compilation_actions	傳回指定 Dataform 編譯結果的編譯結果動作。 name 參數值的格式必須為 projects/{project_id}/locations/{location}/repositories/{repository}/compilationResults/{compilation_result}。
query_workflow_invocation_actions	傳回特定 Dataform 工作流程叫用的工作流程叫用動作。 這些動作代表構成工作流程的個別 BigQuery 工作、資料表建立作業或斷言。 name 參數值的格式必須為 projects/{project_id}/locations/{location}/repositories/{repository}/workflowInvocations/{workflow_invocation}。
get_workflow_invocation	擷取單一 Dataform 工作流程叫用。 name 參數值的格式必須為 projects/{project_id}/locations/{location}/repositories/{repository}/workflowInvocations/{workflow_invocation}。
list_workspaces	列出指定 Dataform 存放區中的開發工作區。 使用這項工具探索現有工作區，然後再執行檔案作業 (使用 read_file 或 write_file 等工具) 或提交程式碼 (使用 commit_workspace_changes 等工具)。 parent 參數值的格式必須為 projects/{project_id}/locations/{location}/repositories/{repository}。
get_workspace	擷取單一 Dataform 開發工作區。 name 參數值的格式必須為 projects/{project_id}/locations/{location}/repositories/{repository}/workspaces/{workspace}。 如果不知道確切的工作區名稱，請使用 list_workspaces 工具尋找。
create_workspace	在指定的 Dataform 存放區中建立新的開發工作區。 工作區是存放區的獨立可編輯結帳版本。當您需要跨多個檔案撰寫或修訂管道程式碼，並在提交前驗證程式碼時，請使用工作區。使用 write_file 和 remove_file 工具編輯工作區中的檔案，使用 commit_workspace_changes 工具記錄結果，並使用 push_git_commits 工具將已提交的變更發布至存放區。 請勿使用 commit_repository_changes 工具開發標準管道。該工具會直接寫入存放區，僅適用於筆記本或已儲存的查詢等單一檔案資產，且無法用於連線至遠端 Git 主機的存放區。 必要條件：必須有父項存放區。 parent 參數值的格式必須為 projects/{project_id}/locations/{location}/repositories/{repository}。 workspace_id 參數值是工作區要使用的 ID。 workspace 參數值會保留要建立的工作區。
query_directory_contents	傳回 Dataform 工作區中指定目錄的內容。 請先使用這項工具探索有效的檔案路徑，再呼叫 read_file 或 write_file 工具。 workspace 參數值的格式必須為 projects/{project_id}/locations/{location}/repositories/{repository}/workspaces/{workspace}。 path 參數值是從工作區根目錄到目錄的相對路徑。請勿使用目錄遍歷，例如 ..。如果省略，系統會使用工作區根目錄。
search_files	在 Dataform 工作區中尋找符合搜尋篩選器的檔案和目錄。 在大型存放區中依名稱或副檔名尋找檔案時，請使用這項工具，而非以 query_directory_contents 工具遞迴列出目錄。 workspace 參數值的格式必須為 projects/{project_id}/locations/{location}/repositories/{repository}/workspaces/{workspace}。 filter 參數值會限制結果。篩選功能僅支援 path 欄位 (例如 path="*.sqlx" 或 path="definitions/model.sqlx")。
read_file	傳回 Dataform 工作區中檔案的內容，包括未提交的變更。 使用這項工具讀取工作區的 workflow_settings.yaml 檔案，其中包含管道的編譯設定，例如預設 BigQuery 資料集、預設位置和 Dataform Core 版本。這個檔案位於管道目錄的根目錄，不一定是工作區根目錄，因為存放區可以在子目錄中保存多個管道。使用 search_files 工具找出檔案。 如要直接從存放區讀取已提交的檔案，而不使用工作區，請改用 read_repository_file 工具。請注意，read_repository_file 僅適用於未連線至遠端 Git 主機的存放區。 workspace 參數值的格式必須為 projects/{project_id}/locations/{location}/repositories/{repository}/workspaces/{workspace}。 path 參數值是檔案相對於工作區根目錄的路徑。請勿使用目錄遍歷，例如 ..。您可以使用 query_directory_contents 或 search_files 工具取得有效路徑。 revision 參數值可選取檔案的特定 Git 修訂版本。如果省略，系統會傳回檔案目前未提交的狀態。
write_file	在 Dataform 工作區中寫入檔案內容，如果檔案不存在，則會建立檔案。 提供的 contents 參數值會取代整個檔案，因此請先使用 read_file 工具讀取目前的內容，再進行部分編輯。在呼叫 commit_workspace_changes 工具前，變更會維持未提交狀態。 workspace 參數值的格式必須為 projects/{project_id}/locations/{location}/repositories/{repository}/workspaces/{workspace}。 path 參數值是檔案相對於工作區根目錄的路徑。請勿使用目錄遍歷，例如 ..。 contents 參數值必須是包含檔案內容的 Base64 編碼字串。
remove_file	刪除 Dataform 工作區中的檔案。 在呼叫 commit_workspace_changes 工具之前，系統不會實際刪除資料。 workspace 參數值的格式必須為 projects/{project_id}/locations/{location}/repositories/{repository}/workspaces/{workspace}。 path 參數值是檔案相對於工作區根目錄的路徑。請勿使用目錄遍歷，例如 ..。您可以使用 query_directory_contents 或 search_files 工具取得有效檔案路徑。
make_directory	在 Dataform 工作區中建立目錄，包括任何缺少的父項目錄。 workspace 參數值的格式必須為 projects/{project_id}/locations/{location}/repositories/{repository}/workspaces/{workspace}。 path 參數值是從工作區根目錄到目錄的相對路徑。請勿使用目錄遍歷，例如 ..。
commit_workspace_changes	在 Dataform 工作區中，記錄未提交變更的 Git 提交。 在透過 push_git_commits 工具發布之前，提交內容會保留在工作區的本機。 根據預設，系統會提交所有未提交的變更。如要只提交部分檔案，請提供 paths 參數值。 name 參數值的格式必須為 projects/{project_id}/locations/{location}/repositories/{repository}/workspaces/{workspace}。 author 參數值會識別為提交記錄的 Git 作者。author.name 和 author.email_address 都是必要欄位。提供可識別使用者身分的值，代表該使用者進行提交。請勿使用預留位置，因為這些位置會寫入 Git 記錄。 commit_message 參數值是提交的訊息。
push_git_commits	將 Dataform 工作區的已提交變更推送至存放區的 Git 遠端。 必要條件：您必須先使用 commit_workspace_changes 工具提交工作區編輯內容，才能推送。未提交的編輯內容會保留在本機，不會推送。 如果您打算使用 create_release_config 工具，請務必先推送提交內容。發布版本設定會針對 Git 遠端存放區解析 git_commitish，因此只有本機工作區中的分支版本或修訂版本會對其隱藏。 name 參數值的格式必須為 projects/{project_id}/locations/{location}/repositories/{repository}/workspaces/{workspace}。 remote_branch 參數值是要推送至的遠端分支。如果省略，啟用分支版本管理功能的工作區會推送至目前已簽出的分支版本，其他工作區則會推送至存放區設定的預設分支版本。
get_repository	擷取單一 Dataform 存放區，包括其 Git 遠端設定、工作區編譯覆寫和預設服務帳戶。 使用這項工具檢查 git_remote_settings 欄位，判斷如何與存放區互動。如果存在 git_remote_settings 欄位，表示存放區已連線至遠端 Git 主機，因此您必須使用工作區工具開發管道，例如 create_workspace 或 commit_workspace_changes。如果缺少這個欄位，存放區會由 Google 代管。在這種情況下，您仍可使用工作區開發管道。除非您要管理單一檔案資產，否則不建議使用 commit_repository_changes 等直接存放區工具。 name 參數值的格式必須為 projects/{project_id}/locations/{location}/repositories/{repository}。 如果不知道確切的存放區名稱，請使用 list_repositories 工具尋找。
update_repository	更新現有 Dataform 存放區的屬性，例如 Git 遠端設定、工作區編譯覆寫或預設服務帳戶。 必要條件：使用 get_repository 工具讀取目前的存放區狀態，再進行更新。 如果省略 update_mask 參數值，所有可變動的欄位都會覆寫為 repository 參數值中提供的值。如要只修改特定欄位，而不清除其他欄位，請在 update_mask 中列出這些欄位。 repository.name 參數值的格式必須為 projects/{project_id}/locations/{location}/repositories/{repository}。
create_folder	在指定的 Google Cloud 雲端專案和位置中，建立新的 Dataform 資料夾。 資料夾會將 Dataform 存放區整理成階層結構。建立資料夾不會將任何存放區移入其中。如要將存放區放在資料夾中，請在使用 create_repository 工具時設定 containing_folder 參數值。 請勿嘗試使用 update_repository 工具將現有存放區移至資料夾。存放區建立完成後，就無法使用 MCP 工具修改 containing_folder 欄位。 parent 參數值的格式必須為 projects/{project_id}/locations/{location}。 folder.display_name 參數值為必要項目，用於指定資料夾的易記名稱。

取得 MCP 工具規格

如要取得 MCP 伺服器中所有工具的 MCP 工具規格，請使用 tools/list 方法。以下範例說明如何使用 curl 列出 MCP 伺服器中目前可用的所有工具及其規格。

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 }'