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