Align server with MCP 2025-06-18 tool spec (#80)

kargnas · web-flow · commit d10ec99d4a4f · 2025-10-12T05:34:31.000+09:00
* Align tools API with MCP 2025-06-18

* Fix styling

---------

Co-authored-by: kargnas &lt;1438533+kargnas@users.noreply.github.com&gt;
diff --git a/README.md b/README.md
@@ -47,6 +47,10 @@ Version 1.4.0 introduces powerful automatic tool and resource generation from Sw
   - Smart naming for readable class names (handles hash-based operationIds)
   - Built-in API testing before generation
   - Complete Laravel HTTP client integration with retry logic
+- **MCP 2025-06-18 compatibility**:
+  - Default protocol negotiation now targets the 2025-06-18 revision.
+  - `tools/list` returns cursor-based pages and advertises the `listChanged` capability flag.
+  - Tool responses automatically expose `structuredContent` alongside text blocks for structured payloads.
 
 **Example Usage:**
 ```bash
diff --git a/config/mcp-server.php b/config/mcp-server.php
@@ -272,6 +272,37 @@
         // App\MCP\Tools\External\PaymentProcessorTool::class,
     ],
 
+    /*
+    |--------------------------------------------------------------------------
+    | Tools Capability Flags
+    |--------------------------------------------------------------------------
+    |
+    | The MCP 2025-06-18 revision requires servers to declare whether they emit
+    | `notifications/tools/list_changed` via the `listChanged` capability flag.
+    | You can opt-in through the `MCP_TOOLS_LIST_CHANGED` environment variable.
+    | @see https://modelcontextprotocol.io/specification/2025-06-18#capabilities
+    |
+    */
+    'tool_capabilities' => [
+        'list_changed' => env('MCP_TOOLS_LIST_CHANGED', false),
+    ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Tools List Pagination
+    |--------------------------------------------------------------------------
+    |
+    | `tools/list` now supports cursor-based pagination per the 2025-06-18 spec.
+    | Configure the maximum number of tool definitions returned per page here.
+    | Clients can request subsequent pages by passing the `nextCursor` value as
+    | the `cursor` parameter. @see
+    | https://modelcontextprotocol.io/specification/2025-06-18#listing-tools
+    |
+    */
+    'tools_list' => [
+        'page_size' => env('MCP_TOOLS_PAGE_SIZE', 50),
+    ],
+
     /*
     |--------------------------------------------------------------------------
     | MCP Resources Registry
diff --git a/scripts/test-setup.sh b/scripts/test-setup.sh
@@ -164,9 +164,11 @@ curl -X POST "$HTTP_ENDPOINT" \
     "id": 1,
     "method": "initialize",
     "params": {
-      "protocolVersion": "2024-11-05",
+      "protocolVersion": "2025-06-18",
       "capabilities": {
-        "tools": {},
+        "tools": {
+          "listChanged": false
+        },
         "resources": {}
       },
       "clientInfo": {
diff --git a/src/Data/Requests/NotificationData.php b/src/Data/Requests/NotificationData.php
@@ -6,7 +6,7 @@
  * JSON-RPC Request Notification Data
  * Represents the data structure for a JSON-RPC notification according to the MCP specification.
  *
- * @see https://modelcontextprotocol.io/specification/2024-11-05/basic/index#notifications
+ * @see https://modelcontextprotocol.io/specification/2025-06-18/basic/index#notifications
  */
 class NotificationData
 {
diff --git a/src/Data/Requests/RequestData.php b/src/Data/Requests/RequestData.php
@@ -6,7 +6,7 @@
  * Represents a JSON-RPC Request object according to the MCP specification.
  * This class encapsulates the data structure for incoming requests.
  *
- * @link https://modelcontextprotocol.io/specification/2024-11-05/basic/index#requests
+ * @link https://modelcontextprotocol.io/specification/2025-06-18/basic/index#requests
  *
  * @property string $method The name of the method to be invoked.
  * @property string $jsonRpc The JSON-RPC version string (e.g., "2.0").
diff --git a/src/Data/Resources/InitializeResource.php b/src/Data/Resources/InitializeResource.php
@@ -38,7 +38,12 @@ class InitializeResource
      * @param  array  $capabilities  The capabilities supported by the server.
      * @param  string  $protocolVersion  The protocol version being used.
      */
-    public function __construct(string $name, string $version, array $capabilities, string $protocolVersion = '2024-11-05')
+    /**
+     * @param  string  $protocolVersion  Defaults to MCP revision 2025-06-18 per the upstream spec.
+     *                                   This ensures initialize echoes the negotiated version documented at
+     *                                   https://modelcontextprotocol.io/specification/2025-06-18#initialization.
+     */
+    public function __construct(string $name, string $version, array $capabilities, string $protocolVersion = '2025-06-18')
     {
         $this->serverInfo = [
             'name' => $name,
diff --git a/src/Protocol/MCPProtocol.php b/src/Protocol/MCPProtocol.php
@@ -24,8 +24,9 @@
  */
 final class MCPProtocol
 {
-    // This was supposed to be 2025-03-26, but I set this to 2024-11-05 because Vercel ai-sdk doesn't support it
-    public const PROTOCOL_VERSION = '2024-11-05';
+    // MCP specification (2025-06-18) requires advertising this protocol version during initialize.
+    // @see https://modelcontextprotocol.io/specification/2025-06-18 for the authoritative definition.
+    public const PROTOCOL_VERSION = '2025-06-18';
 
     private TransportInterface $transport;
 
diff --git a/src/Providers/SseServiceProvider.php b/src/Providers/SseServiceProvider.php
@@ -63,7 +63,11 @@ public function register(): void
                 $capabilities = new ServerCapabilities;
 
                 $toolRepository = app(ToolRepository::class);
-                $capabilities->withTools(['schemas' => $toolRepository->getToolSchemas()]);
+                $capabilities->withTools([
+                    // Advertise pagination & change notifications support as required by MCP 2025-06-18.
+                    'listChanged' => (bool) Config::get('mcp-server.tool_capabilities.list_changed', false),
+                    'schemas' => $toolRepository->getToolSchemas(),
+                ]);
                 $resourceRepository = app(ResourceRepository::class);
                 $capabilities->withResources(['schemas' => [
                     'resources' => $resourceRepository->getResourceSchemas(),
diff --git a/src/Providers/StreamableHttpServiceProvider.php b/src/Providers/StreamableHttpServiceProvider.php
@@ -58,7 +58,11 @@ public function register(): void
                 $capabilities = new ServerCapabilities;
 
                 $toolRepository = app(ToolRepository::class);
-                $capabilities->withTools(['schemas' => $toolRepository->getToolSchemas()]);
+                $capabilities->withTools([
+                    // Advertise pagination & change notifications support as required by MCP 2025-06-18.
+                    'listChanged' => (bool) Config::get('mcp-server.tool_capabilities.list_changed', false),
+                    'schemas' => $toolRepository->getToolSchemas(),
+                ]);
                 $resourceRepository = app(ResourceRepository::class);
                 $capabilities->withResources(['schemas' => [
                     'resources' => $resourceRepository->getResourceSchemas(),
diff --git a/src/Server/Request/ToolsCallHandler.php b/src/Server/Request/ToolsCallHandler.php
@@ -2,6 +2,7 @@
 
 namespace OPGG\LaravelMcpServer\Server\Request;
 
+use JsonException;
 use OPGG\LaravelMcpServer\Enums\ProcessMessageType;
 use OPGG\LaravelMcpServer\Exceptions\Enums\JsonRpcErrorCode;
 use OPGG\LaravelMcpServer\Exceptions\JsonRpcErrorException;
@@ -73,15 +74,60 @@ public function execute(string $method, ?array $params = null): array
                 return $preparedResult;
             }
 
-            if (is_array($preparedResult) && array_key_exists('content', $preparedResult)) {
-                return $preparedResult;
+            if (is_array($preparedResult)) {
+                if (array_key_exists('content', $preparedResult)
+                    || array_key_exists('structuredContent', $preparedResult)
+                    || array_key_exists('isError', $preparedResult)) {
+                    return $preparedResult;
+                }
+
+                try {
+                    $json = json_encode($preparedResult, JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE);
+                } catch (JsonException $exception) {
+                    throw new JsonRpcErrorException(
+                        message: 'Failed to encode tool result as JSON: '.$exception->getMessage(),
+                        code: JsonRpcErrorCode::INTERNAL_ERROR
+                    );
+                }
+
+                return [
+                    'content' => [
+                        [
+                            'type' => 'text',
+                            'text' => $json,
+                        ],
+                    ],
+                    // Provide structuredContent alongside text per MCP 2025-06-18 guidance.
+                    // @see https://modelcontextprotocol.io/specification/2025-06-18#structured-content
+                    'structuredContent' => $preparedResult,
+                ];
+            }
+
+            if (is_string($preparedResult)) {
+                return [
+                    'content' => [
+                        [
+                            'type' => 'text',
+                            'text' => $preparedResult,
+                        ],
+                    ],
+                ];
+            }
+
+            try {
+                $text = json_encode($preparedResult, JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE);
+            } catch (JsonException $exception) {
+                throw new JsonRpcErrorException(
+                    message: 'Failed to encode tool result as JSON: '.$exception->getMessage(),
+                    code: JsonRpcErrorCode::INTERNAL_ERROR
+                );
             }
 
             return [
                 'content' => [
                     [
                         'type' => 'text',
-                        'text' => is_string($preparedResult) ? $preparedResult : json_encode($preparedResult, JSON_UNESCAPED_UNICODE),
+                        'text' => $text,
                     ],
                 ],
             ];
diff --git a/src/Server/Request/ToolsListHandler.php b/src/Server/Request/ToolsListHandler.php
@@ -2,7 +2,10 @@
 
 namespace OPGG\LaravelMcpServer\Server\Request;
 
+use Illuminate\Support\Facades\Config;
 use OPGG\LaravelMcpServer\Enums\ProcessMessageType;
+use OPGG\LaravelMcpServer\Exceptions\Enums\JsonRpcErrorCode;
+use OPGG\LaravelMcpServer\Exceptions\JsonRpcErrorException;
 use OPGG\LaravelMcpServer\Protocol\Handlers\RequestHandler;
 use OPGG\LaravelMcpServer\Services\ToolService\ToolRepository;
 
@@ -14,16 +17,51 @@ class ToolsListHandler extends RequestHandler
 
     private ToolRepository $toolRepository;
 
+    private int $pageSize;
+
     public function __construct(ToolRepository $toolRepository)
     {
         parent::__construct();
         $this->toolRepository = $toolRepository;
+
+        // Enforce the page size mandated by our configuration while defaulting to 50 entries.
+        // This mirrors the cursor based pagination described in the MCP 2025-06-18 tools/list spec.
+        $configuredPageSize = (int) Config::get('mcp-server.tools_list.page_size', 50);
+        $this->pageSize = max(1, $configuredPageSize);
     }
 
     public function execute(string $method, ?array $params = null): array
     {
-        return [
-            'tools' => $this->toolRepository->getToolSchemas(),
+        $schemas = array_values($this->toolRepository->getToolSchemas());
+
+        $cursor = $params['cursor'] ?? null;
+        $offset = 0;
+
+        if ($cursor !== null) {
+            if (! is_string($cursor) || $cursor === '') {
+                throw new JsonRpcErrorException('Cursor must be a non-empty string.', JsonRpcErrorCode::INVALID_PARAMS);
+            }
+
+            if (! ctype_digit($cursor)) {
+                throw new JsonRpcErrorException('Cursor must be a numeric string offset.', JsonRpcErrorCode::INVALID_PARAMS);
+            }
+
+            $offset = (int) $cursor;
+        }
+
+        $page = array_slice($schemas, $offset, $this->pageSize);
+
+        $response = [
+            // The spec requires returning the tool definitions in a `tools` array.
+            // @see https://modelcontextprotocol.io/specification/2025-06-18#listing-tools
+            'tools' => $page,
         ];
+
+        $nextOffset = $offset + $this->pageSize;
+        if ($nextOffset < count($schemas)) {
+            $response['nextCursor'] = (string) $nextOffset;
+        }
+
+        return $response;
     }
 }
diff --git a/src/Server/ServerCapabilities.php b/src/Server/ServerCapabilities.php
@@ -61,6 +61,17 @@ final class ServerCapabilities
     public function withTools(?array $config = []): self
     {
         $this->supportsTools = true;
+        $config = $config ?? [];
+
+        // The MCP 2025-06-18 specification mandates advertising whether `tools/list_changed`
+        // notifications are emitted via the `listChanged` flag within the tools capability block.
+        // When a caller does not provide an explicit value we default to `false` so the payload
+        // still satisfies the schema described at
+        // https://modelcontextprotocol.io/specification/2025-06-18#capabilities.
+        if (! array_key_exists('listChanged', $config)) {
+            $config['listChanged'] = false;
+        }
+
         $this->toolsConfig = $config;
 
         return $this;
diff --git a/src/Services/ToolService/Examples/HelloWorldTool.php b/src/Services/ToolService/Examples/HelloWorldTool.php
@@ -6,6 +6,7 @@
 use OPGG\LaravelMcpServer\Exceptions\Enums\JsonRpcErrorCode;
 use OPGG\LaravelMcpServer\Exceptions\JsonRpcErrorException;
 use OPGG\LaravelMcpServer\Services\ToolService\ToolInterface;
+use OPGG\LaravelMcpServer\Services\ToolService\ToolResponse;
 
 class HelloWorldTool implements ToolInterface
 {
@@ -24,6 +25,11 @@ public function description(): string
         return 'Say HelloWorld developer.';
     }
 
+    public function title(): string
+    {
+        return 'Hello World Greeting';
+    }
+
     public function inputSchema(): array
     {
         return [
@@ -38,12 +44,30 @@ public function inputSchema(): array
         ];
     }
 
+    public function outputSchema(): array
+    {
+        return [
+            'type' => 'object',
+            'properties' => [
+                'name' => [
+                    'type' => 'string',
+                    'description' => 'Echoed developer name.',
+                ],
+                'message' => [
+                    'type' => 'string',
+                    'description' => 'Greeting message returned to the caller.',
+                ],
+            ],
+            'required' => ['name', 'message'],
+        ];
+    }
+
     public function annotations(): array
     {
         return [];
     }
 
-    public function execute(array $arguments): array
+    public function execute(array $arguments): ToolResponse
     {
         $validator = Validator::make($arguments, [
             'name' => ['required', 'string'],
@@ -54,9 +78,18 @@ public function execute(array $arguments): array
 
         $name = $arguments['name'] ?? 'MCP';
 
-        return [
+        $payload = [
             'name' => $name,
             'message' => "Hello, HelloWorld `{$name}` developer.",
         ];
+
+        // Provide both human readable and structured payloads per MCP 2025-06-18 guidance.
+        // @see https://modelcontextprotocol.io/specification/2025-06-18#structured-content
+        return ToolResponse::structured($payload, [
+            [
+                'type' => 'text',
+                'text' => $payload['message'],
+            ],
+        ]);
     }
 }
diff --git a/src/Services/ToolService/ToolInterface.php b/src/Services/ToolService/ToolInterface.php
@@ -26,4 +26,10 @@ public function execute(array $arguments): mixed;
      * @return bool
      */
     // public function isStreaming(): bool;
+
+    /*
+     * Optional helpers recognised by ToolRepository when present:
+     * - title(): string|null                -> Human readable tool title per MCP 2025-06-18.
+     * - outputSchema(): array               -> JSON schema describing structuredContent responses.
+     */
 }
diff --git a/src/Services/ToolService/ToolRepository.php b/src/Services/ToolService/ToolRepository.php
diff --git a/src/Services/ToolService/ToolResponse.php b/src/Services/ToolService/ToolResponse.php
diff --git a/tests/Http/StreamableHttpTest.php b/tests/Http/StreamableHttpTest.php

Original file line number	Diff line number	Diff line change
`@@ -6,7 +6,7 @@`
`6`	`6`	`* JSON-RPC Request Notification Data`
`7`	`7`	`* Represents the data structure for a JSON-RPC notification according to the MCP specification.`
`8`	`8`	`*`
`9`		`- * @see https://modelcontextprotocol.io/specification/2024-11-05/basic/index#notifications`
	`9`	`+ * @see https://modelcontextprotocol.io/specification/2025-06-18/basic/index#notifications`
`10`	`10`	`*/`
`11`	`11`	`class NotificationData`
`12`	`12`	`{`
Original file line number	Diff line number	Diff line change
`@@ -6,7 +6,7 @@`
`6`	`6`	`* Represents a JSON-RPC Request object according to the MCP specification.`
`7`	`7`	`* This class encapsulates the data structure for incoming requests.`
`8`	`8`	`*`
`9`		`- * @link https://modelcontextprotocol.io/specification/2024-11-05/basic/index#requests`
	`9`	`+ * @link https://modelcontextprotocol.io/specification/2025-06-18/basic/index#requests`
`10`	`10`	`*`
`11`	`11`	`* @property string $method The name of the method to be invoked.`
`12`	`12`	`* @property string $jsonRpc The JSON-RPC version string (e.g., "2.0").`