Optimize devdocs_list_docsets MCP tool for context efficiency

- Add pagination support (offset/limit) to reduce response size
- Return condensed format (slug, name, version only) instead of full metadata
- Add query parameter for filtering by slug or name (case-insensitive)
- Include pagination metadata (offset, limit, total, returned) in responses
- Add comprehensive unit tests for all new features (7 new test cases)

All 11 MCP tests passing with 45 assertions.

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

Author: joebutler2

.gitignore

@@ -15,3 +15,4 @@ docs/**/*
 *.zip
 assets/stylesheets/components/_environment.scss
 assets/stylesheets/global/_icons.scss
+.mcp.json

lib/mcp/server.rb

@@ -6,8 +6,16 @@ module Server
     TOOLS = [
       {
         'name' => 'devdocs_list_docsets',
-        'description' => 'List documentation sets available on this DevDocs instance.',
-        'inputSchema' => { 'type' => 'object', 'properties' => {}, 'additionalProperties' => false },
+        'description' => 'List documentation sets available on this DevDocs instance. Returns paginated results with optional filtering.',
+        'inputSchema' => {
+          'type' => 'object',
+          'properties' => {
+            'offset' => { 'type' => 'integer', 'description' => 'Number of results to skip (default: 0)', 'minimum' => 0 },
+            'limit' => { 'type' => 'integer', 'description' => 'Maximum results to return (default: 50, max: 500)', 'minimum' => 1, 'maximum' => 500 },
+            'query' => { 'type' => 'string', 'description' => 'Filter by slug or name (case-insensitive substring match)' },
+          },
+          'additionalProperties' => false,
+        },
       },
       {
         'name' => 'devdocs_search',
@@ -62,8 +70,8 @@ def self.call_tool(request, app_settings)
       params = request['params']
       case params['name']
       when 'devdocs_list_docsets'
-        docsets = app_settings.docs.values
-        as_text_result(request, docsets)
+        result = list_docsets(app_settings, params['arguments'] || {})
+        as_text_result(request, result)
       when 'devdocs_search'
         entries = search_docset(app_settings, params['arguments']['slug'], params['arguments']['query'])
         as_text_result(request, entries)
@@ -73,6 +81,39 @@ def self.call_tool(request, app_settings)
       end
     end
 
+    def self.list_docsets(app_settings, args)
+      offset = (args['offset'] || 0).to_i
+      limit = [(args['limit'] || 50).to_i, 500].min
+      query = args['query']&.downcase
+
+      all_docsets = app_settings.docs.values.map do |docset|
+        {
+          'slug' => docset['slug'],
+          'name' => docset['name'],
+          'version' => docset['version'],
+        }
+      end
+
+      filtered = if query
+        all_docsets.select do |docset|
+          docset['slug'].downcase.include?(query) || docset['name'].downcase.include?(query)
+        end
+      else
+        all_docsets
+      end
+
+      total_count = filtered.length
+      paginated = filtered.drop(offset).take(limit)
+
+      {
+        'docsets' => paginated,
+        'offset' => offset,
+        'limit' => limit,
+        'total' => total_count,
+        'returned' => paginated.length,
+      }
+    end
+
     def self.get_page(app_settings, slug, path)
       db_path = File.join(app_settings.docs_path, slug, 'db.json')
       db = JSON.parse(File.read(db_path))
@@ -83,8 +124,10 @@ def self.get_page(app_settings, slug, path)
     def self.search_docset(app_settings, slug, query)
       index_path = File.join(app_settings.docs_path, slug, 'index.json')
       index = JSON.parse(File.read(index_path))
-      q = query.downcase
-      index['entries'].select { |e| e['name'].downcase.include?(q) || e['path'].downcase.include?(q) }
+      query_lower = query.downcase
+      index['entries'].select do |entry|
+        entry['name'].downcase.include?(query_lower) || entry['path'].downcase.include?(query_lower)
+      end
     end
 
     def self.as_text_result(request, data)

test/mcp_test.rb

@@ -35,14 +35,96 @@ def rpc(method, params = nil, id: 1)
       assert_includes names, 'devdocs_get_page'
     end
 
-    it 'calls devdocs_list_docsets and returns the configured doc sets' do
+    it 'calls devdocs_list_docsets and returns paginated docsets in condensed format' do
       result = rpc('tools/call', { 'name' => 'devdocs_list_docsets', 'arguments' => {} })['result']
-      docsets = JSON.parse(result['content'].first['text'])
+      response = JSON.parse(result['content'].first['text'])
+
+      assert response.key?('docsets')
+      assert response.key?('offset')
+      assert response.key?('limit')
+      assert response.key?('total')
+      assert response.key?('returned')
+
+      docsets = response['docsets']
+      assert docsets.length > 0
+      first = docsets.first
+      assert first.key?('slug')
+      assert first.key?('name')
+      assert first.key?('version')
+      refute first.key?('release_date'), 'should not include release_date'
+      refute first.key?('mtime'), 'should not include mtime'
+
       slugs = docsets.map { |d| d['slug'] }
       assert_includes slugs, 'css'
       assert_includes slugs, 'html~5'
     end
 
+    it 'paginates results with offset and limit' do
+      result = rpc('tools/call', {
+        'name' => 'devdocs_list_docsets',
+        'arguments' => { 'offset' => 0, 'limit' => 2 }
+      })['result']
+      response = JSON.parse(result['content'].first['text'])
+
+      assert_equal 0, response['offset']
+      assert_equal 2, response['limit']
+      assert_equal 2, response['returned']
+      assert response['total'] > 2
+      assert_equal 2, response['docsets'].length
+    end
+
+    it 'respects offset to skip results' do
+      first_page = rpc('tools/call', {
+        'name' => 'devdocs_list_docsets',
+        'arguments' => { 'offset' => 0, 'limit' => 2 }
+      })['result']
+      first_docsets = JSON.parse(first_page['content'].first['text'])['docsets'].map { |d| d['slug'] }
+
+      second_page = rpc('tools/call', {
+        'name' => 'devdocs_list_docsets',
+        'arguments' => { 'offset' => 2, 'limit' => 2 }
+      })['result']
+      second_docsets = JSON.parse(second_page['content'].first['text'])['docsets'].map { |d| d['slug'] }
+
+      assert first_docsets != second_docsets
+    end
+
+    it 'filters docsets by query string' do
+      result = rpc('tools/call', {
+        'name' => 'devdocs_list_docsets',
+        'arguments' => { 'query' => 'css' }
+      })['result']
+      response = JSON.parse(result['content'].first['text'])
+
+      docsets = response['docsets']
+      assert docsets.length > 0
+      assert docsets.all? { |d| d['slug'].downcase.include?('css') || d['name'].downcase.include?('css') }
+    end
+
+    it 'filters case-insensitively' do
+      result = rpc('tools/call', {
+        'name' => 'devdocs_list_docsets',
+        'arguments' => { 'query' => 'CSS' }
+      })['result']
+      response = JSON.parse(result['content'].first['text'])
+
+      docsets = response['docsets']
+      assert docsets.length > 0
+      assert docsets.any? { |d| d['slug'] == 'css' }
+    end
+
+    it 'returns empty docsets for non-matching query' do
+      result = rpc('tools/call', {
+        'name' => 'devdocs_list_docsets',
+        'arguments' => { 'query' => 'nonexistentdocthing' }
+      })['result']
+      response = JSON.parse(result['content'].first['text'])
+
+      assert_equal 0, response['returned']
+      assert_equal [], response['docsets']
+      assert response['total'] == 0
+    end
+
     it 'calls devdocs_search and returns matching entries for a doc set' do
       args = { 'slug' => 'mcp_fixture', 'query' => 'push' }
       result = rpc('tools/call', { 'name' => 'devdocs_search', 'arguments' => args })['result']