MCP Tools Reference: developerconnect.googleapis.com

工具：create-connection

在给定的项目和位置中创建新连接。

以下代码示例展示了如何使用 curl 调用 create-connection MCP 工具。

Curl 请求 
curl --location 'https://developerconnect.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "create-connection",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

输入架构

用于创建连接的消息

CreateConnectionRequest

JSON 表示法 
{
  "parent": string,
  "connectionId": string,
  "connection": {
    object (Connection)
  },
  "requestId": string,
  "validateOnly": boolean
}
字段
parent

string

必需。父级的值。
connectionId

string

必需。要用于连接的 ID，该 ID 将成为连接资源名称的最后一个组成部分。
connection

object (Connection)

必需。正在创建的资源
requestId

string

可选。用于标识请求的可选请求 ID。您可以指定一个唯一的请求 ID，这样，在您必须重试请求时，服务器就会知道忽略该请求（如果该请求已完成）。服务器将保证在第一次完成该请求后的至少 60 分钟内避免重复处理该请求。

例如，假设在您最初发出一个请求后，该请求超时，然后您使用相同的请求 ID 再次发出该请求，那么服务器便可检查是否收到了最初那个具有该请求 ID 的操作。如果收到了，服务器便会忽略这第二个请求。这样可以防止客户端意外创建重复的承诺。

请求 ID 必须是有效的 UUID，且不支持全部由零组成的 UUID（即 00000000-0000-0000-0000-000000000000）。
validateOnly

boolean

可选。如果进行了设置，则只会验证请求，而不会实际发布。

连接

JSON 表示法 
{
  "name": string,
  "createTime": string,
  "updateTime": string,
  "deleteTime": string,
  "labels": {
    string: string,
    ...
  },
  "installationState": {
    object (InstallationState)
  },
  "disabled": boolean,
  "reconciling": boolean,
  "annotations": {
    string: string,
    ...
  },
  "etag": string,
  "uid": string,
  "cryptoKeyConfig": {
    object (CryptoKeyConfig)
  },
  "gitProxyConfig": {
    object (GitProxyConfig)
  },

  // Union field connection_config can be only one of the following:
  "githubConfig": {
    object (GitHubConfig)
  },
  "githubEnterpriseConfig": {
    object (GitHubEnterpriseConfig)
  },
  "gitlabConfig": {
    object (GitLabConfig)
  },
  "gitlabEnterpriseConfig": {
    object (GitLabEnterpriseConfig)
  },
  "bitbucketDataCenterConfig": {
    object (BitbucketDataCenterConfig)
  },
  "bitbucketCloudConfig": {
    object (BitbucketCloudConfig)
  },
  "secureSourceManagerInstanceConfig": {
    object (SecureSourceManagerInstanceConfig)
  },
  "httpConfig": {
    object (GenericHTTPEndpointConfig)
  }
  // End of list of possible types for union field connection_config.
}
字段
name

string

标识符。连接的资源名称，格式为 projects/{project}/locations/{location}/connections/{connection_id}。
createTime

string (Timestamp format)

仅限输出。创建时间戳。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
updateTime

string (Timestamp format)

仅限输出。更新时间戳。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
deleteTime

string (Timestamp format)

仅限输出。删除时间戳。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
labels

map (key: string, value: string)

可选。标签作为键值对

包含一系列 "key": value 对的对象。示例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。
installationState

object (InstallationState)

仅限输出。连接的安装状态。
disabled

boolean

可选。如果 disabled 设置为 true，则此连接的功能会被停用。此连接中代码库的基于代码库的 API 方法和 Webhook 处理将被停用。
reconciling

boolean

仅限输出。在后台设置或更新连接时，此参数会设为 true。
annotations

map (key: string, value: string)

可选。允许客户端存储少量任意数据。

包含一系列 "key": value 对的对象。示例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。
etag

string

可选。此校验和由服务器根据其他字段的值计算得出，可在遇到更新和删除请求时发送，以确保客户端在继续操作之前具有最新值。
uid

string

仅限输出。系统为连接分配的唯一标识符。
cryptoKeyConfig

object (CryptoKeyConfig)

可选。加密密钥配置。此字段由客户管理的加密密钥 (CMEK) 功能使用。
gitProxyConfig

object (GitProxyConfig)

可选。Git 代理功能的配置。启用 Git 代理后，客户端可以对连接中关联的代码库执行 Git 操作。了解详情。
联合字段 connection_config。连接的配置，具体取决于提供商的类型。connection_config 只能是下列其中一项：
githubConfig

object (GitHubConfig)

与 github.com 的连接的配置。
githubEnterpriseConfig

object (GitHubEnterpriseConfig)

与 GitHub Enterprise 实例的连接的配置。
gitlabConfig

object (GitLabConfig)

与 gitlab.com 的连接的配置。
gitlabEnterpriseConfig

object (GitLabEnterpriseConfig)

与 GitLab Enterprise 实例的连接的配置。
bitbucketDataCenterConfig

object (BitbucketDataCenterConfig)

与 Bitbucket 数据中心实例的连接的配置。
bitbucketCloudConfig

object (BitbucketCloudConfig)

用于连接到 Bitbucket Cloud 实例的配置。
secureSourceManagerInstanceConfig

object (SecureSourceManagerInstanceConfig)

与 Secure Source Manager 实例的连接配置。
httpConfig

object (GenericHTTPEndpointConfig)

可选。与 HTTP 服务提供商的连接的配置。

GitHubConfig

JSON 表示法 
{
  "githubApp": enum (GitHubApp),
  "authorizerCredential": {
    object (OAuthCredential)
  },
  "appInstallationId": string,
  "installationUri": string
}
字段
githubApp

enum (GitHubApp)

必需。不可变。已安装到 GitHub 用户或组织的 GitHub 应用。
authorizerCredential

object (OAuthCredential)

可选。已授权 GitHub 应用的账号的 OAuth 凭证。建议使用机器人账号，而不是真人用户账号。OAuth 令牌必须与此配置的 GitHub 应用相关联。
appInstallationId

string (int64 format)

可选。GitHub 应用安装 ID。
installationUri

string

仅限输出。要前往的 URI，以便管理与此 GitHubConfig 关联的安装。

OAuthCredential

JSON 表示法 
{
  "oauthTokenSecretVersion": string,
  "username": string
}
字段
oauthTokenSecretVersion

string

必需。一个 SecretManager 资源，其中包含用于授权连接的 OAuth 令牌。格式：projects/*/secrets/*/versions/* 或 projects/*/locations/*/secrets/*/versions/*（如果该位置支持区域级 Secret）。
username

string

仅限输出。与此令牌关联的用户名。

GitHubEnterpriseConfig

JSON 表示法 
{
  "hostUri": string,
  "appId": string,
  "appSlug": string,
  "privateKeySecretVersion": string,
  "webhookSecretSecretVersion": string,
  "appInstallationId": string,
  "installationUri": string,
  "serviceDirectoryConfig": {
    object (ServiceDirectoryConfig)
  },
  "serverVersion": string,
  "sslCaCertificate": string,
  "organization": string
}
字段
hostUri

string

必需。此连接所针对的 GitHub Enterprise 主机的 URI。
appId

string (int64 format)

可选。根据清单创建的 GitHub 应用的 ID。
appSlug

string

仅限输出。GitHub 应用的网址友好名称。
privateKeySecretVersion

string

可选。包含 GitHub 应用私钥的 SecretManager 资源，格式为 projects/*/secrets/*/versions/* 或 projects/*/locations/*/secrets/*/versions/*（如果该位置支持区域级 Secret）。
webhookSecretSecretVersion

string

可选。包含 GitHub 应用的网络钩子 Secret 的 SecretManager 资源，格式为 projects/*/secrets/*/versions/* 或 projects/*/locations/*/secrets/*/versions/*（如果该位置支持区域级 Secret）。
appInstallationId

string (int64 format)

可选。GitHub 应用的安装 ID。
installationUri

string

仅限输出。要导航到的 URI，以便管理与此 GitHubEnterpriseConfig 关联的安装。
serviceDirectoryConfig

object (ServiceDirectoryConfig)

可选。使用 Service Directory 私密连接到 GitHub Enterprise 服务器的配置。仅当 GitHub Enterprise 服务器托管在本地且无法通过公共互联网访问时，才应设置此字段。如果此字段留空，系统将通过公共互联网调用 GitHub Enterprise 服务器。
serverVersion

string

仅限输出。在 host_uri 安装的 GitHub Enterprise 版本。
sslCaCertificate

string

可选。用于向 GitHub Enterprise 发出请求的 SSL 证书。
organization

string

可选。不可变。创建 GitHub 应用的 GitHub Enterprise 组织。

ServiceDirectoryConfig

JSON 表示法 
{
  "service": string
}
字段
service

string

必需。Service Directory 服务名称。格式：projects/{project}/locations/{location}/namespaces/{namespace}/services/{service}。

GitLabConfig

JSON 表示法 
{
  "webhookSecretSecretVersion": string,
  "readAuthorizerCredential": {
    object (UserCredential)
  },
  "authorizerCredential": {
    object (UserCredential)
  }
}
字段
webhookSecretSecretVersion

string

必需。不可变。包含 GitLab 项目的 webhook 密钥的 SecretManager 资源，格式为 projects/*/secrets/*/versions/* 或 projects/*/locations/*/secrets/*/versions/*（如果该位置支持区域级密钥）。此密钥用于验证 webhook。
readAuthorizerCredential

object (UserCredential)

必需。具有最低 read_api 范围访问权限和最低角色 reporter 的 GitLab 个人访问令牌。此个人访问令牌可见的 GitLab 项目将控制 Developer Connect 有权访问哪些项目。
authorizerCredential

object (UserCredential)

必需。具有最低 api 范围访问权限和最低角色 maintainer 的 GitLab 个人访问令牌。此个人访问令牌可见的 GitLab 项目将控制 Developer Connect 有权访问哪些项目。

UserCredential

JSON 表示法 
{
  "userTokenSecretVersion": string,
  "username": string
}
字段
userTokenSecretVersion

string

必需。一个 SecretManager 资源，其中包含用于向 Developer Connect 连接授权的用户令牌。格式：projects/*/secrets/*/versions/* 或 projects/*/locations/*/secrets/*/versions/*（如果该位置支持区域级 Secret）。
username

string

仅限输出。与此令牌关联的用户名。

GitLabEnterpriseConfig

JSON 表示法 
{
  "hostUri": string,
  "webhookSecretSecretVersion": string,
  "readAuthorizerCredential": {
    object (UserCredential)
  },
  "authorizerCredential": {
    object (UserCredential)
  },
  "serviceDirectoryConfig": {
    object (ServiceDirectoryConfig)
  },
  "sslCaCertificate": string,
  "serverVersion": string
}
字段
hostUri

string

必需。此连接所针对的 GitLab Enterprise 主机的 URI。
webhookSecretSecretVersion

string

必需。不可变。包含 GitLab 项目的 webhook 密钥的 SecretManager 资源，格式为 projects/*/secrets/*/versions/* 或 projects/*/locations/*/secrets/*/versions/*（如果该位置支持区域级密钥）。此密钥用于验证 webhook。
readAuthorizerCredential

object (UserCredential)

必需。具有最低 read_api 范围访问权限和最低角色 reporter 的 GitLab 个人访问令牌。此个人访问令牌可见的 GitLab 项目将控制 Developer Connect 有权访问哪些项目。
authorizerCredential

object (UserCredential)

必需。具有最低 api 范围访问权限和最低角色 maintainer 的 GitLab 个人访问令牌。此个人访问令牌可见的 GitLab 项目将控制 Developer Connect 有权访问哪些项目。
serviceDirectoryConfig

object (ServiceDirectoryConfig)

可选。使用 Service Directory 私密连接到 GitLab Enterprise 实例的配置。仅当 GitLab Enterprise 服务器托管在本地且无法通过公共互联网访问时，才应设置此字段。如果此字段留空，系统将通过公共互联网调用 GitLab Enterprise 服务器。
sslCaCertificate

string

可选。用于向 GitLab Enterprise 实例发出请求的 SSL 证书授权机构证书。
serverVersion

string

仅限输出。在 host_uri 上运行的 GitLab Enterprise 服务器的版本。

BitbucketDataCenterConfig

JSON 表示法 
{
  "hostUri": string,
  "webhookSecretSecretVersion": string,
  "readAuthorizerCredential": {
    object (UserCredential)
  },
  "authorizerCredential": {
    object (UserCredential)
  },
  "serviceDirectoryConfig": {
    object (ServiceDirectoryConfig)
  },
  "sslCaCertificate": string,
  "serverVersion": string
}
字段
hostUri

string

必需。此连接所针对的 Bitbucket 数据中心主机的 URI。
webhookSecretSecretVersion

string

必需。不可变。包含用于验证 Webhook 事件的 Webhook 密钥的 SecretManager 资源，格式为 projects/*/secrets/*/versions/* 或 projects/*/locations/*/secrets/*/versions/*（如果该位置支持区域密钥）。此密钥用于验证 webhook。
readAuthorizerCredential

object (UserCredential)

必需。具有最低 Repository read 访问权限的 HTTP 访问令牌。建议使用系统账号生成凭据。
authorizerCredential

object (UserCredential)

必需。具有最低 Repository admin 范围访问权限的 HTTP 访问令牌。创建 webhook 需要此权限。建议使用系统账号生成这些凭证。
serviceDirectoryConfig

object (ServiceDirectoryConfig)

可选。使用 Service Directory 私密连接到 Bitbucket 数据中心 实例的配置。仅当 Bitbucket 数据中心托管在本地且无法通过公共互联网访问时，才应设置此项。如果此字段留空，系统将通过公共互联网调用 Bitbucket 数据中心。
sslCaCertificate

string

可选。向 Bitbucket 数据中心发出请求时要信任的 SSL 证书授权机构。
serverVersion

string

仅限输出。在 host_uri 上运行的 Bitbucket 数据中心服务器的版本。

BitbucketCloudConfig

JSON 表示法 
{
  "workspace": string,
  "webhookSecretSecretVersion": string,
  "readAuthorizerCredential": {
    object (UserCredential)
  },
  "authorizerCredential": {
    object (UserCredential)
  }
}
字段
workspace

string

必需。要连接到 Google Cloud Platform 的 Bitbucket Cloud 工作区 ID。
webhookSecretSecretVersion

string

必需。不可变。包含用于验证 Webhook 事件的 Webhook 密钥的 SecretManager 资源，格式为 projects/*/secrets/*/versions/* 或 projects/*/locations/*/secrets/*/versions/*（如果该位置支持区域密钥）。此值用于验证和创建 webhook。
readAuthorizerCredential

object (UserCredential)

必需。具有最低 repository 访问权限的访问令牌。它可以是工作区、项目或代码库访问令牌。建议使用系统账号生成凭据。
authorizerCredential

object (UserCredential)

必需。具有最低 repository、pullrequest 和 webhook 范围访问权限的访问令牌。它可以是工作区、项目或代码库访问令牌。创建 webhook 需要此权限。建议使用系统账号生成这些凭证。

SecureSourceManagerInstanceConfig

JSON 表示法 
{
  "instance": string
}
字段
instance

string

必需。不可变。Secure Source Manager 实例资源，格式为 projects/*/locations/*/instances/*

GenericHTTPEndpointConfig

JSON 表示法 
{
  "hostUri": string,
  "serviceDirectoryConfig": {
    object (ServiceDirectoryConfig)
  },
  "sslCaCertificate": string,

  // Union field authentication can be only one of the following:
  "basicAuthentication": {
    object (BasicAuthentication)
  },
  "bearerTokenAuthentication": {
    object (BearerTokenAuthentication)
  }
  // End of list of possible types for union field authentication.
}
字段
hostUri

string

必需。不可变。服务提供商的 HTTPS 端点。
serviceDirectoryConfig

object (ServiceDirectoryConfig)

可选。使用 Service Directory 私密连接到 HTTP 服务提供商的配置。仅当 HTTP 服务提供商托管在本地且无法通过公共互联网访问时，才应设置此字段。如果此字段留空，则系统将通过公共互联网调用 HTTP 服务提供商。
sslCaCertificate

string

可选。用于向 HTTP 服务提供商发送请求的 SSL 证书。
联合字段 authentication。用于向 HTTP 服务提供商发送请求的身份验证机制。authentication 只能是下列其中一项：
basicAuthentication

object (BasicAuthentication)

可选。使用用户名和密码进行基本身份验证。
bearerTokenAuthentication

object (BearerTokenAuthentication)

可选。使用令牌进行不记名令牌身份验证。

BasicAuthentication

JSON 表示法 
{
  "username": string,

  // Union field password can be only one of the following:
  "passwordSecretVersion": string
  // End of list of possible types for union field password.
}
字段
username

string

必需。要进行身份验证的用户名。
联合字段 password。用于进行身份验证的密码。password 只能是下列其中一项：
passwordSecretVersion

string

用于进行身份验证的密码 SecretManager 密文版本。

BearerTokenAuthentication

JSON 表示法 
{

  // Union field token can be only one of the following:
  "tokenSecretVersion": string
  // End of list of possible types for union field token.
}
字段
联合字段 token。用于进行身份验证的令牌。token 只能是下列其中一项：
tokenSecretVersion

string

可选。要作为其进行身份验证的令牌 SecretManager 密钥版本。

时间戳

JSON 表示法 
{
  "seconds": string,
  "nanos": integer
}
字段
seconds

string (int64 format)

表示世界协调时间 (UTC) 的秒数（从 Unix 纪元 1970-01-01T00:00:00Z 开始算起）。必须介于 -62135596800 到 253402300799 之间（含边界值，对应于 0001-01-01T00:00:00Z 到 9999-12-31T23:59:59Z）。
nanos

integer

秒数的非负小数部分（以纳秒为单位）。此字段是时长的纳秒部分，而不是秒的替代。对于含小数部分的负秒数，仍必须包含按时间递升的非负纳秒值。必须在 0 到 999,999,999 之间（含边界值）。

LabelsEntry

JSON 表示法 
{
  "key": string,
  "value": string
}
字段
key

string
value

string

InstallationState

JSON 表示法 
{
  "stage": enum (Stage),
  "message": string,
  "actionUri": string
}
字段
stage

enum (Stage)

仅限输出。安装流程的当前步骤。
message

string

仅限输出。说明用户接下来应采取哪些措施来继续安装的消息。如果安装已完成，则为空字符串。
actionUri

string

仅限输出。Link to follow for next action. 如果安装已完成，则为空字符串。

AnnotationsEntry

JSON 表示法 
{
  "key": string,
  "value": string
}
字段
key

string
value

string

CryptoKeyConfig

JSON 表示法 
{
  "keyReference": string
}
字段
keyReference

string

必需。用于加密/解密客户数据的密钥的名称。对于 Cloud KMS 中的密钥，密钥应采用 projects/*/locations/*/keyRings/*/cryptoKeys/* 格式。

GitProxyConfig

JSON 表示法 
{
  "enabled": boolean,
  "httpProxyBaseUri": string
}
字段
enabled

boolean

可选。如果将此项设置为 true，则可以使用 Git 代理对连接中关联的代码库执行 Git 操作。
httpProxyBaseUri

string

仅限输出。HTTP 代理端点的基本 URI。格式为 https://{generatedID}-c-h-{shortRegion}.developerconnect.dev。仅当 enabled 设置为 true 时才会填充。此端点供与 Developer Connect 集成的其他 Google 服务使用。

GitHubApp

表示可以安装到 GitHub 用户或组织并与 Developer Connect 搭配使用的各种 GitHub 应用。

枚举
GIT_HUB_APP_UNSPECIFIED 未指定 GitHub 应用。
DEVELOPER_CONNECT Developer Connect GitHub 应用。
FIREBASE Firebase GitHub 应用。
GEMINI_CODE_ASSIST Gemini Code Assist 应用。
DATAFORM Dataform GitHub 应用。

阶段

安装流程的阶段。

枚举
STAGE_UNSPECIFIED 未指定阶段。
PENDING_CREATE_APP 仅适用于 GitHub Enterprise。已请求创建应用。用户需要在其 GitHub Enterprise 主机中确认创建。
PENDING_USER_OAUTH 用户需要通过 OAuth 授权 GitHub（或 Enterprise）应用。
PENDING_INSTALL_APP 用户需要点击链接来安装 GitHub（或 Enterprise）应用。
COMPLETE 安装流程已完成。

输出架构

此资源表示由网络 API 调用引发的长时间运行的操作。

操作

JSON 表示法 
{
  "name": string,
  "metadata": {
    "@type": string,
    field1: ...,
    ...
  },
  "done": boolean,

  // Union field result can be only one of the following:
  "error": {
    object (Status)
  },
  "response": {
    "@type": string,
    field1: ...,
    ...
  }
  // End of list of possible types for union field result.
}
字段
name

string

由服务器分配的名称，该名称仅在最初返回它的那项服务中是唯一的。如果您使用默认 HTTP 映射，则 name 应是以 operations/{unique_id} 结尾的资源名称。
metadata

object

与操作关联的服务专属元数据。它通常包含进度信息和常见元数据（如创建时间）。一些服务可能不会提供此类元数据。任何返回长时间运行的操作的方法都应记录元数据类型（如果有的话）。

此对象可以包含任意类型的字段。附加字段 "@type" 包含用于标示相应类型的 URI。示例：{ "id": 1234, "@type": "types.example.com/standard/id" }。
done

boolean

如果值为 false，则表示操作仍在进行中。如果为 true，则表示操作已完成，其结果不是 error 就是 response。
联合字段 result。操作结果，可以是 error，也可以是有效的 response。如果 done == false，则既不会设置 error，也不会设置 response。如果 done == true，则只能设置 error 或 response 中的一项。部分服务可能不会提供结果。result 只能是下列其中一项：
error

object (Status)

操作失败或被取消时表示有错误发生的结果。
response

object

操作的常规成功响应。如果原始方法在成功时不返回任何数据（如 Delete），则响应为 google.protobuf.Empty。如果原始方法为标准 Get/Create/Update 方法，则响应应该为资源。对于其他方法，响应类型应为 XxxResponse，其中 Xxx 是原始方法的名称。例如，如果原始方法名称为 TakeSnapshot()，则推断的响应类型为 TakeSnapshotResponse。

此对象可以包含任意类型的字段。附加字段 "@type" 包含用于标示相应类型的 URI。示例：{ "id": 1234, "@type": "types.example.com/standard/id" }。

不限

JSON 表示法 
{
  "typeUrl": string,
  "value": string
}
字段
typeUrl

string

使用 URI 引用标识序列化 Protobuf 消息的类型，该引用由以斜杠结尾的前缀和完全限定的类型名称组成。

示例：type.googleapis.com/google.protobuf.StringValue

此字符串必须至少包含一个 / 字符，并且最后一个 / 之后的内容必须是规范形式的类型的完全限定名称，不带前导点。请勿在这些 URI 引用上写入 scheme，以免客户端尝试与其联系。

前缀是任意的，Protobuf 实现应直接剥离最后一个 / 之前的所有内容（包括该 ），以识别类型。type.googleapis.com/ 是某些旧版实现所需的常见默认前缀。此前缀并不表示类型的来源，并且包含该前缀的 URI 不会响应任何请求。

所有类型网址字符串都必须是合法的 URI 引用，并具有额外的限制（对于文本格式），即引用的内容只能包含字母数字字符、百分比编码转义符以及以下集合中的字符（不包括外部反引号）：/-.~_!$&()*+,;=。尽管我们允许百分比编码，但实现不应将其转义，以免与现有解析器混淆。例如，type.googleapis.com%2FFoo 应被拒绝。

在 Any 的原始设计中，曾考虑过在这些类型网址上启动类型解析服务的可能性，但 Protobuf 从未实现过这种服务，并且认为与这些网址联系存在问题，可能存在安全隐患。请勿尝试联系类型网址。
value

string (bytes format)

包含 type_url 所描述类型的 Protobuf 序列化。

使用 base64 编码的字符串。

状态

JSON 表示法 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
字段
code

integer

状态代码，应为 google.rpc.Code 的枚举值。
message

string

面向开发者的错误消息（应采用英语）。任何向用户显示的错误消息都应进行本地化并通过 google.rpc.Status.details 字段发送，或者由客户端进行本地化。
details[]

object

包含错误详细信息的消息列表。有一组通用的消息类型可供 API 使用。

可以包含任意类型字段的对象。附加字段 "@type" 包含用于标示相应类型的 URI。示例：{ "id": 1234, "@type": "types.example.com/standard/id" }。

工具注释

工具注解会发送到 MCP 客户端，用于描述给定工具的基本风险。大多数客户端会将这些提示视为不可信，但可用于决定何时向用户发送确认提示。

除了标题字符串之外，还定义了以下布尔值提示：

  • readOnlyHint：如果为 true，则该工具不会修改其环境。默认值：false。
  • destructiveHint：如果为 true，则该工具可以执行破坏性操作。如果为 false，则该工具只能执行添加操作。默认值：true。
  • idempotentHint：如果为 true，则使用相同参数重复调用该工具不会对其环境产生额外影响。默认值：false。
  • openWorldHint：如果为 true，则该工具可以与外部实体的“开放世界”进行交互。如果为 false，则该工具只能与内部实体交互。例如，网页搜索工具是开放世界，而记忆工具不是开放世界。

破坏性提示：❌ | 幂等性提示：❌ | 只读提示：❌ | 开放世界提示：❌