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));