DollhouseMCP

Instructions

Implementation Reference

• src/handlers/EnhancedIndexHandler.ts:163-275 (handler)

  Core handler function executing the tool logic: validates inputs, normalizes element IDs, fetches relationships from EnhancedIndexManager, filters by type if specified, parses relationships, and formats a rich text response with icons and strength scores.

  async getElementRelationships(options: {
    elementName: string;
    elementType?: string;
    relationshipTypes?: string[];
  }) {
    try {
      // FIX: DMCP-SEC-004 - Normalize Unicode in user input
      const normalized = UnicodeValidator.normalize(options.elementName);
      if (!normalized.isValid) {
        throw new Error(`Invalid element name: ${normalized.detectedIssues?.join(', ')}`);
      }
      options.elementName = normalized.normalizedContent;
  
      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;
      }
  
      // 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.getElementRelationships',
        details: `Relationship query performed for element: ${options.elementName}`,
        additionalData: {
          elementType: options.elementType,
          relationshipTypes: options.relationshipTypes
        }
      });
  
      // FIX: Use centralized element ID formatting
      // If no element type provided, use full element name as-is (may already include type)
      const elementId = options.elementType ?
        formatElementId(options.elementType, options.elementName) :
        options.elementName;
  
      const relationships = await this.enhancedIndexManager.getElementRelationships(elementId);
  
      // Filter by type if requested
      let filteredRelationships = relationships;
      if (options.relationshipTypes && options.relationshipTypes.length > 0) {
        filteredRelationships = {};
        for (const type of options.relationshipTypes) {
          if (relationships[type]) {
            filteredRelationships[type] = relationships[type];
          }
        }
      }
  
      // Format results
      let text = `${this.personaIndicator}🔗 **Element Relationships**\n\n`;
      text += `**Element**: ${options.elementName}\n`;
      if (options.elementType) {
        text += `**Type**: ${options.elementType}\n`;
      }
      text += '\n';
  
      const relationshipCount = Object.values(filteredRelationships)
        .reduce((sum, rels) => sum + (Array.isArray(rels) ? rels.length : 0), 0);
  
      if (relationshipCount === 0) {
        text += `No relationships found for this element.\n`;
      } else {
        for (const [relType, relations] of Object.entries(filteredRelationships)) {
          if (Array.isArray(relations) && relations.length > 0) {
            text += `**${relType.charAt(0).toUpperCase() + relType.slice(1)} (${relations.length})**\n`;
            for (const rel of relations) {
              // FIX: Use type-safe relationship parsing
              const parsedRel = parseRelationship(rel);
              if (isParsedRelationship(parsedRel)) {
                const icon = this.getElementIcon(parsedRel.targetType);
                text += `  ${icon} ${parsedRel.targetName}`;
                if (parsedRel.strength) {
                  text += ` (strength: ${(parsedRel.strength * 100).toFixed(0)}%)`;
                }
                text += '\n';
              } else {
                // Fallback for invalid relationships
                const parsed = parseElementIdWithFallback(rel.element);
                const icon = this.getElementIcon(parsed.type);
                text += `  ${icon} ${parsed.name} ⚠️\n`;
              }
            }
            text += '\n';
          }
        }
      }
  
      return {
        content: [{
          type: "text",
          text
        }]
      };
    } catch (error: any) {
      ErrorHandler.logError('EnhancedIndexHandler.getElementRelationships', error, options);
      return {
        content: [{
          type: "text",
          text: `${this.personaIndicator}❌ Failed to get relationships: ${SecureErrorHandler.sanitizeError(error).message}`
        }]
      };
    }
  }

• src/server/tools/EnhancedIndexTools.ts:77-109 (registration)

  Registers the MCP tool 'get_element_relationships' with full input schema, description, and handler that maps args to server.getElementRelationships call.

    tool: {
      name: "get_element_relationships",
      description: "Get all relationships for a specific element, including semantic similarities, verb-based connections, and cross-element references.",
      inputSchema: {
        type: "object",
        properties: {
          element_name: {
            type: "string",
            description: "Name of the element to get relationships for",
          },
          element_type: {
            type: "string",
            enum: ["personas", "skills", "templates", "agents", "memories", "ensembles"],
            description: "Type of the element. If not specified, searches all types.",
          },
          relationship_types: {
            type: "array",
            items: {
              type: "string",
              enum: ["similar", "uses", "extends", "requires", "complements", "verb-based"]
            },
            description: "Filter by specific relationship types. If not specified, returns all types.",
          },
        },
        required: ["element_name"],
      },
    },
    handler: (args: GetElementRelationshipsArgs) => server.getElementRelationships({
      elementName: args.element_name,
      elementType: args.element_type,
      relationshipTypes: args.relationship_types
    })
  },

• src/server/tools/EnhancedIndexTools.ts:80-102 (schema)

  JSON schema for tool inputs defining element_name (required), optional element_type enum, and relationship_types array enum.

  inputSchema: {
    type: "object",
    properties: {
      element_name: {
        type: "string",
        description: "Name of the element to get relationships for",
      },
      element_type: {
        type: "string",
        enum: ["personas", "skills", "templates", "agents", "memories", "ensembles"],
        description: "Type of the element. If not specified, searches all types.",
      },
      relationship_types: {
        type: "array",
        items: {
          type: "string",
          enum: ["similar", "uses", "extends", "requires", "complements", "verb-based"]
        },
        description: "Filter by specific relationship types. If not specified, returns all types.",
      },
    },
    required: ["element_name"],
  },

• src/portfolio/EnhancedIndexManager.ts:2215-2229 (helper)

  Helper method in EnhancedIndexManager that retrieves raw relationships for an element from the in-memory index after parsing the elementId.

  public async getElementRelationships(elementId: string): Promise<Record<string, Relationship[]>> {
    const index = await this.getIndex();
    // FIX: Use centralized element ID parsing
    const parsed = parseElementId(elementId);
    if (!parsed) {
      return {};
    }
    const element = index.elements[parsed.type]?.[parsed.name];
  
    if (!element) {
      return {};
    }
  
    return element.relationships || {};
  }