#33 Expand documentation with sampling support details and interfaces

- Updated sampling documentation to include `SamplingAwareToolInterface`, `SamplingAwarePromptInterface`, and `SamplingAwareResourceInterface`.
- Added examples and best practices for tools, prompts, and resources leveraging sampling.
- Enhanced `building_prompts.md`, `building_tools.md`, and `building_resources.md` with more detailed usage cases.
- Introduced links to sampling-specific content in index and relevant sections.

Author: klapaudius

docs/building_prompts.md

@@ -6,10 +6,11 @@ This guide provides a comprehensive walkthrough for creating MCP prompts in the
 1. [Understanding MCP Prompts](#understanding-mcp-prompts)
 2. [Quick Start with make:mcp-prompt](#quick-start-with-makemcp-prompt)
 3. [Basic Prompt Implementation](#basic-prompt-implementation)
-4. [Advanced Prompt Features](#advanced-prompt-features)
-5. [Multi-Modal Prompts](#multi-modal-prompts)
-6. [Dynamic Prompts with Arguments](#dynamic-prompts-with-arguments)
-7. [Best Practices](#best-practices)
+4. [SamplingAwarePromptInterface](#samplingawarepromptinterface)
+5. [Advanced Prompt Features](#advanced-prompt-features)
+6. [Multi-Modal Prompts](#multi-modal-prompts)
+7. [Dynamic Prompts with Arguments](#dynamic-prompts-with-arguments)
+8. [Best Practices](#best-practices)
 
 ## Understanding MCP Prompts
 
@@ -146,6 +147,92 @@ klp_mcp_server:
             class: App\Mcp\Prompts\BlogPostPrompt
 ```
 
+
+
+## SamplingAwarePromptInterface
+
+For prompts that need to make LLM sampling requests during message generation, implement the `SamplingAwarePromptInterface`. This interface extends `PromptInterface` and provides access to a `SamplingClient` for creating nested LLM calls.
+
+### When to Use Sampling
+
+Use sampling in prompts that need:
+- Dynamic question generation based on input content
+- Context-specific prompt adaptation
+- AI-enhanced prompt customization
+- Analysis of user input to tailor prompt messages
+
+### Implementation
+
+```php
+use KLP\KlpMcpServer\Services\PromptService\SamplingAwarePromptInterface;
+use KLP\KlpMcpServer\Services\SamplingService\SamplingClient;
+use KLP\KlpMcpServer\Services\SamplingService\ModelPreferences;
+
+class AdaptiveReviewPrompt implements SamplingAwarePromptInterface
+{
+    private ?SamplingClient $samplingClient = null;
+
+    public function setSamplingClient(SamplingClient $samplingClient): void
+    {
+        $this->samplingClient = $samplingClient;
+    }
+
+    public function getMessages(array $arguments = []): CollectionPromptMessage
+    {
+        $content = $arguments['content'] ?? '';
+        
+        $collection = new CollectionPromptMessage([
+            new TextPromptMessage('system', 'You are an expert reviewer.')
+        ]);
+
+        // Generate dynamic questions if sampling is available
+        if ($this->samplingClient !== null && $this->samplingClient->canSample()) {
+            $dynamicQuestions = $this->generateQuestions($content);
+            if ($dynamicQuestions) {
+                $collection->addMessage(
+                    new TextPromptMessage('user', $dynamicQuestions)
+                );
+            }
+        }
+
+        $collection->addMessage(
+            new TextPromptMessage('user', "Please review: {$content}")
+        );
+
+        return $collection;
+    }
+
+    private function generateQuestions(string $content): ?string
+    {
+        try {
+            $prompt = "Generate specific review questions for: " . $content;
+            
+            $response = $this->samplingClient->createTextRequest(
+                $prompt,
+                new ModelPreferences(
+                    hints: [['name' => 'claude-3-haiku']],
+                    speedPriority: 0.8
+                ),
+                null,
+                300
+            );
+
+            return $response->getContent()->getText();
+        } catch (\Exception $e) {
+            return null; // Fallback gracefully
+        }
+    }
+}
+```
+
+### Best Practices
+
+- Always check if sampling is available with `canSample()`
+- Handle sampling failures gracefully with fallbacks
+- Use faster models for prompt generation (like Haiku)
+- Keep token limits reasonable for prompt generation
+- Cache results when appropriate to avoid repeated calls
+
 ## Advanced Prompt Features
 
 ### Content Strategy Prompt with Multiple Messages

docs/building_resources.md

@@ -1,5 +1,18 @@
 # Building MCP Resources - Complete Walkthrough
 
+## Table of Contents
+1. [Introduction to Resources in Model Context Protocol (MCP)](#introduction-to-resources-in-model-context-protocol-mcp)
+2. [What are MCP Resources?](#what-are-mcp-resources)
+3. [Types of Resources](#types-of-resources)
+4. [Creating Your First MCP Resource](#creating-your-first-mcp-resource)
+5. [Understanding the Resource Interfaces](#understanding-the-resource-interfaces)
+6. [SamplingAwareResourceInterface](#samplingawareresourceinterface)
+7. [Using the Resource Class](#using-the-resource-class)
+8. [Advanced Resource Development](#advanced-resource-development)
+9. [Best Practices for MCP Resource Development](#best-practices-for-mcp-resource-development)
+10. [Example Resources](#example-resources)
+11. [Conclusion](#conclusion)
+
 ## Introduction to Resources in Model Context Protocol (MCP)
 
 Resources in the Model Context Protocol (MCP) are data objects that can be accessed by Large Language Models (LLMs) through the MCP server. Unlike tools, which provide functionality, resources provide data that LLMs can reference or use in their processing. Resources enable LLMs to:
@@ -155,6 +168,79 @@ Resource templates must implement the `ResourceTemplateInterface`, which extends
    - Checks if a resource with the given URI exists
    - Returns true if the resource exists, false otherwise
 
+## SamplingAwareResourceInterface
+
+For resources that need to make LLM sampling requests during data generation, implement the `SamplingAwareResourceInterface`. This interface extends `ResourceInterface` and provides access to a `SamplingClient` for creating nested LLM calls.
+
+### When to Use Sampling
+
+Use sampling in resources that need:
+- Dynamic content generation based on project data
+- AI-enhanced summaries or analysis
+- Content that adapts based on context
+- Natural language processing of existing data
+
+### Implementation
+
+```php
+use KLP\KlpMcpServer\Services\ResourceService\SamplingAwareResourceInterface;
+use KLP\KlpMcpServer\Services\SamplingService\SamplingClient;
+use KLP\KlpMcpServer\Services\SamplingService\ModelPreferences;
+
+class ProjectAnalysisResource implements SamplingAwareResourceInterface
+{
+    private ?SamplingClient $samplingClient = null;
+    private ?string $cachedData = null;
+
+    public function setSamplingClient(SamplingClient $samplingClient): void
+    {
+        $this->samplingClient = $samplingClient;
+        $this->cachedData = null; // Clear cache when client changes
+    }
+
+    public function getData(): string
+    {
+        if ($this->cachedData !== null) {
+            return $this->cachedData;
+        }
+
+        if ($this->samplingClient === null || !$this->samplingClient->canSample()) {
+            return 'Static fallback content when sampling is not available';
+        }
+
+        try {
+            $projectInfo = $this->gatherProjectInfo();
+            $prompt = "Analyze this project: " . json_encode($projectInfo);
+            
+            $response = $this->samplingClient->createTextRequest(
+                $prompt,
+                new ModelPreferences(
+                    hints: [['name' => 'claude-3-sonnet']],
+                    intelligencePriority: 0.8
+                ),
+                null,
+                2000 // max tokens
+            );
+
+            $this->cachedData = $response->getContent()->getText() ?? 'No analysis generated';
+            return $this->cachedData;
+        } catch (\Exception $e) {
+            return 'Error generating analysis: ' . $e->getMessage();
+        }
+    }
+
+    // ... other required interface methods
+}
+```
+
+### Best Practices
+
+- Always check if sampling is available with `canSample()`
+- Implement caching to avoid repeated expensive LLM calls
+- Provide fallback content when sampling fails
+- Handle sampling failures gracefully
+- Clear cache when sampling client changes
+
 ## Using the Resource Class
 
 For simple resources, you can use the provided `Resource` class instead of implementing the interface from scratch:

docs/building_tools.md

@@ -1,5 +1,19 @@
 # Building MCP Tools - Complete Walkthrough
 
+## Table of Contents
+1. [Introduction to Model Context Protocol (MCP)](#introduction-to-model-context-protocol-mcp)
+2. [What are MCP Tools?](#what-are-mcp-tools)
+3. [Creating Your First MCP Tool](#creating-your-first-mcp-tool)
+4. [Understanding the Tool Interface](#understanding-the-tool-interface)
+5. [Tool Result Types](#tool-result-types)
+6. [Testing Your MCP Tools](#testing-your-mcp-tools)
+7. [Streaming Tools with Progress Notifications](#streaming-tools-with-progress-notifications)
+8. [SamplingAwareToolInterface](#samplingawaretoolinterface)
+9. [Advanced Tool Development](#advanced-tool-development)
+10. [Best Practices for MCP Tool Development](#best-practices-for-mcp-tool-development)
+11. [Example Tools](#example-tools)
+12. [Conclusion](#conclusion)
+
 ## Introduction to Model Context Protocol (MCP)
 
 The Model Context Protocol (MCP) is a standardized communication protocol that enables Large Language Models (LLMs) to interact with external systems and services. MCP allows LLMs to:
@@ -696,6 +710,64 @@ class FileProcessingTool implements StreamableToolInterface
 }
 ```
 
+## SamplingAwareToolInterface
+
+For tools that need to make LLM sampling requests during execution, implement the `SamplingAwareToolInterface`. This interface extends `StreamableToolInterface` and provides access to a `SamplingClient` for creating nested LLM calls.
+
+### When to Use Sampling
+
+Use sampling in tools that need:
+- Code analysis and recommendations
+- Content generation or transformation
+- Complex reasoning tasks
+- Natural language processing
+
+### Implementation
+
+```php
+use KLP\KlpMcpServer\Services\SamplingService\SamplingClient;
+use KLP\KlpMcpServer\Services\SamplingService\ModelPreferences;
+use KLP\KlpMcpServer\Services\ToolService\SamplingAwareToolInterface;
+
+class MyAnalysisTool implements SamplingAwareToolInterface
+{
+    private ?SamplingClient $samplingClient = null;
+
+    public function setSamplingClient(SamplingClient $samplingClient): void
+    {
+        $this->samplingClient = $samplingClient;
+    }
+
+    public function execute(array $arguments): ToolResultInterface
+    {
+        if ($this->samplingClient === null || !$this->samplingClient->canSample()) {
+            return new TextToolResult('This tool requires LLM sampling capability');
+        }
+
+        $prompt = "Analyze this data: " . $arguments['data'];
+        
+        $response = $this->samplingClient->createTextRequest(
+            $prompt,
+            new ModelPreferences(
+                hints: [['name' => 'claude-3-sonnet']],
+                intelligencePriority: 0.8
+            ),
+            null,
+            2000 // max tokens
+        );
+
+        return new TextToolResult($response->getContent()->getText() ?? 'No response');
+    }
+}
+```
+
+### Best Practices
+
+- Always check if sampling is available with `canSample()`
+- Handle sampling failures gracefully
+- Use appropriate model preferences for your use case
+- Set reasonable token limits to control costs
+
 ## Advanced Tool Development
 
 ### Handling Complex Inputs

docs/index.md

@@ -33,6 +33,7 @@ Welcome to the Symfony MCP Server documentation. This bundle enables developers
 - [Transport Layer](../README.md#why-not-stdio) - SSE vs StreamableHTTP vs STDIO
 - [Pub/Sub Architecture](../README.md#pubsub-architecture-with-adapters) - Message broker and adapter system
 - [Progress Notifications](building_tools.md#progress-notifications) - Real-time updates for long-running operations
+- [Sampling Feature](sampling.md) - Enable tools to make nested LLM calls for enhanced AI capabilities
 
 ### Configuration
 - [Configuration Reference](../src/Resources/config/packages/klp_mcp_server.yaml) - Complete configuration options
@@ -47,14 +48,15 @@ Welcome to the Symfony MCP Server documentation. This bundle enables developers
 ## API Reference
 
 ### Interfaces
-- **Tools**: `StreamableToolInterface`, `BaseToolInterface` (deprecated)
-- **Prompts**: `PromptInterface`, `PromptMessageInterface`
-- **Resources**: `ResourceInterface`, `ResourceTemplateInterface`
+- **Tools**: `StreamableToolInterface`, `SamplingAwareToolInterface`, `ToolInterface` (deprecated)
+- **Prompts**: `PromptInterface`, `SamplingAwarePromptInterface`, `PromptMessageInterface`
+- **Resources**: `ResourceInterface`, `SamplingAwareResourceInterface`, `ResourceTemplateInterface`
 - **Results**: `ToolResultInterface` with Text, Image, Audio, Resource types
 
 ### Services
 - **ProgressNotifier**: Real-time progress updates
 - **PromptRepository**: Prompt management and retrieval
+- **SamplingClient**: Interface for making nested LLM calls
 - **MCPProtocol**: Core protocol implementation
 
 ## Requirements & Compatibility