[Add] Resource Template Implementation

src/Console/Commands/MakeResourceTemplateCommand.php

@@ -0,0 +1,55 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Laravel\Mcp\Console\Commands;
+
+use Illuminate\Console\GeneratorCommand;
+use Illuminate\Support\Str;
+use Symfony\Component\Console\Attribute\AsCommand;
+use Symfony\Component\Console\Input\InputOption;
+
+#[AsCommand(
+    name: 'make:mcp-resource-template',
+    description: 'Create a new MCP resource template class'
+)]
+class MakeResourceTemplateCommand extends GeneratorCommand
+{
+    /**
+     * @var string
+     */
+    protected $type = 'ResourceTemplate';
+
+    protected function getStub(): string
+    {
+        return file_exists($customPath = $this->laravel->basePath('stubs/resource-template.stub'))
+            ? $customPath
+            : __DIR__.'/../../../stubs/resource-template.stub';
+    }
+
+    protected function getDefaultNamespace($rootNamespace): string
+    {
+        return "{$rootNamespace}\\Mcp\\ResourceTemplates";
+    }
+
+    /**
+     * @return array<int, array<int, string|int>>
+     */
+    protected function getOptions(): array
+    {
+        return [
+            ['force', 'f', InputOption::VALUE_NONE, 'Create the class even if the resource template already exists'],
+        ];
+    }
+
+    protected function buildClass($name): string
+    {
+        $stub = parent::buildClass($name);
+
+        return str_replace(
+            '{{ classKebab }}',
+            Str::kebab(class_basename($name)),
+            $stub
+        );
+    }
+}

src/Request.php

@@ -100,6 +100,19 @@ public function setArguments(array $arguments): void
         $this->arguments = $arguments;
     }
 
+    /**
+     * Merge new data into the current request data.
+     *
+     * @param  array<string, mixed>  $data
+     * @return $this
+     */
+    public function merge(array $data): static
+    {
+        $this->arguments = array_merge($this->arguments, $data);
+
+        return $this;
+    }
+
     public function setSessionId(?string $sessionId): void
     {
         $this->sessionId = $sessionId;

src/Server.php

@@ -14,11 +14,13 @@
 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;
 use Laravel\Mcp\Server\Prompt;
 use Laravel\Mcp\Server\Resource;
+use Laravel\Mcp\Server\ResourceTemplate;
 use Laravel\Mcp\Server\ServerContext;
 use Laravel\Mcp\Server\Testing\PendingTestResponse;
 use Laravel\Mcp\Server\Testing\TestResponse;
@@ -76,6 +78,11 @@ abstract class Server
      */
     protected array $resources = [];
 
+    /**
+     * @var array<int, ResourceTemplate|class-string<ResourceTemplate>>
+     */
+    protected array $resourceTemplates = [];
+
     /**
      * @var array<int, Prompt|class-string<Prompt>>
      */
@@ -92,6 +99,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,
@@ -219,6 +227,7 @@ public function createContext(): ServerContext
             defaultPaginationLength: $this->defaultPaginationLength,
             tools: $this->tools,
             resources: $this->resources,
+            resourceTemplates: $this->resourceTemplates,
             prompts: $this->prompts,
         );
     }

src/Server/Content/Blob.php

@@ -8,6 +8,7 @@
 use Laravel\Mcp\Server\Contracts\Content;
 use Laravel\Mcp\Server\Prompt;
 use Laravel\Mcp\Server\Resource;
+use Laravel\Mcp\Server\ResourceTemplate;
 use Laravel\Mcp\Server\Tool;
 
 class Blob implements Content
@@ -40,11 +41,11 @@ public function toPrompt(Prompt $prompt): array
     /**
      * @return array<string, mixed>
      */
-    public function toResource(Resource $resource): array
+    public function toResource(Resource|ResourceTemplate $resource): array
     {
         return [
             'blob' => base64_encode($this->content),
-            'uri' => $resource->uri(),
+            'uri' => $resource instanceof ResourceTemplate ? $resource->uriTemplate() : $resource->uri(),
             'name' => $resource->name(),
             'title' => $resource->title(),
             'mimeType' => $resource->mimeType(),

src/Server/Content/Notification.php

@@ -7,6 +7,7 @@
 use Laravel\Mcp\Server\Contracts\Content;
 use Laravel\Mcp\Server\Prompt;
 use Laravel\Mcp\Server\Resource;
+use Laravel\Mcp\Server\ResourceTemplate;
 use Laravel\Mcp\Server\Tool;
 
 class Notification implements Content
@@ -38,7 +39,7 @@ public function toPrompt(Prompt $prompt): array
     /**
      * @return array<string, mixed>
      */
-    public function toResource(Resource $resource): array
+    public function toResource(Resource|ResourceTemplate $resource): array
     {
         return $this->toArray();
     }

src/Server/Content/Text.php

@@ -7,6 +7,7 @@
 use Laravel\Mcp\Server\Contracts\Content;
 use Laravel\Mcp\Server\Prompt;
 use Laravel\Mcp\Server\Resource;
+use Laravel\Mcp\Server\ResourceTemplate;
 use Laravel\Mcp\Server\Tool;
 
 class Text implements Content
@@ -35,11 +36,11 @@ public function toPrompt(Prompt $prompt): array
     /**
      * @return array<string, mixed>
      */
-    public function toResource(Resource $resource): array
+    public function toResource(Resource|ResourceTemplate $resource): array
     {
         return [
             'text' => $this->text,
-            'uri' => $resource->uri(),
+            'uri' => $resource instanceof ResourceTemplate ? $resource->uriTemplate() : $resource->uri(),
             'name' => $resource->name(),
             'title' => $resource->title(),
             'mimeType' => $resource->mimeType(),

src/Server/Contracts/Content.php

@@ -7,6 +7,7 @@
 use Illuminate\Contracts\Support\Arrayable;
 use Laravel\Mcp\Server\Prompt;
 use Laravel\Mcp\Server\Resource;
+use Laravel\Mcp\Server\ResourceTemplate;
 use Laravel\Mcp\Server\Tool;
 use Stringable;
 
@@ -28,7 +29,7 @@ public function toPrompt(Prompt $prompt): array;
     /**
      * @return array<string, mixed>
      */
-    public function toResource(Resource $resource): array;
+    public function toResource(Resource|ResourceTemplate $resource): array;
 
     public function __toString(): string;
 }

src/Server/McpServiceProvider.php

@@ -9,6 +9,7 @@
 use Laravel\Mcp\Console\Commands\InspectorCommand;
 use Laravel\Mcp\Console\Commands\MakePromptCommand;
 use Laravel\Mcp\Console\Commands\MakeResourceCommand;
+use Laravel\Mcp\Console\Commands\MakeResourceTemplateCommand;
 use Laravel\Mcp\Console\Commands\MakeServerCommand;
 use Laravel\Mcp\Console\Commands\MakeToolCommand;
 use Laravel\Mcp\Console\Commands\StartCommand;
@@ -45,6 +46,7 @@ protected function registerPublishing(): void
         $this->publishes([
             __DIR__.'/../../stubs/prompt.stub' => base_path('stubs/prompt.stub'),
             __DIR__.'/../../stubs/resource.stub' => base_path('stubs/resource.stub'),
+            __DIR__.'/../../stubs/resource-template.stub' => base_path('stubs/resource-template.stub'),
             __DIR__.'/../../stubs/server.stub' => base_path('stubs/server.stub'),
             __DIR__.'/../../stubs/tool.stub' => base_path('stubs/tool.stub'),
         ], 'mcp-stubs');
@@ -86,6 +88,7 @@ protected function registerCommands(): void
             MakeToolCommand::class,
             MakePromptCommand::class,
             MakeResourceCommand::class,
+            MakeResourceTemplateCommand::class,
             InspectorCommand::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,12 +8,15 @@
 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\ResourceTemplate;
 use Laravel\Mcp\Server\ServerContext;
+use Laravel\Mcp\Server\Support\UriTemplateMatcher;
 use Laravel\Mcp\Server\Transport\JsonRpcRequest;
 use Laravel\Mcp\Server\Transport\JsonRpcResponse;
 use Laravel\Mcp\Support\ValidationMessages;
@@ -37,14 +40,33 @@ public function handle(JsonRpcRequest $request, ServerContext $context): Generat
             );
         }
 
+        $uri = $request->get('uri');
+
         $resource = $context->resources()
-            ->first(
-                fn (Resource $resource): bool => $resource->uri() === $request->get('uri'),
-                fn () => throw new JsonRpcException(
-                    "Resource [{$request->get('uri')}] not found.",
-                    -32002,
-                    $request->id,
-                ));
+            ->first(fn (Resource $resource): bool => $resource->uri() === $uri);
+
+        if (! $resource) {
+            $resource = $context->resourceTemplates()
+                ->first(fn (ResourceTemplate $template): bool => UriTemplateMatcher::matches($template->uriTemplate(), $uri));
+
+            if ($resource instanceof ResourceTemplate) {
+                $variables = UriTemplateMatcher::extract($resource->uriTemplate(), $uri);
+
+                Container::getInstance()->afterResolving(Request::class, function (Request $mcpRequest) use ($variables): void {
+                    foreach ($variables as $key => $value) {
+                        $mcpRequest->merge([$key => $value]);
+                    }
+                });
+            }
+        }
+
+        if (! $resource) {
+            throw new JsonRpcException(
+                "Resource [{$uri}] not found.",
+                -32002,
+                $request->id,
+            );
+        }
 
         try {
             // @phpstan-ignore-next-line
@@ -54,14 +76,20 @@ public function handle(JsonRpcRequest $request, ServerContext $context): Generat
         }
 
         return is_iterable($response)
-            ? $this->toJsonRpcStreamedResponse($request, $response, $this->serializable($resource))
-            : $this->toJsonRpcResponse($request, $response, $this->serializable($resource));
+            ? $this->toJsonRpcStreamedResponse($request, $response, $this->serializable($resource, $uri))
+            : $this->toJsonRpcResponse($request, $response, $this->serializable($resource, $uri));
     }
 
-    protected function serializable(Resource $resource): callable
+    protected function serializable(Resource|ResourceTemplate $resource, string $requestedUri): callable
     {
         return fn (Collection $responses): array => [
-            'contents' => $responses->map(fn (Response $response): array => $response->content()->toResource($resource))->all(),
+            'contents' => $responses->map(function (Response $response) use ($resource, $requestedUri): array {
+                $content = $response->content()->toResource($resource);
+
+                $content['uri'] = $requestedUri;
+
+                return $content;
+            })->all(),
         ];
     }
 }

src/Server/ResourceTemplate.php

@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Laravel\Mcp\Server;
+
+use Illuminate\Support\Str;
+
+abstract class ResourceTemplate extends Primitive
+{
+    protected string $uriTemplate = '';
+
+    protected string $mimeType = '';
+
+    public function uriTemplate(): string
+    {
+        return $this->uriTemplate !== ''
+            ? $this->uriTemplate
+            : 'file://resources/'.Str::kebab(class_basename($this)).'/{id}';
+    }
+
+    public function mimeType(): string
+    {
+        return $this->mimeType !== ''
+            ? $this->mimeType
+            : 'text/plain';
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function toMethodCall(): array
+    {
+        return ['uriTemplate' => $this->uriTemplate()];
+    }
+
+    public function toArray(): array
+    {
+        return [
+            'name' => $this->name(),
+            'title' => $this->title(),
+            'description' => $this->description(),
+            'uriTemplate' => $this->uriTemplate(),
+            'mimeType' => $this->mimeType(),
+        ];
+    }
+}