attio-mcp 0.1.0

package/dist/utils/config-loader.js

@@ -0,0 +1,167 @@
+/**
+ * Configuration loader for Attio MCP Server
+ * Handles loading and merging of configuration files
+ */
+import fs from 'fs';
+import path from 'path';
+/**
+ * Default paths for configuration files
+ */
+const CONFIG_PATHS = {
+    default: path.resolve(process.cwd(), 'config/mappings/default.json'),
+    user: path.resolve(process.cwd(), 'config/mappings/user.json'),
+};
+/**
+ * Deep merges two objects, with values from the source object taking precedence
+ *
+ * @param target - The target object
+ * @param source - The source object to merge in
+ * @returns The merged object
+ */
+function deepMerge(target, source) {
+    const result = { ...target };
+    for (const key in source) {
+        if (Object.prototype.hasOwnProperty.call(source, key)) {
+            if (source[key] &&
+                typeof source[key] === 'object' &&
+                !Array.isArray(source[key])) {
+                // If both target and source have an object at this key, merge them
+                if (result[key] &&
+                    typeof result[key] === 'object' &&
+                    !Array.isArray(result[key])) {
+                    result[key] = deepMerge(result[key], source[key]);
+                }
+                else {
+                    // Otherwise, just use the source value
+                    result[key] = { ...source[key] };
+                }
+            }
+            else {
+                // For non-objects, use the source value
+                result[key] = source[key];
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Creates an empty mapping configuration with default structure
+ *
+ * @returns An empty mapping configuration
+ */
+function createEmptyConfig() {
+    return {
+        version: '1.0',
+        metadata: {
+            generated: new Date().toISOString(),
+            description: 'Generated empty configuration',
+        },
+        mappings: {
+            attributes: {
+                common: {},
+                objects: {},
+                custom: {},
+            },
+            objects: {},
+            lists: {},
+            relationships: {},
+        },
+    };
+}
+/**
+ * Loads a JSON configuration file
+ *
+ * @param filePath - Path to the JSON file
+ * @returns Parsed JSON object, or null if the file doesn't exist
+ */
+function loadJsonFile(filePath) {
+    try {
+        if (fs.existsSync(filePath)) {
+            const content = fs.readFileSync(filePath, 'utf8');
+            return JSON.parse(content);
+        }
+    }
+    catch (error) {
+        console.warn(`Warning: Failed to load config file ${filePath}:`, error);
+    }
+    return null;
+}
+/**
+ * Loads and merges the mapping configuration from default and user files
+ *
+ * @returns The merged mapping configuration
+ */
+export function loadMappingConfig() {
+    // Start with empty configuration
+    let config = createEmptyConfig();
+    // Load and merge the default configuration
+    const defaultConfig = loadJsonFile(CONFIG_PATHS.default);
+    if (defaultConfig) {
+        config = deepMerge(config, defaultConfig);
+    }
+    // Load and merge the user configuration
+    const userConfig = loadJsonFile(CONFIG_PATHS.user);
+    if (userConfig) {
+        config = deepMerge(config, userConfig);
+    }
+    return config;
+}
+/**
+ * Writes a mapping configuration to a file
+ *
+ * @param config - The configuration to write
+ * @param filePath - The file path to write to (defaults to user.json)
+ */
+export async function writeMappingConfig(config, filePath = CONFIG_PATHS.user) {
+    try {
+        // Ensure the directory exists
+        const dir = path.dirname(filePath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        // Update metadata
+        if (!config.metadata) {
+            config.metadata = {};
+        }
+        config.metadata.generated = new Date().toISOString();
+        // Write the file
+        const content = JSON.stringify(config, null, 2);
+        await fs.promises.writeFile(filePath, content, 'utf8');
+    }
+    catch (error) {
+        throw new Error(`Failed to write config file ${filePath}: ${error}`);
+    }
+}
+/**
+ * Updates a specific section of the mapping configuration
+ *
+ * @param section - The section to update (e.g., 'attributes.common')
+ * @param mappings - The mappings to set or merge
+ * @param merge - Whether to merge with existing mappings (default: true)
+ * @param filePath - The file path to write to (defaults to user.json)
+ */
+export async function updateMappingSection(section, mappings, merge = true, filePath = CONFIG_PATHS.user) {
+    // Load the current config
+    const config = loadMappingConfig();
+    // Parse the section path and navigate to the target section
+    const sectionParts = section.split('.');
+    let target = config.mappings;
+    for (let i = 0; i < sectionParts.length - 1; i++) {
+        const part = sectionParts[i];
+        if (!target[part]) {
+            target[part] = {};
+        }
+        target = target[part];
+    }
+    const finalPart = sectionParts[sectionParts.length - 1];
+    // Update the target section
+    if (merge && target[finalPart]) {
+        target[finalPart] = { ...target[finalPart], ...mappings };
+    }
+    else {
+        target[finalPart] = mappings;
+    }
+    // Write the updated config
+    await writeMappingConfig(config, filePath);
+}
+//# sourceMappingURL=config-loader.js.map

package/dist/utils/config-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-loader.js","sourceRoot":"","sources":["../../src/utils/config-loader.ts"],"names":[],"mappings":"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"}

package/dist/utils/config-migration.d.ts

@@ -0,0 +1,140 @@
+import { MappingConfig } from './config-loader.js';
+export type { MappingConfig };
+export interface MigrationResult {
+    success: boolean;
+    message: string;
+    backupPath?: string;
+    changesApplied?: string[];
+    errors?: string[];
+}
+export interface MigrationDetection {
+    needsMigration: boolean;
+    outdatedMappings: string[];
+    filePath: string;
+    exists: boolean;
+}
+/**
+ * Detects if user.json needs migration for postal code mappings
+ *
+ * Scans the user configuration file for outdated postal code mappings
+ * that use "zip" instead of the correct "postal_code" attribute name.
+ *
+ * @returns MigrationDetection object containing:
+ *   - needsMigration: whether migration is required
+ *   - outdatedMappings: array of problematic mappings found
+ *   - filePath: path to the user config file
+ *   - exists: whether the config file exists
+ *
+ * @example
+ * ```typescript
+ * const detection = detectMigrationNeeds();
+ * if (detection.needsMigration) {
+ *   console.log('Found outdated mappings:', detection.outdatedMappings);
+ * }
+ * ```
+ */
+export declare function detectMigrationNeeds(): MigrationDetection;
+/**
+ * Creates a timestamped backup of the user.json file
+ *
+ * Creates a backup in config/mappings/backup/ directory with ISO timestamp.
+ * Ensures the backup directory exists before creating the backup file.
+ *
+ * @returns Object containing:
+ *   - success: whether backup creation succeeded
+ *   - backupPath: path to the created backup file (if successful)
+ *   - error: error message (if failed)
+ *
+ * @example
+ * ```typescript
+ * const backup = createBackup();
+ * if (backup.success) {
+ *   console.log('Backup created at:', backup.backupPath);
+ * } else {
+ *   console.error('Backup failed:', backup.error);
+ * }
+ * ```
+ */
+export declare function createBackup(): {
+    success: boolean;
+    backupPath?: string;
+    error?: string;
+};
+/**
+ * Applies the postal code mapping migration to user.json
+ *
+ * Performs the complete migration workflow:
+ * 1. Detects if migration is needed
+ * 2. Creates a backup of the current configuration
+ * 3. Applies the postal code mapping fixes
+ * 4. Updates metadata to track migration history
+ *
+ * @returns MigrationResult object containing:
+ *   - success: whether the migration succeeded
+ *   - message: descriptive message about the operation
+ *   - backupPath: path to the backup file (if created)
+ *   - changesApplied: array of changes that were made
+ *   - errors: array of error messages (if any failures occurred)
+ *
+ * @example
+ * ```typescript
+ * const result = applyMigration();
+ * if (result.success) {
+ *   console.log('Migration completed:', result.message);
+ *   console.log('Changes:', result.changesApplied);
+ * } else {
+ *   console.error('Migration failed:', result.message);
+ * }
+ * ```
+ */
+export declare function applyMigration(): MigrationResult;
+/**
+ * Validates that the migration was applied correctly
+ *
+ * Checks if the user configuration still contains any outdated postal
+ * code mappings after migration has been applied.
+ *
+ * @returns Object containing:
+ *   - valid: whether the configuration passes validation
+ *   - issues: array of validation issues found (if any)
+ *
+ * @example
+ * ```typescript
+ * const validation = validateMigration();
+ * if (!validation.valid) {
+ *   console.error('Validation failed:', validation.issues);
+ * }
+ * ```
+ */
+export declare function validateMigration(): {
+    valid: boolean;
+    issues: string[];
+};
+/**
+ * Complete migration workflow with validation
+ *
+ * Main entry point for the migration process. Orchestrates detection,
+ * migration, and validation with optional dry-run mode.
+ *
+ * @param options Configuration options for the migration:
+ *   - dryRun: if true, only shows what would be changed without applying
+ *
+ * @returns MigrationResult object with complete operation status
+ *
+ * @example
+ * ```typescript
+ * // Preview changes without applying
+ * const preview = migrateUserConfig({ dryRun: true });
+ * console.log('Would apply:', preview.changesApplied);
+ *
+ * // Apply the migration
+ * const result = migrateUserConfig();
+ * if (result.success) {
+ *   console.log('Migration completed successfully');
+ * }
+ * ```
+ */
+export declare function migrateUserConfig(options?: {
+    dryRun?: boolean;
+}): MigrationResult;
+//# sourceMappingURL=config-migration.d.ts.map

package/dist/utils/config-migration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-migration.d.ts","sourceRoot":"","sources":["../../src/utils/config-migration.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAInD,YAAY,EAAE,aAAa,EAAE,CAAC;AAE9B,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,cAAc,EAAE,OAAO,CAAC;IACxB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;CACjB;AA0BD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,IAAI,kBAAkB,CA6CzD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,IAAI;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAsBA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,cAAc,IAAI,eAAe,CA6EhD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,IAAI;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAmBxE;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACjC,eAAe,CAmDjB"}

package/dist/utils/config-migration.js

@@ -0,0 +1,310 @@
+/**
+ * Configuration migration utility for Attio MCP Server
+ * Handles migration of user.json files to fix outdated mappings
+ */
+import fs from 'fs';
+import path from 'path';
+import logger from './logger.js';
+/**
+ * Known problematic mappings that need to be fixed
+ */
+const MAPPINGS_TO_FIX = {
+    ZIP: {
+        from: 'zip',
+        to: 'postal_code',
+        reason: 'zip attribute does not exist in Attio schema',
+    },
+    'Postal Code': {
+        from: 'zip',
+        to: 'postal_code',
+        reason: 'zip attribute does not exist in Attio schema',
+    },
+};
+/**
+ * Paths for configuration files
+ */
+const CONFIG_PATHS = {
+    user: path.resolve(process.cwd(), 'config/mappings/user.json'),
+    backup: path.resolve(process.cwd(), 'config/mappings/backup'),
+};
+/**
+ * Detects if user.json needs migration for postal code mappings
+ *
+ * Scans the user configuration file for outdated postal code mappings
+ * that use "zip" instead of the correct "postal_code" attribute name.
+ *
+ * @returns MigrationDetection object containing:
+ *   - needsMigration: whether migration is required
+ *   - outdatedMappings: array of problematic mappings found
+ *   - filePath: path to the user config file
+ *   - exists: whether the config file exists
+ *
+ * @example
+ * ```typescript
+ * const detection = detectMigrationNeeds();
+ * if (detection.needsMigration) {
+ *   console.log('Found outdated mappings:', detection.outdatedMappings);
+ * }
+ * ```
+ */
+export function detectMigrationNeeds() {
+    const result = {
+        needsMigration: false,
+        outdatedMappings: [],
+        filePath: CONFIG_PATHS.user,
+        exists: false,
+    };
+    // Check if user.json exists
+    if (!fs.existsSync(CONFIG_PATHS.user)) {
+        return result;
+    }
+    result.exists = true;
+    try {
+        const userConfig = JSON.parse(fs.readFileSync(CONFIG_PATHS.user, 'utf8'));
+        // Check common mappings for problematic postal code mappings
+        const commonMappings = userConfig.mappings?.attributes?.common || {};
+        for (const [displayName, expectedFix] of Object.entries(MAPPINGS_TO_FIX)) {
+            const currentMapping = commonMappings[displayName];
+            if (currentMapping === expectedFix.from) {
+                result.needsMigration = true;
+                result.outdatedMappings.push(`"${displayName}": "${currentMapping}" → should be "${expectedFix.to}"`);
+            }
+        }
+    }
+    catch (error) {
+        // If we can't parse the file, we can't migrate it
+        logger.warn('config-migration', 'Could not parse user configuration file for migration detection', {
+            filePath: CONFIG_PATHS.user,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+    return result;
+}
+/**
+ * Creates a timestamped backup of the user.json file
+ *
+ * Creates a backup in config/mappings/backup/ directory with ISO timestamp.
+ * Ensures the backup directory exists before creating the backup file.
+ *
+ * @returns Object containing:
+ *   - success: whether backup creation succeeded
+ *   - backupPath: path to the created backup file (if successful)
+ *   - error: error message (if failed)
+ *
+ * @example
+ * ```typescript
+ * const backup = createBackup();
+ * if (backup.success) {
+ *   console.log('Backup created at:', backup.backupPath);
+ * } else {
+ *   console.error('Backup failed:', backup.error);
+ * }
+ * ```
+ */
+export function createBackup() {
+    try {
+        // Ensure backup directory exists
+        if (!fs.existsSync(CONFIG_PATHS.backup)) {
+            fs.mkdirSync(CONFIG_PATHS.backup, { recursive: true });
+        }
+        // Create timestamped backup filename
+        const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+        const backupFileName = `user.json.backup.${timestamp}`;
+        const backupPath = path.join(CONFIG_PATHS.backup, backupFileName);
+        // Copy the current user.json to backup
+        fs.copyFileSync(CONFIG_PATHS.user, backupPath);
+        return { success: true, backupPath };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+/**
+ * Applies the postal code mapping migration to user.json
+ *
+ * Performs the complete migration workflow:
+ * 1. Detects if migration is needed
+ * 2. Creates a backup of the current configuration
+ * 3. Applies the postal code mapping fixes
+ * 4. Updates metadata to track migration history
+ *
+ * @returns MigrationResult object containing:
+ *   - success: whether the migration succeeded
+ *   - message: descriptive message about the operation
+ *   - backupPath: path to the backup file (if created)
+ *   - changesApplied: array of changes that were made
+ *   - errors: array of error messages (if any failures occurred)
+ *
+ * @example
+ * ```typescript
+ * const result = applyMigration();
+ * if (result.success) {
+ *   console.log('Migration completed:', result.message);
+ *   console.log('Changes:', result.changesApplied);
+ * } else {
+ *   console.error('Migration failed:', result.message);
+ * }
+ * ```
+ */
+export function applyMigration() {
+    const detection = detectMigrationNeeds();
+    if (!detection.exists) {
+        return {
+            success: true,
+            message: 'No user.json file found - no migration needed',
+        };
+    }
+    if (!detection.needsMigration) {
+        return {
+            success: true,
+            message: 'User configuration is already up to date - no migration needed',
+        };
+    }
+    try {
+        // Create backup first
+        const backup = createBackup();
+        if (!backup.success) {
+            return {
+                success: false,
+                message: `Failed to create backup: ${backup.error}`,
+                errors: [backup.error || 'Unknown backup error'],
+            };
+        }
+        // Load and modify the user config
+        const userConfig = JSON.parse(fs.readFileSync(CONFIG_PATHS.user, 'utf8'));
+        const changesApplied = [];
+        // Apply postal code mapping fixes
+        if (userConfig.mappings?.attributes?.common) {
+            for (const [displayName, fix] of Object.entries(MAPPINGS_TO_FIX)) {
+                const currentMapping = userConfig.mappings.attributes.common[displayName];
+                if (currentMapping === fix.from) {
+                    userConfig.mappings.attributes.common[displayName] = fix.to;
+                    changesApplied.push(`Updated "${displayName}": "${fix.from}" → "${fix.to}"`);
+                }
+            }
+        }
+        // Update metadata to track migration
+        if (!userConfig.metadata) {
+            userConfig.metadata = {};
+        }
+        userConfig.metadata.lastMigration = new Date().toISOString();
+        userConfig.metadata.migratedMappings = changesApplied;
+        // Write the updated config back to file
+        fs.writeFileSync(CONFIG_PATHS.user, JSON.stringify(userConfig, null, 2), 'utf8');
+        return {
+            success: true,
+            message: `Migration completed successfully. Applied ${changesApplied.length} changes.`,
+            backupPath: backup.backupPath,
+            changesApplied,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            message: `Migration failed: ${error instanceof Error ? error.message : String(error)}`,
+            errors: [error instanceof Error ? error.message : String(error)],
+        };
+    }
+}
+/**
+ * Validates that the migration was applied correctly
+ *
+ * Checks if the user configuration still contains any outdated postal
+ * code mappings after migration has been applied.
+ *
+ * @returns Object containing:
+ *   - valid: whether the configuration passes validation
+ *   - issues: array of validation issues found (if any)
+ *
+ * @example
+ * ```typescript
+ * const validation = validateMigration();
+ * if (!validation.valid) {
+ *   console.error('Validation failed:', validation.issues);
+ * }
+ * ```
+ */
+export function validateMigration() {
+    const detection = detectMigrationNeeds();
+    if (!detection.exists) {
+        return { valid: true, issues: [] };
+    }
+    if (detection.needsMigration) {
+        return {
+            valid: false,
+            issues: [
+                `Migration incomplete. Still found outdated mappings: ${detection.outdatedMappings.join(', ')}`,
+            ],
+        };
+    }
+    return { valid: true, issues: [] };
+}
+/**
+ * Complete migration workflow with validation
+ *
+ * Main entry point for the migration process. Orchestrates detection,
+ * migration, and validation with optional dry-run mode.
+ *
+ * @param options Configuration options for the migration:
+ *   - dryRun: if true, only shows what would be changed without applying
+ *
+ * @returns MigrationResult object with complete operation status
+ *
+ * @example
+ * ```typescript
+ * // Preview changes without applying
+ * const preview = migrateUserConfig({ dryRun: true });
+ * console.log('Would apply:', preview.changesApplied);
+ *
+ * // Apply the migration
+ * const result = migrateUserConfig();
+ * if (result.success) {
+ *   console.log('Migration completed successfully');
+ * }
+ * ```
+ */
+export function migrateUserConfig(options = {}) {
+    const detection = detectMigrationNeeds();
+    // Early return if no migration needed
+    if (!detection.exists) {
+        return {
+            success: true,
+            message: 'No user.json file found - no migration needed',
+        };
+    }
+    if (!detection.needsMigration) {
+        return {
+            success: true,
+            message: 'User configuration is already up to date - no migration needed',
+        };
+    }
+    // Dry run mode - just report what would be changed
+    if (options.dryRun) {
+        return {
+            success: true,
+            message: `Migration needed. Would fix: ${detection.outdatedMappings.join(', ')}`,
+            changesApplied: detection.outdatedMappings,
+        };
+    }
+    // Apply the migration
+    const migrationResult = applyMigration();
+    if (!migrationResult.success) {
+        return migrationResult;
+    }
+    // Validate the migration worked
+    const validation = validateMigration();
+    if (!validation.valid) {
+        return {
+            success: false,
+            message: `Migration applied but validation failed: ${validation.issues.join(', ')}`,
+            errors: validation.issues,
+            backupPath: migrationResult.backupPath,
+            changesApplied: migrationResult.changesApplied,
+        };
+    }
+    return migrationResult;
+}
+//# sourceMappingURL=config-migration.js.map

package/dist/utils/config-migration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-migration.js","sourceRoot":"","sources":["../../src/utils/config-migration.ts"],"names":[],"mappings":"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"}