MCP-enabled Gradio Space using PowerMCP as external dependency

.gitignore

@@ -0,0 +1,62 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+venv/
+ENV/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Gradio
+flagged/
+gradio_cached_examples/
+
+# Logs
+*.log
+logs/
+
+# Environment
+.env
+.env.local
+
+# Developer documentation (not needed for MCP users)
+DEPLOYMENT.md
+DEPLOYMENT_CHECKLIST.md
+EXAMPLES.md
+IMPLEMENTATION_SUMMARY.md
+QUICKSTART.md
+test_setup.py
+.env.example
+PowerMCP_Tutorial.pdf
+
+# Keep README.md as it's required for Hugging Face Space
+INSTALL.md
+MANIFEST.in
+setup.py

README.md

@@ -1,12 +1,240 @@
 ---
-title: PandaPower MCP
-emoji: 📈
-colorFrom: yellow
-colorTo: red
+title: PowerMCP - Power System Analysis MCP Server
+emoji: ⚡
+colorFrom: blue
+colorTo: green
 sdk: gradio
-sdk_version: 6.1.0
+sdk_version: 5.0.0
 app_file: app.py
 pinned: false
+license: mit
+tags:
+  - mcp
+  - power-systems
+  - electrical-engineering
+  - simulation
+  - model-context-protocol
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# ⚡ PowerMCP - Power System Analysis MCP Server
+
+[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io/)
+[![Gradio](https://img.shields.io/badge/Gradio-5.0+-orange)](https://gradio.app/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+This is an **MCP-enabled Hugging Face Space** for **PowerMCP** - an open-source collection of Model Context Protocol (MCP) servers for power system software. This Space can be added as an MCP tool to Claude Desktop, Cursor, or any other MCP-compatible client with a single click!
+
+## 🌟 What is PowerMCP?
+
+PowerMCP enables Large Language Models (LLMs) to directly interact with power system applications through the Model Context Protocol. It bridges the gap between AI and power system analysis, facilitating:
+
+- **Intelligent Power Flow Analysis**: Let AI perform complex power system simulations
+- **Automated Contingency Analysis**: AI-driven evaluation of grid contingencies  
+- **Dynamic Simulation**: Transient stability and time-domain analysis
+- **Energy System Optimization**: Network expansion and optimal power flow
+- **Professional Report Generation**: AI-generated analysis reports
+
+## 🔧 Supported Power System Tools
+
+### 🔌 pandapower
+Python-based power system analysis focusing on power flow and contingency analysis.
+- Create and manage power networks
+- AC/DC power flow calculations
+- N-1 and N-2 contingency analysis
+- Network modification and optimization
+
+### ⚡ PyPSA (Python for Power System Analysis)
+Energy system optimization and network expansion planning.
+- Multi-period optimization
+- Unit commitment and economic dispatch
+- Network expansion planning
+- Renewable integration analysis
+
+### 🌊 ANDES
+Dynamic simulation and transient stability analysis.
+- Time-domain simulation
+- Transient stability analysis
+- Small-signal stability
+- Dynamic model library
+
+## 🚀 Quick Start
+
+### Option 1: Install from GitHub (Local MCP Server)
+
+```bash
+# Install PowerMCP
+pip install git+https://github.com/Power-Agent/PowerMCP.git
+
+# Configure Claude Desktop (macOS)
+# Edit: ~/Library/Application Support/Claude/claude_desktop_config.json
+{
+  "mcpServers": {
+    "pandapower": {
+      "command": "powermcp-pandapower"
+    }
+  }
+}
+
+# Restart Claude Desktop and start using PowerMCP!
+```
+
+See [INSTALL.md](INSTALL.md) for detailed installation instructions.
+
+### Option 2: Use Hugging Face Space as MCP Tool
+
+1. **Install an MCP Client**:
+   - [Claude Desktop](https://claude.ai/download)
+   - [Cursor](https://cursor.sh/)
+   - [Windsurf](https://codeium.com/windsurf)
+   - VS Code with Cline extension
+
+2. **Add PowerMCP to Your Client**:
+   - Click the **MCP badge** on this Space
+   - Select "Add to MCP tools"
+   - Confirm when prompted
+   - The tools will be available instantly in your MCP client!
+
+3. **Use PowerMCP in Your AI Assistant**:
+   ```
+   Ask Claude: "Create a power network and run power flow analysis"
+   Ask Cursor: "Load test_case.json and perform N-1 contingency analysis"
+   ```
+
+### Option 2: Use Web Interface
+
+1. Select a power system tool (pandapower, PyPSA, or ANDES)
+2. Click "List Available Tools" to see all functions
+3. Enter the tool name and arguments in JSON format
+4. Click "Execute Tool" to run
+5. View results in JSON format
+
+## 📖 Example Usage
+
+### In MCP Clients (Claude Desktop, Cursor, etc.)
+
+```python
+# Create and analyze a power network
+create_empty_network(server="pandapower")
+load_network(file_path="test_case.json", server="pandapower")
+run_power_flow(server="pandapower", algorithm="nr")
+get_network_info(server="pandapower")
+
+# Run contingency analysis
+run_contingency_analysis(
+    server="pandapower",
+    contingency_type="N-1",
+    elements=["line", "trafo"]
+)
+
+# PyPSA optimization
+create_network(name="my_network", server="pypsa")
+add_bus(network_name="my_network", bus_id="bus1", v_nom=380.0, server="pypsa")
+run_optimization(network_name="my_network", server="pypsa")
+
+# ANDES dynamic simulation
+run_power_flow(file_path="kundur_full.json", server="andes")
+run_time_domain_simulation(
+    file_path="kundur_full.json",
+    end_time=10.0,
+    step_size=0.01,
+    server="andes"
+)
+```
+
+### In Web Interface
+
+#### Create an Empty Network
+```json
+Tool Name: create_empty_network
+Arguments: {}
+```
+
+#### Load a Network
+```json
+Tool Name: load_network
+Arguments: {"file_path": "PowerMCP/pandapower/test_case.json"}
+```
+
+#### Run Power Flow
+```json
+Tool Name: run_power_flow
+Arguments: {"algorithm": "nr"}
+```
+
+## 🎯 Available Tools by Server
+
+### pandapower Tools
+- `create_empty_network()` - Create new empty network
+- `load_network(file_path)` - Load from JSON/pickle
+- `run_power_flow(algorithm, ...)` - Power flow analysis
+- `run_contingency_analysis(contingency_type, elements)` - N-1/N-2 analysis
+- `get_network_info()` - Network statistics
+
+### PyPSA Tools
+- `create_network(name, snapshots, crs)` - Create PyPSA network
+- `add_bus(network_name, bus_id, v_nom, x, y, carrier)` - Add bus
+- `add_generator(network_name, generator_id, bus, p_nom, ...)` - Add generator
+- `run_optimization(network_name)` - Optimal power flow
+- `get_network_info(network_name)` - Network information
+
+### ANDES Tools
+- `run_power_flow(file_path)` - Power flow with ANDES
+- `run_time_domain_simulation(file_path, end_time, step_size)` - Dynamic simulation
+- `get_bus_results()` - Bus voltage/angle results
+
+## 💻 Development
+
+### Deploy Your Own Space
+
+1. Fork this repository
+2. Create a new Space on [Hugging Face](https://huggingface.co/new-space)
+3. Choose Gradio SDK and link your repository
+4. The Space will automatically get the MCP badge!
+
+### Running Locally
+
+```bash
+git clone https://github.com/Power-Agent/PowerMCP.git
+cd PowerMCP
+pip install -r requirements.txt
+python app.py
+```
+
+### Local MCP Configuration
+
+For Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "pandapower": {
+      "command": "/usr/local/bin/python3",
+      "args": ["/path/to/PowerMCP/PowerMCP/pandapower/panda_mcp.py"]
+    }
+  }
+}
+```
+
+## 🔗 Resources
+
+- **GitHub**: [Power-Agent/PowerMCP](https://github.com/Power-Agent/PowerMCP)
+- **MCP Docs**: [modelcontextprotocol.io](https://modelcontextprotocol.io/)
+- **Tutorial**: [PowerMCP Tutorial](https://github.com/Power-Agent/PowerMCP/blob/main/PowerMCP_Tutorial.pdf)
+- **Gradio MCP Guide**: [Building MCP Servers](https://www.gradio.app/guides/building-mcp-server-with-gradio)
+
+## 🎥 Video Demos
+
+- [Contingency Evaluation](https://www.youtube.com/watch?v=MbF-SlBI4Ws)
+- [Load Growth Evaluation](https://www.youtube.com/watch?v=euFUvhhV5dM)
+
+## 📄 License
+
+MIT License - See [LICENSE](LICENSE) file for details
+
+## 🤝 Contributing
+
+Contributions welcome! PowerMCP is community-driven. Help us accelerate AI adoption in power systems.
+
+---
+
+Built with ❤️ by the PowerMCP Community

app.py

@@ -0,0 +1,320 @@
+"""
+PowerMCP Hugging Face Space - MCP Server Interface
+This application provides a Gradio interface for interacting with PowerMCP servers.
+"""
+
+import gradio as gr
+import json
+from typing import Dict, Any, List, Optional
+import importlib
+import traceback
+
+class PowerMCPInterface:
+    """Interface for interacting with PowerMCP servers"""
+    
+    def __init__(self):
+        self.servers = {}
+        self.current_states = {}  # Store network states per server
+        self._initialize_servers()
+    
+    def _initialize_servers(self):
+        """Initialize all available MCP servers"""
+        # Try to import each server from installed PowerMCP package
+        servers_config = {
+            "pandapower": "PowerMCP.pandapower.panda_mcp",
+            "pypsa": "PowerMCP.PyPSA.pypsa_mcp",
+            "andes": "PowerMCP.ANDES.andes_mcp",
+        }
+        
+        for server_name, module_path in servers_config.items():
+            try:
+                module = importlib.import_module(module_path)
+                if hasattr(module, 'mcp'):
+                    self.servers[server_name] = module.mcp
+                    print(f"✓ Loaded {server_name} server")
+            except Exception as e:
+                print(f"✗ Could not load {server_name}: {str(e)}")
+    
+    def get_available_servers(self) -> List[str]:
+        """Get list of available servers"""
+        return list(self.servers.keys())
+    
+    def get_tools_for_server(self, server_name: str) -> List[Dict[str, str]]:
+        """Get list of available tools for a specific server"""
+        if server_name not in self.servers:
+            return []
+        
+        server = self.servers[server_name]
+        tools = []
+        
+        # FastMCP stores tools in list_tools()
+        if hasattr(server, 'list_tools'):
+            try:
+                tool_list = server.list_tools()
+                for tool in tool_list:
+                    tools.append({
+                        "name": tool.name if hasattr(tool, 'name') else str(tool),
+                        "description": tool.description if hasattr(tool, 'description') else "No description"
+                    })
+            except Exception as e:
+                print(f"Error listing tools: {e}")
+        
+        return tools
+    
+    def call_tool(self, server_name: str, tool_name: str, arguments: Dict[str, Any]) -> Dict[str, Any]:
+        """Call a tool on the MCP server"""
+        try:
+            if server_name not in self.servers:
+                return {"error": f"Server '{server_name}' not found"}
+            
+            server = self.servers[server_name]
+            
+            # Get the tool function
+            tool_func = None
+            if hasattr(server, '_mcp_tools'):
+                tool_func = server._mcp_tools.get(tool_name)
+            
+            if tool_func is None:
+                return {"error": f"Tool '{tool_name}' not found"}
+            
+            # Execute the tool
+            result = tool_func(**arguments)
+            return result if isinstance(result, dict) else {"result": str(result)}
+                
+        except Exception as e:
+            return {
+                "error": str(e),
+                "traceback": traceback.format_exc()
+            }
+
+# Initialize the interface
+interface = PowerMCPInterface()
+
+# ============= MCP Tool Functions (for Gradio MCP server mode) =============
+
+def create_empty_network(server: str = "pandapower") -> Dict[str, Any]:
+    """Create an empty power network.
+    
+    Args:
+        server: The power system tool to use (pandapower, pypsa, andes)
+        
+    Returns:
+        Dictionary with status and network information
+    """
+    return interface.call_tool(server, "create_empty_network", {})
+
+def load_network(file_path: str, server: str = "pandapower") -> Dict[str, Any]:
+    """Load a power network from a file.
+    
+    Args:
+        file_path: Path to the network file
+        server: The power system tool to use
+        
+    Returns:
+        Dictionary with status and network information
+    """
+    return interface.call_tool(server, "load_network", {"file_path": file_path})
+
+def run_power_flow(server: str = "pandapower", algorithm: str = "nr") -> Dict[str, Any]:
+    """Run power flow analysis on the loaded network.
+    
+    Args:
+        server: The power system tool to use
+        algorithm: Power flow algorithm to use
+        
+    Returns:
+        Dictionary with power flow results
+    """
+    return interface.call_tool(server, "run_power_flow", {"algorithm": algorithm})
+
+def get_network_info(server: str = "pandapower") -> Dict[str, Any]:
+    """Get information about the current network.
+    
+    Args:
+        server: The power system tool to use
+        
+    Returns:
+        Dictionary with network statistics
+    """
+    return interface.call_tool(server, "get_network_info", {})
+
+# ============= UI Helper Functions =============
+
+def format_tools_list(server_name: str) -> str:
+    """Format the list of available tools"""
+    tools = interface.get_tools_for_server(server_name)
+    if not tools:
+        return "No tools available for this server"
+    
+    output = f"## Available Tools for {server_name}\n\n"
+    for tool in tools:
+        output += f"### {tool['name']}\n{tool['description']}\n\n"
+    
+    return output
+
+def execute_tool_call(server_name: str, tool_name: str, arguments_json: str) -> str:
+    """Execute a tool call and return the result"""
+    try:
+        # Parse arguments
+        if arguments_json.strip():
+            arguments = json.loads(arguments_json)
+        else:
+            arguments = {}
+        
+        # Call the tool
+        result = interface.call_tool(server_name, tool_name, arguments)
+        return json.dumps(result, indent=2, default=str)
+    except json.JSONDecodeError as e:
+        return json.dumps({"error": f"Invalid JSON in arguments: {str(e)}"}, indent=2)
+    except Exception as e:
+        return json.dumps({"error": f"Execution failed: {str(e)}", "traceback": traceback.format_exc()}, indent=2)
+
+# Create Gradio interface with MCP server support
+with gr.Blocks(title="PowerMCP Server Interface", theme=gr.themes.Soft()) as demo:
+    gr.Markdown("""
+    # ⚡ PowerMCP - Power System Analysis MCP Server
+    
+    This is an MCP-enabled Hugging Face Space for **PowerMCP** - an open-source collection of 
+    Model Context Protocol (MCP) servers for power system software.
+    
+    **Available Tools:**
+    - **pandapower**: Power flow, contingency analysis, network management
+    - **PyPSA**: Energy system optimization, network expansion
+    - **ANDES**: Dynamic simulation, transient stability analysis
+    
+    This Space can be used in two ways:
+    1. **As an MCP tool** in Claude Desktop, Cursor, or other MCP clients (click the MCP badge)
+    2. **Web interface** for manual tool execution and testing
+    """)
+    
+    with gr.Tab("🔧 Tool Explorer"):
+        with gr.Row():
+            with gr.Column(scale=1):
+                gr.Markdown("## Server Configuration")
+                server_dropdown = gr.Dropdown(
+                    choices=interface.get_available_servers(),
+                    value=interface.get_available_servers()[0] if interface.get_available_servers() else None,
+                    label="Select Power System Tool",
+                    interactive=True
+                )
+                
+                tools_button = gr.Button("📋 List Available Tools", variant="primary")
+                tools_output = gr.Markdown(label="Available Tools")
+                
+            with gr.Column(scale=2):
+                gr.Markdown("## Execute Tool")
+                
+                tool_name_input = gr.Textbox(
+                    label="Tool Name",
+                    placeholder="e.g., create_empty_network",
+                    lines=1
+                )
+                
+                arguments_input = gr.Code(
+                    label="Arguments (JSON)",
+                    language="json",
+                    value="{}",
+                    lines=5
+                )
+                
+                execute_button = gr.Button("▶️ Execute Tool", variant="primary")
+                
+                result_output = gr.Code(
+                    label="Result",
+                    language="json",
+                    lines=15
+                )
+    
+    with gr.Tab("📚 Documentation"):
+        gr.Markdown("""
+        ## PowerMCP Tools Documentation
+        
+        ### pandapower
+        A Python-based power system analysis tool focusing on power flow and contingency analysis.
+        
+        **Key Functions:**
+        - `create_empty_network()` - Create a new empty network
+        - `load_network(file_path)` - Load network from JSON/pickle file
+        - `run_power_flow(algorithm, calculate_voltage_angles, max_iteration, tolerance_mva)` - Run power flow analysis
+        - `run_contingency_analysis(contingency_type, elements)` - Perform N-1 or N-2 analysis
+        - `get_network_info()` - Get network statistics
+        
+        ### PyPSA (Python for Power System Analysis)
+        Energy system optimization and network expansion planning.
+        
+        **Key Functions:**
+        - `create_network(name, snapshots, crs)` - Create new PyPSA network
+        - `add_bus(network_name, bus_id, v_nom, x, y, carrier)` - Add bus to network
+        - `add_generator(network_name, generator_id, bus, p_nom, ...)` - Add generator
+        - `run_optimization(network_name)` - Run optimal power flow
+        - `get_network_info(network_name)` - Get network information
+        
+        ### ANDES
+        Dynamic simulation and transient stability analysis.
+        
+        **Key Functions:**
+        - `run_power_flow(file_path)` - Run power flow analysis
+        - `run_time_domain_simulation(file_path, end_time, step_size)` - Run transient analysis
+        - `get_bus_results()` - Get bus voltage and angle results
+        - `get_generator_results()` - Get generator output results
+        
+        ## Example Usage in MCP Clients
+        
+        ```python
+        # In Claude Desktop or Cursor with PowerMCP enabled:
+        
+        # Create and analyze a network
+        create_empty_network(server="pandapower")
+        load_network(file_path="test_case.json", server="pandapower")
+        run_power_flow(server="pandapower", algorithm="nr")
+        get_network_info(server="pandapower")
+        ```
+        
+        ## About PowerMCP
+        
+        PowerMCP enables Large Language Models to directly interact with power system 
+        applications through the Model Context Protocol (MCP). This allows AI assistants 
+        to perform power system analysis, optimization, and simulation tasks.
+        
+        **Links:**
+        - [GitHub Repository](https://github.com/Power-Agent/PowerMCP)
+        - [MCP Documentation](https://modelcontextprotocol.io/)
+        - [Tutorial](https://huggingface.co/learn/mcp-course)
+        
+        ## Setting Up MCP Client
+        
+        1. Install Claude Desktop, Cursor, or another MCP-compatible client
+        2. Click the MCP badge on this Space
+        3. Select "Add to MCP tools"
+        4. The tools will be available in your client immediately
+        
+        For local development, see the [PowerMCP README](https://github.com/Power-Agent/PowerMCP).
+        """)
+    
+    # Event handlers
+    tools_button.click(
+        fn=format_tools_list,
+        inputs=[server_dropdown],
+        outputs=[tools_output]
+    )
+    
+    execute_button.click(
+        fn=execute_tool_call,
+        inputs=[server_dropdown, tool_name_input, arguments_input],
+        outputs=[result_output]
+    )
+    
+    # Load tools on startup
+    demo.load(
+        fn=format_tools_list,
+        inputs=[server_dropdown],
+        outputs=[tools_output]
+    )
+
+def main():
+    """Entry point for powermcp-app command"""
+    # Enable MCP server mode - this exposes the Space as an MCP tool
+    demo.launch(mcp_server=True)
+
+if __name__ == "__main__":
+    main()

requirements.txt

@@ -0,0 +1,19 @@
+# Gradio with MCP support
+gradio[mcp]>=5.0.0
+
+# PowerMCP - Install from GitHub
+git+https://github.com/Power-Agent/PowerMCP.git
+
+# Core dependencies
+numpy>=1.24.0
+pandas>=2.0.0
+scipy>=1.10.0
+networkx>=3.0
+matplotlib>=3.7.0
+
+# Additional PyPSA dependencies
+xarray>=2023.0.0
+netcdf4>=1.6.0
+
+# Additional ANDES dependencies
+kvxopt>=1.3.0