DollhouseMCP

Instructions

Implementation Reference

• src/handlers/EnhancedIndexHandler.ts:34-158 (handler)

  Core handler function implementing the tool logic: validates inputs with security checks (Unicode normalization), retrieves similar elements from EnhancedIndexManager using relationship strength, sorts and limits results, formats Markdown response with scores and relationships.

  async findSimilarElements(options: {
    elementName: string;
    elementType?: string;
    limit: number;
    threshold: number;
  }) {
    try {
      // Validate inputs
      if (!options.elementName || typeof options.elementName !== 'string') {
        throw new Error('Element name is required and must be a string');
      }
  
      // FIX: DMCP-SEC-004 - Normalize Unicode in user input to prevent homograph attacks
      const normalized = UnicodeValidator.normalize(options.elementName);
      if (!normalized.isValid) {
        throw new Error(`Invalid element name: ${normalized.detectedIssues?.join(', ')}`);
      }
      options.elementName = normalized.normalizedContent;
  
      // Also normalize element type if provided
      if (options.elementType) {
        const normalizedType = UnicodeValidator.normalize(options.elementType);
        if (!normalizedType.isValid) {
          throw new Error(`Invalid element type: ${normalizedType.detectedIssues?.join(', ')}`);
        }
        options.elementType = normalizedType.normalizedContent;
      }
      if (options.limit <= 0 || options.limit > 100) {
        options.limit = 5; // Default to reasonable limit
      }
      if (options.threshold < 0 || options.threshold > 1) {
        options.threshold = 0.3; // Default to reasonable threshold
      }
      // Ensure the enhanced index is available with error handling
      try {
        await this.enhancedIndexManager.getIndex();
      } catch (indexError) {
        logger.error('Failed to get Enhanced Index', indexError);
        // Try to recover by forcing rebuild
        try {
          await this.enhancedIndexManager.getIndex({ forceRebuild: true });
        } catch (rebuildError) {
          throw new Error('Enhanced Index is unavailable. Please try again later.');
        }
      }
  
      // FIX: DMCP-SEC-006 - Add security audit logging for index operations
      SecurityMonitor.logSecurityEvent({
        type: 'ELEMENT_CREATED',
        severity: 'LOW',
        source: 'EnhancedIndexHandler.findSimilarElements',
        details: `Similarity search performed for element: ${options.elementName}`,
        additionalData: {
          elementType: options.elementType,
          limit: options.limit,
          threshold: options.threshold
        }
      });
  
      // Find the element
      const elementId = options.elementType ?
        `${options.elementType}/${options.elementName}` :
        options.elementName;
  
      // Get connected elements (similar/related)
      const connectedMap = await this.enhancedIndexManager.getConnectedElements(
        elementId,
        {
          maxDepth: 1,  // Direct relationships only
          minStrength: options.threshold
        }
      );
  
      // Convert to array and sort by relationship strength
      const similarElements = Array.from(connectedMap.entries())
        .map(([id, path]) => {
          const [type, name] = id.split('/');
          return {
            type,
            name,
            score: path.totalStrength || 0,
            relationships: path.relationships || []  // relationships is already an array of strings
          };
        })
        .sort((a, b) => b.score - a.score)
        .slice(0, options.limit);
  
      // Format results
      let text = `${this.personaIndicator}🔍 **Similar Elements**\n\n`;
      text += `**Reference**: ${options.elementName}\n`;
      if (options.elementType) {
        text += `**Type**: ${options.elementType}\n`;
      }
      text += `**Found**: ${similarElements.length} similar elements\n\n`;
  
      if (similarElements.length === 0) {
        text += `No similar elements found with similarity score >= ${options.threshold}\n`;
      } else {
        for (const element of similarElements) {
          const icon = this.getElementIcon(element.type);
          text += `${icon} **${element.name}** (${element.type})\n`;
          text += `   📊 Similarity: ${(element.score * 100).toFixed(1)}%\n`;
          if (element.relationships && element.relationships.length > 0) {
            text += `   🔗 Relationships: ${element.relationships.join(', ')}\n`;
          }
          text += '\n';
        }
      }
  
      return {
        content: [{
          type: "text",
          text
        }]
      };
    } catch (error: any) {
      ErrorHandler.logError('EnhancedIndexHandler.findSimilarElements', error, options);
      return {
        content: [{
          type: "text",
          text: `${this.personaIndicator}❌ Failed to find similar elements: ${SecureErrorHandler.sanitizeError(error).message}`
        }]
      };
    }
  }

• src/server/tools/EnhancedIndexTools.ts:42-75 (registration)

  Tool registration defining the 'find_similar_elements' MCP tool with description, input schema, and handler that maps args to server.findSimilarElements call.

    tool: {
      name: "find_similar_elements",
      description: "Find elements that are semantically similar to a given element using NLP scoring (Jaccard similarity and Shannon entropy). Returns elements with similarity scores and relationships.",
      inputSchema: {
        type: "object",
        properties: {
          element_name: {
            type: "string",
            description: "Name of the element to find similar items for",
          },
          element_type: {
            type: "string",
            enum: ["personas", "skills", "templates", "agents", "memories", "ensembles"],
            description: "Type of the element. If not specified, searches all types.",
          },
          limit: {
            type: "number",
            description: `Maximum number of similar elements to return. Defaults to ${config.performance.defaultSimilarLimit}.`,
          },
          threshold: {
            type: "number",
            description: `Minimum similarity score (0-1) to include. Defaults to ${config.performance.defaultSimilarityThreshold}.`,
          },
        },
        required: ["element_name"],
      },
    },
    handler: (args: FindSimilarElementsArgs) => server.findSimilarElements({
      elementName: args.element_name,
      elementType: args.element_type,
      limit: args.limit || config.performance.defaultSimilarLimit,
      threshold: args.threshold || config.performance.defaultSimilarityThreshold
    })
  },

• src/server/tools/EnhancedIndexTools.ts:16-21 (schema)

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

  interface FindSimilarElementsArgs {
    element_name: string;
    element_type?: string;
    limit?: number;
    threshold?: number;
  }

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

  Interface definition in IToolHandler for the server's findSimilarElements method.

  findSimilarElements(options: {elementName: string; elementType?: string; limit: number; threshold: number}): Promise<any>;