DollhouseMCP

Instructions

Implementation Reference

• src/server/tools/PortfolioTools.ts:177-231 (registration)

  Registers the 'search_portfolio' MCP tool with full input schema definition and handler that delegates to the internal server.searchPortfolio method.

  {
    tool: {
      name: "search_portfolio",
      description: "Search your local portfolio by content name, metadata, keywords, tags, or description. This searches your local elements using the portfolio index for fast metadata-based lookups.",
      inputSchema: {
        type: "object",
        properties: {
          query: {
            type: "string",
            description: "Search query. Can match element names, keywords, tags, triggers, or descriptions. Examples: 'creative writer', 'debug', 'code review', 'research'.",
          },
          type: {
            type: "string",
            enum: ["personas", "skills", "templates", "agents", "memories", "ensembles"],
            description: "Limit search to specific element type. If not specified, searches all types.",
          },
          fuzzy_match: {
            type: "boolean",
            description: "Enable fuzzy matching for approximate name matches. Defaults to true.",
          },
          max_results: {
            type: "number",
            description: "Maximum number of results to return. Defaults to 20.",
          },
          include_keywords: {
            type: "boolean",
            description: "Include keyword matching in search. Defaults to true.",
          },
          include_tags: {
            type: "boolean",
            description: "Include tag matching in search. Defaults to true.",
          },
          include_triggers: {
            type: "boolean",
            description: "Include trigger word matching in search (for personas). Defaults to true.",
          },
          include_descriptions: {
            type: "boolean",
            description: "Include description text matching in search. Defaults to true.",
          },
        },
        required: ["query"],
      },
    },
    handler: (args: SearchPortfolioArgs) => server.searchPortfolio({
      query: args.query,
      elementType: args.type as any,
      fuzzyMatch: args.fuzzy_match,
      maxResults: args.max_results,
      includeKeywords: args.include_keywords,
      includeTags: args.include_tags,
      includeTriggers: args.include_triggers,
      includeDescriptions: args.include_descriptions
    })
  },

• src/server/types.ts:71-83 (schema)

  TypeScript interface definition for the searchPortfolio method signature used by the tool handler.

    searchPortfolio(options: {query: string; elementType?: string; fuzzyMatch?: boolean; maxResults?: number; includeKeywords?: boolean; includeTags?: boolean; includeTriggers?: boolean; includeDescriptions?: boolean}): Promise<any>;
    searchAll(options: {query: string; sources?: string[]; elementType?: string; page?: number; pageSize?: number; sortBy?: string}): Promise<any>;
    
    // New unified config and sync handlers
    handleConfigOperation(options: any): Promise<any>;
    handleSyncOperation(options: any): Promise<any>;
  
    // Enhanced Index tools
    findSimilarElements(options: {elementName: string; elementType?: string; limit: number; threshold: number}): Promise<any>;
    getElementRelationships(options: {elementName: string; elementType?: string; relationshipTypes?: string[]}): Promise<any>;
    searchByVerb(options: {verb: string; limit: number}): Promise<any>;
    getRelationshipStats(): Promise<any>;
  }

• src/portfolio/PortfolioIndexManager.ts:225-328 (handler)

  Core search implementation in PortfolioIndexManager.search() that performs multi-field search over indexed portfolio elements, used by the tool handler.

  public async search(query: string, options: SearchOptions = {}): Promise<SearchResult[]> {
    const index = await this.getIndex();
    
    // Normalize query for security
    const normalizedQuery = UnicodeValidator.normalize(query);
    if (!normalizedQuery.isValid) {
      logger.warn('Invalid Unicode in search query', {
        issues: normalizedQuery.detectedIssues
      });
      return [];
    }
    
    const safeQuery = normalizedQuery.normalizedContent.toLowerCase().trim();
    const queryTokens = safeQuery.split(/\s+/).filter(token => token.length > 0);
    
    if (queryTokens.length === 0) {
      return [];
    }
    
    const results: SearchResult[] = [];
    const seenPaths = new Set<string>();
    const maxResults = options.maxResults || 20;
    
    // Helper to add unique results
    const addResult = (entry: IndexEntry, matchType: SearchResult['matchType'], score: number = 1) => {
      if (!seenPaths.has(entry.filePath) && results.length < maxResults) {
        // Filter by element type if specified
        if (options.elementType && entry.elementType !== options.elementType) {
          return;
        }
        
        seenPaths.add(entry.filePath);
        results.push({ entry, matchType, score });
      }
    };
    
    // 1. Search by name (highest priority)
    for (const [name, entry] of index.byName) {
      if (this.matchesQuery(name, queryTokens)) {
        addResult(entry, 'name', 3);
      }
    }
    
    // 2. Search by filename
    for (const [filename, entry] of index.byFilename) {
      if (this.matchesQuery(filename, queryTokens)) {
        addResult(entry, 'filename', 2.5);
      }
    }
    
    // 3. Search by keywords
    if (options.includeKeywords !== false) {
      for (const [keyword, entries] of index.byKeyword) {
        if (this.matchesQuery(keyword, queryTokens)) {
          for (const entry of entries) {
            addResult(entry, 'keyword', 2);
          }
        }
      }
    }
    
    // 4. Search by tags
    if (options.includeTags !== false) {
      for (const [tag, entries] of index.byTag) {
        if (this.matchesQuery(tag, queryTokens)) {
          for (const entry of entries) {
            addResult(entry, 'tag', 2);
          }
        }
      }
    }
    
    // 5. Search by triggers
    if (options.includeTriggers !== false) {
      for (const [trigger, entries] of index.byTrigger) {
        if (this.matchesQuery(trigger, queryTokens)) {
          for (const entry of entries) {
            addResult(entry, 'trigger', 1.8);
          }
        }
      }
    }
    
    // 6. Search by description
    if (options.includeDescriptions !== false) {
      for (const [_, entry] of index.byName) {
        if (entry.metadata.description && 
            this.matchesQuery(entry.metadata.description.toLowerCase(), queryTokens)) {
          addResult(entry, 'description', 1.5);
        }
      }
    }
    
    // Sort by score (descending)
    results.sort((a, b) => b.score - a.score);
    
    logger.debug('Portfolio search completed', {
      query: safeQuery,
      resultCount: results.length,
      totalIndexed: index.byName.size
    });
    
    return results;
  }

• src/portfolio/PortfolioIndexManager.ts:177-220 (helper)

  findByName helper for exact and fuzzy matching of element names by metadata or filename, supporting the search functionality.

  public async findByName(name: string, options: SearchOptions = {}): Promise<IndexEntry | null> {
    const index = await this.getIndex();
    
    // Normalize input for security
    const normalizedName = UnicodeValidator.normalize(name);
    if (!normalizedName.isValid) {
      logger.warn('Invalid Unicode in search name', {
        issues: normalizedName.detectedIssues
      });
      return null;
    }
    
    const safeName = normalizedName.normalizedContent;
    
    // Try exact match first (case insensitive)
    const exactMatch = index.byName.get(safeName.toLowerCase());
    if (exactMatch) {
      logger.debug('Found exact name match', { name: safeName, filePath: exactMatch.filePath });
      return exactMatch;
    }
    
    // Try filename match
    const filenameMatch = index.byFilename.get(safeName.toLowerCase());
    if (filenameMatch) {
      logger.debug('Found filename match', { name: safeName, filePath: filenameMatch.filePath });
      return filenameMatch;
    }
    
    // Try fuzzy matching if enabled
    if (options.fuzzyMatch !== false) {
      const fuzzyMatch = this.findFuzzyMatch(safeName, index, options);
      if (fuzzyMatch) {
        logger.debug('Found fuzzy match', { 
          name: safeName, 
          matchName: fuzzyMatch.metadata.name,
          filePath: fuzzyMatch.filePath 
        });
        return fuzzyMatch;
      }
    }
    
    logger.debug('No match found for name', { name: safeName });
    return null;
  }