add support for package: uris

Author: jakemac53

.github/workflows/dart_mcp_server.yaml

@@ -28,7 +28,7 @@ jobs:
       fail-fast: false
       matrix:
         flutterSdk:
-          - beta
+          # - beta
           - master
         os:
           - ubuntu-latest

pkgs/dart_mcp_server/lib/src/mixins/analyzer.dart

@@ -11,10 +11,13 @@ import 'package:dart_mcp/server.dart';
 import 'package:json_rpc_2/json_rpc_2.dart';
 import 'package:language_server_protocol/protocol_generated.dart' as lsp;
 import 'package:meta/meta.dart';
+import 'package:package_config/package_config.dart';
 
 import '../lsp/wire_format.dart';
 import '../utils/analytics.dart';
+import '../utils/cli_utils.dart';
 import '../utils/constants.dart';
+import '../utils/file_system.dart';
 import '../utils/sdk.dart';
 
 /// Mix this in to any MCPServer to add support for analyzing Dart projects.
@@ -23,7 +26,7 @@ import '../utils/sdk.dart';
 /// mixins applied.
 base mixin DartAnalyzerSupport
     on ToolsSupport, LoggingSupport, RootsTrackingSupport
-    implements SdkSupport {
+    implements FileSystemSupport, SdkSupport {
   /// The LSP server connection for the analysis server.
   Peer? _lspConnection;
 
@@ -325,10 +328,42 @@ base mixin DartAnalyzerSupport
   /// Implementation of the [readSummaryTool], gets summary information for a
   /// given library.
   Future<CallToolResult> _readSummary(CallToolRequest request) async {
-    final errorResult = await _ensurePrerequisites(request);
+    if (await _ensurePrerequisites(request) case final errorResult?) {
+      return errorResult;
+    }
+
+    final uriString = request.arguments![ParameterNames.uri] as String;
+    Uri? uri = Uri.parse(uriString);
+    final (
+      root: Root? root,
+      // We do our own path handling because we have to handle package URIs
+      // after getting a root.
+      paths: _,
+      errorResult: CallToolResult? errorResult,
+    ) = validateRootConfig(
+      request.arguments,
+      fileSystem: fileSystem,
+      knownRoots: await roots,
+      // Validates that the non-package: uris are valid under the provided root.
+      defaultPaths: [if (uri.scheme != 'package') uriString],
+    );
     if (errorResult != null) return errorResult;
 
-    final uri = Uri.parse(request.arguments![ParameterNames.uri] as String);
+    // This normalizes the URI to ensure it is treated as a directory (for
+    // example ensures it ends with a trailing slash).
+    final rootDir = fileSystem.directory(Uri.parse(root!.uri));
+
+    // Resolve package URIs using the package config.
+    if (uri.scheme == 'package') {
+      final packageConfig = await findPackageConfig(rootDir);
+      if (packageConfig == null) return noPackageConfig(root);
+
+      uri = packageConfig.resolve(uri);
+      if (uri == null) return unableToResolveUri(uriString);
+    } else if (uri.scheme == '' && !uri.isAbsolute) {
+      uri = rootDir.uri.resolve('$uri');
+    }
+
     final result =
         (await _lspConnection!.sendRequest(
               'dart/textDocument/summary',
@@ -486,20 +521,30 @@ base mixin DartAnalyzerSupport
   static final readSummaryTool = Tool(
     name: 'read_summary',
     description:
-        'Gets a summary of a given dart library by URI. This should be '
-        'preferred over reading files when the only goal is to understand '
-        'how to use a given library. Supports `package:` URIs and `file:` '
-        'URIs. The library must be available to one of the currently active '
-        'projects.',
+        'Read a summary of a given Dart library by URI. It is absolutely '
+        'critical that you read the summary of any library before using it to '
+        'ensure you know the correct API - failure to do so may result in '
+        'catastrophe. A project root is required in order to use this tool, '
+        'because `package:` URIs are specific to a given root. \n\n'
+        'Note that summary files omit implementation details for brevity, but '
+        'you must assume real implementations exist unless explicitly told '
+        'otherwise. DO NOT provide your own implementation. Failure to follow '
+        'this instruction will have dire consequences.',
     inputSchema: Schema.object(
       properties: {
+        ParameterNames.root: rootSchema,
         ParameterNames.uri: Schema.string(
           description:
-              'The URI of the library, either a `package:` or `file:` URI.',
+              'The URI of the library, either a `package:` or `file:` URI. '
+              'All `file:` URIs must resolve to a path under the given root.',
         ),
       },
+      required: [ParameterNames.root, ParameterNames.uri],
+    ),
+    annotations: ToolAnnotations(
+      title: 'Dart library summary',
+      readOnlyHint: true,
     ),
-    annotations: ToolAnnotations(title: 'Dart summary', readOnlyHint: true),
   );
 
   @visibleForTesting
@@ -513,6 +558,30 @@ base mixin DartAnalyzerSupport
       ),
     ],
   )..failureReason = CallToolFailureReason.noRootsSet;
+
+  @visibleForTesting
+  static CallToolResult noPackageConfig(Root root) => CallToolResult(
+    isError: true,
+    content: [
+      TextContent(
+        text:
+            'Unable to find a package config for root ${root.uri}. Please '
+            'make sure you have ran `flutter pub get` or `dart pub get`.',
+      ),
+    ],
+  );
+
+  @visibleForTesting
+  static CallToolResult unableToResolveUri(String uri) => CallToolResult(
+    isError: true,
+    content: [
+      TextContent(
+        text:
+            'Unable to resolve URI $uri. Have you added that package as a '
+            'dependency?',
+      ),
+    ],
+  );
 }
 
 /// Common schema for tools that require a file URI, line, and column.

pkgs/dart_mcp_server/lib/src/utils/cli_utils.dart

@@ -153,71 +153,24 @@ Future<CallToolResult> runCommandInRoot(
   required Sdk sdk,
 }) async {
   rootConfig ??= request.arguments;
-  final rootUriString = rootConfig?[ParameterNames.root] as String?;
-  if (rootUriString == null) {
-    // This shouldn't happen based on the schema, but handle defensively.
-    return CallToolResult(
-      content: [
-        TextContent(text: 'Invalid root configuration: missing `root` key.'),
-      ],
-      isError: true,
-    )..failureReason ??= CallToolFailureReason.noRootGiven;
-  }
-
-  final root = knownRoots.firstWhereOrNull(
-    (root) => _isUnderRoot(root, rootUriString, fileSystem),
+  final (
+    root: Root? root,
+    paths: List<String>? paths,
+    errorResult: CallToolResult? errorResult,
+  ) = validateRootConfig(
+    rootConfig,
+    defaultPaths: defaultPaths,
+    fileSystem: fileSystem,
+    knownRoots: knownRoots,
   );
-  if (root == null) {
-    return CallToolResult(
-      content: [
-        TextContent(
-          text:
-              'Invalid root $rootUriString, must be under one of the '
-              'registered project roots:\n\n${knownRoots.join('\n')}',
-        ),
-      ],
-      isError: true,
-    )..failureReason ??= CallToolFailureReason.invalidRootPath;
-  }
-
-  final rootUri = Uri.parse(rootUriString);
-  if (rootUri.scheme != 'file') {
-    return CallToolResult(
-      content: [
-        TextContent(
-          text:
-              'Only file scheme uris are allowed for roots, but got '
-              '$rootUri',
-        ),
-      ],
-      isError: true,
-    )..failureReason ??= CallToolFailureReason.invalidRootScheme;
-  }
-  final projectRoot = fileSystem.directory(rootUri);
+  if (errorResult != null) return errorResult;
 
+  final projectRoot = Uri.parse(root!.uri);
   final commandWithPaths = <String>[
-    await commandForRoot(rootUriString, fileSystem, sdk),
+    await commandForRoot(root.uri, fileSystem, sdk),
     ...arguments,
   ];
-  final paths =
-      (rootConfig?[ParameterNames.paths] as List?)?.cast<String>() ??
-      defaultPaths;
-  final invalidPaths = paths.where(
-    (path) => !_isUnderRoot(root, path, fileSystem),
-  );
-  if (invalidPaths.isNotEmpty) {
-    return CallToolResult(
-      content: [
-        TextContent(
-          text:
-              'Paths are not allowed to escape their project root:\n'
-              '${invalidPaths.join('\n')}',
-        ),
-      ],
-      isError: true,
-    )..failureReason ??= CallToolFailureReason.invalidPath;
-  }
-  commandWithPaths.addAll(paths);
+  if (paths != null) commandWithPaths.addAll(paths);
 
   final workingDir = fileSystem.directory(projectRoot.path);
   await workingDir.create(recursive: true);
@@ -252,6 +205,106 @@ Future<CallToolResult> runCommandInRoot(
   );
 }
 
+/// Validates a root argument given via [rootConfig], ensuring that it falls
+/// under one of the [knownRoots], and that all `paths` arguments are also under
+/// the given root.
+///
+/// Returns a root on success, equal to the given root (but this could be a
+/// subdirectory of one of the [knownRoots]), as well as any paths that were
+/// validated.
+///
+/// If no [ParameterNames.paths] are provided, then the [defaultPaths] will be
+/// used, if present. Otherwise no paths are validated or will be returned.
+///
+/// On failure, returns a [CallToolResult].
+({Root? root, List<String>? paths, CallToolResult? errorResult})
+validateRootConfig(
+  Map<String, Object?>? rootConfig, {
+  List<String>? defaultPaths,
+  required FileSystem fileSystem,
+  required List<Root> knownRoots,
+}) {
+  final rootUriString = rootConfig?[ParameterNames.root] as String?;
+  if (rootUriString == null) {
+    // This shouldn't happen based on the schema, but handle defensively.
+    return (
+      root: null,
+      paths: null,
+      errorResult: CallToolResult(
+        content: [
+          TextContent(text: 'Invalid root configuration: missing `root` key.'),
+        ],
+        isError: true,
+      )..failureReason ??= CallToolFailureReason.noRootGiven,
+    );
+  }
+
+  final knownRoot = knownRoots.firstWhereOrNull(
+    (root) => _isUnderRoot(root, rootUriString, fileSystem),
+  );
+  if (knownRoot == null) {
+    return (
+      root: null,
+      paths: null,
+      errorResult: CallToolResult(
+        content: [
+          TextContent(
+            text:
+                'Invalid root $rootUriString, must be under one of the '
+                'registered project roots:\n\n${knownRoots.join('\n')}',
+          ),
+        ],
+        isError: true,
+      )..failureReason ??= CallToolFailureReason.invalidRootPath,
+    );
+  }
+  final root = Root(uri: rootUriString);
+
+  final rootUri = Uri.parse(rootUriString);
+  if (rootUri.scheme != 'file') {
+    return (
+      root: null,
+      paths: null,
+      errorResult: CallToolResult(
+        content: [
+          TextContent(
+            text:
+                'Only file scheme uris are allowed for roots, but got '
+                '$rootUri',
+          ),
+        ],
+        isError: true,
+      )..failureReason ??= CallToolFailureReason.invalidRootScheme,
+    );
+  }
+
+  final paths =
+      (rootConfig?[ParameterNames.paths] as List?)?.cast<String>() ??
+      defaultPaths;
+  if (paths != null) {
+    final invalidPaths = paths.where(
+      (path) => !_isUnderRoot(root, path, fileSystem),
+    );
+    if (invalidPaths.isNotEmpty) {
+      return (
+        root: null,
+        paths: null,
+        errorResult: CallToolResult(
+          content: [
+            TextContent(
+              text:
+                  'Paths are not allowed to escape their project root:\n'
+                  '${invalidPaths.join('\n')}',
+            ),
+          ],
+          isError: true,
+        )..failureReason ??= CallToolFailureReason.invalidPath,
+      );
+    }
+  }
+  return (root: root, paths: paths, errorResult: null);
+}
+
 /// Returns 'dart' or 'flutter' based on the pubspec contents.
 ///
 /// Throws an [ArgumentError] if there is no pubspec.
@@ -316,7 +369,8 @@ final rootSchema = Schema.string(
   description:
       'This must be equal to or a subdirectory of one of the roots '
       'allowed by the client. Must be a URI with a `file:` '
-      'scheme (e.g. file:///absolute/path/to/root).',
+      'scheme (e.g. file:///absolute/path/to/root). Dart and Flutter project '
+      'roots can be identified by the existence of a `pubspec.yaml` file.',
 );
 
 /// Very thin extension type for a pubspec just containing what we need.

pkgs/dart_mcp_server/pubspec.yaml

@@ -4,7 +4,7 @@ description: >-
   models.
 publish_to: none
 environment:
-  sdk: ^3.9.0-163.0.dev
+  sdk: ^3.10.0-18.0.dev
 
 executables:
   dart_mcp_server: main
@@ -27,8 +27,9 @@ dependencies:
       path: third_party/pkg/language_server_protocol
       # When changing this, also update .github/workflows/dart_mcp_server.yaml
       # to cache the correct directory.
-      ref: b0838eac58308fc4e6654ca99eda75b30649c08f
+      ref: 82a01bb69cbee93663f3891d481c96f0ada4437c
   meta: ^1.16.0
+  package_config: ^2.2.0
   path: ^1.9.1
   pool: ^1.5.1
   process: ^5.0.3