From 7c61ad647095c82aee393160821e41dc0eb889d4 Mon Sep 17 00:00:00 2001
From: Kyrian Obikwelu <koshnawaza@gmail.com>
Date: Wed, 25 Jun 2025 23:35:33 +0100
Subject: [PATCH] feat: add instructions in server initialization result

This update introduces an optional instructions parameter to the Configuration class, allowing for the provision of usage instructions for the server's features, enhancing the InitializeResult with instructions for improved client understanding.
---
 src/Configuration.php |  2 ++
 src/Dispatcher.php    |  3 ++-
 src/ServerBuilder.php | 19 ++++++++++++++++++-
 3 files changed, 22 insertions(+), 2 deletions(-)

diff --git a/src/Configuration.php b/src/Configuration.php
index 60f873f..b0af280 100644
--- a/src/Configuration.php
+++ b/src/Configuration.php
@@ -26,6 +26,7 @@ class Configuration
      * @param  CacheInterface|null  $cache  Optional PSR-16 Cache instance for registry/state.
      * @param  ContainerInterface  $container  PSR-11 DI Container for resolving handlers/dependencies.
      * @param  int  $paginationLimit  Maximum number of items to return for list methods.
+     * @param  string|null  $instructions  Instructions describing how to use the server and its features.
      */
     public function __construct(
         public readonly Implementation $serverInfo,
@@ -35,5 +36,6 @@ public function __construct(
         public readonly ?CacheInterface $cache,
         public readonly ContainerInterface $container,
         public readonly int $paginationLimit = 50,
+        public readonly ?string $instructions = null,
     ) {}
 }
diff --git a/src/Dispatcher.php b/src/Dispatcher.php
index a5bab0f..9cc9748 100644
--- a/src/Dispatcher.php
+++ b/src/Dispatcher.php
@@ -132,8 +132,9 @@ public function handleInitialize(InitializeRequest $request, SessionInterface $s
 
         $serverInfo = $this->configuration->serverInfo;
         $capabilities = $this->configuration->capabilities;
+        $instructions = $this->configuration->instructions;
 
-        return new InitializeResult($protocolVersion, $capabilities, $serverInfo);
+        return new InitializeResult($protocolVersion, $capabilities, $serverInfo, $instructions);
     }
 
     public function handlePing(PingRequest $request): EmptyResult
diff --git a/src/ServerBuilder.php b/src/ServerBuilder.php
index 69f2320..047a455 100644
--- a/src/ServerBuilder.php
+++ b/src/ServerBuilder.php
@@ -52,6 +52,8 @@ final class ServerBuilder
 
     private ?int $paginationLimit = 50;
 
+    private ?string $instructions = null;
+
     /** @var array<
      *     array{handler: array|string,
      *     name: string|null,
@@ -120,6 +122,20 @@ public function withPaginationLimit(int $paginationLimit): self
         return $this;
     }
 
+    /**
+     * Configures the instructions describing how to use the server and its features. 
+     * 
+     * This can be used by clients to improve the LLM's understanding of available tools, resources,
+     * etc. It can be thought of like a "hint" to the model. For example, this information MAY 
+     * be added to the system prompt.
+     */
+    public function withInstructions(string $instructions): self
+    {
+        $this->instructions = $instructions;
+
+        return $this;
+    }
+
     /**
      * Provides a PSR-3 logger instance. Defaults to NullLogger.
      */
@@ -257,7 +273,8 @@ public function build(): Server
             loop: $loop,
             cache: $cache,
             container: $container,
-            paginationLimit: $this->paginationLimit ?? 50
+            paginationLimit: $this->paginationLimit ?? 50,
+            instructions: $this->instructions,
         );
 
         $sessionHandler = $this->createSessionHandler();