powermcp 0.1.0__tar.gz

powermcp-0.1.0/.gitignore

@@ -0,0 +1,108 @@
+# Environments
+.venv/
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Python
+**/__pycache__/**
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# AI Tools
+.claude/
+.gemini/
+.cursor/
+
+# Personal Configuration
+myconfig.json
+
+# IDEs and Editors
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Power System Tools Output & Temporary Files
+
+# PSLF / ProvisoHD
+soln.log
+output.crf
+output.sum
+temp.wrk
+cont.otg
+contproc-run-status.csv
+control.cntl
+datacheck.txt
+runs.cases
+duplicate.txt
+sstools.sav
+term.log
+case.pcrf
+output.pcrf
+Output.xlsx
+run.bat
+template.ctab
+contproc-run-status_contingency_errors.csv
+font-color
+gediwork.drw
+gediworkScan.drw
+winter.sav
+summer.drw
+summer.sav
+hs_err*
+basecase.sav
+temp.sav
+
+# PyLTSpice
+simulation_output/
+*.raw
+*.net
+*.log
+*.plt
+
+# ANDES
+.andes_runs/
+mcp_server.log
+pf_*/
+td_*/
+eig_*/
+
+# PyPSA
+*.nc
+
+# PowerWorld
+*.pwd
+# Note: .pwb files might be case files you want to keep (like IEEE 39 bus.pwb), 
+# so we don't ignore them globally.
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# PSCAD generated docs (can be re-synced)
+PSCAD/docs/

powermcp-0.1.0/ANDES/README.md

@@ -0,0 +1,49 @@
+# ANDES MCP Server
+
+MCP server for ANDES (Python-based power system dynamic analysis), enabling power flow and time-domain simulation.
+
+> **Note:** This MCP server is under active development and may need further modification to handle some internal code output and ensure full compatibility with all ANDES features.
+
+## Requirements
+
+- Python 3.10 or higher
+- [ANDES](https://andes.readthedocs.io/)
+
+Install dependencies:
+```bash
+pip install -r requirements.txt
+```
+
+## Usage
+
+Run the MCP server:
+```bash
+python andes_mcp.py
+```
+
+Configure in your MCP client (e.g., Cursor, Claude Desktop):
+```json
+{
+  "mcpServers": {
+    "andes": {
+      "command": "python",
+      "args": ["ANDES/andes_mcp.py"]
+    }
+  }
+}
+```
+
+## Available Tools
+
+- **run_power_flow(file_path: str)**: Run power flow analysis on a power system case file.
+- **run_time_domain_simulation(step_size: float = 0.01, t_end: float = 10.0)**: Run time domain simulation on the currently loaded power system.
+- **run_eigenvalue_analysis(file_path: str)**: Run eigenvalue analysis on a power system case.
+- **get_system_info()**: Get information about the currently loaded power system.
+
+## Prompt Example
+
+Could you run power flow on the Kundur case at `yourpath\PowerMCP\ANDES\kundur_full.json` using ANDES and summarize the results? Then call `get_system_info` to show the system details.
+
+## Resources
+
+- [ANDES Documentation](https://andes.readthedocs.io/)

powermcp-0.1.0/ANDES/andes_mcp.py

@@ -0,0 +1,339 @@
+import andes
+import logging
+import os
+import io
+import sys
+import shutil
+import json
+from pathlib import Path
+from contextlib import redirect_stdout, redirect_stderr
+from mcp.server.fastmcp import FastMCP
+from typing import Dict, Any
+
+# Storage directory resolved lazily (no filesystem writes at import time)
+def _andes_runs_dir():
+    try:
+        from powermcp.paths import runs_dir
+        return str(runs_dir("andes"))
+    except Exception:
+        import os
+        d = os.path.join(os.path.expanduser("~"), ".powermcp", "runs", "andes")
+        os.makedirs(d, exist_ok=True)
+        return d
+
+# Configure logging (stream only at import; file handler attached lazily)
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+    handlers=[
+        logging.StreamHandler()
+    ]
+)
+
+# Configure ANDES logging
+andes.config_logger(stream_level=50)  # 50 is CRITICAL level
+logging.getLogger('andes').setLevel(logging.WARNING)
+logging.getLogger('numpy').setLevel(logging.WARNING)
+logging.getLogger('scipy').setLevel(logging.WARNING)
+logger = logging.getLogger(__name__)
+
+# Attach a file handler lazily on first tool use (no log file opened at import)
+_file_handler_added = False
+
+def _ensure_file_logging():
+    global _file_handler_added
+    if _file_handler_added:
+        return
+    try:
+        fh = logging.FileHandler(os.path.join(_andes_runs_dir(), 'mcp_server.log'))
+        fh.setFormatter(logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s'))
+        logging.getLogger().addHandler(fh)
+    except Exception:
+        pass
+    _file_handler_added = True
+
+# Initialize MCP server
+mcp = FastMCP("ANDES MCP Server")
+
+# Initialize system state
+system_state: Dict[str, Any] = {}
+
+@mcp.tool()
+def run_power_flow(file_path: str) -> Dict[str, Any]:
+    """Run power flow analysis on a power system case
+    
+    Args:
+        file_path: Path to the case file
+    
+    Returns:
+        Dict containing power flow results and output information
+    """
+    try:
+        _ensure_file_logging()
+        # Convert to absolute path if not already
+        abs_file_path = os.path.abspath(file_path)
+        if not os.path.exists(abs_file_path):
+            return {
+                "status": "error",
+                "message": f"Input file not found: {abs_file_path}"
+            }
+
+        # Create a unique directory for this run
+        run_dir = os.path.join(_andes_runs_dir(), f"pf_{Path(abs_file_path).stem}")
+        os.makedirs(run_dir, exist_ok=True)
+        
+        # Copy input file to run directory
+        input_file = os.path.join(run_dir, os.path.basename(abs_file_path))
+        shutil.copy2(abs_file_path, input_file)
+        
+        # Save current directory and change to run directory
+        original_dir = os.getcwd()
+        os.chdir(run_dir)
+        
+        try:
+            # Capture stdout/stderr
+            f_out = io.StringIO()
+            f_err = io.StringIO()
+            
+            with redirect_stdout(f_out), redirect_stderr(f_err):
+                # Run power flow with minimal output
+                ss = andes.run(input_file, no_output=True, verbose=50)
+                
+                # Store system state for other tools
+                system_state['current_system'] = ss
+                
+                # Extract key power flow results
+                pflow_results = {
+                    "converged": ss.PFlow.converged,
+                    "iterations": ss.PFlow.niter if hasattr(ss.PFlow, 'niter') else 0,
+                    "max_mis": float(ss.PFlow.mis[-1]) if hasattr(ss.PFlow, 'mis') and len(ss.PFlow.mis) > 0 else 0.0,
+                    "time": float(ss.PFlow.t) if hasattr(ss.PFlow, 't') else 0.0
+                }
+                
+                # Get list of output files
+                output_files = [f for f in os.listdir(run_dir) if os.path.isfile(os.path.join(run_dir, f))]
+                
+                result = {
+                    "status": "success",
+                    "message": "Power flow completed successfully" if ss.PFlow.converged else "Power flow did not converge",
+                    "power_flow": pflow_results,
+                    "output_dir": run_dir,
+                    "output_files": output_files,
+                    "stdout": f_out.getvalue(),
+                    "stderr": f_err.getvalue()
+                }
+                
+                return result
+                
+        finally:
+            # Always change back to original directory
+            os.chdir(original_dir)
+            
+    except Exception as e:
+        logger.error(f"Error in power flow analysis: {str(e)}")
+        return {
+            "status": "error",
+            "message": str(e)
+        }
+
+@mcp.tool()
+def run_time_domain_simulation(step_size: float = 0.01, t_end: float = 10.0) -> Dict[str, Any]:
+    """Run time domain simulation on the currently loaded power system
+    
+    Args:
+        step_size: Time step size in seconds
+        t_end: End time in seconds
+    
+    Returns:
+        Dict containing simulation results and output information
+    """
+    try:
+        _ensure_file_logging()
+        if 'current_system' not in system_state:
+            return {
+                "status": "error",
+                "message": "No power system currently loaded. Run power flow first."
+            }
+
+        ss = system_state['current_system']
+
+        # Create a unique directory for this run
+        run_dir = os.path.join(_andes_runs_dir(), f"tds_{int(t_end)}s")
+        os.makedirs(run_dir, exist_ok=True)
+        
+        # Save current directory and change to run directory
+        original_dir = os.getcwd()
+        os.chdir(run_dir)
+        
+        try:
+            # Capture stdout/stderr
+            f_out = io.StringIO()
+            f_err = io.StringIO()
+            
+            with redirect_stdout(f_out), redirect_stderr(f_err):
+                # Configure time domain simulation parameters
+                ss.TDS.config.tf = t_end
+                ss.TDS.config.tstep = step_size
+                
+                # Run time domain simulation
+                ss.TDS.init()
+                success = ss.TDS.run()
+                
+                # Extract key simulation results
+                tds_results = {
+                    "t_array": ss.dae.t.tolist() if hasattr(ss.dae, 't') else [],
+                    "step_size": float(ss.TDS.config.tstep),
+                    "t_end": float(ss.TDS.config.tf),
+                    "success": success,
+                    "status": "completed" if success else "failed"
+                }
+                
+                # Get list of output files
+                output_files = [f for f in os.listdir(run_dir) if os.path.isfile(os.path.join(run_dir, f))]
+                
+                result = {
+                    "status": "success",
+                    "message": "Time domain simulation completed successfully" if success else "Time domain simulation failed",
+                    "simulation": tds_results,
+                    "output_dir": run_dir,
+                    "output_files": output_files,
+                    "stdout": f_out.getvalue(),
+                    "stderr": f_err.getvalue()
+                }
+                
+                return result
+                
+        finally:
+            # Always change back to original directory
+            os.chdir(original_dir)
+            
+    except Exception as e:
+        logger.error(f"Error in time domain simulation: {str(e)}")
+        return {
+            "status": "error",
+            "message": str(e)
+        }
+
+@mcp.tool()
+def run_eigenvalue_analysis(file_path: str) -> Dict[str, Any]:
+    """Run eigenvalue analysis on a power system case
+    
+    Args:
+        file_path: Path to the case file
+    
+    Returns:
+        Dict containing the eigenvalue analysis results
+    """
+    try:
+        _ensure_file_logging()
+        # Convert to absolute path if relative
+        abs_file_path = os.path.abspath(file_path)
+
+        if not os.path.exists(abs_file_path):
+            return {
+                "status": "error",
+                "message": f"File not found: {file_path}"
+            }
+
+        # Create a unique directory for this run
+        run_dir = os.path.join(_andes_runs_dir(), f"eig_{Path(abs_file_path).stem}")
+        os.makedirs(run_dir, exist_ok=True)
+        
+        # Save current directory and change to run directory
+        original_dir = os.getcwd()
+        os.chdir(run_dir)
+        
+        try:
+            # Capture stdout/stderr
+            f_out = io.StringIO()
+            f_err = io.StringIO()
+            
+            with redirect_stdout(f_out), redirect_stderr(f_err):
+                # Load the system
+                ss = andes.run(abs_file_path, no_output=True)
+                system_state['current_system'] = ss
+                
+                # Run eigenvalue analysis
+                success = ss.EIG.run()
+                
+                # Extract eigenvalue results
+                eig_results = {
+                    "n_eigenvalues": len(ss.EIG.mu) if hasattr(ss.EIG, 'mu') else 0,
+                    "eigenvalues": ss.EIG.mu.tolist() if hasattr(ss.EIG, 'mu') else [],
+                    "eigenvectors": ss.EIG.vectors.tolist() if hasattr(ss.EIG, 'vectors') else [],
+                    "participation_factors": ss.EIG.pfactors.tolist() if hasattr(ss.EIG, 'pfactors') else [],
+                    "state_variables": ss.EIG.state_desc if hasattr(ss.EIG, 'state_desc') else [],
+                    "success": success
+                }
+                
+                # Get list of output files
+                output_files = [f for f in os.listdir(run_dir) if os.path.isfile(os.path.join(run_dir, f))]
+                
+                result = {
+                    "status": "success",
+                    "message": "Eigenvalue analysis completed successfully" if success else "Eigenvalue analysis failed",
+                    "analysis": eig_results,
+                    "output_dir": run_dir,
+                    "output_files": output_files,
+                    "stdout": f_out.getvalue(),
+                    "stderr": f_err.getvalue()
+                }
+                
+                return result
+                
+        finally:
+            # Always change back to original directory
+            os.chdir(original_dir)
+            
+    except Exception as e:
+        logger.error(f"Error in eigenvalue analysis: {str(e)}")
+        return {
+            "status": "error",
+            "message": str(e)
+        }
+
+@mcp.tool()
+def get_system_info() -> Dict[str, Any]:
+    """
+    Get information about the currently loaded power system
+    
+    Returns:
+        Dict containing system information
+    """
+    if 'current_system' not in system_state:
+        return {
+            "status": "error",
+            "message": "No power system currently loaded"
+        }
+    
+    try:
+        # Capture stdout/stderr
+        f_out = io.StringIO()
+        f_err = io.StringIO()
+        
+        with redirect_stdout(f_out), redirect_stderr(f_err):
+            ss = system_state['current_system']
+            info = {
+                "status": "success",
+                "num_buses": len(ss.Bus.idx.v) if hasattr(ss.Bus, 'idx') else 0,
+                "num_generators": (len(ss.PV.idx.v) if hasattr(ss.PV, 'idx') else 0) + 
+                                (len(ss.GENROU.idx.v) if hasattr(ss.GENROU, 'idx') else 0),
+                "system_name": ss.name if hasattr(ss, 'name') else "Unknown",
+                "base_mva": float(ss.config.mva) if hasattr(ss.config, 'mva') else 100.0,
+                "stdout": f_out.getvalue(),
+                "stderr": f_err.getvalue()
+            }
+        
+        return info
+    except Exception as e:
+        logger.error(f"Error getting system info: {str(e)}")
+        return {
+            "status": "error",
+            "message": str(e)
+        }
+
+
+if __name__ == "__main__":
+    print(f"Starting ANDES MCP Server")
+    print(f"Using storage directory: {_andes_runs_dir()}")
+    mcp.run(transport="stdio")