DollhouseMCP

Instructions

Implementation Reference

• src/server/tools/CollectionTools.ts:47-95 (registration)

  Registration of the 'search_collection_enhanced' tool, including full input schema (with query, elementType, category, page, pageSize, sortBy) and thin handler that delegates to server.searchCollectionEnhanced
  { tool: { name: "search_collection_enhanced", description: "Enhanced search for collection content with pagination, filtering, and sorting. Use this for advanced searches when users need specific content types or want to browse results in pages.", inputSchema: { type: "object", properties: { query: { type: "string", description: "Search query for finding content. Examples: 'creative writer', 'explain like I'm five', 'coding assistant'.", }, elementType: { type: "string", description: "Filter by content type: personas, skills, agents, templates, tools, memories, prompts", enum: ["personas", "skills", "agents", "templates", "tools", "memories", "prompts"] }, category: { type: "string", description: "Filter by category: creative, professional, educational, personal, gaming", enum: ["creative", "professional", "educational", "personal", "gaming"] }, page: { type: "number", description: "Page number for paginated results (default: 1)", minimum: 1 }, pageSize: { type: "number", description: "Number of results per page (default: 25, max: 100)", minimum: 1, maximum: 100 }, sortBy: { type: "string", description: "Sort results by relevance, name, or date", enum: ["relevance", "name", "date"] } }, required: ["query"], }, }, handler: (args: any) => server.searchCollectionEnhanced(args.query, { elementType: args.elementType, category: args.category, page: args.page, pageSize: args.pageSize, sortBy: args.sortBy }) },
• src/server/types.ts:36-36 (schema)

  Interface definition for the server.searchCollectionEnhanced method called by the tool handler
  searchCollectionEnhanced(query: string, options?: any): Promise<any>;
• src/collection/CollectionSearch.ts:30-61 (handler)

  Core implementation of enhanced collection search logic (searchCollectionWithOptions), supporting filtering, pagination, sorting, index-based search with fallback to GitHub API and cache
  async searchCollectionWithOptions(query: string, options: SearchOptions = {}): Promise<SearchResults> { const startTime = Date.now(); logger.debug(`CollectionSearch.searchCollectionWithOptions called with query: "${query}"`, options); // Validate search query for security try { validateSearchQuery(query, 1000); } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); logger.error('Search query validation failed:', { query, error: errorMessage }); ErrorHandler.logError('CollectionSearch.searchWithOptions.validateQuery', error, { query }); return this.createEmptySearchResults(query, options); } try { // Try index-based search first const indexResults = await this.searchFromIndex(query, options); const searchTime = Date.now() - startTime; logger.debug(`Index search completed in ${searchTime}ms with ${indexResults.items.length} results`); return { ...indexResults, searchTime }; } catch (error) { logger.debug('Index search failed, falling back to legacy search:', error); // Fallback to legacy search const legacyResults = await this.searchCollection(query); const searchTime = Date.now() - startTime; // Convert legacy results to new format return this.convertLegacyResults(legacyResults, query, options, searchTime); } }
• src/collection/CollectionSearch.ts:290-327 (helper)

  Index-based search helper with filtering by elementType/category, relevance scoring, sorting, and pagination logic used by enhanced search
  private async searchFromIndex(query: string, options: SearchOptions): Promise<SearchResults> { const index = await this.indexCache.getIndex(); const allEntries = this.flattenIndexEntries(index); // Filter by element type if specified let filteredEntries = allEntries; if (options.elementType) { filteredEntries = allEntries.filter(entry => entry.type === options.elementType); } // Filter by category if specified if (options.category) { filteredEntries = filteredEntries.filter(entry => entry.category === options.category); } // Search matching const matchedEntries = this.performIndexSearch(query, filteredEntries); // Sort results const sortedEntries = this.sortSearchResults(matchedEntries, options.sortBy || 'relevance', query); // Apply pagination const page = options.page || 1; const pageSize = options.pageSize || 25; const startIndex = (page - 1) * pageSize; const endIndex = startIndex + pageSize; const paginatedEntries = sortedEntries.slice(startIndex, endIndex); return { items: paginatedEntries, total: sortedEntries.length, page, pageSize, hasMore: endIndex < sortedEntries.length, query, searchTime: 0 // Will be set by caller }; }
• src/collection/CollectionSearch.ts:67-105 (helper)

  Legacy/basic searchCollection fallback used by enhanced search when index unavailable; searches GitHub API or cache/seed data
  async searchCollection(query: string): Promise<any[]> { logger.debug(`CollectionSearch.searchCollection called with query: "${query}"`); // Validate search query for security try { validateSearchQuery(query, 1000); } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); logger.error('Search query validation failed:', { query, error: errorMessage }); ErrorHandler.logError('CollectionSearch.search.validateQuery', error, { query }); return []; } try { // First, try GitHub API search if authenticated const searchUrl = `${this.searchBaseUrl}?q=${encodeURIComponent(query)}+repo:DollhouseMCP/collection+path:library+extension:md`; logger.debug(`Attempting GitHub API search with URL: ${searchUrl}`); const data = await this.githubClient.fetchFromGitHub(searchUrl, false); // Don't require auth for search if (data.items && Array.isArray(data.items)) { logger.debug(`Found ${data.items.length} items via GitHub API search`); // Update cache with fresh data from API await this.updateCacheFromGitHubItems(data.items); return data.items; } logger.debug('GitHub API search returned no items, falling back to cache'); return []; } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); logger.debug(`GitHub API search failed: ${errorMessage}. Falling back to cached search.`); ErrorHandler.logError('CollectionSearch.search.githubApi', error, { query }); // Fallback to cached search return this.searchFromCache(query); } }