DollhouseMCP

Instructions

Implementation Reference

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

  Registration of the browse_collection tool, including its description, inputSchema for parameters (section, type), and handler lambda delegating to server.browseCollection
  { 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/collection/CollectionBrowser.ts:58-120 (handler)

  Core handler logic for browsing the collection: prioritizes index, falls back to GitHub API fetch, then cache/seed data. Filters for MCP-supported types and formats directory listings.
  */ 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/collection/CollectionBrowser.ts:337-417 (helper)

  Helper method to format browse results into readable Markdown with navigation commands for sections, types, and individual items.
  */ 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(''); }
• src/server/ServerSetup.ts:58-59 (registration)

  Registers all collection tools (including browse_collection) via ToolRegistry during server setup.
  // Register collection tools this.toolRegistry.registerMany(getCollectionTools(instance));
• src/server/tools/CollectionTools.ts:14-26 (schema)

  Input schema definition for browse_collection tool parameters: optional section (library, showcase, catalog) and type (personas, skills, etc.).
  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'.", }, }, },