Add resource template support

src/Server.php

@@ -14,6 +14,7 @@
 use Laravel\Mcp\Server\Methods\Initialize;
 use Laravel\Mcp\Server\Methods\ListPrompts;
 use Laravel\Mcp\Server\Methods\ListResources;
+use Laravel\Mcp\Server\Methods\ListResourceTemplates;
 use Laravel\Mcp\Server\Methods\ListTools;
 use Laravel\Mcp\Server\Methods\Ping;
 use Laravel\Mcp\Server\Methods\ReadResource;
@@ -92,6 +93,7 @@ abstract class Server
         'tools/list' => ListTools::class,
         'tools/call' => CallTool::class,
         'resources/list' => ListResources::class,
+        'resources/templates/list' => ListResourceTemplates::class,
         'resources/read' => ReadResource::class,
         'prompts/list' => ListPrompts::class,
         'prompts/get' => GetPrompt::class,

src/Server/Methods/ListResourceTemplates.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Laravel\Mcp\Server\Methods;
+
+use Laravel\Mcp\Server\Contracts\Method;
+use Laravel\Mcp\Server\Pagination\CursorPaginator;
+use Laravel\Mcp\Server\ServerContext;
+use Laravel\Mcp\Server\Transport\JsonRpcRequest;
+use Laravel\Mcp\Server\Transport\JsonRpcResponse;
+
+class ListResourceTemplates implements Method
+{
+    public function handle(JsonRpcRequest $request, ServerContext $context): JsonRpcResponse
+    {
+        $paginator = new CursorPaginator(
+            items: $context->resourceTemplates(),
+            perPage: $context->perPage($request->get('per_page')),
+            cursor: $request->cursor(),
+        );
+
+        return JsonRpcResponse::result($request->id, $paginator->paginate('resourceTemplates'));
+    }
+}

src/Server/Methods/ReadResource.php

@@ -8,11 +8,13 @@
 use Illuminate\Container\Container;
 use Illuminate\Support\Collection;
 use Illuminate\Validation\ValidationException;
+use Laravel\Mcp\Request;
 use Laravel\Mcp\Response;
 use Laravel\Mcp\Server\Contracts\Method;
 use Laravel\Mcp\Server\Exceptions\JsonRpcException;
 use Laravel\Mcp\Server\Methods\Concerns\InteractsWithResponses;
 use Laravel\Mcp\Server\Resource;
+use Laravel\Mcp\Server\Resources\Uri;
 use Laravel\Mcp\Server\ServerContext;
 use Laravel\Mcp\Server\Transport\JsonRpcRequest;
 use Laravel\Mcp\Server\Transport\JsonRpcResponse;
@@ -37,9 +39,37 @@ public function handle(JsonRpcRequest $request, ServerContext $context): Generat
             );
         }
 
-        $resource = $context->resources()
+        $resource = $context->resources(true)
             ->first(
-                fn (Resource $resource): bool => $resource->uri() === $request->get('uri'),
+                function (Resource $resource) use ($request): bool {
+                    $matches = $resource->match($request->get('uri'));
+
+                    if ($matches) {
+                        $resource->setActualUri($request->get('uri'));
+
+                        // Add the path variables to the mcp request only if
+                        // the resource is a template since resources can
+                        // only have path variables if they are templates
+                        if (
+                            $resource->isTemplate()
+                            && ($pathVariables = Uri::pathVariables($resource->originalUri(), $resource->uri())) !== []
+                        ) {
+                            $container = Container::getInstance();
+
+                            if ($container->has('mcp.request')) {
+                                /** @var Request $request */
+                                $request = $container->make('mcp.request');
+
+                                $request->setArguments([
+                                    ...$request->all(),
+                                    ...$pathVariables,
+                                ]);
+                            }
+                        }
+                    }
+
+                    return $matches;
+                },
                 fn () => throw new JsonRpcException(
                     "Resource [{$request->get('uri')}] not found.",
                     -32002,

src/Server/Resource.php

@@ -5,14 +5,53 @@
 namespace Laravel\Mcp\Server;
 
 use Illuminate\Support\Str;
+use Laravel\Mcp\Server\Resources\Matching\SchemeValidator;
+use Laravel\Mcp\Server\Resources\Matching\UriValidator;
+use Laravel\Mcp\Server\Resources\Matching\ValidatorInterface;
+use Laravel\Mcp\Server\Resources\Uri;
 
 abstract class Resource extends Primitive
 {
     protected string $uri = '';
 
+    private string $actualUri = '';
+
     protected string $mimeType = '';
 
+    /**
+     * We can use this property to make the method
+     * $this->isTemplate() more efficient and
+     * avoid compiling the regex of the uri
+     */
+    protected ?bool $isTemplate = null;
+
+    /**
+     * @var array<int, ValidatorInterface>
+     */
+    public static array $validators;
+
+    /**
+     * @return array<int, ValidatorInterface>
+     */
+    public static function getValidators(): array
+    {
+        // To match the route, we will use a chain of responsibility pattern with the
+        // validator implementations. We will spin through each one making sure it
+        // passes, and then we will know if the route as a whole matches request.
+        return static::$validators ?? static::$validators = [
+            new UriValidator, new SchemeValidator,
+        ];
+    }
+
     public function uri(): string
+    {
+        return
+            $this->actualUri !== ''
+                ? $this->actualUri
+                : $this->originalUri();
+    }
+
+    public function originalUri(): string
     {
         return $this->uri !== ''
             ? $this->uri
@@ -26,12 +65,55 @@ public function mimeType(): string
             : 'text/plain';
     }
 
+    public function setActualUri(string $uri): static
+    {
+        $this->actualUri = $uri;
+
+        return $this;
+    }
+
+    public function match(string $uri): bool
+    {
+        if ($this->uri() === $uri) {
+            return true;
+        }
+
+        foreach (self::getValidators() as $validator) {
+            if (! $validator->matches($this, $uri)) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    public function isTemplate(): bool
+    {
+        return $this->isTemplate ?? count(Uri::pathRegex($this->originalUri())['variables']) > 0;
+    }
+
+    public function getUriPath(): string
+    {
+        return Uri::path($this->uri());
+    }
+
+    public function getUriScheme(): string
+    {
+        return Uri::scheme($this->uri());
+    }
+
     /**
      * @return array<string, mixed>
      */
     public function toMethodCall(): array
     {
-        return ['uri' => $this->uri()];
+        $response = ['uri' => $this->uri()];
+
+        if ($this->isTemplate()) {
+            $response['uriTemplate'] = $this->originalUri();
+        }
+
+        return $response;
     }
 
     public function toArray(): array
@@ -40,8 +122,8 @@ public function toArray(): array
             'name' => $this->name(),
             'title' => $this->title(),
             'description' => $this->description(),
-            'uri' => $this->uri(),
             'mimeType' => $this->mimeType(),
+            ...$this->toMethodCall(),
         ];
     }
 }

src/Server/Resources/Matching/SchemeValidator.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Laravel\Mcp\Server\Resources\Matching;
+
+use Laravel\Mcp\Server\Resource;
+use Laravel\Mcp\Server\Resources\Uri;
+
+class SchemeValidator implements ValidatorInterface
+{
+    public function matches(Resource $resource, string $uri): bool
+    {
+        return $resource->getUriScheme() === Uri::scheme($uri);
+    }
+}

src/Server/Resources/Matching/UriValidator.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Laravel\Mcp\Server\Resources\Matching;
+
+use Laravel\Mcp\Server\Resource;
+use Laravel\Mcp\Server\Resources\Uri;
+
+class UriValidator implements ValidatorInterface
+{
+    public function matches(Resource $resource, string $uri): bool
+    {
+        $path = Uri::path($uri);
+
+        return preg_match(Uri::pathRegex($resource->uri())['regex'], rawurldecode($path)) === 1;
+    }
+}

src/Server/Resources/Matching/ValidatorInterface.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Laravel\Mcp\Server\Resources\Matching;
+
+use Laravel\Mcp\Server\Resource;
+
+interface ValidatorInterface
+{
+    public function matches(Resource $resource, string $uri): bool;
+}