DollhouseMCP

Instructions

Implementation Reference

• src/collection/CollectionBrowser.ts:59-120 (handler)

  Core implementation of browseCollection logic: uses index first, falls back to GitHub API, then cache. Filters for MCP-supported types.

  async browseCollection(section?: string, type?: string): Promise<{ items: any[], categories: any[], sections?: any[] }> {
    try {
      // Try using collection index first for faster browsing
      const indexResult = await this.browseFromIndex(section, type);
      if (indexResult) {
        logger.debug('Used collection index for browsing');
        return indexResult;
      }
      
      // Fallback to GitHub API
      let url = this.baseUrl;
      
      // If no section provided, show top-level sections
      if (!section) {
        const data = await this.githubClient.fetchFromGitHub(url, false);
        if (!Array.isArray(data)) {
          throw new Error('Invalid collection response. Expected directory listing.');
        }
        
        // Filter to only show content directories
        const sections = data.filter((item: any) => 
          item.type === 'dir' && ['library', 'showcase', 'catalog'].includes(item.name)
        );
        
        return { items: [], categories: [], sections };
      }
      
      // Browse within a section
      url = type 
        ? `${this.baseUrl}/${section}/${type}` 
        : `${this.baseUrl}/${section}`;
      
      const data = await this.githubClient.fetchFromGitHub(url, false);
      
      if (!Array.isArray(data)) {
        throw new Error('Invalid collection response. Expected directory listing.');
      }
      
      // In the library section, we have content type directories
      if (section === 'library' && !type) {
        // Filter to only show MCP-supported content types
        const contentTypes = data.filter((item: any) => {
          if (item.type !== 'dir') return false;
          const elementType = isElementType(item.name) ? item.name as ElementType : null;
          return elementType && isMCPSupportedType(elementType);
        });
        return { items: [], categories: contentTypes };
      }
      
      // For library content types, show files directly (flat structure)
      const items = data.filter((item: any) => item.type === 'file' && item.name.endsWith('.md'));
      // For non-library sections, they might still have subdirectories
      const categories = section === 'library' ? [] : data.filter((item: any) => item.type === 'dir');
      
      return { items, categories };
    } catch (error) {
      logger.debug(`GitHub API browse failed, falling back to cache: ${error}`);
      
      // Fallback to cached data
      return this.browseFromCache(section, type);
    }
  }

• src/server/tools/CollectionTools.ts:11-27 (schema)

  Input schema and description for the browse_collection tool.

  tool: {
    name: "browse_collection",
    description: "Browse content from the DollhouseMCP collection by section and content type. Content types include personas (AI behavioral profiles), skills, agents, and templates. When users ask for 'personas', they're referring to content in the personas type.",
    inputSchema: {
      type: "object",
      properties: {
        section: {
          type: "string",
          description: "Collection section to browse (library, showcase, catalog). Leave empty to see all sections.",
        },
        type: {
          type: "string",
          description: "Content type within the library section: personas, skills, agents, templates, or memories. Only used when section is 'library'.",
        },
      },
    },
  },

• src/server/tools/CollectionTools.ts:10-29 (registration)

  Tool definition and handler registration returned by getCollectionTools().

  {
    tool: {
      name: "browse_collection",
      description: "Browse content from the DollhouseMCP collection by section and content type. Content types include personas (AI behavioral profiles), skills, agents, and templates. When users ask for 'personas', they're referring to content in the personas type.",
      inputSchema: {
        type: "object",
        properties: {
          section: {
            type: "string",
            description: "Collection section to browse (library, showcase, catalog). Leave empty to see all sections.",
          },
          type: {
            type: "string",
            description: "Content type within the library section: personas, skills, agents, templates, or memories. Only used when section is 'library'.",
          },
        },
      },
    },
    handler: (args: any) => server.browseCollection(args?.section, args?.type)
  },

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

  Registers the collection tools (including browse_collection) in the MCP tool registry.

  this.toolRegistry.registerMany(getCollectionTools(instance));

• src/collection/CollectionBrowser.ts:338-417 (helper)

  Helper function to format browse results into user-friendly Markdown with navigation and install instructions.

  formatBrowseResults(items: any[], categories: any[], section?: string, type?: string, personaIndicator: string = ''): string {
    const textParts = [`${personaIndicator}🏪 **DollhouseMCP Collection**\n\n`];
    
    // Show top-level sections if no section specified
    if (!section && categories.length > 0) {
      textParts.push(`**📚 Collection Sections (${categories.length}):**\n`);
      categories.forEach((sec: any) => {
        const sectionIcons: { [key: string]: string } = {
          'library': '📖',
          'showcase': '⭐',
          'catalog': '💎'
        };
        const icon = sectionIcons[sec.name] || '📁';
        const descriptions: { [key: string]: string } = {
          'library': 'Free community content',
          'showcase': 'Featured high-quality content (coming soon)',
          'catalog': 'Premium content (coming soon)'
        };
        textParts.push(
          `   ${icon} **${sec.name}** - ${descriptions[sec.name] || 'Content collection'}\n`,
          `      Browse: \`browse_collection "${sec.name}"\`\n\n`
        );
      });
      return textParts.join('');
    }
    
    // Show content types within library section
    if (section === 'library' && !type && categories.length > 0) {
      textParts.push(`**📖 Library Content Types (${categories.length}):**\n`);
      categories.forEach((cat: any) => {
        const typeIcons: { [key: string]: string } = {
          'personas': '🎭',
          'skills': '🛠️',
          'agents': '🤖',
          'templates': '📄',
          'ensembles': '🎼',
          'memories': '🧠'
        };
        const icon = typeIcons[cat.name] || '📁';
        textParts.push(`   ${icon} **${cat.name}** - Browse: \`browse_collection "library" "${cat.name}"\`\n`);
      });
      textParts.push('\n');
    } else if (categories.length > 0) {
      // Only show category navigation for non-library sections (showcase, catalog)
      textParts.push(`**📁 Subdirectories in ${section}${type ? `/${type}` : ''} (${categories.length}):**\n`);
      categories.forEach((cat: any) => {
        const browsePath = type ? `"${section}" "${type}/${cat.name}"` : `"${section}" "${cat.name}"`;
        textParts.push(`   📂 **${cat.name}** - Browse: \`browse_collection ${browsePath}\`\n`);
      });
      textParts.push('\n');
    }
    
    if (items.length > 0) {
      const contentType = type || 'content';
      const contentIcons: { [key: string]: string } = {
        'personas': '🎭',
        'skills': '🛠️',
        'agents': '🤖',
        'templates': '📄',
        'ensembles': '🎼',
        'memories': '🧠'
      };
      const icon = contentIcons[contentType] || '📄';
      
      textParts.push(`**${icon} ${contentType.charAt(0).toUpperCase() + contentType.slice(1)} in ${section}${type ? `/${type}` : ''} (${items.length}):**\n`);
      items.forEach((item: any) => {
        // Use item.path for correct GitHub file path, item.name for display
        // This fixes the mismatch where browse returned "Code Review.md" but file is "code-review.md"
        const fullPath = item.path || (section + (type ? `/${type}` : '') + `/${item.name}`);
        const displayName = item.name.replace('.md', '');
        textParts.push(
          `   ▫️ **${displayName}**\n`,
          `      📥 Install: \`install_collection_content "${fullPath}"\`\n`,
          `      👁️ Details: \`get_collection_content "${fullPath}"\`\n\n`
        );
      });
    }
    
    return textParts.join('');
  }