tools

package
v1.0.8 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 12, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

README

MCP Tools & Permissions

The handler filters tools dynamically based on the Sysdig user's permissions. Each tool declares mandatory permissions via WithRequiredPermissions.

Sysdig Monitor
Tool File Capability Required Permissions Useful Prompts
k8s_list_clusters tool_k8s_list_clusters.go Lists Kubernetes cluster information. metrics-data.read "List all Kubernetes clusters"
k8s_list_nodes tool_k8s_list_nodes.go Lists Kubernetes node information. metrics-data.read "List all Kubernetes nodes in the cluster 'production-gke'"
k8s_list_workloads tool_k8s_list_workloads.go Lists Kubernetes workload information. metrics-data.read "List all desired workloads in the cluster 'production-gke' and namespace 'default'"
k8s_list_pod_containers tool_k8s_list_pod_containers.go Retrieves information from a particular pod and container. metrics-data.read "Show me info for pod 'my-pod' in cluster 'production-gke'"
k8s_list_cronjobs tool_k8s_list_cronjobs.go Retrieves information from the cronjobs in the cluster. metrics-data.read "List all cronjobs in cluster 'prod' and namespace 'default'"
k8s_list_count_pods_per_cluster tool_k8s_list_count_pods_per_cluster.go List the count of running Kubernetes Pods grouped by cluster and namespace. metrics-data.read "List the count of running Kubernetes Pods in cluster 'production'"
k8s_list_top_unavailable_pods tool_k8s_list_top_unavailable_pods.go Shows the top N pods with the highest number of unavailable or unready replicas. metrics-data.read "Show the top 20 unavailable pods in cluster 'production'"
k8s_list_top_restarted_pods tool_k8s_list_top_restarted_pods.go Lists the pods with the highest number of container restarts. metrics-data.read "Show the top 10 pods with the most container restarts in cluster 'production'"
k8s_list_top_http_errors_in_pods tool_k8s_list_top_http_errors_in_pods.go Lists the pods with the highest rate of HTTP 4xx and 5xx errors over a specified time interval. metrics-data.read "Show the top 20 pods with the most HTTP errors in cluster 'production'"
k8s_list_top_network_errors_in_pods tool_k8s_list_top_network_errors_in_pods.go Shows the top network errors by pod over a given interval. metrics-data.read "Show the top 10 pods with the most network errors in cluster 'production'"
k8s_list_top_cpu_consumed_workload tool_k8s_list_top_cpu_consumed_workload.go Identifies the Kubernetes workloads (all containers) consuming the most CPU (in cores). metrics-data.read "Show the top 10 workloads consuming the most CPU in cluster 'production'"
k8s_list_top_cpu_consumed_container tool_k8s_list_top_cpu_consumed_container.go Identifies the Kubernetes containers consuming the most CPU (in cores). metrics-data.read "Show the top 10 containers consuming the most CPU in cluster 'production'"
k8s_list_top_memory_consumed_workload tool_k8s_list_top_memory_consumed_workload.go Lists memory-intensive workloads (all containers). metrics-data.read "Show the top 10 workloads consuming the most memory in cluster 'production'"
k8s_list_top_memory_consumed_container tool_k8s_list_top_memory_consumed_container.go Lists memory-intensive containers. metrics-data.read "Show the top 10 containers consuming the most memory in cluster 'production'"
k8s_list_underutilized_pods_cpu_quota tool_k8s_list_underutilized_pods_cpu_quota.go List Kubernetes pods with CPU usage below 25% of the quota limit. metrics-data.read "Show the top 10 underutilized pods by CPU quota in cluster 'production'"
k8s_list_underutilized_pods_memory_quota tool_k8s_list_underutilized_pods_memory_quota.go List Kubernetes pods with memory usage below 25% of the limit. metrics-data.read "Show the top 10 underutilized pods by memory quota in cluster 'production'"
Sysdig Secure
Tool File Capability Required Permissions Useful Prompts
list_runtime_events tool_list_runtime_events.go Query runtime events with filters, cursor, scope. policy-events.read "Show high severity runtime events from last 2h."
get_event_info tool_get_event_info.go Pull full payload for a single policy event. policy-events.read "Fetch event abc123 details."
get_event_process_tree tool_get_event_process_tree.go Retrieve the process tree for an event when available. policy-events.read "Show the process tree behind event abc123."
run_sysql tool_run_sysql.go Execute caller-supplied Sysdig SysQL queries safely. sage.exec, risks.read "Run the following SysQL…".
Sysdig Monitor & Sysdig Secure
Tool File Capability Required Permissions Useful Prompts
generate_sysql tool_generate_sysql.go Convert natural language to SysQL via Sysdig Sage. sage.exec (does not work with Service Accounts) "Create a SysQL to list S3 buckets."

Historical range (start / end)

All Sysdig Monitor k8s_list_* tools accept two optional parameters:

  • start — RFC3339 timestamp, e.g. 2026-04-16T00:00:00Z
  • end — RFC3339 timestamp, e.g. 2026-04-16T01:00:00Z

When omitted, tools return an instant snapshot (current behaviour). When provided, the underlying PromQL is wrapped in the aggregation appropriate for each tool and evaluated at end:

Tool group Wrapping applied when windowed
CPU / memory usage, underutilized quota, pod count avg_over_time(metric[Ns])
Top restarted pods increase(kube_pod_container_status_restarts_total[Ns])
Top unavailable pods min_over_time(kube_workload_status_unavailable[Ns]) >= 1 (Sysdig-canonical pattern — requires continuous unavailability for the entire window)
HTTP / network errors sum_over_time(metric[Ns]) / N (rate per second)
Inventory tools (clusters, nodes, workloads, pod_containers, cronjobs) max_over_time(metric[Ns]) > 0 (workloads with status=ready/desired/running drop the > 0 guard)

Validation rules (helper: utils.go):

  • end without start → error.
  • start without end → end defaults to now.
  • end in the future → clamped to now.
  • end <= start → error.

Windowed queries carry a 60 s client-side PromQL Timeout to fail fast before the Sysdig edge proxy's own 80–90 s cut-off.

Adding a New Tool

  1. See other tools: Check how other tools are implemented so you can have the context on how they should look like.

  2. Create Files: Add tool_<name>.go and tool_<name>_test.go in internal/infra/mcp/tools/.

  3. Implement the Tool:

    • Define a struct that holds the Sysdig client, or any required collaborator.
    • Implement the handle method, which contains the tool's core logic.
    • Implement the RegisterInServer method to define the tool's MCP schema, including its name, description, parameters, and required permissions. Use helpers from utils.go.
    • If a tool does not have any required permission, just specify WithRequiredPermissions(). If the tool requires one or multiple permissions, specify them like WithRequiredPermissions("a.permission", "another.permission").

  4. Write Tests: Use Ginkgo/Gomega to write BDD-style tests. Mock the Sysdig client to cover:

    • Parameter validation
    • Permission metadata
    • Sysdig API client interactions (mocked)
    • Error handling

  5. Register the Tool: Add the new tool to setupHandler() in cmd/server/main.go.

  6. Document: Add the new tool to the README.md and the table in this document.

Testing Philosophy

  • Use BDD-style tests with Ginkgo/Gomega
  • Each tool requires comprehensive test coverage for:
    • Parameter validation (all possible combinations need to be tested)
    • Permission metadata
    • Sysdig API client interactions (mocked using go-mock)
    • Error handling
  • No focused specs (FDescribe, FIt) should be committed

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Examples 

func Examples[T any](examples ...T) mcp.PropertyOption

func RequiredPermissionsFromTool 

func RequiredPermissionsFromTool(tool mcp.Tool) []string

func WithRequiredPermissions 

func WithRequiredPermissions(permissions ...string) mcp.ToolOption

func WithTimeWindowParams added in v1.0.8 

func WithTimeWindowParams() mcp.ToolOption

Types

type K8sListClusters added in v0.5.2 

type K8sListClusters struct {
	SysdigClient sysdig.ExtendedClientWithResponsesInterface
	// contains filtered or unexported fields
}

func NewK8sListClusters added in v0.5.2 

func NewK8sListClusters(sysdigClient sysdig.ExtendedClientWithResponsesInterface, clk clock.Clock) *K8sListClusters

func (*K8sListClusters) RegisterInServer added in v0.5.2 

func (t *K8sListClusters) RegisterInServer(s *server.MCPServer)

type K8sListCountPodsPerCluster added in v0.5.2 

type K8sListCountPodsPerCluster struct {
	SysdigClient sysdig.ExtendedClientWithResponsesInterface
	// contains filtered or unexported fields
}

func NewK8sListCountPodsPerCluster added in v0.5.2 

func NewK8sListCountPodsPerCluster(sysdigClient sysdig.ExtendedClientWithResponsesInterface, clk clock.Clock) *K8sListCountPodsPerCluster

func (*K8sListCountPodsPerCluster) RegisterInServer added in v0.5.2 

func (t *K8sListCountPodsPerCluster) RegisterInServer(s *server.MCPServer)

type K8sListCronjobs added in v0.5.2 

type K8sListCronjobs struct {
	SysdigClient sysdig.ExtendedClientWithResponsesInterface
	// contains filtered or unexported fields
}

func NewK8sListCronjobs added in v0.5.2 

func NewK8sListCronjobs(sysdigClient sysdig.ExtendedClientWithResponsesInterface, clk clock.Clock) *K8sListCronjobs

func (*K8sListCronjobs) RegisterInServer added in v0.5.2 

func (t *K8sListCronjobs) RegisterInServer(s *server.MCPServer)

type K8sListNodes added in v0.5.2 

type K8sListNodes struct {
	SysdigClient sysdig.ExtendedClientWithResponsesInterface
	// contains filtered or unexported fields
}

func NewK8sListNodes added in v0.5.2 

func NewK8sListNodes(sysdigClient sysdig.ExtendedClientWithResponsesInterface, clk clock.Clock) *K8sListNodes

func (*K8sListNodes) RegisterInServer added in v0.5.2 

func (t *K8sListNodes) RegisterInServer(s *server.MCPServer)

type K8sListPodContainers added in v0.5.2 

type K8sListPodContainers struct {
	SysdigClient sysdig.ExtendedClientWithResponsesInterface
	// contains filtered or unexported fields
}

func NewK8sListPodContainers added in v0.5.2 

func NewK8sListPodContainers(sysdigClient sysdig.ExtendedClientWithResponsesInterface, clk clock.Clock) *K8sListPodContainers

func (*K8sListPodContainers) RegisterInServer added in v0.5.2 

func (t *K8sListPodContainers) RegisterInServer(s *server.MCPServer)

type K8sListTopCPUConsumedContainer added in v0.5.2 

type K8sListTopCPUConsumedContainer struct {
	SysdigClient sysdig.ExtendedClientWithResponsesInterface
	// contains filtered or unexported fields
}

func NewK8sListTopCPUConsumedContainer added in v0.5.2 

func NewK8sListTopCPUConsumedContainer(sysdigClient sysdig.ExtendedClientWithResponsesInterface, clk clock.Clock) *K8sListTopCPUConsumedContainer

func (*K8sListTopCPUConsumedContainer) RegisterInServer added in v0.5.2 

func (t *K8sListTopCPUConsumedContainer) RegisterInServer(s *server.MCPServer)

type K8sListTopCPUConsumedWorkload added in v0.5.2 

type K8sListTopCPUConsumedWorkload struct {
	SysdigClient sysdig.ExtendedClientWithResponsesInterface
	// contains filtered or unexported fields
}

func NewK8sListTopCPUConsumedWorkload added in v0.5.2 

func NewK8sListTopCPUConsumedWorkload(sysdigClient sysdig.ExtendedClientWithResponsesInterface, clk clock.Clock) *K8sListTopCPUConsumedWorkload

func (*K8sListTopCPUConsumedWorkload) RegisterInServer added in v0.5.2 

func (t *K8sListTopCPUConsumedWorkload) RegisterInServer(s *server.MCPServer)

type K8sListTopHttpErrorsInPods added in v0.5.2 

type K8sListTopHttpErrorsInPods struct {
	SysdigClient sysdig.ExtendedClientWithResponsesInterface
	// contains filtered or unexported fields
}

func NewK8sListTopHttpErrorsInPods added in v0.5.2 

func NewK8sListTopHttpErrorsInPods(sysdigClient sysdig.ExtendedClientWithResponsesInterface, clk clock.Clock) *K8sListTopHttpErrorsInPods

func (*K8sListTopHttpErrorsInPods) RegisterInServer added in v0.5.2 

func (t *K8sListTopHttpErrorsInPods) RegisterInServer(s *server.MCPServer)

type K8sListTopMemoryConsumedContainer added in v0.5.2 

type K8sListTopMemoryConsumedContainer struct {
	SysdigClient sysdig.ExtendedClientWithResponsesInterface
	// contains filtered or unexported fields
}

func NewK8sListTopMemoryConsumedContainer added in v0.5.2 

func NewK8sListTopMemoryConsumedContainer(sysdigClient sysdig.ExtendedClientWithResponsesInterface, clk clock.Clock) *K8sListTopMemoryConsumedContainer

func (*K8sListTopMemoryConsumedContainer) RegisterInServer added in v0.5.2 

func (t *K8sListTopMemoryConsumedContainer) RegisterInServer(s *server.MCPServer)

type K8sListTopMemoryConsumedWorkload added in v0.5.2 

type K8sListTopMemoryConsumedWorkload struct {
	SysdigClient sysdig.ExtendedClientWithResponsesInterface
	// contains filtered or unexported fields
}

func NewK8sListTopMemoryConsumedWorkload added in v0.5.2 

func NewK8sListTopMemoryConsumedWorkload(sysdigClient sysdig.ExtendedClientWithResponsesInterface, clk clock.Clock) *K8sListTopMemoryConsumedWorkload

func (*K8sListTopMemoryConsumedWorkload) RegisterInServer added in v0.5.2 

func (t *K8sListTopMemoryConsumedWorkload) RegisterInServer(s *server.MCPServer)

type K8sListTopNetworkErrorsInPods added in v0.5.2 

type K8sListTopNetworkErrorsInPods struct {
	SysdigClient sysdig.ExtendedClientWithResponsesInterface
	// contains filtered or unexported fields
}

func NewK8sListTopNetworkErrorsInPods added in v0.5.2 

func NewK8sListTopNetworkErrorsInPods(sysdigClient sysdig.ExtendedClientWithResponsesInterface, clk clock.Clock) *K8sListTopNetworkErrorsInPods

func (*K8sListTopNetworkErrorsInPods) RegisterInServer added in v0.5.2 

func (t *K8sListTopNetworkErrorsInPods) RegisterInServer(s *server.MCPServer)

type K8sListTopRestartedPods added in v0.5.2 

type K8sListTopRestartedPods struct {
	SysdigClient sysdig.ExtendedClientWithResponsesInterface
	// contains filtered or unexported fields
}

func NewK8sListTopRestartedPods added in v0.5.2 

func NewK8sListTopRestartedPods(sysdigClient sysdig.ExtendedClientWithResponsesInterface, clk clock.Clock) *K8sListTopRestartedPods

func (*K8sListTopRestartedPods) RegisterInServer added in v0.5.2 

func (t *K8sListTopRestartedPods) RegisterInServer(s *server.MCPServer)

type K8sListTopUnavailablePods added in v0.5.2 

type K8sListTopUnavailablePods struct {
	SysdigClient sysdig.ExtendedClientWithResponsesInterface
	// contains filtered or unexported fields
}

func NewK8sListTopUnavailablePods added in v0.5.2 

func NewK8sListTopUnavailablePods(sysdigClient sysdig.ExtendedClientWithResponsesInterface, clk clock.Clock) *K8sListTopUnavailablePods

func (*K8sListTopUnavailablePods) RegisterInServer added in v0.5.2 

func (t *K8sListTopUnavailablePods) RegisterInServer(s *server.MCPServer)

type K8sListUnderutilizedPodsCPUQuota added in v0.5.2 

type K8sListUnderutilizedPodsCPUQuota struct {
	SysdigClient sysdig.ExtendedClientWithResponsesInterface
	// contains filtered or unexported fields
}

func NewK8sListUnderutilizedPodsCPUQuota added in v0.5.2 

func NewK8sListUnderutilizedPodsCPUQuota(sysdigClient sysdig.ExtendedClientWithResponsesInterface, clk clock.Clock) *K8sListUnderutilizedPodsCPUQuota

func (*K8sListUnderutilizedPodsCPUQuota) RegisterInServer added in v0.5.2 

func (t *K8sListUnderutilizedPodsCPUQuota) RegisterInServer(s *server.MCPServer)

type K8sListUnderutilizedPodsMemoryQuota added in v0.5.2 

type K8sListUnderutilizedPodsMemoryQuota struct {
	SysdigClient sysdig.ExtendedClientWithResponsesInterface
	// contains filtered or unexported fields
}

func NewK8sListUnderutilizedPodsMemoryQuota added in v0.5.2 

func NewK8sListUnderutilizedPodsMemoryQuota(sysdigClient sysdig.ExtendedClientWithResponsesInterface, clk clock.Clock) *K8sListUnderutilizedPodsMemoryQuota

func (*K8sListUnderutilizedPodsMemoryQuota) RegisterInServer added in v0.5.2 

func (t *K8sListUnderutilizedPodsMemoryQuota) RegisterInServer(s *server.MCPServer)

type K8sListWorkloads added in v0.5.2 

type K8sListWorkloads struct {
	SysdigClient sysdig.ExtendedClientWithResponsesInterface
	// contains filtered or unexported fields
}

func NewK8sListWorkloads added in v0.5.2 

func NewK8sListWorkloads(sysdigClient sysdig.ExtendedClientWithResponsesInterface, clk clock.Clock) *K8sListWorkloads

func (*K8sListWorkloads) RegisterInServer added in v0.5.2 

func (t *K8sListWorkloads) RegisterInServer(s *server.MCPServer)

type TimeWindow added in v1.0.8 

type TimeWindow struct {
	Start time.Time
	End   time.Time
}

func ParseTimeWindow added in v1.0.8 

func ParseTimeWindow(request mcp.CallToolRequest, clk clock.Clock) (TimeWindow, error)

Reads "start" and "end" from the request, validates them, and return the resolved TimeWindow.

func (TimeWindow) ApplyToParams added in v1.0.8 

func (w TimeWindow) ApplyToParams(params *sysdig.GetQueryV1Params) error

func (TimeWindow) EvalTime added in v1.0.8 

func (w TimeWindow) EvalTime() (*sysdig.Time, error)

func (TimeWindow) IsZero added in v1.0.8 

func (w TimeWindow) IsZero() bool

func (TimeWindow) RangeSelector added in v1.0.8 

func (w TimeWindow) RangeSelector() string

func (TimeWindow) WindowSeconds added in v1.0.8 

func (w TimeWindow) WindowSeconds() int64

type ToolGenerateSysql 

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

func NewToolGenerateSysql 

func NewToolGenerateSysql(client sysdig.ExtendedClientWithResponsesInterface) *ToolGenerateSysql

func (*ToolGenerateSysql) RegisterInServer 

func (h *ToolGenerateSysql) RegisterInServer(s *server.MCPServer)

type ToolGetEventInfo 

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

func NewToolGetEventInfo 

func NewToolGetEventInfo(client sysdig.ExtendedClientWithResponsesInterface) *ToolGetEventInfo

func (*ToolGetEventInfo) RegisterInServer 

func (h *ToolGetEventInfo) RegisterInServer(s *server.MCPServer)

type ToolGetEventProcessTree 

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

func NewToolGetEventProcessTree 

func NewToolGetEventProcessTree(sysdigClient sysdig.ExtendedClientWithResponsesInterface) *ToolGetEventProcessTree

func (*ToolGetEventProcessTree) RegisterInServer 

func (h *ToolGetEventProcessTree) RegisterInServer(s *server.MCPServer)

type ToolListRuntimeEvents 

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

func NewToolListRuntimeEvents 

func NewToolListRuntimeEvents(client sysdig.ExtendedClientWithResponsesInterface, clock clock.Clock) *ToolListRuntimeEvents

func (*ToolListRuntimeEvents) RegisterInServer 

func (h *ToolListRuntimeEvents) RegisterInServer(s *server.MCPServer)

type ToolRunSysql 

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

func NewToolRunSysql 

func NewToolRunSysql(client sysdig.ExtendedClientWithResponsesInterface) *ToolRunSysql

func (*ToolRunSysql) RegisterInServer 

func (h *ToolRunSysql) RegisterInServer(s *server.MCPServer)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.