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.

Package tools provides shared utilities for MCP tool handlers.

Index

• func AddClusterContextParams(sc *server.ServerContext) []mcp.ToolOption
• func CheckMutatingOperation(sc *server.ServerContext, operation string) *mcp.CallToolResult
• func ExtractClusterParam(args map[string]interface{}) string
• func FormatAuthenticationError(err error) string
• func FormatClusterError(err error, clusterName string) string
• func GetK8sClient(ctx context.Context, sc *server.ServerContext) (k8s.Client, error)
• func IsAuthenticationError(err error) bool
• 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 CheckMutatingOperation

func CheckMutatingOperation(sc *server.ServerContext, operation string) *mcp.CallToolResult

CheckMutatingOperation verifies if a mutating operation is allowed given the current server configuration. Returns an error result if blocked, nil if allowed.

This centralizes the non-destructive mode check to avoid code duplication across all tool handlers that perform mutating operations.

Operations are allowed if:

• NonDestructiveMode is disabled, OR
• DryRun mode is enabled (operations will be validated but not applied), OR
• The operation is explicitly listed in AllowedOperations

Protected operations include: create, apply, delete, patch, scale, exec, port-forward

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 FormatAuthenticationError

func FormatAuthenticationError(err error) string

FormatAuthenticationError returns a user-friendly error message for authentication errors. If the error is not an authentication error, returns a generic message.

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, error)

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.

When downstream OAuth strict mode is enabled and authentication fails, returns (nil, error) with an authentication error.

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

Error Handling

Returns (nil, error) when downstream OAuth strict mode is enabled and:

• No OAuth token is present in the context (server.ErrOAuthTokenMissing)
• The OAuth token cannot be used to create a client (server.ErrOAuthClientFailed)

Returns (client, nil) on success.

func IsAuthenticationError

func IsAuthenticationError(err error) bool

IsAuthenticationError returns true if the error is an OAuth authentication error. This can be used to distinguish between authentication failures and other errors.

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.