// Copyright 2026 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package google.cloud.ces.v1;

import "google/api/field_behavior.proto";
import "google/cloud/ces/v1/auth.proto";
import "google/cloud/ces/v1/common.proto";
import "google/cloud/ces/v1/schema.proto";

option go_package = "cloud.google.com/go/ces/apiv1/cespb;cespb";
option java_multiple_files = true;
option java_outer_classname = "McpToolsetProto";
option java_package = "com.google.cloud.ces.v1";

// A toolset that contains a list of tools that are offered by the MCP
// server.
message McpToolset {
  // Required. The address of the MCP server, for example,
  // "https://example.com/mcp/". If the server is built with the MCP SDK, the
  // url should be suffixed with
  // "/mcp/". Only Streamable HTTP transport based servers are supported. See
  // https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http
  // for more details.
  string server_address = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. Authentication information required to access tools and execute a
  // tool against the MCP server. For bearer token authentication, the token
  // applies only to tool execution, not to listing tools. This requires that
  // tools can be listed without authentication.
  ApiAuthentication api_authentication = 2
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. Service Directory configuration for VPC-SC, used to resolve
  // service names within a perimeter.
  ServiceDirectoryConfig service_directory_config = 3
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. The TLS configuration. Includes the custom server certificates
  // that the client should trust.
  TlsConfig tls_config = 4 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The custom headers to send in the request to the MCP server. The
  // values must be in the format `$context.variables.<name_of_variable>` and
  // can be set in the session variables. See
  // https://docs.cloud.google.com/customer-engagement-ai/conversational-agents/ps/tool/open-api#openapi-injection
  // for more details.
  map<string, string> custom_headers = 5
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. Overrides for individual tools within this toolset.
  // This allows overriding specific details like descriptions, names,
  // or pinning the tools' states so they aren't fully dynamic.
  repeated McpToolOverride tool_overrides = 6
      [(google.api.field_behavior) = OPTIONAL];
}

// Overrides associated with a given tool in a Toolset.
// This enables "pinning" or "overriding" of tool definitions from the external
// dynamic server.
message McpToolOverride {
  // Required. The original name of the tool as it is emitted by the MCP server.
  string tool = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. If present, this tool uses this name in the Agent instead of the
  // original name. This is primarily used as an alias if the MCP server offers
  // poorly named tools.
  string name_override = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. If present, this tool uses this description instead of the
  // original description from the server.
  string description_override = 3 [(google.api.field_behavior) = OPTIONAL];

  // Output only. If present, this tool is "Pinned" and uses the snapshot values
  // as fallbacks if the server becomes temporarily unavailable or if no
  // Override is present.
  McpToolDefinition snapshot = 4 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// Container for a tool's core definition elements that are snapshot.
// Schemas in the snapshot are used as-is and cannot be overridden.
message McpToolDefinition {
  // Output only. The description of the MCP tool. This can be overridden
  // by `description_override` in `McpToolOverride`.
  string description = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The schema of the input arguments of the MCP tool.
  Schema input_schema = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The schema of the output arguments of the MCP tool.
  Schema output_schema = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
}