A 'pub-dev-search' mcp tool

pkgs/dart_tooling_mcp_server/README.md

@@ -15,6 +15,7 @@ WIP. This package is still experimental and is likely to evolve quickly.
 | `dart_fix` | `static tool` | Runs `dart fix --apply` for the given project roots. |
 | `dart_format` | `static tool` | Runs `dart format .` for the given project roots. |
 | `pub` | `static tool` | Runs a `dart pub` command for the given project roots. |
+| `pub_dev_search` | `package search` | Searches pub.dev for packages relevant to a given search query. |
 | `get_runtime_errors` | `runtime analysis` | Retrieves the list of runtime errors that have occurred in the active Dart or Flutter application. |
 | `take_screenshot` | `runtime analysis` | Takes a screenshot of the active Flutter application in its current state. |
 | `get_widget_tree` | `runtime analysis` | Retrieves the widget tree from the active Flutter application. |

pkgs/dart_tooling_mcp_server/lib/src/mixins/pub_dev_search.dart

@@ -0,0 +1,211 @@
+// Copyright (c) 2025, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'dart:async';
+import 'dart:convert';
+
+import 'package:dart_mcp/server.dart';
+import 'package:http/http.dart';
+import 'package:pool/pool.dart';
+
+import '../utils/json.dart';
+
+/// Limit the number of concurrent requests.
+final _pool = Pool(10);
+
+/// The number of reults to return for a query.
+// If this should be set higher than 10 we need to implement paging of the
+// http://pub.dev/api/search endpoint.
+final _resultsLimit = 10;
+
+/// The number of identifiers we list per packages.
+final _maxIdentifiersListed = 200;
+
+/// Mix this in to any MCPServer to add support for doing searches on pub.dev.
+base mixin PubDevSupport on ToolsSupport {
+  final _client = Client();
+
+  @override
+  FutureOr<InitializeResult> initialize(InitializeRequest request) {
+    registerTool(pubDevTool, _runPubDevSearch);
+    return super.initialize(request);
+  }
+
+  /// Implementation of the [pubDevTool].
+  Future<CallToolResult> _runPubDevSearch(CallToolRequest request) async {
+    final query = request.arguments?['query'] as String?;
+    if (query == null) {
+      return CallToolResult(
+        content: [TextContent(text: 'Missing required argument `query`.')],
+        isError: true,
+      );
+    }
+    final searchUrl = Uri.https('pub.dev', 'api/search', {'q': query});
+    final Object? result;
+    try {
+      result = jsonDecode(await _client.read(searchUrl));
+
+      final packageNames =
+          dig<List>(result, ['packages'])
+              .take(_resultsLimit)
+              .map((p) => dig<String>(p, ['package']))
+              .toList();
+
+      if (packageNames.isEmpty) {
+        return CallToolResult(
+          content: [
+            TextContent(
+              text: 'No packages mached the query, consider simplifying it.',
+            ),
+          ],
+          isError: true,
+        );
+      }
+
+      Future<Object?> retrieve(String path) {
+        return _pool.withResource(() async {
+          try {
+            return jsonDecode(await _client.read(Uri.https('pub.dev', path)));
+          } on ClientException {
+            return null;
+          }
+        });
+      }
+
+      // Retrieve information about all the packages in parallel.
+      final subQueryFutures =
+          packageNames
+              .map(
+                (packageName) => (
+                  versionListing: retrieve('api/packages/$packageName'),
+                  score: retrieve('api/packages/$packageName/score'),
+                  docIndex: retrieve(
+                    'documentation/$packageName/latest/index.json',
+                  ),
+                ),
+              )
+              .toList();
+
+      // Aggregate the retrieved information about each package into a
+      // TextContent.
+      final results = <TextContent>[];
+      for (var i = 0; i < packageNames.length; i++) {
+        final packageName = packageNames[i];
+        final versionListing = await subQueryFutures[i].versionListing;
+        final scoreResult = await subQueryFutures[i].score;
+        final docIndex = await subQueryFutures[i].docIndex;
+
+        Map<String, Object?> identifiers(Object index) {
+          final items = dig<List>(index, []);
+          return {
+            'qualifiedNames': [
+              for (final item in items.take(_maxIdentifiersListed))
+                dig<String>(item, ['qualifiedName']),
+            ],
+          };
+        }
+
+        results.add(
+          TextContent(
+            text: jsonEncode({
+              'packageName': packageName,
+              if (versionListing != null) ...{
+                'latestVersion': dig<String>(versionListing, [
+                  'latest',
+                  'version',
+                ]),
+                'description': dig<String>(versionListing, [
+                  'latest',
+                  'pubspec',
+                  'description',
+                ]),
+              },
+              if (scoreResult != null) ...{
+                'scores': {
+                  'pubPoints': dig<int>(scoreResult, ['grantedPoints']),
+                  'maxPubPoints': dig<int>(scoreResult, ['maxPoints']),
+                  'likes': dig<int>(scoreResult, ['likeCount']),
+                  'downloadCount': dig<int>(scoreResult, [
+                    'downloadCount30Days',
+                  ]),
+                },
+                'topics':
+                    dig<List>(
+                      scoreResult,
+                      ['tags'],
+                    ).where((t) => (t as String).startsWith('topic:')).toList(),
+                'licenses':
+                    dig<List>(scoreResult, ['tags'])
+                        .where((t) => (t as String).startsWith('license'))
+                        .toList(),
+                'publisher':
+                    dig<List>(scoreResult, ['tags'])
+                        .where((t) => (t as String).startsWith('publisher:'))
+                        .firstOrNull,
+              },
+              if (docIndex != null) ...{'api': identifiers(docIndex)},
+            }),
+          ),
+        );
+      }
+
+      return CallToolResult(content: results);
+    } on Exception catch (e) {
+      return CallToolResult(
+        content: [TextContent(text: 'Failed searching pub.dev: $e')],
+        isError: true,
+      );
+    }
+  }
+
+  static final pubDevTool = Tool(
+    name: 'pub_dev_search',
+    description:
+        'Searches pub.dev for packages relevant to a given search query. '
+        'The response will describe each result with its download count, '
+        'package description, topics, license, publisher, and a list of '
+        'identifiers in the public api.',
+    annotations: ToolAnnotations(title: 'pub.dev search', readOnlyHint: true),
+    inputSchema: Schema.object(
+      properties: {
+        'query': Schema.string(
+          title: 'Search query',
+          description: '''
+The query to run against pub.dev package search.
+
+Besides freeform keyword search `pub.dev` supports the following search query
+expressions:
+
+  - `"exact phrase"`: By default, when you perform a search, the results include
+    packages with similar phrases. When a phrase is inside quotes, you'll see
+    only those packages that contain exactly the specified phrase.
+
+  - `dependency:<package_name>`: Searches for packages that reference
+    `package_name` in their `pubspec.yaml`.
+
+  - `dependency*:<package_name>`: Searches for packages that depend on
+    `package_name` (as direct, dev, or transitive dependencies).
+
+  - `topic:<topic-name>`: Searches for packages that have specified the
+    `topic-name` [topic](/topics).
+
+  - `publisher:<publisher-name.com>`: Searches for packages published by `publisher-name.com`
+
+  - `sdk:<sdk>`: Searches for packages that support the given SDK. `sdk` can be either `flutter` or `dart`
+
+  - `runtime:<runtime>`: Searches for packages that support the given runtime. `runtime` can be one of `web`, `native-jit` and `native-aot`.
+
+  - `updated:<duration>`: Searches for packages updated in the given past days,
+    with the following recognized formats: `3d` (3 days), `2w` (two weeks), `6m` (6 months), `2y` 2 years.
+
+  - `has:executable`: Search for packages with Dart files in their `bin/` directory.
+
+To search for alternatives do multiple searches. There is no "or" operator.
+  ''',
+        ),
+      },
+      required: ['query'],
+    ),
+  );
+}

pkgs/dart_tooling_mcp_server/lib/src/server.dart

@@ -15,6 +15,7 @@ import 'mixins/analyzer.dart';
 import 'mixins/dash_cli.dart';
 import 'mixins/dtd.dart';
 import 'mixins/pub.dart';
+import 'mixins/pub_dev_search.dart';
 import 'utils/file_system.dart';
 import 'utils/process_manager.dart';
 
@@ -28,6 +29,7 @@ final class DartToolingMCPServer extends MCPServer
         DartAnalyzerSupport,
         DashCliSupport,
         PubSupport,
+        PubDevSupport,
         DartToolingDaemonSupport
     implements ProcessManagerSupport, FileSystemSupport {
   DartToolingMCPServer(

pkgs/dart_tooling_mcp_server/lib/src/utils/json.dart

@@ -0,0 +1,111 @@
+// Copyright (c) 2025, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+/// Utility for indexing json data structures.
+///
+/// Each element of [path] should be a `String`, `int` or `(String, String)`.
+///
+/// For each element `key` of [path], recurse into [json].
+///
+/// If the `key` is a String, the next json structure should be a Map, and have
+/// `key` as a property. Recurse into that property.
+///
+/// If `key` is an `int`, the next json structure must be a List, with that
+/// index. Recurse into that index.
+///
+/// If `key` is a `(String k, String v)` the next json structure must be a List
+/// of maps, one of them having the property `k` with value `v`, recurse into
+/// that map.
+///
+/// If at some point the types don't match throw a [FormatException].
+///
+/// Returns the result as a [T].
+T dig<T>(dynamic json, List<Object> path) {
+  var i = 0;
+  String currentElementType() => switch (json) {
+    Null _ => 'null',
+    num _ => 'a number',
+    String _ => 'a string',
+    List _ => 'a list',
+    Map _ => 'a map',
+    _ => throw ArgumentError('Bad json'),
+  };
+  String currentPath() =>
+      i == 0 ? 'root' : path.sublist(0, i).map((i) => '[$i]').join('');
+  for (; i < path.length; i++) {
+    outer:
+    switch (path[i]) {
+      case final String key:
+        if (json is! Map) {
+          throw FormatException(
+            'Expected a map at ${currentPath()}. '
+            'Found ${currentElementType()}.',
+          );
+        }
+        json = json[key];
+      case final int key:
+        if (json is! List) {
+          throw FormatException(
+            'Expected a list at ${currentPath()}. '
+            'Found ${currentElementType()}.',
+          );
+        }
+        if (key >= json.length) {
+          throw FormatException(
+            'Expected at least ${key + 1} element(s) at ${currentPath()}. '
+            'Found only ${json.length} element(s)',
+          );
+        }
+        json = json[key];
+      case (final String key, final String value):
+        if (json is! List) {
+          throw FormatException(
+            'Expected a list at ${currentPath()}. '
+            'Found ${currentElementType()}.',
+          );
+        }
+        final t = json;
+        for (var j = 0; j < t.length; j++) {
+          final element = t[j];
+          if (element is! Map) {
+            json = element;
+            throw FormatException(
+              'Expected a map at ${currentPath()}[$j]. '
+              'Found ${currentElementType()}.',
+            );
+          }
+          if (element[key] == value) {
+            json = element;
+            break outer;
+          }
+        }
+        throw FormatException(
+          'No element with $key=$value at ${currentPath()}',
+        );
+      case final key:
+        throw ArgumentError('Bad key $key in', 'path');
+    }
+  }
+
+  if (json is! T) {
+    final targetTypeName = switch (T) {
+      const (int) => 'an int',
+      const (double) => 'a number',
+      const (num) => 'a number',
+      const (String) => 'a string',
+      const (List) => 'a list',
+      const (Map) => 'a map',
+      const (List<Object?>) => 'a list',
+      const (Map<String, Object?>) => 'a map',
+      const (Map<String, dynamic>) => 'a map',
+      const (Null) => 'null',
+      _ => throw ArgumentError('$T is not a json type'),
+    };
+    throw FormatException(
+      'Expected $targetTypeName at ${currentPath()}. '
+      'Found ${currentElementType()}.',
+    );
+  }
+  return json;
+}

pkgs/dart_tooling_mcp_server/pubspec.yaml

@@ -19,6 +19,7 @@ dependencies:
   devtools_shared: ^11.2.0
   dtd: ^2.4.0
   file: ^7.0.1
+  http: ^1.3.0
   json_rpc_2: ^3.0.3
   # TODO: Get this another way.
   language_server_protocol:
@@ -28,6 +29,7 @@ dependencies:
         third_party/pkg/language_server_protocol
   meta: ^1.16.0
   path: ^1.9.1
+  pool: ^1.5.1
   process: ^5.0.3
   pubspec_parse: ^1.5.0
   stream_channel: ^2.1.4