documcp

Instructions

Implementation Reference

• src/memory/export-import.ts:447-489 (handler)

  Implementation of createMigrationPlan method handling 'create_plan' action for memory_migration tool

  async createMigrationPlan(
    sourceSchema: any,
    targetSchema: any,
    options?: {
      autoMap?: boolean;
      preserveStructure?: boolean;
      customMappings?: Record<string, string>;
    },
  ): Promise<MigrationPlan> {
    const plan: MigrationPlan = {
      sourceSystem: sourceSchema.system || "Unknown",
      targetSystem: "DocuMCP",
      mapping: {},
      transformations: [],
      validation: [],
      postProcessing: [],
    };
  
    // Auto-generate field mappings
    if (options?.autoMap !== false) {
      plan.mapping = this.generateFieldMappings(sourceSchema, targetSchema);
    }
  
    // Apply custom mappings
    if (options?.customMappings) {
      Object.assign(plan.mapping, options.customMappings);
    }
  
    // Generate transformations
    plan.transformations = this.generateTransformations(
      sourceSchema,
      targetSchema,
      plan.mapping,
    );
  
    // Generate validation rules
    plan.validation = this.generateValidationRules(targetSchema);
  
    // Generate post-processing steps
    plan.postProcessing = this.generatePostProcessingSteps(targetSchema);
  
    return plan;
  }

• src/memory/export-import.ts:494-551 (handler)

  Implementation of executeMigration method handling 'execute_migration' action for memory_migration tool

  async executeMigration(
    inputPath: string,
    migrationPlan: MigrationPlan,
    options?: Partial<ImportOptions>,
  ): Promise<ImportResult> {
    this.emit("migration_started", { inputPath, plan: migrationPlan });
  
    try {
      // Load source data
      const sourceData = await this.loadRawData(inputPath);
  
      // Apply transformations
      const transformedData = await this.applyTransformations(
        sourceData,
        migrationPlan,
      );
  
      // Convert to import format
      const importData = this.convertToImportFormat(
        transformedData,
        migrationPlan,
      );
  
      // Execute import with migration settings
      const importOptions: ImportOptions = {
        format: "json",
        mode: "merge",
        validation: "strict",
        conflictResolution: "merge",
        backup: true,
        dryRun: false,
        ...options,
        transformation: {
          enabled: true,
          rules: migrationPlan.transformations.map((t) => ({
            field: t.target,
            operation: t.type as any,
            params: { source: t.source, operation: t.operation },
          })),
        },
      };
  
      const result = await this.processImportData(importData, importOptions);
  
      // Execute post-processing
      if (migrationPlan.postProcessing.length > 0) {
        await this.executePostProcessing(migrationPlan.postProcessing);
      }
  
      this.emit("migration_completed", { result });
      return result;
    } catch (error) {
      this.emit("migration_error", {
        error: error instanceof Error ? error.message : String(error),
      });
      throw error;
    }
  }

• src/memory/export-import.ts:573-636 (handler)

  Implementation of validateCompatibility method handling 'validate_compatibility' action for memory_migration tool

  async validateCompatibility(
    sourcePath: string,
    _targetSystem: string = "DocuMCP",
  ): Promise<{
    compatible: boolean;
    issues: string[];
    recommendations: string[];
    migrationRequired: boolean;
  }> {
    try {
      const format = await this.detectFormat(sourcePath);
      const sampleData = await this.loadSampleData(sourcePath, format);
  
      const issues: string[] = [];
      const recommendations: string[] = [];
      let compatible = true;
      let migrationRequired = false;
  
      // Check format compatibility
      if (!this.getSupportedFormats().import.includes(format)) {
        issues.push(`Unsupported format: ${format}`);
        compatible = false;
      }
  
      // Check schema compatibility
      const schemaIssues = this.validateSchema(sampleData);
      if (schemaIssues.length > 0) {
        issues.push(...schemaIssues);
        migrationRequired = true;
      }
  
      // Check data integrity
      const integrityIssues = this.validateDataIntegrity(sampleData);
      if (integrityIssues.length > 0) {
        issues.push(...integrityIssues);
        recommendations.push("Consider data cleaning before import");
      }
  
      // Generate recommendations
      if (migrationRequired) {
        recommendations.push("Create migration plan for schema transformation");
      }
  
      if (format === "csv") {
        recommendations.push(
          "Consider using JSON or JSONL for better data preservation",
        );
      }
  
      return {
        compatible,
        issues,
        recommendations,
        migrationRequired,
      };
    } catch (error) {
      return {
        compatible: false,
        issues: [error instanceof Error ? error.message : String(error)],
        recommendations: ["Verify file format and accessibility"],
        migrationRequired: false,
      };
    }
  }

• src/memory/index.ts:751-787 (schema)

  Tool schema definition including input schema matching the handler methods

  {
    name: "memory_migration",
    description:
      "Create and execute migration plans between different memory systems",
    inputSchema: {
      type: "object",
      properties: {
        action: {
          type: "string",
          enum: ["create_plan", "execute_migration", "validate_compatibility"],
          default: "create_plan",
        },
        sourcePath: { type: "string", description: "Source data path" },
        migrationPlan: {
          type: "object",
          properties: {
            sourceSystem: { type: "string" },
            targetSystem: { type: "string", default: "DocuMCP" },
            mapping: { type: "object" },
            transformations: { type: "array" },
            validation: { type: "array" },
            postProcessing: { type: "array", items: { type: "string" } },
          },
        },
        sourceSchema: { type: "object", description: "Source system schema" },
        targetSchema: { type: "object", description: "Target system schema" },
        options: {
          type: "object",
          properties: {
            autoMap: { type: "boolean", default: true },
            preserveStructure: { type: "boolean", default: true },
            customMappings: { type: "object" },
          },
        },
      },
    },
  },

• src/memory/export-import.ts:103-120 (schema)

  Type definitions for MigrationPlan used in the memory_migration tool implementation

  export interface MigrationPlan {
    sourceSystem: string;
    targetSystem: string;
    mapping: Record<string, string>;
    transformations: Array<{
      field: string;
      type: "rename" | "convert" | "merge" | "split" | "calculate";
      source: string | string[];
      target: string;
      operation?: string;
    }>;
    validation: Array<{
      field: string;
      rules: string[];
      required: boolean;
    }>;
    postProcessing: string[];
  }