DollhouseMCP

Instructions

Implementation Reference

• src/handlers/SyncHandlerV2.ts:41-87 (handler)

  Main handler function executing the portfolio_element_manager tool logic. Maps tool arguments to sync operation, checks permissions, delegates to PortfolioSyncManager, and formats the MCP-compatible response.
  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/server/tools/ConfigToolsV2.ts:49-111 (registration)

  Tool registration including name, description, input/output schema, and handler wrapper that forwards 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/portfolio/PortfolioSyncManager.ts:110-201 (handler)

  Core handler in PortfolioSyncManager that dispatches to specific sync operations (list-remote, download, upload, compare) with permission checks and error handling.
  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/server/ServerSetup.ts:75-76 (registration)

  Final registration of ConfigToolsV2 (containing portfolio_element_manager) into the main tool registry during server setup.
  // Register new unified config and sync tools this.toolRegistry.registerMany(getConfigToolsV2(instance));