DollhouseMCP

Instructions

Implementation Reference

• src/server/tools/ConfigToolsV2.ts:49-111 (registration)

  Tool registration and schema definition for 'portfolio_element_manager'. Delegates execution to server.handleSyncOperation.
  tool: { name: "portfolio_element_manager", description: "Manage individual elements between your local portfolio and GitHub repository. USE THIS TO DOWNLOAD/UPLOAD INDIVIDUAL PERSONAS, SKILLS, OR OTHER ELEMENTS! When a user asks to 'download X persona from my GitHub' or 'upload Y skill to GitHub', use this tool. Operations: 'download' (GitHub→local), 'upload' (local→GitHub), 'list-remote' (see what's on GitHub), 'compare' (diff local vs GitHub). FUZZY MATCHING enabled - 'verbose victorian scholar' will find 'Verbose-Victorian-Scholar'. After downloading, use reload_elements then activate_element.", inputSchema: { type: "object", properties: { operation: { type: "string", enum: ["list-remote", "download", "upload", "compare"], description: "The operation to perform. 'download' = get from GitHub to local, 'upload' = send from local to GitHub, 'list-remote' = see what's on GitHub, 'compare' = see differences" }, element_name: { type: "string", description: "Name of the element (required for download, upload, compare). FUZZY MATCHING ENABLED: Just type the name naturally - 'verbose victorian scholar', 'Victorian Scholar', 'verbose-victorian', etc. will all work" }, element_type: { type: "string", enum: ["personas", "skills", "templates", "agents", "memories", "ensembles"], description: "Type of element (required for download, upload, compare). For personas use 'personas'" }, filter: { type: "object", properties: { type: { type: "string", enum: ["personas", "skills", "templates", "agents", "memories", "ensembles"], description: "Filter by element type" }, author: { type: "string", description: "Filter by author username" }, updated_after: { type: "string", description: "Filter by update date (ISO 8601 format)" } }, description: "Filters for bulk operations" }, options: { type: "object", properties: { force: { type: "boolean", description: "Force overwrite existing elements. Use force:true when downloading to skip confirmation prompts" }, dry_run: { type: "boolean", description: "Preview changes without applying them" }, include_private: { type: "boolean", description: "Include elements marked as private/local-only" } }, description: "Additional options. For downloads, use options:{force:true} to skip confirmations" } }, required: ["operation"] } }, handler: (args: any) => server.handleSyncOperation(args) }
• src/handlers/SyncHandlerV2.ts:41-87 (handler)

  Direct handler implementation (server.handleSyncOperation). Processes args, calls PortfolioSyncManager, formats results.
  async handleSyncOperation(options: SyncOperationOptions, indicator: string = '') { try { await this.configManager.initialize(); // Check if sync is enabled (allow list-remote and compare even when disabled) const syncEnabled = this.configManager.getSetting('sync.enabled'); const readOnlyOperations = ['list-remote', 'compare']; if (!syncEnabled && !readOnlyOperations.includes(options.operation)) { return { content: [{ type: "text", text: `${indicator}⚠️ **Sync is Disabled**\n\n` + `Portfolio sync is currently disabled for privacy.\n\n` + `To enable sync:\n` + `\`dollhouse_config action: "set", setting: "sync.enabled", value: true\`\n\n` + `You can still use \`list-remote\` and \`compare\` to view differences.` }] }; } // Map our operation to PortfolioSyncManager's SyncOperation format const syncOp: SyncOperation = { operation: this.mapOperation(options.operation), element_name: options.element_name, element_type: options.element_type || options.filter?.type, // Use filter.type if element_type not provided bulk: options.operation.includes('bulk'), show_diff: options.operation === 'compare', force: options.options?.force, confirm: options.options?.force || options.options?.dry_run === false // force implies confirm, dry_run=false means confirm }; // Call the unified handleSyncOperation method const result = await this.syncManager.handleSyncOperation(syncOp); // Format the result based on the operation type return this.formatResult(result, options, indicator); } catch (error) { const sanitizedError = SecureErrorHandler.sanitizeError(error); return { content: [{ type: "text", text: `${indicator}❌ Sync operation failed: ${sanitizedError.message}` }] }; } }
• src/portfolio/PortfolioSyncManager.ts:110-201 (handler)

  Core handler dispatching to specific operations (download, upload, list-remote, compare) with full business logic.
  public async handleSyncOperation(params: SyncOperation): Promise<SyncResult> { try { // Check if sync is enabled in config const config = this.configManager.getConfig(); if (!config.sync.enabled && params.operation !== 'list-remote') { return { success: false, message: 'Sync is disabled. Enable it with: dollhouse_config --action update --setting sync.enabled --value true' }; } // Check bulk permissions if (params.bulk) { const bulkAllowed = this.isBulkOperationAllowed(params.operation, config); if (!bulkAllowed.allowed) { return { success: false, message: bulkAllowed.message }; } } // Handle operations switch (params.operation) { case 'list-remote': return await this.listRemoteElements(params.element_type); case 'download': if (params.bulk) { return await this.bulkDownload(params.element_type, params.confirm); } else if (params.element_name) { return await this.downloadElement( params.element_name, params.element_type!, params.version, params.force ); } else { return { success: false, message: 'Element name required for individual download' }; } case 'upload': if (params.bulk) { return await this.bulkUpload(params.element_type, params.confirm); } else if (params.element_name) { return await this.uploadElement( params.element_name, params.element_type!, params.confirm ); } else { return { success: false, message: 'Element name required for individual upload' }; } case 'compare': if (params.element_name && params.element_type) { return await this.compareVersions( params.element_name, params.element_type, params.show_diff ); } else { return { success: false, message: 'Element name and type required for comparison' }; } default: return { success: false, message: `Unknown operation: ${params.operation}` }; } } catch (error) { logger.error('Sync operation failed', { operation: params.operation, error: error instanceof Error ? error.message : String(error) }); return { success: false, message: `Sync operation failed: ${error instanceof Error ? error.message : String(error)}` }; } }
• src/portfolio/PortfolioSyncManager.ts:288-432 (helper)

  Key helper method for downloading individual elements from GitHub with fuzzy matching and conflict resolution.
  private async downloadElement( elementName: string, elementType: ElementType, version?: string, force?: boolean ): Promise<SyncResult> { try { const config = this.configManager.getConfig(); // Validate element name const validation = UnicodeValidator.normalize(elementName); if (!validation.isValid) { return { success: false, message: `Invalid element name: ${validation.detectedIssues?.[0] || 'unknown error'}` }; } // Get token and set it const token = await TokenManager.getGitHubTokenAsync(); if (!token) { return { success: false, message: 'GitHub authentication required' }; } this.repoManager.setToken(token); // Get GitHub index const index = await this.indexer.getIndex(); // Find the element - first try exact match, then fuzzy match const entries = index.elements.get(elementType) || []; let entry = entries.find(e => e.name === elementName); // If exact match not found, try fuzzy matching if (!entry) { // Try case-insensitive exact match first entry = entries.find(e => e.name.toLowerCase() === elementName.toLowerCase()); // If still not found, try fuzzy matching if (!entry) { const fuzzyMatch = this.findFuzzyMatch(elementName, entries); if (fuzzyMatch) { logger.info(`Fuzzy match found: '${elementName}' matched to '${fuzzyMatch.name}'`); entry = fuzzyMatch; } } } if (!entry) { // Generate helpful suggestions const suggestions = this.getSuggestions(elementName, entries); const suggestionText = suggestions.length > 0 ? `\n\nDid you mean one of these?\n${suggestions.map(s => ` • ${s.name}`).join('\n')}` : ''; return { success: false, message: `Element '${elementName}' (${elementType}) not found in GitHub portfolio${suggestionText}` }; } // Check for local conflicts const localPath = this.portfolioManager.getElementPath(elementType, `${elementName}.md`); let hasLocalVersion = false; let localContent: string | null = null; try { localContent = await fs.readFile(localPath, 'utf-8'); hasLocalVersion = true; } catch { // No local version exists } // Download the element const response = await fetch(entry.downloadUrl, { headers: { 'Authorization': `Bearer ${token}`, 'Accept': 'application/vnd.github.v3.raw' } }); if (!response.ok) { throw new Error(`Failed to download: ${response.statusText}`); } const remoteContent = await response.text(); // Validate content security const validationResult = ContentValidator.validateAndSanitize(remoteContent); if (!validationResult.isValid && validationResult.severity === 'critical') { return { success: false, message: `Security issue detected in remote content: ${validationResult.detectedPatterns?.join(', ')}` }; } // Check if content is different if (hasLocalVersion && localContent) { const localHash = createHash('sha256').update(localContent).digest('hex'); const remoteHash = createHash('sha256').update(remoteContent).digest('hex'); if (localHash === remoteHash) { return { success: true, message: `Element '${elementName}' is already up to date` }; } // Show confirmation for overwrite unless force flag is set if (config.sync.individual.require_confirmation && !force) { const diff = await this.generateDiff(localContent, remoteContent); return { success: false, message: `Local version exists. Please confirm download will overwrite:\n\n${diff}\n\nTo proceed, use --force flag`, data: { requiresConfirmation: true } }; } } // Save the element await fs.mkdir(path.dirname(localPath), { recursive: true }); await fs.writeFile(localPath, remoteContent, 'utf-8'); logger.info('Element downloaded from GitHub', { element: elementName, type: elementType, version: entry.version }); return { success: true, message: `Successfully downloaded '${elementName}' (${elementType}) from GitHub portfolio` }; } catch (error) { return { success: false, message: `Failed to download element: ${error instanceof Error ? error.message : String(error)}` }; } }
• src/portfolio/PortfolioSyncManager.ts:437-584 (helper)

  Key helper method for uploading individual elements to GitHub with security checks.
  private async uploadElement( elementName: string, elementType: ElementType, confirm?: boolean ): Promise<SyncResult> { try { const config = this.configManager.getConfig(); // Check for local element const localPath = this.portfolioManager.getElementPath(elementType, `${elementName}.md`); let content: string; try { content = await fs.readFile(localPath, 'utf-8'); } catch { return { success: false, message: `Element '${elementName}' (${elementType}) not found locally` }; } // Check privacy metadata const parsed = SecureYamlParser.parse(content, { maxYamlSize: 64 * 1024, validateContent: false, validateFields: false }); if (parsed.data?.privacy?.local_only === true) { return { success: false, message: `Element '${elementName}' is marked as local-only and cannot be uploaded` }; } // Validate content security const validationResult = ContentValidator.validateAndSanitize(content); if (!validationResult.isValid && validationResult.severity === 'critical') { return { success: false, message: `Security issue detected: ${validationResult.detectedPatterns?.join(', ')}` }; } // Scan for sensitive content if configured if (config.sync.privacy.scan_for_secrets) { logger.debug('Scanning for secrets before upload'); // Implement actual secret scanning const secretPatterns = [ /api[_-]?key\s*[:=]\s*['"][^'"]+['"]/gi, /secret\s*[:=]\s*['"][^'"]+['"]/gi, /password\s*[:=]\s*['"][^'"]+['"]/gi, /token\s*[:=]\s*['"][^'"]+['"]/gi, /private[_-]?key\s*[:=]\s*['"][^'"]+['"]/gi ]; for (const pattern of secretPatterns) { if (pattern.test(content)) { return { success: false, message: `Potential secret detected in content. Please review and remove sensitive information before uploading.` }; } } } // Get confirmation if required (unless already confirmed) if (config.sync.individual.require_confirmation && !confirm) { return { success: false, message: `Please confirm upload of '${elementName}' (${elementType}) to GitHub.\n\nContent preview:\n${content.substring(0, 500)}...\n\nTo proceed, use --confirm flag`, data: { requiresConfirmation: true } }; } // Get token and validate const token = await TokenManager.getGitHubTokenAsync(); if (!token) { return { success: false, message: 'GitHub authentication required' }; } // Create a PortfolioElement for the adapter (fixes Issue #913) // Using PortfolioElementAdapter instead of incomplete IElement implementation const portfolioElement = { type: elementType, metadata: { name: elementName, description: parsed.data?.description || '', author: parsed.data?.author || 'unknown', created: parsed.data?.created || new Date().toISOString(), updated: new Date().toISOString(), version: parsed.data?.version || '1.0.0', tags: parsed.data?.tags || [] }, content: content }; // Use PortfolioElementAdapter to properly implement IElement interface const adapter = new PortfolioElementAdapter(portfolioElement); // Use PortfolioRepoManager to upload this.repoManager.setToken(token); // DEBUG: Log upload attempt logger.debug('[BULK_SYNC_DEBUG] Upload element attempt', { elementName, elementType, hasToken: !!token, tokenPrefix: token ? token.substring(0, 10) + '...' : 'none', adapterHasMetadata: !!(adapter && adapter.metadata), timestamp: new Date().toISOString() }); try { const url = await this.repoManager.saveElement(adapter, true); // consent is true since we've already checked logger.info('Element uploaded to GitHub', { element: elementName, type: elementType, url }); return { success: true, message: `Successfully uploaded '${elementName}' (${elementType}) to GitHub portfolio`, data: { url } }; } catch (uploadError) { // Handle specific errors if (uploadError instanceof Error && uploadError.message.includes('repository does not exist')) { return { success: false, message: `GitHub portfolio repository not found. Please initialize it first using init_portfolio tool.` }; } throw uploadError; } } catch (error) { return { success: false, message: `Failed to upload element: ${error instanceof Error ? error.message : String(error)}` }; } }