DollhouseMCP

Instructions

Implementation Reference

• src/handlers/EnhancedIndexHandler.ts:280-354 (handler)

  Core implementation of the searchByVerb method in EnhancedIndexHandler class. Performs input validation (Unicode normalization), security logging, retrieves elements matching the verb via EnhancedIndexManager.getElementsByAction, limits results, and formats a markdown response listing matching elements by type and name.

  async searchByVerb(options: {
    verb: string;
    limit: number;
  }) {
    try {
      // FIX: DMCP-SEC-004 - Normalize Unicode in user input
      const normalized = UnicodeValidator.normalize(options.verb);
      if (!normalized.isValid) {
        throw new Error(`Invalid verb: ${normalized.detectedIssues?.join(', ')}`);
      }
      options.verb = normalized.normalizedContent;
  
      // Get the index with error handling
      await this.enhancedIndexManager.getIndex().catch(async (error) => {
        logger.error('Failed to get Enhanced Index, attempting rebuild', error);
        return this.enhancedIndexManager.getIndex({ forceRebuild: true });
      });
  
      // FIX: DMCP-SEC-006 - Add security audit logging
      SecurityMonitor.logSecurityEvent({
        type: 'ELEMENT_CREATED',
        severity: 'LOW',
        source: 'EnhancedIndexHandler.searchByVerb',
        details: `Verb search performed for action: ${options.verb}`,
        additionalData: {
          verb: options.verb,
          limit: options.limit
        }
      });
  
      // Search by verb
      const results = await this.enhancedIndexManager.getElementsByAction(options.verb);
  
      // Limit results
      const limited = results.slice(0, options.limit);
  
      // Format results
      let text = `${this.personaIndicator}🎯 **Elements for Action: "${options.verb}"**\n\n`;
      text += `**Found**: ${limited.length} element${limited.length === 1 ? '' : 's'}\n\n`;
  
      if (limited.length === 0) {
        text += `No elements found that can handle the action "${options.verb}".\n\n`;
        text += `**Tips:**\n`;
        text += `• Try related verbs (e.g., "analyze" → "review", "examine")\n`;
        text += `• Use common action verbs like "create", "debug", "optimize"\n`;
        text += `• Check element descriptions for supported actions\n`;
      } else {
        for (const elementName of limited) {
          // FIX: Use centralized element ID parsing
          // Note: getElementsByAction returns names in "type/name" format for legacy reasons
          const parsed = elementName.includes('/') ?
            { type: elementName.split('/')[0], name: elementName.split('/')[1] } :
            parseElementIdWithFallback(elementName);
  
          const icon = this.getElementIcon(parsed.type);
          text += `${icon} **${parsed.name}** (${parsed.type})\n`;
        }
      }
  
      return {
        content: [{
          type: "text",
          text
        }]
      };
    } catch (error: any) {
      ErrorHandler.logError('EnhancedIndexHandler.searchByVerb', error, options);
      return {
        content: [{
          type: "text",
          text: `${this.personaIndicator}❌ Failed to search by verb: ${SecureErrorHandler.sanitizeError(error).message}`
        }]
      };
    }
  }

• src/server/tools/EnhancedIndexTools.ts:111-133 (registration)

  Registers the MCP tool 'search_by_verb' in getEnhancedIndexTools function, providing tool definition (name, description, inputSchema) and a handler that forwards arguments to the server's searchByVerb method using config defaults.

    tool: {
      name: "search_by_verb",
      description: "Search for elements that can handle a specific action verb (e.g., 'analyze', 'create', 'debug'). Uses verb trigger patterns to find matching elements.",
      inputSchema: {
        type: "object",
        properties: {
          verb: {
            type: "string",
            description: "Action verb to search for (e.g., 'analyze', 'create', 'debug', 'review')",
          },
          limit: {
            type: "number",
            description: `Maximum number of results to return. Defaults to ${config.performance.defaultVerbSearchLimit}.`,
          },
        },
        required: ["verb"],
      },
    },
    handler: (args: SearchByVerbArgs) => server.searchByVerb({
      verb: args.verb,
      limit: args.limit || config.performance.defaultVerbSearchLimit
    })
  },

• src/server/tools/EnhancedIndexTools.ts:29-32 (schema)

  TypeScript interface defining the input arguments for the search_by_verb tool handler.

  interface SearchByVerbArgs {
    verb: string;
    limit?: number;
  }

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

  Type definition in IToolHandler interface for the searchByVerb method signature used by the server.

  searchByVerb(options: {verb: string; limit: number}): Promise<any>;