DollhouseMCP

Instructions

Implementation Reference

• src/server/tools/PersonaTools.ts:47-67 (handler)

  MCP tool definition including name, description, input schema, and handler function that executes the tool logic by calling server.importPersona(source, overwrite)

  {
    tool: {
      name: "import_persona",
      description: "Import a persona from a file path or JSON string",
      inputSchema: {
        type: "object",
        properties: {
          source: {
            type: "string",
            description: "File path to a .md or .json file, or a JSON string of the persona",
          },
          overwrite: {
            type: "boolean",
            description: "Overwrite if persona already exists (default: false)",
          },
        },
        required: ["source"],
      },
    },
    handler: (args: any) => server.importPersona(args.source, args.overwrite)
  }

• src/server/ServerSetup.ts:55-57 (registration)

  Registration of the persona tools (including import_persona) into the MCP tool registry during server setup

  // Register persona export/import tools (core functionality moved to element tools)
  this.toolRegistry.registerMany(getPersonaExportImportTools(instance));

• src/server/tools/PersonaTools.ts:51-64 (schema)

  Input schema validation for the import_persona tool

  inputSchema: {
    type: "object",
    properties: {
      source: {
        type: "string",
        description: "File path to a .md or .json file, or a JSON string of the persona",
      },
      overwrite: {
        type: "boolean",
        description: "Overwrite if persona already exists (default: false)",
      },
    },
    required: ["source"],
  },

• src/persona/export-import/PersonaImporter.ts:35-80 (helper)

  Core helper class with detailed import logic, validation, security checks, and file handling likely used by server.importPersona

  async importPersona(source: string, existingPersonas: Map<string, Persona>, overwrite = false): Promise<ImportResult> {
    try {
      // Determine source type
      let personaData: ExportedPersona | null = null;
  
      // Check if it's a file path
      if (source.startsWith('/') || source.startsWith('./') || source.endsWith('.md') || source.endsWith('.json')) {
        personaData = await this.importFromFile(source);
      } 
      // Check if it's base64 encoded
      else if (this.isBase64(source)) {
        personaData = await this.importFromBase64(source);
      }
      // Try parsing as JSON directly
      else {
        try {
          const parsed = JSON.parse(source);
          if (this.isExportBundle(parsed)) {
            return this.importBundle(parsed, existingPersonas, overwrite);
          } else if (this.isExportedPersona(parsed)) {
            personaData = parsed;
          }
        } catch {
          // Not JSON, might be raw markdown
          return this.importFromMarkdown(source, existingPersonas, overwrite);
        }
      }
  
      if (!personaData) {
        return {
          success: false,
          message: "Could not parse import source. Please provide a file path, JSON string, or base64 encoded data."
        };
      }
  
      // Validate and create persona
      return await this.createPersonaFromExport(personaData, existingPersonas, overwrite);
  
    } catch (error) {
      logger.error('Import error', error);
      return {
        success: false,
        message: `Import failed: ${error instanceof Error ? error.message : String(error)}`
      };
    }
  }

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

  Function that provides the tool definitions and handlers for registration, called during server setup

  export function getPersonaExportImportTools(server: IToolHandler): Array<{ tool: ToolDefinition; handler: any }> {