DollhouseMCP

Instructions

Implementation Reference

• src/portfolio/PortfolioManager.ts:251-286 (handler)

  Core handler logic that lists elements of a given type by scanning the filesystem directory, filtering by type-specific file extension, excluding test elements, and handling various filesystem errors gracefully.

  public async listElements(type: ElementType): Promise<string[]> {
    const elementDir = this.getElementDir(type);
    const fileExtension = ELEMENT_FILE_EXTENSIONS[type] || DEFAULT_ELEMENT_FILE_EXTENSION;
  
    try {
      const files = await fs.readdir(elementDir);
      // Filter for correct file extension based on element type and exclude test elements
      return files
        .filter(file => file.endsWith(fileExtension))
        .filter(file => !this.isTestElement(file));
    } catch (error) {
      const err = error as NodeJS.ErrnoException;
      
      if (err.code === 'ENOENT') {
        // Directory doesn't exist yet - this is expected for new installations
        logger.debug(`[PortfolioManager] Element directory doesn't exist yet: ${elementDir}`);
        return [];
      }
      
      if (err.code === 'EACCES' || err.code === 'EPERM') {
        // Permission denied - log but return empty array
        ErrorHandler.logError('PortfolioManager.listElements', error, { elementDir });
        return [];
      }
      
      if (err.code === 'ENOTDIR') {
        // Path exists but is not a directory
        ErrorHandler.logError('PortfolioManager.listElements', error, { elementDir });
        throw ErrorHandler.createError(`Path is not a directory: ${elementDir}`, ErrorCategory.SYSTEM_ERROR);
      }
      
      // For any other errors, throw with context
      ErrorHandler.logError('PortfolioManager.listElements', error, { elementDir });
      throw ErrorHandler.wrapError(error, 'Failed to list elements', ErrorCategory.SYSTEM_ERROR);
    }
  }

• src/server/tools/ElementTools.ts:78-92 (schema)

  Tool schema definition including input validation schema for 'type' parameter constrained to valid ElementType enum values.

  tool: {
    name: "list_elements",
    description: "List all available elements of a specific type",
    inputSchema: {
      type: "object",
      properties: {
        type: {
          type: "string",
          description: "The element type to list",
          enum: Object.values(ElementType),
        },
      },
      required: ["type"],
    },
  },

• src/server/ServerSetup.ts:52-54 (registration)

  Registers the element tools (including list_elements) from ElementTools into the central ToolRegistry during server setup.

  // Register element tools (new generic tools for all element types)
  this.toolRegistry.registerMany(getElementTools(instance));

• src/server/tools/ElementTools.ts:77-94 (registration)

  Defines and prepares the list_elements tool definition and thin handler (delegating to server.listElements) for registration in getElementTools().

  {
    tool: {
      name: "list_elements",
      description: "List all available elements of a specific type",
      inputSchema: {
        type: "object",
        properties: {
          type: {
            type: "string",
            description: "The element type to list",
            enum: Object.values(ElementType),
          },
        },
        required: ["type"],
      },
    },
    handler: (args: ListElementsArgs) => server.listElements(args.type)
  },

• src/portfolio/PortfolioManager.ts:200-247 (helper)

  Helper method used by listElements to filter out test and dangerous files from the listing.

  public isTestElement(filename: string): boolean {
    // Dangerous test patterns that should never appear in production
    const dangerousPatterns = [
      /^bin-sh/i,
      /^rm-rf/i,
      /^nc-e-bin/i,
      /^python-c-import/i,
      /^curl.*evil/i,
      /^wget.*malicious/i,
      /^eval-/i,
      /^exec-/i,
      /^bash-c-/i,
      /^sh-c-/i,
      /^powershell-/i,
      /^cmd-c-/i,
      /shell-injection/i
    ];
    
    // Common test patterns
    const testPatterns = [
      /^test-/i,
      /^memory-test-/i,
      /^yaml-test/i,
      /^perf-test-/i,
      /^stability-test-/i,
      /^roundtrip-test/i,
      /test-persona/i,
      /test-skill/i,
      /test-template/i,
      /test-agent/i,
      /\.test\./,
      /__test__/,
      /test-data/,
      /penetration-test/i,
      /metadata-test/i,
      /testpersona\d+/i  // Generated test personas with timestamps
    ];
    
    // Check dangerous patterns first
    if (dangerousPatterns.some(pattern => pattern.test(filename))) {
      logger.warn(`[PortfolioManager] Filtered dangerous test element: ${filename}`);
      return true;
    }
    
    // Check common test patterns
    return testPatterns.some(pattern => pattern.test(filename));
  }