MCP Reference: dataform.googleapis.com

Dataform MCP 服务器提供用于与 Dataform 交互的工具。

Model Context Protocol (MCP) 服务器充当外部服务（为大语言模型 [LLM] 或 AI 应用提供上下文、数据或功能）与 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 参数，以便在新代码库中将其保留为未设置状态。请注意，默认情况下，系统会对新项目强制执行严格的 act-as 检查，因此在此代码库中执行工作流需要使用自定义服务账号。
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 服务代理。服务账号必须具有执行工作流所需的权限，并且用户必须获得授权才能以所选账号的身份执行操作。此授权通常通过 Service Account User (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 服务代理。服务账号必须具有执行工作流所需的权限，并且用户必须获得授权才能以所选服务账号的身份执行操作。此授权通常通过 Service Account User (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_compilation_result 工具之前，使用 create_repository 工具创建代码库。
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 服务代理。服务账号必须具有执行工作流所需的权限，并且用户必须获得授权才能以所选服务账号的身份执行操作。此授权通常通过 Service Account User 角色 (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 核心版本。此文件位于流水线目录的根目录中，该目录不一定是工作区根目录，因为一个代码库可以在子目录中包含多个流水线。使用 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
}'