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>;