feat(mcp): implement template-based prompt extension system

- Add support for template-based prompts that can be extended
- Implement variable substitution in templates using existing variable system
- Allow templates to extend other templates (inheritance chain)
- Add proper error handling for circular dependencies or missing templates
- Maintain backward compatibility with existing prompts

Closes #180

Author: butschster

docs/example/config/prompt-templates.yml

@@ -0,0 +1,75 @@
+prompts:
+  # Template for issues
+  - id: template-issue
+    description: Template for creating issues
+    type: template
+    messages:
+      - role: user
+        content: "Create a new issue with the following title and description: {{title}} {{description}}"
+
+  # Template for bug issues, extending the base issue template
+  - id: bug-issue
+    description: Create a new bug issue
+    type: prompt
+    extend:
+      - id: template-issue
+        arguments:
+          title: 'Bug: {{title}}'
+          description: '{{description}}'
+    schema:
+      properties:
+        title:
+          description: The title of the bug
+        description:
+          description: The description of the bug
+      required:
+        - title
+        - description
+
+  # Template for feature issues, extending the base issue template
+  - id: feature-issue
+    description: Create a new feature issue
+    type: prompt
+    extend:
+      - id: template-issue
+        arguments:
+          title: 'Feature: {{title}}'
+          description: '{{description}}'
+    schema:
+      properties:
+        title:
+          description: The title of the feature
+        description:
+          description: The description of the feature
+      required:
+        - title
+        - description
+
+  # More complex template example, extending another template
+  - id: template-complex-issue
+    type: template
+    description: Template for complex issues with priority
+    extend:
+      - id: template-issue
+        arguments:
+          title: '{{type}}: {{title}}'
+          description: '{{description}} \n\n**Priority**: {{priority}}'
+
+  # Priority bug issue using the complex template
+  - id: priority-bug-issue
+    description: Create a new priority bug issue
+    type: prompt
+    extend:
+      - id: template-complex-issue
+        arguments:
+          type: 'Bug'
+          priority: 'High'
+    schema:
+      properties:
+        title:
+          description: The title of the bug
+        description:
+          description: The description of the bug
+      required:
+        - title
+        - description

json-schema.json

@@ -269,7 +269,10 @@
         },
         "type": {
           "type": "string",
-          "enum": ["run", "http"],
+          "enum": [
+            "run",
+            "http"
+          ],
           "description": "Type of tool (run = command execution, http = HTTP requests)",
           "default": "run"
         },
@@ -309,7 +312,9 @@
             }
           },
           "then": {
-            "required": ["commands"]
+            "required": [
+              "commands"
+            ]
           }
         },
         {
@@ -321,22 +326,34 @@
             }
           },
           "then": {
-            "required": ["requests"]
+            "required": [
+              "requests"
+            ]
           }
         }
       ]
     },
     "httpRequest": {
       "type": "object",
-      "required": ["url"],
+      "required": [
+        "url"
+      ],
       "properties": {
         "url": {
           "type": "string",
           "description": "URL to send the request to, may contain {{argument}} placeholders"
         },
         "method": {
           "type": "string",
-          "enum": ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"],
+          "enum": [
+            "GET",
+            "POST",
+            "PUT",
+            "DELETE",
+            "PATCH",
+            "HEAD",
+            "OPTIONS"
+          ],
           "description": "HTTP method to use",
           "default": "GET"
         },
@@ -423,8 +440,7 @@
     "prompt": {
       "type": "object",
       "required": [
-        "id",
-        "messages"
+        "id"
       ],
       "properties": {
         "id": {
@@ -435,6 +451,15 @@
           "type": "string",
           "description": "Human-readable description of the prompt"
         },
+        "type": {
+          "type": "string",
+          "enum": [
+            "prompt",
+            "template"
+          ],
+          "description": "Type of prompt (regular prompt or template)",
+          "default": "prompt"
+        },
         "schema": {
           "$ref": "#/definitions/inputSchema",
           "description": "Defines input parameters for this prompt"
@@ -459,13 +484,74 @@
               },
               "content": {
                 "type": "string",
-                "description": "The content of the message, may contain variable placeholders like ${variableName}"
+                "description": "The content of the message, may contain variable placeholders like ${variableName} or {{variableName}}"
+              }
+            }
+          }
+        },
+        "extend": {
+          "type": "array",
+          "description": "List of templates to extend",
+          "items": {
+            "type": "object",
+            "required": [
+              "id"
+            ],
+            "properties": {
+              "id": {
+                "type": "string",
+                "description": "ID of the template to extend"
+              },
+              "arguments": {
+                "type": "object",
+                "description": "Arguments to pass to the template",
+                "additionalProperties": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "type": {
+                "const": "prompt"
               }
             }
           },
-          "minItems": 1
+          "then": {
+            "anyOf": [
+              {
+                "required": [
+                  "messages"
+                ]
+              },
+              {
+                "required": [
+                  "extend"
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "type": {
+                "const": "template"
+              }
+            }
+          },
+          "then": {
+            "required": [
+              "messages"
+            ]
+          }
         }
-      }
+      ]
     },
     "document": {
       "type": "object",
@@ -1257,7 +1343,9 @@
           "description": "Patterns to include only specific paths"
         },
         "maxFiles": {
-          "type": ["integer"],
+          "type": [
+            "integer"
+          ],
           "description": "Maximum number of files to include (0 for no limit)",
           "minimum": 0,
           "default": 0

src/Lib/Variable/CompositeProcessor.php

@@ -10,7 +10,7 @@
      * @param VariableReplacementProcessor[] $processors
      */
     public function __construct(
-        public array $processors,
+        public array $processors = [],
     ) {}
 
     public function process(string $text): string

src/Lib/Variable/VariableResolver.php

@@ -10,7 +10,7 @@
 final readonly class VariableResolver
 {
     public function __construct(
-        private VariableReplacementProcessorInterface $processor,
+        private VariableReplacementProcessorInterface $processor = new CompositeProcessor(),
     ) {}
 
     public function with(VariableReplacementProcessorInterface $processor): self

src/McpServer/Prompt/Exception/PromptParsingException.php

@@ -7,7 +7,7 @@
 /**
  * Exception thrown when a prompt configuration cannot be parsed.
  */
-final class PromptParsingException extends \RuntimeException
+class PromptParsingException extends \RuntimeException
 {
     // No additional methods needed, this is just a specialized exception type
 }

src/McpServer/Prompt/Exception/TemplateResolutionException.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Butschster\ContextGenerator\McpServer\Prompt\Exception;
+
+/**
+ * Exception thrown when a template resolution fails.
+ */
+final class TemplateResolutionException extends PromptParsingException
+{
+    // No additional methods needed, this is just a specialized exception type
+}

src/McpServer/Prompt/PromptDefinition.php renamed to src/McpServer/Prompt/Extension/PromptDefinition.php

@@ -2,8 +2,9 @@
 
 declare(strict_types=1);
 
-namespace Butschster\ContextGenerator\McpServer\Prompt;
+namespace Butschster\ContextGenerator\McpServer\Prompt\Extension;
 
+use Butschster\ContextGenerator\McpServer\Prompt\PromptType;
 use Mcp\Types\Prompt;
 use Mcp\Types\PromptMessage;
 
@@ -14,6 +15,9 @@ public function __construct(
         public Prompt $prompt,
         /** @var PromptMessage[] */
         public array $messages = [],
+        public PromptType $type = PromptType::Prompt,
+        /** @var PromptExtension[] */
+        public array $extensions = [],
     ) {}
 
     public function jsonSerialize(): array
@@ -35,9 +39,32 @@ public function jsonSerialize(): array
 
         return \array_filter([
             'id' => $this->id,
+            'type' => $this->type->value,
             'description' => $this->prompt->description,
             'schema' => $schema,
             'messages' => $this->messages,
+            'extend' => $this->serializeExtensions(),
         ], static fn($value) => $value !== null && $value !== []);
     }
+
+    /**
+     * Serializes the extensions for JSON output.
+     *
+     * @return array<mixed>|null The serialized extensions or null if empty
+     */
+    private function serializeExtensions(): ?array
+    {
+        if (empty($this->extensions)) {
+            return null;
+        }
+
+        // Convert extensions to the format used in configuration
+        return \array_map(static function (PromptExtension $ext) {
+            $args = [];
+            foreach ($ext->arguments as $arg) {
+                $args[$arg->name] = $arg->value;
+            }
+            return ['id' => $ext->templateId, 'arguments' => $args];
+        }, $this->extensions);
+    }
 }

src/McpServer/Prompt/Extension/PromptExtension.php

@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Butschster\ContextGenerator\McpServer\Prompt\Extension;
+
+/**
+ * Represents a template extension configuration.
+ */
+final readonly class PromptExtension
+{
+    /**
+     * @param string $templateId The ID of the template to extend
+     * @param PromptExtensionArgument[] $arguments The arguments to pass to the template
+     */
+    public function __construct(
+        public string $templateId,
+        public array $arguments = [],
+    ) {}
+
+    /**
+     * Creates a PromptExtension from a configuration array.
+     *
+     * @param array<string, mixed> $config The extension configuration
+     * @return self The created PromptExtension
+     * @throws \InvalidArgumentException If the configuration is invalid
+     */
+    public static function fromArray(array $config): self
+    {
+        if (empty($config['id']) || !\is_string($config['id'])) {
+            throw new \InvalidArgumentException('Extension must have a template ID');
+        }
+
+        $arguments = [];
+        if (isset($config['arguments']) && \is_array($config['arguments'])) {
+            foreach ($config['arguments'] as $name => $value) {
+                if (!\is_string($name) || !\is_string($value)) {
+                    throw new \InvalidArgumentException(
+                        \sprintf('Extension argument "%s" must have a string value', $name),
+                    );
+                }
+
+                $arguments[] = new PromptExtensionArgument($name, $value);
+            }
+        }
+
+        return new self($config['id'], $arguments);
+    }
+}