Add resource template support (#68)

See https://modelcontextprotocol.io/specification/2024-11-05/server/resources#resource-templates

The support is pretty low level right now, and we do not provide any assistance for matching the provided templates or extracting out the values.

We likely should add that support at some point later on, but we should be able to do so in a non-breaking manner. We will simply stop invoking the `handlers` for URIs that can't possibly match the template.

Author: jakemac53

pkgs/dart_mcp/CHANGELOG.md

@@ -2,6 +2,7 @@
 
 - Save the `ServerCapabilities` object on the `ServerConnection` class to make
   it easier to check the capabilities of the server.
+- Added support for adding and listing `ResourceTemplate`s.
 
 ## 0.1.0
 

pkgs/dart_mcp/lib/src/client/client.dart

@@ -257,14 +257,20 @@ base class ServerConnection extends MCPBase {
   Future<CallToolResult> callTool(CallToolRequest request) =>
       sendRequest(CallToolRequest.methodName, request);
 
-  /// Lists all the resources from this server.
+  /// Lists all the [Resource]s from this server.
   Future<ListResourcesResult> listResources(ListResourcesRequest request) =>
       sendRequest(ListResourcesRequest.methodName, request);
 
-  /// Reads a [Resource] returned from the [ListResourcesResult].
+  /// Reads a [Resource] returned from the [ListResourcesResult] or matching
+  /// a [ResourceTemplate] from a [ListResourceTemplatesResult].
   Future<ReadResourceResult> readResource(ReadResourceRequest request) =>
       sendRequest(ReadResourceRequest.methodName, request);
 
+  /// Lists all the [ResourceTemplate]s from this server.
+  Future<ListResourceTemplatesResult> listResourceTemplates(
+    ListResourceTemplatesRequest request,
+  ) => sendRequest(ListResourceTemplatesRequest.methodName, request);
+
   /// Lists all the prompts from this server.
   Future<ListPromptsResult> listPrompts(ListPromptsRequest request) =>
       sendRequest(ListPromptsRequest.methodName, request);

pkgs/dart_mcp/lib/src/server/resources_support.dart

@@ -4,26 +4,38 @@
 
 part of 'server.dart';
 
+typedef ReadResourceHandler =
+    FutureOr<ReadResourceResult?> Function(ReadResourceRequest);
+
 /// A mixin for MCP servers which support the `resources` capability.
 ///
-/// Servers should add resources using the [addResource] method, typically
-/// inside the [initialize] method, but they may also be added after
-/// initialization if needed.
+/// Servers should add [Resource]s using the [addResource] method, typically
+/// inside the [initialize] method or constructor, but they may also be added
+/// after initialization if needed.
 ///
 /// Resources can later be removed using [removeResource], or the client can be
 /// notified of updates using [updateResource].
 ///
 /// Implements the `subscribe` and `listChanges` capabilities for clients, so
 /// they can be notified of changes to resources.
 ///
+/// Any [ResourceTemplate]s, should typically be added in [initialize] method or
+/// the constructor using [addResourceTemplate]. There is no notification
+/// protocol for templates which are added after a client requests them once, so
+/// they should be added eagerly.
+///
 /// See https://modelcontextprotocol.io/docs/concepts/resources.
 base mixin ResourcesSupport on MCPServer {
   /// The current resources by URI.
   final Map<String, Resource> _resources = {};
 
   /// The current resource implementations by URI.
-  final Map<String, FutureOr<ReadResourceResult> Function(ReadResourceRequest)>
-  _resourceImpls = {};
+  final Map<String, ReadResourceHandler> _resourceImpls = {};
+
+  /// All the resource templates supported by this server, see
+  /// [addResourceTemplate].
+  final List<({ResourceTemplate template, ReadResourceHandler handler})>
+  _resourceTemplates = [];
 
   /// The list of currently subscribed resources by URI.
   final Set<String> _subscribedResources = {};
@@ -39,6 +51,10 @@ base mixin ResourcesSupport on MCPServer {
   @override
   FutureOr<InitializeResult> initialize(InitializeRequest request) async {
     registerRequestHandler(ListResourcesRequest.methodName, _listResources);
+    registerRequestHandler(
+      ListResourceTemplatesRequest.methodName,
+      _listResourceTemplates,
+    );
 
     registerRequestHandler(ReadResourceRequest.methodName, _readResource);
 
@@ -57,7 +73,7 @@ base mixin ResourcesSupport on MCPServer {
   /// If this server is already initialized and still connected to a client,
   /// then the client will be notified that the resources list has changed.
   ///
-  /// Throws a [StateError] if there is already a [Tool] registered with the
+  /// Throws a [StateError] if there is already a [Resource] registered with the
   /// same name.
   void addResource(
     Resource resource,
@@ -77,6 +93,43 @@ base mixin ResourcesSupport on MCPServer {
     }
   }
 
+  /// Adds the [ResourceTemplate] [template] with [handler].
+  ///
+  /// When reading resources, first regular resources added by [addResource]
+  /// are prioritized. Then, we call the [handler] for each [template], in the
+  /// order they were added (using this method), and the first one to return a
+  /// non-null response wins. This package does not automatically handle
+  /// matching of templates and handlers must accept URIs in any form.
+  ///
+  /// Throws a [StateError] if there is already a template registered with the
+  /// same uri template.
+  void addResourceTemplate(
+    ResourceTemplate template,
+    ReadResourceHandler handler,
+  ) {
+    if (_resourceTemplates.any(
+      (t) => t.template.uriTemplate == template.uriTemplate,
+    )) {
+      throw StateError(
+        'Failed to add resource template ${template.name}, there is '
+        'already a resource template with the same uri pattern '
+        '${template.uriTemplate}.',
+      );
+    }
+    _resourceTemplates.add((template: template, handler: handler));
+  }
+
+  /// Lists all the [ResourceTemplate]s currently available.
+  ListResourceTemplatesResult _listResourceTemplates(
+    ListResourceTemplatesRequest request,
+  ) {
+    return ListResourceTemplatesResult(
+      resourceTemplates: [
+        for (var descriptor in _resourceTemplates) descriptor.template,
+      ],
+    );
+  }
+
   /// Notifies the client that [resource] has been updated.
   ///
   /// The implementation of that resource can optionally be updated, otherwise
@@ -121,13 +174,23 @@ base mixin ResourcesSupport on MCPServer {
   ///
   /// Throws an [ArgumentError] if it does not exist (this gets translated into
   /// a generic JSON RPC2 error response).
-  FutureOr<ReadResourceResult> _readResource(ReadResourceRequest request) {
+  FutureOr<ReadResourceResult> _readResource(
+    ReadResourceRequest request,
+  ) async {
     final impl = _resourceImpls[request.uri];
     if (impl == null) {
-      throw ArgumentError.value(request.uri, 'uri', 'Resource not found');
+      // Check if it matches any resource template.
+      for (var descriptor in _resourceTemplates) {
+        final response = await descriptor.handler(request);
+        if (response != null) return response;
+      }
     }
 
-    return impl(request);
+    final response = await impl?.call(request);
+    if (response == null) {
+      throw ArgumentError.value(request.uri, 'uri', 'Resource not found');
+    }
+    return response;
   }
 
   /// Subscribes the client to the resource at `request.uri`.

pkgs/dart_mcp/test/resources_support_test.dart

@@ -3,6 +3,8 @@
 // BSD-style license that can be found in the LICENSE file.
 
 import 'dart:async';
+import 'dart:io';
+import 'dart:isolate';
 
 import 'package:async/async.dart';
 import 'package:dart_mcp/server.dart';
@@ -133,6 +135,35 @@ void main() {
     /// complete.
     await environment.shutdown();
   });
+
+  test('Resource templates can be listed and queried', () async {
+    final environment = TestEnvironment(
+      TestMCPClient(),
+      (c) => TestMCPServerWithResources(channel: c),
+    );
+    await environment.initializeServer();
+
+    final serverConnection = environment.serverConnection;
+
+    final templatesResponse = await serverConnection.listResourceTemplates(
+      ListResourceTemplatesRequest(),
+    );
+
+    expect(
+      templatesResponse.resourceTemplates.single,
+      TestMCPServerWithResources.packageUriTemplate,
+    );
+
+    final readResourceResponse = await serverConnection.readResource(
+      ReadResourceRequest(uri: 'package:test/test.dart'),
+    );
+    expect(
+      (readResourceResponse.contents.single as TextResourceContents).text,
+      await File.fromUri(
+        (await Isolate.resolvePackageUri(Uri.parse('package:test/test.dart')))!,
+      ).readAsString(),
+    );
+  });
 }
 
 final class TestMCPServerWithResources extends TestMCPServer
@@ -149,8 +180,34 @@ final class TestMCPServerWithResources extends TestMCPServer
         ],
       ),
     );
+    addResourceTemplate(packageUriTemplate, _readPackageResource);
     return super.initialize(request);
   }
 
+  Future<ReadResourceResult?> _readPackageResource(
+    ReadResourceRequest request,
+  ) async {
+    if (!request.uri.startsWith('package:')) return null;
+    if (!request.uri.endsWith('.dart')) {
+      throw UnsupportedError('Only dart files can be read');
+    }
+    final resolvedUri =
+        (await Isolate.resolvePackageUri(Uri.parse(request.uri)))!;
+
+    return ReadResourceResult(
+      contents: [
+        TextResourceContents(
+          uri: request.uri,
+          text: await File.fromUri(resolvedUri).readAsString(),
+        ),
+      ],
+    );
+  }
+
   static final helloWorld = Resource(name: 'hello world', uri: 'hello://world');
+
+  static final packageUriTemplate = ResourceTemplate(
+    uriTemplate: 'package:{package}/{library}',
+    name: 'Dart package resource',
+  );
 }