@mseep/csv-editor 1.0.0

package/examples/history_demo.py

@@ -0,0 +1,317 @@
+#!/usr/bin/env python3
+"""Demonstration of history tracking with undo/redo functionality."""
+
+import asyncio
+import tempfile
+import os
+import pandas as pd
+from pathlib import Path
+import json
+
+# Setup path for imports
+import sys
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from src.csv_editor.models.csv_session import CSVSession
+from src.csv_editor.models.history_manager import HistoryStorage
+from src.csv_editor.models.data_models import OperationType
+
+
+async def demonstrate_history():
+    """Demonstrate history tracking with undo/redo capabilities."""
+    
+    print("=" * 60)
+    print("CSV Editor History & Undo/Redo Demonstration")
+    print("=" * 60)
+    
+    # Create initial data
+    initial_data = pd.DataFrame({
+        'product': ['Laptop', 'Mouse', 'Keyboard', 'Monitor'],
+        'price': [999.99, 29.99, 79.99, 299.99],
+        'stock': [50, 200, 150, 75],
+        'category': ['Electronics', 'Accessories', 'Accessories', 'Electronics']
+    })
+    
+    # Create session with history enabled (JSON persistence)
+    session = CSVSession(
+        enable_history=True,
+        history_storage=HistoryStorage.JSON
+    )
+    
+    # Load data
+    temp_file = os.path.join(tempfile.gettempdir(), "demo_data.csv")
+    initial_data.to_csv(temp_file, index=False)
+    session.load_data(initial_data, file_path=temp_file)
+    
+    print(f"\n✓ Created session with history tracking")
+    print(f"Initial data:\n{session.df}\n")
+    
+    # Perform a series of operations
+    print("-" * 40)
+    print("Performing operations...")
+    print("-" * 40)
+    
+    # Operation 1: Increase prices
+    print("\n1. Increasing all prices by 10%")
+    session.df['price'] = session.df['price'] * 1.1
+    session.record_operation(OperationType.TRANSFORM, {"operation": "price_increase_10%"})
+    print(f"Prices after increase:\n{session.df['price'].tolist()}")
+    
+    # Operation 2: Filter low stock
+    print("\n2. Filtering items with stock >= 100")
+    session.df = session.df[session.df['stock'] >= 100]
+    session.record_operation(OperationType.FILTER, {"condition": "stock >= 100"})
+    print(f"Products after filter: {session.df['product'].tolist()}")
+    
+    # Operation 3: Add discount column
+    print("\n3. Adding discount column")
+    session.df['discount'] = 0.15
+    session.record_operation(OperationType.ADD_COLUMN, {"column": "discount", "value": 0.15})
+    print(f"Columns: {session.df.columns.tolist()}")
+    
+    # Operation 4: Sort by price
+    print("\n4. Sorting by price (descending)")
+    session.df = session.df.sort_values('price', ascending=False)
+    session.record_operation(OperationType.SORT, {"column": "price", "ascending": False})
+    print(f"Products after sort: {session.df['product'].tolist()}")
+    
+    # Show current history
+    print("\n" + "=" * 60)
+    print("Current History")
+    print("=" * 60)
+    history_result = session.get_history()
+    if history_result["success"]:
+        print(f"Total operations: {history_result['statistics']['total_operations']}")
+        print(f"Current position: {history_result['statistics']['current_position']}")
+        print(f"Can undo: {history_result['statistics']['can_undo']}")
+        print(f"Can redo: {history_result['statistics']['can_redo']}")
+        
+        print("\nOperations:")
+        for op in history_result['history']:
+            print(f"  [{op['index']}] {op['operation_type']} - {op['timestamp']}")
+            if op['is_current']:
+                print(f"      ^ Current position")
+    
+    # Demonstrate undo
+    print("\n" + "=" * 60)
+    print("Undo Operations")
+    print("=" * 60)
+    
+    print("\n1. Undoing last operation (sort)...")
+    undo_result = await session.undo()
+    if undo_result["success"]:
+        print(f"✓ {undo_result['message']}")
+        print(f"Products order: {session.df['product'].tolist() if session.df is not None else 'N/A'}")
+    
+    print("\n2. Undoing again (add discount column)...")
+    undo_result = await session.undo()
+    if undo_result["success"]:
+        print(f"✓ {undo_result['message']}")
+        print(f"Columns: {session.df.columns.tolist() if session.df is not None else 'N/A'}")
+    
+    print("\n3. Undoing once more (filter)...")
+    undo_result = await session.undo()
+    if undo_result["success"]:
+        print(f"✓ {undo_result['message']}")
+        print(f"Row count: {len(session.df) if session.df is not None else 0}")
+        print(f"Products: {session.df['product'].tolist() if session.df is not None else 'N/A'}")
+    
+    # Show history after undo
+    history_result = session.get_history()
+    print(f"\nCurrent position after undos: {history_result['statistics']['current_position']}")
+    print(f"Can redo: {history_result['statistics']['can_redo']}")
+    
+    # Demonstrate redo
+    print("\n" + "=" * 60)
+    print("Redo Operations")
+    print("=" * 60)
+    
+    print("\n1. Redoing (re-apply filter)...")
+    redo_result = await session.redo()
+    if redo_result["success"]:
+        print(f"✓ {redo_result['message']}")
+        print(f"Row count: {len(session.df) if session.df is not None else 0}")
+    
+    print("\n2. Redoing again (re-add discount column)...")
+    redo_result = await session.redo()
+    if redo_result["success"]:
+        print(f"✓ {redo_result['message']}")
+        print(f"Columns: {session.df.columns.tolist() if session.df is not None else 'N/A'}")
+    
+    # Perform a new operation (clears redo stack)
+    print("\n" + "=" * 60)
+    print("New Operation (clears redo stack)")
+    print("=" * 60)
+    
+    print("\nAdding a new column 'in_stock'...")
+    session.df['in_stock'] = True
+    session.record_operation(OperationType.ADD_COLUMN, {"column": "in_stock", "value": True})
+    print(f"Columns: {session.df.columns.tolist()}")
+    
+    history_result = session.get_history()
+    print(f"\nCan still redo? {history_result['statistics']['can_redo']} (should be False)")
+    
+    # Demonstrate restore to specific operation
+    print("\n" + "=" * 60)
+    print("Restore to Specific Operation")
+    print("=" * 60)
+    
+    # Get first operation ID
+    history_result = session.get_history()
+    if history_result["success"] and history_result["history"]:
+        first_op = history_result["history"][0]
+        print(f"\nRestoring to first operation: {first_op['operation_type']}")
+        
+        restore_result = await session.restore_to_operation(first_op['operation_id'])
+        if restore_result["success"]:
+            print(f"✓ {restore_result['message']}")
+            print(f"Data shape: {restore_result['shape']}")
+            print(f"Current data:\n{session.df}")
+    
+    # Export history
+    print("\n" + "=" * 60)
+    print("Export History")
+    print("=" * 60)
+    
+    # Export as JSON
+    history_file = os.path.join(tempfile.gettempdir(), "history_export.json")
+    if session.history_manager:
+        success = session.history_manager.export_history(history_file, "json")
+        if success:
+            print(f"✓ History exported to: {history_file}")
+            
+            # Show exported content
+            with open(history_file, 'r') as f:
+                history_data = json.load(f)
+            print(f"  Total operations: {history_data['total_operations']}")
+            print(f"  Exported at: {history_data['exported_at']}")
+    
+    # Show history statistics
+    print("\n" + "=" * 60)
+    print("History Statistics")
+    print("=" * 60)
+    
+    if session.history_manager:
+        stats = session.history_manager.get_statistics()
+        print(f"Total operations: {stats['total_operations']}")
+        print(f"Current position: {stats['current_position']}")
+        print(f"Snapshots saved: {stats['snapshots_count']}")
+        print(f"Storage type: {stats['storage_type']}")
+        print("\nOperation breakdown:")
+        for op_type, count in stats['operation_types'].items():
+            print(f"  {op_type}: {count}")
+    
+    # Show persistence
+    print("\n" + "=" * 60)
+    print("History Persistence")
+    print("=" * 60)
+    
+    history_dir = session.history_manager.history_dir if session.history_manager else None
+    if history_dir:
+        print(f"History directory: {history_dir}")
+        
+        # List history files
+        history_files = list(Path(history_dir).glob(f"*{session.session_id}*"))
+        print(f"History files created: {len(history_files)}")
+        for hf in history_files:
+            print(f"  - {hf.name}")
+        
+        # Check snapshot directory
+        snapshot_dir = Path(history_dir) / "snapshots" / session.session_id
+        if snapshot_dir.exists():
+            snapshots = list(snapshot_dir.glob("*.pkl"))
+            print(f"Snapshots saved: {len(snapshots)}")
+    
+    print("\n✅ History demonstration completed!")
+    
+    return session
+
+
+async def demonstrate_history_recovery():
+    """Demonstrate recovering history from a previous session."""
+    
+    print("\n" + "=" * 60)
+    print("History Recovery from Previous Session")
+    print("=" * 60)
+    
+    # Create a session and perform operations
+    print("\n1. Creating initial session with operations...")
+    session1 = CSVSession(
+        session_id="demo-recovery-session",
+        enable_history=True,
+        history_storage=HistoryStorage.JSON
+    )
+    
+    data = pd.DataFrame({
+        'item': ['A', 'B', 'C'],
+        'value': [10, 20, 30]
+    })
+    
+    session1.load_data(data)
+    
+    # Perform operations
+    session1.df['value'] = session1.df['value'] * 2
+    session1.record_operation(OperationType.TRANSFORM, {"operation": "double_values"})
+    
+    session1.df['status'] = 'active'
+    session1.record_operation(OperationType.ADD_COLUMN, {"column": "status"})
+    
+    print(f"  Operations performed: 2")
+    print(f"  Final data:\n{session1.df}")
+    
+    # Simulate session end
+    session1_id = session1.session_id
+    del session1
+    
+    print("\n2. Session ended. Creating new session with same ID...")
+    
+    # Create new session with same ID - should load history
+    session2 = CSVSession(
+        session_id=session1_id,
+        enable_history=True,
+        history_storage=HistoryStorage.JSON
+    )
+    
+    # Load the data (in real scenario, would load from file)
+    session2.load_data(data)
+    
+    # Check if history was recovered
+    history_result = session2.get_history()
+    if history_result["success"]:
+        print(f"✓ History recovered! Found {history_result['statistics']['total_operations']} operations")
+        
+        # Can we undo operations from previous session?
+        print("\n3. Testing undo on recovered history...")
+        if history_result['statistics']['can_undo']:
+            undo_result = await session2.undo()
+            if undo_result["success"]:
+                print(f"✓ Successfully undid operation from previous session!")
+                print(f"  Operation: {undo_result['operation']['operation_type']}")
+    
+    print("\n✅ History recovery demonstration completed!")
+
+
+async def main():
+    """Run all history demonstrations."""
+    
+    # Demo 1: Basic history with undo/redo
+    session = await demonstrate_history()
+    
+    # Demo 2: History recovery
+    await demonstrate_history_recovery()
+    
+    print("\n" + "=" * 60)
+    print("Key Features Demonstrated")
+    print("=" * 60)
+    print("✓ Operation history tracking with timestamps")
+    print("✓ Persistent history storage (JSON/Pickle)")
+    print("✓ Undo/Redo functionality")
+    print("✓ Restore to any previous operation")
+    print("✓ History export (JSON/CSV)")
+    print("✓ History recovery across sessions")
+    print("✓ Automatic snapshots for data recovery")
+    print("✓ History statistics and analysis")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

package/examples/test_default_autosave.py

@@ -0,0 +1,124 @@
+#!/usr/bin/env python3
+"""Test that auto-save is enabled by default and works correctly."""
+
+import asyncio
+import tempfile
+import os
+import pandas as pd
+from pathlib import Path
+
+# Setup path for imports
+import sys
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from src.csv_editor.models.csv_session import CSVSession
+from src.csv_editor.models.data_models import OperationType
+
+
+async def test_default_autosave():
+    """Test that auto-save is enabled by default."""
+    
+    print("=" * 60)
+    print("Testing Default Auto-Save Configuration")
+    print("=" * 60)
+    
+    # Create a temporary CSV file
+    temp_dir = tempfile.mkdtemp()
+    test_file = os.path.join(temp_dir, "test_data.csv")
+    
+    # Create initial data
+    initial_data = pd.DataFrame({
+        'id': [1, 2, 3],
+        'name': ['Alice', 'Bob', 'Charlie'],
+        'value': [100, 200, 300]
+    })
+    
+    # Save initial data
+    initial_data.to_csv(test_file, index=False)
+    print(f"\n✓ Created test file: {test_file}")
+    print(f"Initial content:\n{initial_data}")
+    
+    # Create session WITHOUT explicitly configuring auto-save
+    session = CSVSession()  # Using defaults
+    
+    # Check default auto-save configuration
+    print("\n" + "-" * 40)
+    print("Default Auto-Save Configuration:")
+    print("-" * 40)
+    config = session.auto_save_config
+    print(f"Enabled: {config.enabled}")
+    print(f"Mode: {config.mode.value}")
+    print(f"Strategy: {config.strategy.value}")
+    
+    # Verify defaults
+    assert config.enabled == True, "Auto-save should be enabled by default"
+    assert config.mode.value == "after_operation", "Mode should be 'after_operation' by default"
+    assert config.strategy.value == "overwrite", "Strategy should be 'overwrite' by default"
+    print("\n✅ All defaults are correct!")
+    
+    # Load the CSV file
+    df = pd.read_csv(test_file)
+    session.load_data(df, file_path=test_file)
+    
+    print("\n" + "-" * 40)
+    print("Testing Auto-Save on Operations:")
+    print("-" * 40)
+    
+    # Perform an operation
+    print("\n1. Doubling all values...")
+    session.df['value'] = session.df['value'] * 2
+    session.record_operation(OperationType.TRANSFORM, {"operation": "double_values"})
+    
+    # Trigger auto-save (should happen automatically after operation)
+    result = await session.trigger_auto_save_if_needed()
+    print(f"   Auto-save triggered: {result is not None}")
+    
+    # Read the file to verify it was updated
+    saved_df = pd.read_csv(test_file)
+    print(f"   Values in file after operation: {saved_df['value'].tolist()}")
+    assert saved_df['value'].tolist() == [200, 400, 600], "File should be auto-saved with new values"
+    print("   ✓ File was automatically updated!")
+    
+    # Perform another operation
+    print("\n2. Adding a new column...")
+    session.df['status'] = 'active'
+    session.record_operation(OperationType.ADD_COLUMN, {"column": "status"})
+    
+    # Trigger auto-save again
+    result = await session.trigger_auto_save_if_needed()
+    print(f"   Auto-save triggered: {result is not None}")
+    
+    # Verify the file has the new column
+    saved_df = pd.read_csv(test_file)
+    print(f"   Columns in file: {saved_df.columns.tolist()}")
+    assert 'status' in saved_df.columns, "New column should be in the saved file"
+    print("   ✓ New column was automatically saved!")
+    
+    # Show final file content
+    print("\n" + "-" * 40)
+    print("Final File Content:")
+    print("-" * 40)
+    print(saved_df)
+    
+    print("\n" + "=" * 60)
+    print("✅ Default Auto-Save Test Passed!")
+    print("=" * 60)
+    print("\nSummary:")
+    print("• Auto-save is ENABLED by default")
+    print("• Mode is 'after_operation' by default")
+    print("• Strategy is 'overwrite' by default")
+    print("• Original file is automatically updated after each operation")
+    print("• No manual configuration needed!")
+    
+    return test_file
+
+
+async def main():
+    """Run the test."""
+    test_file = await test_default_autosave()
+    print(f"\nTest file location: {test_file}")
+    print("(File has been automatically saved with all changes)")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

package/examples/update_consignee_example.py

@@ -0,0 +1,179 @@
+#!/usr/bin/env python3
+"""Example showing how to update the consignee name field using the new update_column function."""
+
+import asyncio
+from mcp_client import MCPClient
+
+
+async def update_consignee_example():
+    """Example of updating consignee field to keep only the company name."""
+    
+    # Initialize MCP client
+    client = MCPClient()
+    await client.connect("csv-editor")
+    
+    # Load the CSV file
+    print("Loading CSV file...")
+    result = await client.call_tool(
+        "load_csv",
+        {
+            "file_path": "/home/santosh/projects/csv-editor/tests/sample_data/123456/1753698447530_BOL_Lubecon USA LLC_GHY 1.csv"
+        }
+    )
+    session_id = result["session_id"]
+    print(f"Session created: {session_id}")
+    print(f"Loaded {result['row_count']} rows with {result['column_count']} columns")
+    
+    # Get current consignee value
+    print("\nGetting current consignee value...")
+    info_result = await client.call_tool(
+        "get_session_info",
+        {"session_id": session_id}
+    )
+    print(f"Columns: {info_result['columns'][:10]}...")  # Show first 10 columns
+    
+    # Method 1: Using 'split' operation to extract company name
+    print("\n--- Method 1: Using 'split' operation ---")
+    print("Extracting company name (everything before the dash)...")
+    
+    result = await client.call_tool(
+        "update_column",
+        {
+            "session_id": session_id,
+            "column": "Consignee Name",
+            "operation": "split",
+            "pattern": " -",  # Split on " -" (space and dash)
+            "value": 0  # Take the first part (index 0)
+        }
+    )
+    
+    if result["success"]:
+        print(f"✓ Column updated successfully!")
+        print(f"  Original: {result['original_sample'][0] if result['original_sample'] else 'N/A'}")
+        print(f"  Updated:  {result['updated_sample'][0] if result['updated_sample'] else 'N/A'}")
+    
+    # Export the result
+    print("\nExporting updated CSV...")
+    export_result = await client.call_tool(
+        "export_csv",
+        {
+            "session_id": session_id,
+            "file_path": "/tmp/updated_bol_method1.csv",
+            "format": "csv"
+        }
+    )
+    print(f"✓ Exported to: {export_result['file_path']}")
+    
+    # Close session
+    await client.call_tool("close_session", {"session_id": session_id})
+    
+    # Method 2: Using 'replace' operation with regex
+    print("\n--- Method 2: Using 'replace' with regex ---")
+    
+    # Load the file again
+    result = await client.call_tool(
+        "load_csv",
+        {
+            "file_path": "/home/santosh/projects/csv-editor/tests/sample_data/123456/1753698447530_BOL_Lubecon USA LLC_GHY 1.csv"
+        }
+    )
+    session_id = result["session_id"]
+    
+    print("Removing location information using regex...")
+    result = await client.call_tool(
+        "update_column",
+        {
+            "session_id": session_id,
+            "column": "Consignee Name",
+            "operation": "replace",
+            "pattern": r"\s*-.*$",  # Match everything from " -" to end of string
+            "replacement": ""  # Replace with empty string
+        }
+    )
+    
+    if result["success"]:
+        print(f"✓ Column updated successfully!")
+        print(f"  Original: {result['original_sample'][0] if result['original_sample'] else 'N/A'}")
+        print(f"  Updated:  {result['updated_sample'][0] if result['updated_sample'] else 'N/A'}")
+    
+    # Export the result
+    export_result = await client.call_tool(
+        "export_csv",
+        {
+            "session_id": session_id,
+            "file_path": "/tmp/updated_bol_method2.csv",
+            "format": "csv"
+        }
+    )
+    print(f"✓ Exported to: {export_result['file_path']}")
+    
+    # Close session
+    await client.call_tool("close_session", {"session_id": session_id})
+    
+    # Method 3: Using 'extract' operation
+    print("\n--- Method 3: Using 'extract' with regex ---")
+    
+    # Load the file again
+    result = await client.call_tool(
+        "load_csv",
+        {
+            "file_path": "/home/santosh/projects/csv-editor/tests/sample_data/123456/1753698447530_BOL_Lubecon USA LLC_GHY 1.csv"
+        }
+    )
+    session_id = result["session_id"]
+    
+    print("Extracting company name using regex...")
+    result = await client.call_tool(
+        "update_column",
+        {
+            "session_id": session_id,
+            "column": "Consignee Name",
+            "operation": "extract",
+            "pattern": r"^([^-]+)",  # Extract everything before the first dash
+        }
+    )
+    
+    if result["success"]:
+        print(f"✓ Column updated successfully!")
+        print(f"  Original: {result['original_sample'][0] if result['original_sample'] else 'N/A'}")
+        print(f"  Updated:  {result['updated_sample'][0] if result['updated_sample'] else 'N/A'}")
+        
+        # Also clean up any trailing spaces
+        print("\nCleaning up whitespace...")
+        result = await client.call_tool(
+            "update_column",
+            {
+                "session_id": session_id,
+                "column": "Consignee Name",
+                "operation": "strip"
+            }
+        )
+        print(f"✓ Whitespace cleaned")
+    
+    # Export the result
+    export_result = await client.call_tool(
+        "export_csv",
+        {
+            "session_id": session_id,
+            "file_path": "/tmp/updated_bol_method3.csv",
+            "format": "csv"
+        }
+    )
+    print(f"✓ Exported to: {export_result['file_path']}")
+    
+    # Close session
+    await client.call_tool("close_session", {"session_id": session_id})
+    
+    await client.disconnect()
+    
+    print("\n✅ All methods completed successfully!")
+    print("\nThe new 'update_column' function makes it simple to:")
+    print("  • Extract parts of text (split, extract)")
+    print("  • Clean up text (strip, replace)")
+    print("  • Transform text (upper, lower)")
+    print("  • Fill missing values")
+    print("\nCheck the exported files in /tmp/ to see the results.")
+
+
+if __name__ == "__main__":
+    asyncio.run(update_consignee_example())

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@mseep/csv-editor",
+  "version": "1.0.0",
+  "description": "MCP server for comprehensive CSV file operations",
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "csv",
+    "excel",
+    "data",
+    "pandas",
+    "model-context-protocol",
+    "ai",
+    "claude",
+    "llm",
+    "mseep"
+  ],
+  "homepage": "https://github.com/santoshray02/csv-editor#readme",
+  "bugs": {
+    "url": "https://github.com/santoshray02/csv-editor/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/santoshray02/csv-editor.git"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Santosh Ray",
+    "email": "rayskumar02@gmail.com"
+  },
+  "type": "module",
+  "scripts": {
+    "build": "echo 'Python package - no JS build needed'",
+    "prepare": "echo 'Installing Python dependencies...'"
+  },
+  "mcp": {
+    "serverType": "python",
+    "command": "python",
+    "args": [
+      "-m",
+      "csv_editor.server"
+    ],
+    "env": {},
+    "capabilities": {
+      "tools": true,
+      "resources": true,
+      "prompts": true
+    }
+  },
+  "publisher": "mseep"
+}