DollhouseMCP

Instructions

Implementation Reference

• src/collection/ElementInstaller.ts:930-938 (handler)

  The installContent method called by the server handler to install element from collection path. Delegates to installFromCollection for core logic.

  async installContent(inputPath: string): Promise<{
    success: boolean;
    message: string;
    metadata?: IElementMetadata;
    elementType?: ElementType;
    filename?: string;
  }> {
    return await this.installFromCollection(inputPath);
  }

• src/collection/ElementInstaller.ts:700-748 (handler)

  Core handler logic for installing from collection: validates path, fetches content from GitHub API, sanitizes and validates content, performs atomic file write to local portfolio.

  private async installFromCollection(collectionPath: string): Promise<InstallResult> {
    // ENHANCEMENT (PR #1453): Log collection installation attempt
    logger.debug('Installing from collection', {
      collectionPath
    });
  
    // SECURITY: Validate and sanitize the input path first
    const sanitizedPath = validatePath(collectionPath);
    const elementType = this.validateAndExtractElementType(sanitizedPath);
  
    // STEP 1: FETCH CONTENT INTO MEMORY (NO DISK OPERATIONS YET)
    const content = await this.fetchCollectionContent(sanitizedPath);
  
    // STEP 2: PERFORM ALL VALIDATION BEFORE ANY DISK OPERATIONS
    const { sanitizedContent, metadata } = await this.validateCollectionContent(content);
  
    // STEP 3: PREPARE FILE PATH AND CHECK EXISTENCE
    // FIX (SonarCloud L704): Remove unused elementDir variable
    const { filename, localPath } = this.prepareFilePath(sanitizedPath, elementType);
  
    // SECURITY: Check if file already exists before any write operations
    const existsResult = await this.checkFileExists(localPath, filename);
    if (existsResult) {
      logger.debug('Element already exists in collection', {
        filename,
        elementType
      });
      return existsResult;
    }
  
    // STEP 4: ALL VALIDATION COMPLETE - NOW PERFORM ATOMIC WRITE OPERATION
    await this.atomicWriteFile(localPath, sanitizedContent);
  
    // ENHANCEMENT (PR #1453): Log successful installation
    logger.debug('Element installed successfully from collection', {
      elementName: metadata.name,
      elementType,
      filename,
      localPath
    });
  
    return {
      success: true,
      message: `AI customization element installed successfully!`,
      metadata,
      filename,
      elementType
    };
  }

• src/server/tools/CollectionTools.ts:117-126 (schema)

  Input schema validation for the tool: requires 'path' parameter with collection path format.

  inputSchema: {
    type: "object",
    properties: {
      path: {
        type: "string",
        description: "The collection path to the AI customization element. Format: 'library/[type]/[element].md' where type is personas, skills, templates, agents, or memories. Example: 'library/skills/code-review.md'.",
      },
    },
    required: ["path"],
  },

• src/server/tools/CollectionTools.ts:114-129 (registration)

  Tool definition and registration in getCollectionTools: includes name, description, schema, and handler that delegates to server.installContent.

    tool: {
      name: "install_collection_content",
      description: "Install AI customization elements FROM the DollhouseMCP collection TO your local portfolio. Use this when users ask to download/install any element type (personas, skills, templates, agents, or memories) from the collection. Examples: 'install the creative writer persona from the collection', 'get the code review skill from collection', 'download the meeting notes template from collection', 'get the project context memory from collection'.",
      inputSchema: {
        type: "object",
        properties: {
          path: {
            type: "string",
            description: "The collection path to the AI customization element. Format: 'library/[type]/[element].md' where type is personas, skills, templates, agents, or memories. Example: 'library/skills/code-review.md'.",
          },
        },
        required: ["path"],
      },
    },
    handler: (args: any) => server.installContent(args.path)
  },

• src/server/ServerSetup.ts:58-60 (registration)

  Registers all collection tools including install_collection_content via ToolRegistry.registerMany(getCollectionTools(instance)).

  // Register collection tools
  this.toolRegistry.registerMany(getCollectionTools(instance));