tools

Documentation

Overview

Package tools provides shared utilities and types for MCP tool implementations.

Package tools provides shared utilities and types for MCP tool implementations.

Index

• func AddClusterContextParams(sc *server.ServerContext) []mcp.ToolOption
• func ExtractClusterParam(args map[string]interface{}) string
• func FormatClusterError(err error, clusterName string) string
• func GetK8sClient(ctx context.Context, sc *server.ServerContext) k8s.Client
• func ValidateClusterParam(sc *server.ServerContext, clusterName string) string
• type ClusterClient
  • func GetClusterClient(ctx context.Context, sc *server.ServerContext, clusterName string) (*ClusterClient, string)
  • func (cc *ClusterClient) ClusterName() string
  • func (cc *ClusterClient) IsFederated() bool
  • func (cc *ClusterClient) K8s() k8s.Client
  • func (cc *ClusterClient) User() *federation.UserInfo
• type EmptyRequest

Functions

func AddClusterContextParams

func AddClusterContextParams(sc *server.ServerContext) []mcp.ToolOption

AddClusterContextParams returns tool options for cluster and kubeContext parameters based on the server's operating mode. This ensures backwards compatibility:

• cluster parameter is only added when federation is enabled
• kubeContext parameter is only added when NOT in in-cluster mode

Usage in tool registration:

opts := []mcp.ToolOption{
    mcp.WithDescription("..."),
}
opts = append(opts, tools.AddClusterContextParams(sc)...)
opts = append(opts, /* tool-specific params */...)
tool := mcp.NewTool("tool_name", opts...)

func ExtractClusterParam

func ExtractClusterParam(args map[string]interface{}) string

ExtractClusterParam extracts the cluster parameter from request arguments. Returns an empty string if not provided.

func FormatClusterError

func FormatClusterError(err error, clusterName string) string

FormatClusterError formats a federation error into a user-friendly message. This function handles the various error types from the federation package and returns appropriate messages for MCP tool responses.

Security

This function uses UserFacingError() methods from federation error types to ensure no internal details (cluster names, network topology) are leaked.

TODO: This function will be used when federated k8s.Client wrapper is implemented to provide user-friendly error messages for multi-cluster operations.

func GetK8sClient

func GetK8sClient(ctx context.Context, sc *server.ServerContext) k8s.Client

GetK8sClient returns the appropriate Kubernetes client for the given context. If downstream OAuth is enabled and an access token is present in the context, it returns a per-user client. Otherwise, it returns the shared service account client.

Tool handlers should use this function instead of directly calling sc.K8sClient() to ensure proper OAuth passthrough when enabled.

func ValidateClusterParam

func ValidateClusterParam(sc *server.ServerContext, clusterName string) string

ValidateClusterParam validates that the cluster parameter can be used. Returns an error message if the cluster parameter is specified but federation is not enabled or not yet supported.

This is a convenience function for handlers that don't yet support multi-cluster operations but want to provide clear error messages.

Types

type ClusterClient

type ClusterClient struct {
	// contains filtered or unexported fields
}

ClusterClient provides access to Kubernetes operations with multi-cluster support. It wraps either the local k8s.Client or federation-based clients.

Usage Pattern

Tool handlers should use GetClusterClient to get the appropriate client:

client, errMsg := tools.GetClusterClient(ctx, sc, clusterName)
if errMsg != "" {
    return mcp.NewToolResultError(errMsg), nil
}
// Use client.K8s() for standard operations, or client.User() for user info

func GetClusterClient

func GetClusterClient(ctx context.Context, sc *server.ServerContext, clusterName string) (*ClusterClient, string)

GetClusterClient returns a ClusterClient for the specified cluster. If clusterName is empty, returns a client for the local cluster.

Federation Behavior

When federation is enabled AND a cluster name is specified:

• Returns an error (federation-based operations not yet implemented in k8s.Client)
• Future: will create a federated client with user impersonation

When federation is NOT enabled or cluster is empty:

• Returns the standard k8s client from ServerContext
• Does not require OAuth authentication

Return Values

Returns (ClusterClient, "") on success or (nil, errorMessage) on failure. The error message is suitable for direct use in MCP tool responses.

func (*ClusterClient) ClusterName

func (cc *ClusterClient) ClusterName() string

ClusterName returns the target cluster name (empty for local cluster).

func (*ClusterClient) IsFederated

func (cc *ClusterClient) IsFederated() bool

IsFederated returns true if this client uses federation.

func (*ClusterClient) K8s

func (cc *ClusterClient) K8s() k8s.Client

K8s returns the underlying Kubernetes client. This client is configured for the target cluster.

func (*ClusterClient) User

func (cc *ClusterClient) User() *federation.UserInfo

User returns the authenticated user info. Returns nil if federation is not enabled or if using local fallback.

type EmptyRequest

type EmptyRequest struct{}

EmptyRequest represents a request with no parameters. Used by tools that don't require any input arguments.