add configurable prompts support

Enable administrators to define custom MCP prompts in config.toml
using template substitution with {{argument}} syntax.

Features:
- PromptLoader for loading prompts from TOML config
- Core prompt types (ServerPrompt, Prompt, PromptArgument, PromptMessage)
- Template argument substitution with {{variable}} syntax
- Required argument validation
- Integration with MCP server to register and serve config prompts

Signed-off-by: Nader Ziada <[email protected]>

Author: nader-ziada

README.md

@@ -292,6 +292,27 @@ vim /etc/kubernetes-mcp-server/conf.d/99-local.toml
 pkill -HUP kubernetes-mcp-server
 ```
 
+### MCP Prompts
+
+The server supports MCP prompts for workflow templates. Define custom prompts in `config.toml`:
+
+```toml
+[[prompts]]
+name = "my-workflow"
+title = "my workflow"
+description = "Custom workflow"
+
+[[prompts.arguments]]
+name = "resource_name"
+required = true
+
+[[prompts.messages]]
+role = "user"
+content = "Help me with {{resource_name}}"
+```
+
+See docs/PROMPTS.md for detailed documentation.
+
 ## 🛠️ Tools and Functionalities <a id="tools-and-functionalities"></a>
 
 The Kubernetes MCP server supports enabling or disabling specific groups of tools and functionalities (tools, resources, prompts, and so on) via the `--toolsets` command-line flag or `toolsets` configuration option.

docs/PROMPTS.md

@@ -0,0 +1,62 @@
+# MCP Prompts Support
+
+The Kubernetes MCP Server supports [MCP Prompts](https://modelcontextprotocol.io/docs/concepts/prompts), which provide pre-defined workflow templates and guidance to AI assistants.
+
+## What are MCP Prompts?
+
+MCP Prompts are pre-defined templates that guide AI assistants through specific workflows. They combine:
+- **Structured guidance**: Step-by-step instructions for common tasks
+- **Parameterization**: Arguments that customize the prompt for specific contexts
+- **Conversation templates**: Pre-formatted messages that guide the interaction
+
+## Creating Custom Prompts
+
+Define custom prompts in your `config.toml` file - no code changes or recompilation needed!
+
+### Example
+
+```toml
+[[prompts]]
+name = "check-pod-logs"
+title = "Check Pod Logs"
+description = "Quick way to check pod logs"
+
+[[prompts.arguments]]
+name = "pod_name"
+description = "Name of the pod"
+required = true
+
+[[prompts.arguments]]
+name = "namespace"
+description = "Namespace of the pod"
+required = false
+
+[[prompts.messages]]
+role = "user"
+content = "Show me the logs for pod {{pod_name}} in {{namespace}}"
+
+[[prompts.messages]]
+role = "assistant"
+content = "I'll retrieve and analyze the logs for you."
+```
+
+## Configuration Reference
+
+### Prompt Fields
+- **name** (required): Unique identifier for the prompt
+- **title** (optional): Human-readable display name
+- **description** (required): Brief explanation of what the prompt does
+- **arguments** (optional): List of parameters the prompt accepts
+- **messages** (required): Conversation template with role/content pairs
+
+### Argument Fields
+- **name** (required): Argument identifier
+- **description** (optional): Explanation of the argument's purpose
+- **required** (optional): Whether the argument must be provided (default: false)
+
+### Argument Substitution
+Use `{{argument_name}}` placeholders in message content. The template engine replaces these with actual values when the prompt is called.
+
+## Configuration File Location
+
+Place your prompts in the `config.toml` file used by the MCP server. Specify the config file path using the `--config` flag when starting the server.

pkg/api/prompt_config.go

@@ -0,0 +1,22 @@
+package api
+
+import (
+	"context"
+
+	"github.com/BurntSushi/toml"
+	"github.com/containers/kubernetes-mcp-server/pkg/config"
+)
+
+// promptsParser parses prompts from TOML configuration
+func promptsParser(ctx context.Context, primitive toml.Primitive, md toml.MetaData) (interface{}, error) {
+	var prompts []Prompt
+	if err := md.PrimitiveDecode(primitive, &prompts); err != nil {
+		return nil, err
+	}
+	return prompts, nil
+}
+
+func init() {
+	// Register the prompts parser with the config package
+	config.RegisterPromptsParser(promptsParser)
+}

pkg/api/prompt_loader.go

@@ -0,0 +1,88 @@
+package api
+
+import (
+	"fmt"
+	"strings"
+)
+
+// PromptLoader loads prompts from configuration
+type PromptLoader struct {
+	prompts []Prompt
+}
+
+// NewPromptLoader creates a new prompt loader
+func NewPromptLoader() *PromptLoader {
+	return &PromptLoader{
+		prompts: make([]Prompt, 0),
+	}
+}
+
+// GetServerPrompts converts loaded prompts to ServerPrompt instances with handlers
+func (l *PromptLoader) GetServerPrompts() []ServerPrompt {
+	serverPrompts := make([]ServerPrompt, 0, len(l.prompts))
+	for _, prompt := range l.prompts {
+		serverPrompts = append(serverPrompts, ServerPrompt{
+			Prompt:  prompt,
+			Handler: l.createHandler(prompt),
+		})
+	}
+	return serverPrompts
+}
+
+// createHandler creates a prompt handler function for a prompt
+func (l *PromptLoader) createHandler(prompt Prompt) PromptHandlerFunc {
+	return func(params PromptHandlerParams) (*PromptCallResult, error) {
+		args := params.GetArguments()
+
+		// Validate required arguments
+		for _, arg := range prompt.Arguments {
+			if arg.Required {
+				if _, exists := args[arg.Name]; !exists {
+					return nil, fmt.Errorf("required argument '%s' is missing", arg.Name)
+				}
+			}
+		}
+
+		// Render messages with argument substitution
+		messages := make([]PromptMessage, 0, len(prompt.Templates))
+		for _, template := range prompt.Templates {
+			content := l.substituteArguments(template.Content, args)
+			messages = append(messages, PromptMessage{
+				Role: template.Role,
+				Content: PromptContent{
+					Type: "text",
+					Text: content,
+				},
+			})
+		}
+
+		return NewPromptCallResult(prompt.Description, messages, nil), nil
+	}
+}
+
+// substituteArguments replaces {{argument}} placeholders in content with actual values
+func (l *PromptLoader) substituteArguments(content string, args map[string]string) string {
+	result := content
+	for key, value := range args {
+		placeholder := fmt.Sprintf("{{%s}}", key)
+		result = strings.ReplaceAll(result, placeholder, value)
+	}
+	return result
+}
+
+// LoadFromParsedConfig loads prompts from already-parsed config data
+// parsedPrompts is stored as interface{} in config.Config to avoid circular dependencies
+func (l *PromptLoader) LoadFromParsedConfig(parsedPrompts interface{}) error {
+	if parsedPrompts == nil {
+		return nil
+	}
+
+	// Type assert to []Prompt
+	prompts, ok := parsedPrompts.([]Prompt)
+	if !ok {
+		return fmt.Errorf("unexpected type for parsed prompts: %T, expected []api.Prompt", parsedPrompts)
+	}
+
+	l.prompts = append(l.prompts, prompts...)
+	return nil
+}

pkg/api/prompts.go

@@ -0,0 +1,96 @@
+package api
+
+import (
+	"context"
+
+	internalk8s "github.com/containers/kubernetes-mcp-server/pkg/kubernetes"
+)
+
+// ServerPrompt represents a prompt that can be registered with the MCP server.
+// Prompts provide pre-defined workflow templates and guidance to AI assistants.
+type ServerPrompt struct {
+	Prompt         Prompt
+	Handler        PromptHandlerFunc
+	ClusterAware   *bool
+	ArgumentSchema map[string]PromptArgument
+}
+
+// IsClusterAware indicates whether the prompt can accept a "cluster" or "context" parameter
+// to operate on a specific Kubernetes cluster context.
+// Defaults to true if not explicitly set
+func (s *ServerPrompt) IsClusterAware() bool {
+	if s.ClusterAware != nil {
+		return *s.ClusterAware
+	}
+	return true
+}
+
+// Prompt represents the metadata and content of an MCP prompt.
+// See MCP specification: https://spec.modelcontextprotocol.io/specification/server/prompts/
+type Prompt struct {
+	Name        string           `yaml:"name" json:"name" toml:"name"`
+	Title       string           `yaml:"title,omitempty" json:"title,omitempty" toml:"title,omitempty"`
+	Description string           `yaml:"description,omitempty" json:"description,omitempty" toml:"description,omitempty"`
+	Arguments   []PromptArgument `yaml:"arguments,omitempty" json:"arguments,omitempty" toml:"arguments,omitempty"`
+	Templates   []PromptTemplate `yaml:"messages,omitempty" json:"messages,omitempty" toml:"messages,omitempty"`
+}
+
+// PromptArgument defines a parameter that can be passed to a prompt.
+// See MCP specification: https://spec.modelcontextprotocol.io/specification/server/prompts/
+type PromptArgument struct {
+	Name        string `yaml:"name" json:"name" toml:"name"`
+	Description string `yaml:"description,omitempty" json:"description,omitempty" toml:"description,omitempty"`
+	Required    bool   `yaml:"required" json:"required" toml:"required"`
+}
+
+// PromptTemplate represents a message template from configuration with placeholders like {{arg}}.
+// This is used for configuration parsing and gets rendered into PromptMessage at runtime.
+type PromptTemplate struct {
+	Role    string `yaml:"role" json:"role" toml:"role"`
+	Content string `yaml:"content" json:"content" toml:"content"`
+}
+
+// PromptMessage represents a single message in a prompt response.
+// See MCP specification: https://spec.modelcontextprotocol.io/specification/server/prompts/
+type PromptMessage struct {
+	Role    string        `yaml:"role" json:"role" toml:"role"`
+	Content PromptContent `yaml:"content" json:"content" toml:"content"`
+}
+
+// PromptContent represents the content of a prompt message.
+// See MCP specification: https://spec.modelcontextprotocol.io/specification/server/prompts/
+type PromptContent struct {
+	Type string `yaml:"type" json:"type" toml:"type"`
+	Text string `yaml:"text,omitempty" json:"text,omitempty" toml:"text,omitempty"`
+}
+
+// PromptCallRequest interface for accessing prompt call arguments
+type PromptCallRequest interface {
+	GetArguments() map[string]string
+}
+
+// PromptCallResult represents the result of executing a prompt
+type PromptCallResult struct {
+	Description string
+	Messages    []PromptMessage
+	Error       error
+}
+
+// NewPromptCallResult creates a new PromptCallResult
+func NewPromptCallResult(description string, messages []PromptMessage, err error) *PromptCallResult {
+	return &PromptCallResult{
+		Description: description,
+		Messages:    messages,
+		Error:       err,
+	}
+}
+
+// PromptHandlerParams contains the parameters passed to a prompt handler
+type PromptHandlerParams struct {
+	context.Context
+	*internalk8s.Kubernetes
+	PromptCallRequest
+}
+
+// PromptHandlerFunc is a function that handles prompt execution
+type PromptHandlerFunc func(params PromptHandlerParams) (*PromptCallResult, error)

pkg/api/prompts_test.go

@@ -0,0 +1,80 @@
+package api
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"k8s.io/utils/ptr"
+)
+
+func TestServerPrompt_IsClusterAware(t *testing.T) {
+	tests := []struct {
+		name         string
+		clusterAware *bool
+		want         bool
+	}{
+		{
+			name:         "nil defaults to true",
+			clusterAware: nil,
+			want:         true,
+		},
+		{
+			name:         "explicitly true",
+			clusterAware: ptr.To(true),
+			want:         true,
+		},
+		{
+			name:         "explicitly false",
+			clusterAware: ptr.To(false),
+			want:         false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			sp := &ServerPrompt{
+				ClusterAware: tt.clusterAware,
+			}
+			assert.Equal(t, tt.want, sp.IsClusterAware())
+		})
+	}
+}
+
+func TestNewPromptCallResult(t *testing.T) {
+	tests := []struct {
+		name        string
+		description string
+		messages    []PromptMessage
+		err         error
+	}{
+		{
+			name:        "successful result",
+			description: "Test description",
+			messages: []PromptMessage{
+				{
+					Role: "user",
+					Content: PromptContent{
+						Type: "text",
+						Text: "Hello",
+					},
+				},
+			},
+			err: nil,
+		},
+		{
+			name:        "result with error",
+			description: "Error description",
+			messages:    nil,
+			err:         assert.AnError,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := NewPromptCallResult(tt.description, tt.messages, tt.err)
+			assert.Equal(t, tt.description, result.Description)
+			assert.Equal(t, tt.messages, result.Messages)
+			assert.Equal(t, tt.err, result.Error)
+		})
+	}
+}