Epic: suews-mcp

Overview

Implement a lightweight MCP server that wraps the existing SuPy Python interface to provide AI-assisted access to SUEWS urban climate modeling. The server will leverage SuPy's existing functionality rather than reimplementing features, focusing on translating between natural language requests and SuPy API calls while providing intelligent assistance for configuration, execution, and analysis.

Architecture Decisions

Core Simplifications

• Leverage SuPy entirely: No direct Fortran interaction, use SuPy's proven API
• Minimal new code: Wrap existing functionality, don't recreate it
• File-based workflows: Use SuPy's existing file I/O rather than custom formats
• Stateless design: Each MCP request maps to discrete SuPy operations

Technology Stack

• MCP Python SDK: Official SDK for protocol implementation
• SuPy: Existing Python wrapper for SUEWS (no modifications needed)
• Standard library: asyncio for concurrent operations
• Minimal dependencies: Only add what MCP specifically requires

Technical Approach

MCP Server Core

• Single server.py implementing MCP protocol
• Tool registry mapping MCP functions to SuPy calls
• Resource server for templates and examples
• Simple prompt templates for guided workflows

Tool Implementations

• Direct SuPy mappings: Most tools just call SuPy functions with parameter translation
• Intelligent wrappers: Add validation and helpful error messages
• Batch operations: Use SuPy's existing multi-grid support
• Results formatting: Transform SuPy DataFrames to AI-friendly summaries

Success Criteria (Technical)

Performance Benchmarks

• Tool response < 5 seconds for all operations
• Support 10 concurrent grid simulations
• Handle multi-year runs without timeout
• Memory usage < 2GB for typical workflows

Quality Gates

• 100% MCP protocol compliance
• 90% code coverage in tests
• All SuPy errors gracefully handled
• Self-documenting tool descriptions

Estimated Effort

• Total Duration: 3-4 weeks
• Development: 2 weeks core implementation
• Testing & Polish: 1 week
• Documentation: Throughout development

Tasks

• 001 - MCP Server Setup (8h, parallel)
• 002 - Core SuPy Tools (16h, depends on 001)
• 003 - Data Preprocessing Tools (8h, parallel with 002)
• 004 - Resource Management (4h, parallel)
• 005 - Error Handling & Intelligence (8h, depends on 002,003)
• 006 - Testing Suite (12h, depends on 002,003,005)
• 007 - Packaging & Documentation (8h, depends on 006)

Total effort: 64 hours