# API Reference
Complete documentation for all MCP-K8sWizard tools and their usage. This reference covers all 37 available tools organized by category.
## Table of Contents
- [Kubernetes Operations (14 tools)](#kubernetes-operations-14-tools)
- [Kubectl Operations (12 tools)](#kubectl-operations-12-tools)
- [Context Management (4 tools)](#context-management-4-tools)
- [AI-Powered Guidance (7 tools)](#ai-powered-guidance-7-tools)
- [Tool Categories Overview](#tool-categories-overview)
- [Common Parameters](#common-parameters)
- [Error Handling](#error-handling)
- [Examples](#examples)
## Kubernetes Operations (14 tools)
### k8s_cluster_info
Get comprehensive information about Kubernetes clusters including nodes, namespaces, and cluster type detection.
**Parameters:**
- `context` (optional): Kubernetes context name
**Returns:**
- Cluster version and type
- Node information and status
- Namespace details
- Resource counts
**Example:**
```json
{
"context": "rancher-desktop"
}
```
**Response:**
```json
{
"version": "v1.33.4+k3s1",
"nodes": 1,
"namespaces": 6,
"node_details": [
{
"name": "lima-rancher-desktop",
"version": "v1.33.4+k3s1",
"status": "Ready",
"roles": ["control-plane", "master"]
}
],
"namespace_details": [
{
"name": "default",
"status": "Active"
}
]
}
```
### k8s_check_all_clusters
Check status of all available clusters in parallel for faster results.
**Parameters:**
- `context` (optional): Kubernetes context name
**Returns:**
- Status of all configured clusters
- Health information
- Connection status
**Example:**
```json
{
"context": "rancher-desktop"
}
```
### k8s_ping
Verify connection to the Kubernetes cluster.
**Parameters:**
- `context` (optional): Kubernetes context name
**Returns:**
- Connection status
- Response time
- Error details if connection fails
**Example:**
```json
{
"context": "rancher-desktop"
}
```
### k8s_list_resources
List Kubernetes resources with filtering options.
**Parameters:**
- `kind`: Resource kind (pods, services, deployments, etc.)
- `namespace` (optional): Namespace to list resources from
- `labelSelector` (optional): Label selector for filtering
- `limit` (optional): Maximum number of resources to return
- `context` (optional): Kubernetes context name
**Example:**
```json
{
"kind": "pods",
"namespace": "default",
"labelSelector": "app=nginx",
"limit": 10,
"context": "rancher-desktop"
}
```
### k8s_get_resource
Get detailed information about a specific Kubernetes resource.
**Parameters:**
- `kind`: Resource kind
- `name`: Resource name
- `namespace` (optional): Namespace of the resource
- `context` (optional): Kubernetes context name
**Example:**
```json
{
"kind": "pod",
"name": "nginx-pod",
"namespace": "default",
"context": "rancher-desktop"
}
```
### k8s_get_logs
Get logs from Kubernetes pods with filtering and streaming options.
**Parameters:**
- `namespace`: Namespace of the pod
- `pod`: Pod name
- `container` (optional): Container name
- `tail` (optional): Number of lines to return from the end
- `since` (optional): Return logs since this time
- `follow` (optional): Follow log output in real-time
- `context` (optional): Kubernetes context name
**Example:**
```json
{
"namespace": "default",
"pod": "nginx-pod",
"container": "nginx",
"tail": 100,
"since": "1h",
"follow": false,
"context": "rancher-desktop"
}
```
### k8s_get_events
Get Kubernetes events with filtering options.
**Parameters:**
- `namespace` (optional): Namespace to get events from
- `labelSelector` (optional): Label selector for filtering
- `fieldSelector` (optional): Field selector for filtering
- `limit` (optional): Maximum number of events to return
- `context` (optional): Kubernetes context name
**Example:**
```json
{
"namespace": "default",
"labelSelector": "app=nginx",
"limit": 50,
"context": "rancher-desktop"
}
```
### k8s_exec_in_pod
Execute commands in Kubernetes pods.
**Parameters:**
- `namespace`: Namespace of the pod
- `pod`: Pod name
- `command`: Command to execute in the pod
- `container` (optional): Container name
- `args` (optional): Additional command arguments
- `tty` (optional): Allocate a TTY for the command
- `stdin` (optional): Attach stdin to the command
- `context` (optional): Kubernetes context name
**Example:**
```json
{
"namespace": "default",
"pod": "nginx-pod",
"command": "ls",
"args": "-la /",
"tty": false,
"stdin": false,
"context": "rancher-desktop"
}
```
### k8s_natural_language_query
Process natural language queries about Kubernetes resources and get intelligent responses.
**Parameters:**
- `query`: Natural language query about Kubernetes resources
- `context` (optional): Kubernetes context name
**Example:**
```json
{
"query": "Show me all pods that are not running",
"context": "rancher-desktop"
}
```
### k8s_list_contexts
List all available Kubernetes contexts.
**Parameters:**
- `random_string`: Dummy parameter for no-parameter tools
**Example:**
```json
{
"random_string": "list"
}
```
### k8s_get_current_context
Get the current Kubernetes context.
**Parameters:**
- `random_string`: Dummy parameter for no-parameter tools
**Example:**
```json
{
"random_string": "current"
}
```
### k8s_set_context
Set the current Kubernetes context for all subsequent operations.
**Parameters:**
- `context`: Kubernetes context name to set as current
**Example:**
```json
{
"context": "rancher-desktop"
}
```
### k8s_clear_context
Clear the current context (will use default context).
**Parameters:**
- `random_string`: Dummy parameter for no-parameter tools
**Example:**
```json
{
"random_string": "clear"
}
```
### list_api_resources
List all API resources available in the cluster.
**Parameters:**
- `context` (optional): Kubernetes context name
**Example:**
```json
{
"context": "rancher-desktop"
}
```
## Kubectl Operations (12 tools)
### kubectl_get
Get or list Kubernetes resources with filtering options.
**Parameters:**
- `resourceType`: Type of Kubernetes resource (pods, services, deployments, etc.)
- `name` (optional): Specific resource name
- `namespace` (optional): Namespace to list resources from
- `labelSelector` (optional): Label selector for filtering
- `fieldSelector` (optional): Field selector for filtering
- `output` (optional): Output format (wide, yaml, json, name)
- `context` (optional): Kubernetes context name
**Example:**
```json
{
"resourceType": "pods",
"namespace": "default",
"labelSelector": "app=nginx",
"output": "wide",
"context": "rancher-desktop"
}
```
### kubectl_describe
Describe detailed information about a specific Kubernetes resource.
**Parameters:**
- `resourceType`: Type of Kubernetes resource
- `name`: Name of the resource
- `namespace` (optional): Namespace of the resource
- `context` (optional): Kubernetes context name
**Example:**
```json
{
"resourceType": "pod",
"name": "nginx-pod",
"namespace": "default",
"context": "rancher-desktop"
}
```
### kubectl_create
Create Kubernetes resources from command line arguments.
**Parameters:**
- `resourceType`: Type of Kubernetes resource to create
- `name`: Name of the resource
- `namespace` (optional): Namespace to create the resource in
- `args` (optional): Additional kubectl create arguments
- `context` (optional): Kubernetes context name
**Example:**
```json
{
"resourceType": "namespace",
"name": "staging",
"context": "rancher-desktop"
}
```
### kubectl_apply
Apply Kubernetes resources from YAML or JSON manifests.
**Parameters:**
- `manifest`: YAML or JSON manifest content
- `namespace` (optional): Namespace to apply the manifest in
- `context` (optional): Kubernetes context name
**Example:**
```json
{
"manifest": "apiVersion: v1\nkind: Namespace\nmetadata:\n name: staging",
"context": "rancher-desktop"
}
```
### kubectl_delete
Delete Kubernetes resources.
**Parameters:**
- `resourceType`: Type of Kubernetes resource to delete
- `name`: Name of the resource
- `namespace` (optional): Namespace of the resource
- `force` (optional): Force deletion
- `gracePeriod` (optional): Grace period in seconds
- `context` (optional): Kubernetes context name
**Example:**
```json
{
"resourceType": "pod",
"name": "nginx-pod",
"namespace": "default",
"gracePeriod": 30,
"context": "rancher-desktop"
}
```
### kubectl_scale
Scale Kubernetes resources (deployments, replicasets, etc.).
**Parameters:**
- `resourceType`: Type of Kubernetes resource to scale
- `name`: Name of the resource
- `replicas`: Number of replicas
- `namespace` (optional): Namespace of the resource
- `context` (optional): Kubernetes context name
**Example:**
```json
{
"resourceType": "deployment",
"name": "nginx-deployment",
"replicas": 3,
"namespace": "default",
"context": "rancher-desktop"
}
```
### kubectl_patch
Update field(s) of a Kubernetes resource using strategic merge patch.
**Parameters:**
- `resourceType`: Type of Kubernetes resource to patch
- `name`: Name of the resource
- `patch`: JSON patch to apply
- `type` (optional): Patch type (strategic, merge, json)
- `namespace` (optional): Namespace of the resource
- `context` (optional): Kubernetes context name
**Example:**
```json
{
"resourceType": "deployment",
"name": "nginx-deployment",
"patch": "{\"spec\":{\"replicas\":5}}",
"type": "strategic",
"namespace": "default",
"context": "rancher-desktop"
}
```
### kubectl_rollout
Manage deployment rollouts - status, history, pause, resume, undo.
**Parameters:**
- `action`: Rollout action (status, history, pause, resume, undo, restart)
- `resourceType`: Type of Kubernetes resource
- `name`: Name of the resource
- `namespace` (optional): Namespace of the resource
- `revision` (optional): Revision number for undo action
- `context` (optional): Kubernetes context name
**Example:**
```json
{
"action": "status",
"resourceType": "deployment",
"name": "nginx-deployment",
"namespace": "default",
"context": "rancher-desktop"
}
```
### kubectl_context
Manage kubectl contexts - list, switch, or get current context.
**Parameters:**
- `action` (optional): Action to perform (list, get, set)
- `context` (optional): Context name for set action
**Example:**
```json
{
"action": "list"
}
```
### kubectl_generic
Execute any kubectl command with custom arguments.
**Parameters:**
- `command`: kubectl command to execute (without 'kubectl' prefix)
- `context` (optional): Kubernetes context name
**Example:**
```json
{
"command": "get pods -o wide",
"context": "rancher-desktop"
}
```
### explain_resource
Explain Kubernetes resources and their fields.
**Parameters:**
- `resourceType`: Type of Kubernetes resource to explain
- `field` (optional): Specific field to explain
- `context` (optional): Kubernetes context name
**Example:**
```json
{
"resourceType": "pod",
"field": "spec.containers",
"context": "rancher-desktop"
}
```
## Context Management (4 tools)
### k8s_set_context
Set the current Kubernetes context for all subsequent operations.
**Parameters:**
- `context`: Kubernetes context name to set as current
**Example:**
```json
{
"context": "rancher-desktop"
}
```
### k8s_get_current_context
Get the current Kubernetes context.
**Parameters:**
- `random_string`: Dummy parameter for no-parameter tools
**Example:**
```json
{
"random_string": "current"
}
```
### k8s_list_contexts
List all available Kubernetes contexts.
**Parameters:**
- `random_string`: Dummy parameter for no-parameter tools
**Example:**
```json
{
"random_string": "list"
}
```
### k8s_clear_context
Clear the current context (will use default context).
**Parameters:**
- `random_string`: Dummy parameter for no-parameter tools
**Example:**
```json
{
"random_string": "clear"
}
```
## AI-Powered Guidance (7 tools)
### k8s_diagnose
Generate systematic troubleshooting prompts for Kubernetes pods with step-by-step diagnostic guidance.
**Parameters:**
- `keyword`: Keyword or resource name to diagnose
- `namespace`: Namespace of the resource
- `context`: Kubernetes context name
**Example:**
```json
{
"keyword": "nginx-pod",
"namespace": "default",
"context": "rancher-desktop"
}
```
### k8s_troubleshoot
Generate advanced troubleshooting prompts for comprehensive Kubernetes debugging.
**Parameters:**
- `keyword`: Keyword or resource name to troubleshoot
- `namespace`: Namespace of the resource
- `context`: Kubernetes context name
**Example:**
```json
{
"keyword": "deployment",
"namespace": "default",
"context": "rancher-desktop"
}
```
### k8s_optimize
Generate performance optimization prompts for Kubernetes resources.
**Parameters:**
- `keyword`: Keyword or resource name to optimize
- `namespace`: Namespace of the resource
- `context`: Kubernetes context name
**Example:**
```json
{
"keyword": "nginx-deployment",
"namespace": "default",
"context": "rancher-desktop"
}
```
### k8s_security
Generate security analysis prompts for Kubernetes resources and configurations.
**Parameters:**
- `keyword`: Keyword or resource name to analyze
- `namespace`: Namespace of the resource
- `context`: Kubernetes context name
**Example:**
```json
{
"keyword": "nginx-pod",
"namespace": "default",
"context": "rancher-desktop"
}
```
### k8s_performance
Generate performance monitoring prompts for Kubernetes resources.
**Parameters:**
- `keyword`: Keyword or resource name to monitor
- `namespace`: Namespace of the resource
- `context`: Kubernetes context name
**Example:**
```json
{
"keyword": "nginx-deployment",
"namespace": "default",
"context": "rancher-desktop"
}
```
### k8s_deployment
Generate deployment analysis prompts for Kubernetes deployments and rollouts.
**Parameters:**
- `keyword`: Keyword or resource name to analyze
- `namespace`: Namespace of the resource
- `context`: Kubernetes context name
**Example:**
```json
{
"keyword": "nginx-deployment",
"namespace": "default",
"context": "rancher-desktop"
}
```
### prompt_suggestions
Get contextual prompt suggestions based on your current situation or keywords.
**Parameters:**
- `keyword`: Keyword or resource name
- `namespace`: Namespace of the resource
- `context`: Kubernetes context name
**Example:**
```json
{
"keyword": "pod",
"namespace": "default",
"context": "rancher-desktop"
}
```
## Tool Categories Overview
| Category | Count | Tools | Purpose |
|----------|-------|-------|---------|
| **Kubernetes Operations** | 14 | `k8s_cluster_info`, `k8s_check_all_clusters`, `ping`, `k8s_list_resources`, `k8s_get_resource`, `k8s_get_logs`, `k8s_get_events`, `k8s_exec_in_pod`, `k8s_natural_language_query`, `k8s_list_contexts`, `k8s_get_current_context`, `k8s_set_context`, `k8s_clear_context`, `list_api_resources` | Direct Kubernetes API operations, monitoring, and debugging |
| **Kubectl Operations** | 12 | `kubectl_get`, `kubectl_describe`, `kubectl_create`, `kubectl_apply`, `kubectl_delete`, `kubectl_context`, `kubectl_scale`, `kubectl_patch`, `kubectl_rollout`, `kubectl_generic`, `explain_resource` | Full CRUD operations, scaling, rollouts, and resource management via kubectl |
| **Context Management** | 4 | `k8s_set_context`, `k8s_get_current_context`, `k8s_list_contexts`, `k8s_clear_context` | Multi-cluster context switching and management |
| **AI-Powered Guidance** | 7 | `k8s_diagnose`, `k8s_troubleshoot`, `k8s_optimize`, `k8s_security`, `k8s_performance`, `k8s_deployment`, `prompt_suggestions` | Intelligent diagnostic, optimization, and troubleshooting prompts |
## Common Parameters
### Context Parameter
Most tools accept an optional `context` parameter to specify which Kubernetes context to use:
```json
{
"context": "rancher-desktop"
}
```
### Namespace Parameter
Many tools accept an optional `namespace` parameter to specify the target namespace:
```json
{
"namespace": "default"
}
```
### Label Selector
Tools that list resources often support label-based filtering:
```json
{
"labelSelector": "app=nginx,version=1.0"
}
```
### Field Selector
Some tools support field-based filtering:
```json
{
"fieldSelector": "status.phase=Running"
}
```
### Output Format
Kubectl tools support various output formats:
```json
{
"output": "wide" // wide, yaml, json, name
}
```
## Error Handling
### Common Error Types
1. **Connection Errors**
```json
{
"error": "connection refused",
"message": "Unable to connect to Kubernetes API server",
"code": "CONNECTION_ERROR"
}
```
2. **Authentication Errors**
```json
{
"error": "unauthorized",
"message": "User does not have permission to access resource",
"code": "AUTH_ERROR"
}
```
3. **Resource Not Found**
```json
{
"error": "not found",
"message": "Resource 'nginx-pod' not found in namespace 'default'",
"code": "NOT_FOUND"
}
```
4. **Validation Errors**
```json
{
"error": "validation failed",
"message": "Invalid resource type 'invalid-type'",
"code": "VALIDATION_ERROR"
}
```
### Error Response Format
All tools return errors in a consistent format:
```json
{
"success": false,
"error": {
"code": "ERROR_CODE",
"message": "Human-readable error message",
"details": {
"field": "Additional error details",
"timestamp": "2024-01-15T10:30:00Z"
}
}
}
```
## Examples
### Basic Pod Operations
```json
// List all pods
{
"tool": "k8s_list_resources",
"parameters": {
"kind": "pods",
"namespace": "default"
}
}
// Get pod details
{
"tool": "k8s_get_resource",
"parameters": {
"kind": "pod",
"name": "nginx-pod",
"namespace": "default"
}
}
// Get pod logs
{
"tool": "k8s_get_logs",
"parameters": {
"namespace": "default",
"pod": "nginx-pod",
"tail": 100
}
}
```
### Deployment Management
```json
// Scale deployment
{
"tool": "kubectl_scale",
"parameters": {
"resourceType": "deployment",
"name": "nginx-deployment",
"replicas": 5,
"namespace": "default"
}
}
// Check rollout status
{
"tool": "kubectl_rollout",
"parameters": {
"action": "status",
"resourceType": "deployment",
"name": "nginx-deployment",
"namespace": "default"
}
}
// Update deployment
{
"tool": "kubectl_patch",
"parameters": {
"resourceType": "deployment",
"name": "nginx-deployment",
"patch": "{\"spec\":{\"template\":{\"spec\":{\"containers\":[{\"name\":\"nginx\",\"image\":\"nginx:1.21\"}]}}}}",
"namespace": "default"
}
}
```
### Multi-Cluster Operations
```json
// List all contexts
{
"tool": "k8s_list_contexts",
"parameters": {
"random_string": "list"
}
}
// Switch context
{
"tool": "k8s_set_context",
"parameters": {
"context": "production"
}
}
// Check cluster health
{
"tool": "k8s_cluster_info",
"parameters": {
"context": "production"
}
}
```
### AI-Powered Operations
```json
// Diagnose pod issues
{
"tool": "k8s_diagnose",
"parameters": {
"keyword": "nginx-pod",
"namespace": "default",
"context": "rancher-desktop"
}
}
// Get optimization suggestions
{
"tool": "k8s_optimize",
"parameters": {
"keyword": "nginx-deployment",
"namespace": "default",
"context": "rancher-desktop"
}
}
// Security analysis
{
"tool": "k8s_security",
"parameters": {
"keyword": "nginx-pod",
"namespace": "default",
"context": "rancher-desktop"
}
}
```
### Natural Language Queries
```json
// Natural language query
{
"tool": "k8s_natural_language_query",
"parameters": {
"query": "Show me all pods that are not running",
"context": "rancher-desktop"
}
}
// Get prompt suggestions
{
"tool": "prompt_suggestions",
"parameters": {
"keyword": "pod",
"namespace": "default",
"context": "rancher-desktop"
}
}
```
## Best Practices
1. **Always specify context** for multi-cluster environments
2. **Use appropriate namespaces** to avoid conflicts
3. **Handle errors gracefully** and provide meaningful feedback
4. **Use label selectors** for efficient resource filtering
5. **Monitor resource usage** to avoid performance issues
6. **Test commands** in development before production
7. **Use AI-powered tools** for complex troubleshooting scenarios
## Next Steps
- [Installation Manual](installation.md) - Complete setup guide
- [Configuration Guide](configuration.md) - Advanced configuration options
- [Troubleshooting Guide](troubleshooting.md) - Common issues and solutions
