Description

As a Kubernetes MCP Server administrator, I want to be able to define MCP prompts using the configuration TOML file, so that I can launch a server with custom workflow templates without needing to compile a specific version of the MCP server.

Background

The Model Context Protocol (MCP) specification defines Prompts as user-controlled templates that servers expose to clients. Prompts provide structured messages and instructions for interacting with language models, enabling pre-defined workflow templates and guidance for AI assistants.

Expected Behavior

Administrators can define custom prompts in the TOML configuration file, and these prompts are exposed through the MCP server's prompts/list and prompts/get endpoints.

Configuration file example:

[[prompts]]
name = "troubleshoot-pod"
title = "Troubleshoot Pod"
description = "Debug a failing or crashed pod"

  [[prompts.arguments]]
  name = "pod_name"
  description = "Name of the pod to troubleshoot"
  required = true

  [[prompts.arguments]]
  name = "namespace"
  description = "Namespace of the pod"
  required = false

  [[prompts.messages]]
  role = "user"
  content = "Help me troubleshoot pod {{pod_name}} in namespace {{namespace}}"

  [[prompts.messages]]
  role = "assistant"
  content = "I'll investigate the pod {{pod_name}} for you."

• prompts/list returns the prompt metadata (name, title, description, arguments)
• prompts/get returns the configured messages with {{argument}} placeholders substituted with provided values

Implementation Notes

Since prompt definitions will likely be reused for other purposes (e.g., toolset-defined prompts in future enhancements), the core data structures should be defined in the pkg/api/ package with appropriate struct tags for JSON/YAML/TOML serialization and godoc comments referencing the MCP specification.

Only text content type is supported for messages in this implementation.

Scope

In scope:

• Define prompt data structures in pkg/api/ (Prompt, PromptArgument, PromptMessage, PromptContent)
• Add prompt configuration support in pkg/config/
• Parse prompt definitions from TOML configuration
• Register and expose configured prompts through the MCP server
• Support {{argument}} placeholder substitution in prompt messages
• Validate required arguments when prompts/get is called
• Support configuration reload (SIGHUP) for prompt changes

Out of scope (future enhancements):

• Toolset-defined prompts (allowing toolset implementers to define prompts via GetPrompts() interface)
  [API] Toolset-defined prompt templates #556
• Built-in/embedded prompts shipped with the server
• System prompts support
• Non-text content types (image, audio, embedded resources)

Related

• PR feat: add MCP prompts support #510 (implements this and additional features - should be broken down into separate enhancements)

Acceptance Criteria

• Prompt data structures are defined in pkg/api/prompts.go with JSON/YAML/TOML struct tags
• Prompt configuration structures are defined in pkg/config/
• TOML configuration parsing correctly deserializes prompt definitions
• MCP server exposes configured prompts via prompts/list
• MCP server returns rendered prompts via prompts/get with argument substitution
• Required argument validation returns appropriate error when arguments are missing
• Configuration reload (SIGHUP) properly updates available prompts

Tests

• Unit tests for prompt data structures in pkg/api/
• Unit tests for TOML parsing of prompt configurations
• Test parsing single and multiple prompt definitions
• Test parsing prompts with required and optional arguments
• Test argument substitution in prompt messages
• Test required argument validation
• Integration test for prompts/list and prompts/get MCP endpoints
• Test configuration reload with prompt changes