feat(backend): implement minimal server response format for list endpoints

Author: Lasim

services/backend/api-spec.json

@@ -10,7 +10,7 @@ import {
   type ListServersQueryParams,
   type ListServersSuccessResponse,
   type ErrorResponse,
-  formatServerResponse
+  formatServerListResponse
 } from './schemas';
 
 export default async function listServers(server: FastifyInstance) {
@@ -121,8 +121,8 @@ export default async function listServers(server: FastifyInstance) {
         appliedFilters: filters
       }, 'MCP server list completed');
 
-      // Format dates for response using the shared utility function
-      const responseServers = paginatedServers.map(server => formatServerResponse(server));
+      // Format response using minimal list formatter (excludes config schemas, packages, etc.)
+      const responseServers = paginatedServers.map(server => formatServerListResponse(server));
 
       // Manual JSON serialization to ensure consistent JSON output
       const successResponse: ListServersSuccessResponse = {

services/backend/api-spec.yaml

@@ -1001,10 +1001,40 @@ export const COMMON_ERROR_RESPONSES = {
   500: { ...ERROR_RESPONSE_SCHEMA, description: 'Internal Server Error' }
 } as const;
 
+// Minimal server entity for list endpoints - excludes configuration schemas and heavy fields
+export const SERVER_LIST_ENTITY_SCHEMA = {
+  type: 'object',
+  properties: {
+    id: { type: 'string', description: 'Unique server identifier' },
+    name: { type: 'string', description: 'Server name' },
+    slug: { type: 'string', description: 'URL-friendly server slug' },
+    description: { type: 'string', description: 'Server description' },
+    icon_url: { type: 'string', nullable: true, description: 'Icon/logo URL' },
+    website_url: { type: 'string', nullable: true, description: 'Website URL' },
+    language: { type: 'string', description: 'Programming language' },
+    runtime: { type: 'string', description: 'Runtime environment' },
+    transport_type: { type: 'string', enum: ['stdio', 'http', 'sse'], description: 'Transport type' },
+    visibility: { type: 'string', enum: ['global', 'team'], description: 'Server visibility' },
+    owner_team_id: { type: 'string', nullable: true, description: 'Owning team ID' },
+    category_id: { type: 'string', nullable: true, description: 'Category ID' },
+    tags: { type: 'array', items: { type: 'string' }, nullable: true, description: 'Server tags' },
+    status: { type: 'string', enum: ['active', 'deprecated', 'maintenance'], description: 'Server status' },
+    featured: { type: 'boolean', description: 'Whether server is featured' },
+    requires_oauth: { type: 'boolean', description: 'Whether server requires OAuth' },
+    github_stars: { type: 'number', nullable: true, description: 'GitHub stars count' },
+    author_name: { type: 'string', nullable: true, description: 'Author name' },
+    organization: { type: 'string', nullable: true, description: 'Organization' },
+    official_name: { type: 'string', nullable: true, description: 'Official registry name' },
+    created_at: { type: 'string', format: 'date-time', description: 'Creation timestamp' },
+    updated_at: { type: 'string', format: 'date-time', description: 'Last update timestamp' }
+  },
+  required: ['id', 'name', 'slug', 'description', 'language', 'runtime', 'transport_type', 'visibility', 'status', 'featured', 'requires_oauth', 'created_at', 'updated_at']
+} as const;
+
 export const LIST_SERVERS_SUCCESS_RESPONSE_SCHEMA = {
   type: 'object',
   properties: {
-    success: { 
+    success: {
       type: 'boolean',
       description: 'Indicates successful server list retrieval'
     },
@@ -1013,8 +1043,8 @@ export const LIST_SERVERS_SUCCESS_RESPONSE_SCHEMA = {
       properties: {
         servers: {
           type: 'array',
-          items: SERVER_ENTITY_SCHEMA,
-          description: 'Array of server objects'
+          items: SERVER_LIST_ENTITY_SCHEMA,
+          description: 'Array of server objects (minimal fields for listing)'
         },
         pagination: {
           ...PAGINATION_SCHEMA,
@@ -1519,10 +1549,36 @@ export interface DeleteGlobalServerSuccessResponse {
   };
 }
 
+// Minimal server entity for list responses
+export interface ServerListEntity {
+  id: string;
+  name: string;
+  slug: string;
+  description: string;
+  icon_url: string | null;
+  website_url: string | null;
+  language: string;
+  runtime: string;
+  transport_type: 'stdio' | 'http' | 'sse';
+  visibility: 'global' | 'team';
+  owner_team_id: string | null;
+  category_id: string | null;
+  tags: string[] | null;
+  status: 'active' | 'deprecated' | 'maintenance';
+  featured: boolean;
+  requires_oauth: boolean;
+  github_stars: number | null;
+  author_name: string | null;
+  organization: string | null;
+  official_name: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
 export interface ListServersSuccessResponse {
   success: boolean;
   data: {
-    servers: ServerEntity[];
+    servers: ServerListEntity[];
     pagination: PaginationInfo;
   };
 }
@@ -1647,3 +1703,46 @@ export function formatServerResponse(server: any): ServerEntity {
     last_sync_at: server.last_sync_at?.toISOString() || null
   };
 }
+
+/**
+ * Converts McpServer to minimal API response format for list endpoints
+ * Excludes configuration schemas, packages, remotes, and other heavy fields
+ */
+export function formatServerListResponse(server: any): ServerListEntity {
+  const safeJsonParse = (field: any, defaultValue: any) => {
+    if (!field) return defaultValue;
+    if (typeof field === 'string') {
+      try {
+        return JSON.parse(field);
+      } catch {
+        return defaultValue;
+      }
+    }
+    return field;
+  };
+
+  return {
+    id: server.id,
+    name: server.name,
+    slug: server.slug,
+    description: server.description,
+    icon_url: server.icon_url || null,
+    website_url: server.website_url || null,
+    language: server.language,
+    runtime: server.runtime,
+    transport_type: server.transport_type,
+    visibility: server.visibility,
+    owner_team_id: server.owner_team_id || null,
+    category_id: server.category_id || null,
+    tags: safeJsonParse(server.tags, null),
+    status: server.status,
+    featured: server.featured,
+    requires_oauth: server.requires_oauth || false,
+    github_stars: server.github_stars || null,
+    author_name: server.author_name || null,
+    organization: server.organization || null,
+    official_name: server.official_name || null,
+    created_at: server.created_at.toISOString(),
+    updated_at: server.updated_at.toISOString()
+  };
+}

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

@@ -10,7 +10,7 @@ import {
   type ListServersQueryParams,
   type ListServersSuccessResponse,
   type ErrorResponse,
-  formatServerResponse
+  formatServerListResponse
 } from './schemas';
 
 // TypeScript interface for search query params
@@ -138,8 +138,8 @@ export default async function searchServers(server: FastifyInstance) {
         teamCount: teamIds.length
       }, 'MCP server search completed');
 
-      // Format servers using the shared utility function
-      const responseServers = paginatedServers.map(server => formatServerResponse(server));
+      // Format response using minimal list formatter (excludes config schemas, packages, etc.)
+      const responseServers = paginatedServers.map(server => formatServerListResponse(server));
 
       // Use the same response structure as list endpoint
       const response: ListServersSuccessResponse = {

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

@@ -4,6 +4,7 @@ import mcpRoutes from '../../../../src/routes/mcp/index';
 
 // Mock all the route modules
 vi.mock('../../../../src/routes/mcp/categories/list');
+vi.mock('../../../../src/routes/mcp/categories/list-featured');
 vi.mock('../../../../src/routes/mcp/categories/create');
 vi.mock('../../../../src/routes/mcp/categories/update');
 vi.mock('../../../../src/routes/mcp/categories/delete');
@@ -35,6 +36,7 @@ vi.mock('../../../../src/routes/mcp/user-configurations');
 
 // Import mocked modules
 import listCategories from '../../../../src/routes/mcp/categories/list';
+import listFeaturedCategories from '../../../../src/routes/mcp/categories/list-featured';
 import createCategory from '../../../../src/routes/mcp/categories/create';
 import updateCategory from '../../../../src/routes/mcp/categories/update';
 import deleteCategory from '../../../../src/routes/mcp/categories/delete';
@@ -66,6 +68,7 @@ import userConfigurationsRoutes from '../../../../src/routes/mcp/user-configurat
 
 // Type the mocked functions
 const mockListCategories = listCategories as MockedFunction<typeof listCategories>;
+const mockListFeaturedCategories = listFeaturedCategories as MockedFunction<typeof listFeaturedCategories>;
 const mockCreateCategory = createCategory as MockedFunction<typeof createCategory>;
 const mockUpdateCategory = updateCategory as MockedFunction<typeof updateCategory>;
 const mockDeleteCategory = deleteCategory as MockedFunction<typeof deleteCategory>;
@@ -115,6 +118,7 @@ describe('MCP Routes Registration', () => {
 
     // Mock all route modules to return resolved promises
     mockListCategories.mockResolvedValue(undefined);
+    mockListFeaturedCategories.mockResolvedValue(undefined);
     mockCreateCategory.mockResolvedValue(undefined);
     mockUpdateCategory.mockResolvedValue(undefined);
     mockDeleteCategory.mockResolvedValue(undefined);
@@ -148,14 +152,15 @@ describe('MCP Routes Registration', () => {
     it('should register all MCP route modules', async () => {
       await mcpRoutes(mockFastify as FastifyInstance);
 
-      // Verify that all 24 routes are registered
-      expect(mockFastify.register).toHaveBeenCalledTimes(24);
+      // Verify that all 25 routes are registered
+      expect(mockFastify.register).toHaveBeenCalledTimes(25);
     });
 
     it('should register all category routes', async () => {
       await mcpRoutes(mockFastify as FastifyInstance);
 
       expect(mockFastify.register).toHaveBeenCalledWith(listCategories);
+      expect(mockFastify.register).toHaveBeenCalledWith(listFeaturedCategories);
       expect(mockFastify.register).toHaveBeenCalledWith(createCategory);
       expect(mockFastify.register).toHaveBeenCalledWith(updateCategory);
       expect(mockFastify.register).toHaveBeenCalledWith(deleteCategory);
@@ -222,88 +227,89 @@ describe('MCP Routes Registration', () => {
       await mcpRoutes(mockFastify as FastifyInstance);
 
       const registerCalls = (mockFastify.register as any).mock.calls;
-      
-      // Check that category routes are registered first (positions 0-3)
+
+      // Check that category routes are registered first (positions 0-4)
       expect(registerCalls[0][0]).toBe(listCategories);
-      expect(registerCalls[1][0]).toBe(createCategory);
-      expect(registerCalls[2][0]).toBe(updateCategory);
-      expect(registerCalls[3][0]).toBe(deleteCategory);
+      expect(registerCalls[1][0]).toBe(listFeaturedCategories);
+      expect(registerCalls[2][0]).toBe(createCategory);
+      expect(registerCalls[3][0]).toBe(updateCategory);
+      expect(registerCalls[4][0]).toBe(deleteCategory);
     });
 
     it('should register server routes after categories', async () => {
       await mcpRoutes(mockFastify as FastifyInstance);
 
       const registerCalls = (mockFastify.register as any).mock.calls;
-      
-      // Check that server routes are in positions 4-10
-      expect(registerCalls[4][0]).toBe(listServers);
-      expect(registerCalls[5][0]).toBe(getServer);
-      expect(registerCalls[6][0]).toBe(getServerReadme);
-      expect(registerCalls[7][0]).toBe(searchServers);
-      expect(registerCalls[8][0]).toBe(getTags);
-      expect(registerCalls[9][0]).toBe(getLanguages);
-      expect(registerCalls[10][0]).toBe(getRuntimes);
+
+      // Check that server routes are in positions 5-11
+      expect(registerCalls[5][0]).toBe(listServers);
+      expect(registerCalls[6][0]).toBe(getServer);
+      expect(registerCalls[7][0]).toBe(getServerReadme);
+      expect(registerCalls[8][0]).toBe(searchServers);
+      expect(registerCalls[9][0]).toBe(getTags);
+      expect(registerCalls[10][0]).toBe(getLanguages);
+      expect(registerCalls[11][0]).toBe(getRuntimes);
     });
 
     it('should register global server management routes correctly', async () => {
       await mcpRoutes(mockFastify as FastifyInstance);
 
       const registerCalls = (mockFastify.register as any).mock.calls;
-      
-      // Check that global server management routes are in positions 11-13
-      expect(registerCalls[11][0]).toBe(createGlobalServer);
-      expect(registerCalls[12][0]).toBe(updateGlobalServer);
-      expect(registerCalls[13][0]).toBe(deleteGlobalServer);
+
+      // Check that global server management routes are in positions 12-14
+      expect(registerCalls[12][0]).toBe(createGlobalServer);
+      expect(registerCalls[13][0]).toBe(updateGlobalServer);
+      expect(registerCalls[14][0]).toBe(deleteGlobalServer);
     });
 
     it('should register team server management routes correctly', async () => {
       await mcpRoutes(mockFastify as FastifyInstance);
 
       const registerCalls = (mockFastify.register as any).mock.calls;
-      
-      // Check that team server management routes are in positions 14-17
-      expect(registerCalls[14][0]).toBe(listTeamServers);
-      expect(registerCalls[15][0]).toBe(createTeamServer);
-      expect(registerCalls[16][0]).toBe(updateTeamServer);
-      expect(registerCalls[17][0]).toBe(deleteTeamServer);
+
+      // Check that team server management routes are in positions 15-18
+      expect(registerCalls[15][0]).toBe(listTeamServers);
+      expect(registerCalls[16][0]).toBe(createTeamServer);
+      expect(registerCalls[17][0]).toBe(updateTeamServer);
+      expect(registerCalls[18][0]).toBe(deleteTeamServer);
     });
 
     it('should register version management routes correctly', async () => {
       await mcpRoutes(mockFastify as FastifyInstance);
 
       const registerCalls = (mockFastify.register as any).mock.calls;
-      
-      // Check that version management routes are in positions 18-20
-      expect(registerCalls[18][0]).toBe(listVersions);
-      expect(registerCalls[19][0]).toBe(createVersion);
-      expect(registerCalls[20][0]).toBe(updateVersion);
+
+      // Check that version management routes are in positions 19-21
+      expect(registerCalls[19][0]).toBe(listVersions);
+      expect(registerCalls[20][0]).toBe(createVersion);
+      expect(registerCalls[21][0]).toBe(updateVersion);
     });
 
     it('should register GitHub integration routes correctly', async () => {
       await mcpRoutes(mockFastify as FastifyInstance);
 
       const registerCalls = (mockFastify.register as any).mock.calls;
-      
-      // Check that GitHub route is at position 21
-      expect(registerCalls[21][0]).toBe(getRepoInfo);
+
+      // Check that GitHub route is at position 22
+      expect(registerCalls[22][0]).toBe(getRepoInfo);
     });
 
     it('should register installations routes correctly', async () => {
       await mcpRoutes(mockFastify as FastifyInstance);
 
       const registerCalls = (mockFastify.register as any).mock.calls;
-      
-      // Check that installations route is at position 22
-      expect(registerCalls[22][0]).toBe(installationsRoutes);
+
+      // Check that installations route is at position 23
+      expect(registerCalls[23][0]).toBe(installationsRoutes);
     });
 
     it('should register user configurations routes last', async () => {
       await mcpRoutes(mockFastify as FastifyInstance);
 
       const registerCalls = (mockFastify.register as any).mock.calls;
-      
-      // Check that user configurations route is at position 23 (last)
-      expect(registerCalls[23][0]).toBe(userConfigurationsRoutes);
+
+      // Check that user configurations route is at position 24 (last)
+      expect(registerCalls[24][0]).toBe(userConfigurationsRoutes);
     });
   });
 
@@ -333,6 +339,7 @@ describe('MCP Routes Registration', () => {
     it('should properly import and use all route modules', () => {
       // Verify that all modules are properly imported and mocked
       expect(listCategories).toBeDefined();
+      expect(listFeaturedCategories).toBeDefined();
       expect(createCategory).toBeDefined();
       expect(updateCategory).toBeDefined();
       expect(deleteCategory).toBeDefined();

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

@@ -192,8 +192,8 @@ describe('MCP Servers - List Servers', () => {
               id: 'server-1',
               name: 'Test Server 1',
               created_at: '2024-01-01T00:00:00.000Z',
-              updated_at: '2024-01-01T00:00:00.000Z',
-              last_sync_at: null
+              updated_at: '2024-01-01T00:00:00.000Z'
+              // Minimal list response excludes last_sync_at
             })
           ]),
           pagination: {