DollhouseMCP

Instructions

Implementation Reference

• src/collection/CollectionSearch.ts:67-105 (handler)

  Core handler function that implements the search logic for the collection. Performs GitHub API search, falls back to cache and seed data, with security validation.
  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); } }
• src/server/tools/CollectionTools.ts:30-46 (registration)

  Registers the 'search_collection' tool with schema and handler that delegates to server.searchCollection(query). This is returned by getCollectionTools() and registered in ServerSetup.
  { tool: { name: "search_collection", description: "Search for content in the collection by keywords. This searches all content types including personas (AI behavioral profiles that users activate to change AI behavior), skills, agents, prompts, etc. When a user asks to 'find a persona', search in the collection.", inputSchema: { type: "object", properties: { query: { type: "string", description: "Search query for finding content. Examples: 'creative writer', 'explain like I'm five', 'coding assistant'. Users typically search for personas by their behavioral traits or names.", }, }, required: ["query"], }, }, handler: (args: any) => server.searchCollection(args.query) },
• src/server/tools/CollectionTools.ts:34-43 (schema)

  Input schema definition for the search_collection tool requiring a 'query' string.
  inputSchema: { type: "object", properties: { query: { type: "string", description: "Search query for finding content. Examples: 'creative writer', 'explain like I'm five', 'coding assistant'. Users typically search for personas by their behavioral traits or names.", }, }, required: ["query"], },
• src/server/ServerSetup.ts:58-59 (registration)

  Registers all collection tools (including search_collection) from getCollectionTools into the ToolRegistry.
  // Register collection tools this.toolRegistry.registerMany(getCollectionTools(instance));
• src/collection/CollectionSearch.ts:105-110 (helper)

  Supporting helper methods for cache search, seed data search, fuzzy matching, and result formatting used by the main handler.
  } /** * Search cached collection items */ private async searchFromCache(query: string): Promise<any[]> {