feat(backend): add sorting functionality for mcp server search results

Author: Lasim

services/backend/api-spec.json

@@ -14337,6 +14337,19 @@
             "required": false,
             "description": "Filter by auto-install flag"
           },
+          {
+            "schema": {
+              "type": "string",
+              "enum": [
+                "name",
+                "github_stars"
+              ]
+            },
+            "in": "query",
+            "name": "sort_by",
+            "required": false,
+            "description": "Sort results by name (default) or GitHub stars (descending, nulls last)"
+          },
           {
             "schema": {
               "type": "string",

services/backend/api-spec.yaml

@@ -10043,6 +10043,16 @@ paths:
           name: auto_install_new_default_team
           required: false
           description: Filter by auto-install flag
+        - schema:
+            type: string
+            enum:
+              - name
+              - github_stars
+          in: query
+          name: sort_by
+          required: false
+          description: Sort results by name (default) or GitHub stars (descending, nulls
+            last)
         - schema:
             type: string
             pattern: ^\d+$

services/backend/src/routes/mcp/servers/schemas.ts

@@ -109,6 +109,11 @@ export const SEARCH_SERVERS_QUERY_SCHEMA = {
       type: 'boolean',
       description: 'Filter by auto-install flag'
     },
+    sort_by: {
+      type: 'string',
+      enum: ['name', 'github_stars'],
+      description: 'Sort results by name (default) or GitHub stars (descending, nulls last)'
+    },
     limit: { 
       type: 'string',
       pattern: '^\\d+$',

services/backend/src/routes/mcp/servers/search.ts

@@ -16,6 +16,7 @@ import {
 // TypeScript interface for search query params
 interface SearchServersQueryParams extends Omit<ListServersQueryParams, 'search'> {
   q: string; // Search query is required for search endpoint
+  sort_by?: 'name' | 'github_stars'; // Optional sort parameter
 }
 
 export default async function searchServers(server: FastifyInstance) {
@@ -62,6 +63,7 @@ export default async function searchServers(server: FastifyInstance) {
         status: queryParams.status,
         featured: queryParams.featured
       },
+      sortBy: queryParams.sort_by,
       pagination: {
         limit: queryParams.limit,
         offset: queryParams.offset
@@ -96,6 +98,7 @@ export default async function searchServers(server: FastifyInstance) {
       const offset = parseInt(queryParams.offset || '0') || 0;
       const featured = queryParams.featured === 'true' ? true : queryParams.featured === 'false' ? false : undefined;
       const status = queryParams.status as 'active' | 'deprecated' | 'maintenance' | undefined;
+      const sortBy = (queryParams.sort_by as 'name' | 'github_stars') || 'name';
 
       // Build filters object - use 'search' internally (service expects 'search', not 'q')
       const filters = {
@@ -112,7 +115,8 @@ export default async function searchServers(server: FastifyInstance) {
         request.user!.id,
         userRole,
         teamIds,
-        filters
+        filters,
+        sortBy
       );
 
       // Apply pagination
@@ -123,6 +127,7 @@ export default async function searchServers(server: FastifyInstance) {
         operation: 'search_mcp_servers',
         userId: request.user!.id,
         query: queryParams.q,
+        sortBy: sortBy,
         totalResults: total,
         returnedResults: paginatedServers.length,
         userRole,

services/backend/src/services/mcpCatalogService.ts

@@ -223,7 +223,8 @@ export class McpCatalogService {
     userId: string, 
     userRole: string, 
     teamIds: string[],
-    filters?: McpServerFilters
+    filters?: McpServerFilters,
+    sortBy: 'name' | 'github_stars' = 'name'
   ): Promise<McpServer[]> {
     this.logger.debug({
       operation: 'get_servers_for_user',
@@ -288,8 +289,14 @@ export class McpCatalogService {
       query = query.where(and(...whereConditions));
     }
 
-    // Order by featured first, then by name
-    query = query.orderBy(desc(mcpServers.featured), asc(mcpServers.name));
+    // Apply sorting based on sortBy parameter
+    if (sortBy === 'github_stars') {
+      // Sort by GitHub stars (descending, nulls last), then by name
+      query = query.orderBy(desc(mcpServers.github_stars), asc(mcpServers.name));
+    } else {
+      // Default: Sort by featured first, then by name
+      query = query.orderBy(desc(mcpServers.featured), asc(mcpServers.name));
+    }
 
     const servers = await query;
 

services/backend/tests/unit/routes/mcp/servers/search.test.ts

@@ -219,7 +219,8 @@ describe('MCP Servers - Search Servers', () => {
         [],
         expect.objectContaining({
           search: 'test'
-        })
+        }),
+        'name'
       );
 
       expect(mockReply.status).toHaveBeenCalledWith(200);
@@ -276,7 +277,8 @@ describe('MCP Servers - Search Servers', () => {
           runtime: 'node',
           status: 'active',
           featured: true
-        }
+        },
+        'name'
       );
 
       expect(mockReply.status).toHaveBeenCalledWith(200);
@@ -386,7 +388,8 @@ describe('MCP Servers - Search Servers', () => {
         'test-user-id',
         'global_admin',
         [],
-        expect.any(Object)
+        expect.any(Object),
+        'name'
       );
     });
 
@@ -421,7 +424,8 @@ describe('MCP Servers - Search Servers', () => {
         'test-user-id',
         'global_user',
         ['team-1', 'team-2'],
-        expect.any(Object)
+        expect.any(Object),
+        'name'
       );
     });
 
@@ -445,7 +449,8 @@ describe('MCP Servers - Search Servers', () => {
         'test-user-id',
         'global_user',
         [],
-        expect.any(Object)
+        expect.any(Object),
+        'name'
       );
     });
 
@@ -621,6 +626,66 @@ describe('MCP Servers - Search Servers', () => {
     });
   });
 
+  describe('Sorting', () => {
+    beforeEach(async () => {
+      await searchServers(mockFastify as FastifyInstance);
+    });
+
+    it('should sort by name by default', async () => {
+      mockMcpService.getServersForUser.mockResolvedValue([]);
+
+      const handler = routeHandlers['GET /mcp/servers/search'];
+      await handler({
+        ...mockRequest,
+        query: { q: 'test', limit: '20', offset: '0' }
+      }, mockReply);
+
+      expect(mockMcpService.getServersForUser).toHaveBeenCalledWith(
+        'test-user-id',
+        'global_user',
+        [],
+        expect.any(Object),
+        'name'
+      );
+    });
+
+    it('should sort by github_stars when specified', async () => {
+      mockMcpService.getServersForUser.mockResolvedValue([]);
+
+      const handler = routeHandlers['GET /mcp/servers/search'];
+      await handler({
+        ...mockRequest,
+        query: { q: 'test', sort_by: 'github_stars', limit: '20', offset: '0' }
+      }, mockReply);
+
+      expect(mockMcpService.getServersForUser).toHaveBeenCalledWith(
+        'test-user-id',
+        'global_user',
+        [],
+        expect.any(Object),
+        'github_stars'
+      );
+    });
+
+    it('should sort by name when explicitly specified', async () => {
+      mockMcpService.getServersForUser.mockResolvedValue([]);
+
+      const handler = routeHandlers['GET /mcp/servers/search'];
+      await handler({
+        ...mockRequest,
+        query: { q: 'test', sort_by: 'name', limit: '20', offset: '0' }
+      }, mockReply);
+
+      expect(mockMcpService.getServersForUser).toHaveBeenCalledWith(
+        'test-user-id',
+        'global_user',
+        [],
+        expect.any(Object),
+        'name'
+      );
+    });
+  });
+
   describe('Query Parameter Validation', () => {
     beforeEach(async () => {
       await searchServers(mockFastify as FastifyInstance);
@@ -659,7 +724,8 @@ describe('MCP Servers - Search Servers', () => {
         'test-user-id',
         'global_user',
         [],
-        expect.objectContaining({ featured: true })
+        expect.objectContaining({ featured: true }),
+        'name'
       );
 
       // Test featured: 'false' (as string, which gets converted to boolean)
@@ -672,7 +738,8 @@ describe('MCP Servers - Search Servers', () => {
         'test-user-id',
         'global_user',
         [],
-        expect.objectContaining({ featured: false })
+        expect.objectContaining({ featured: false }),
+        'name'
       );
     });
   });