Examples#

This page demonstrates end-to-end workflows using the OpenSWMM MCP Server tools, resources, and prompts.

Example 1: Basic Simulation Workflow#

A minimal open-run-query-close workflow.

1. Open the model#

Tool: lifecycle_open_model
Arguments:
  inp_path: "/models/site_drainage.inp"
  session_id: "basic"

Response confirms 12 nodes, 11 links, 6 subcatchments, dynamic wave routing.

2. Run the simulation#

Tool: lifecycle_run_simulation
Arguments:
  session_id: "basic"

Progress reports stream from 0 % to 100 %. Final response shows 2880 steps completed, runoff continuity error of -0.012 %, routing continuity error of -0.008 %.

3. Check for flooding#

Tool: analysis_get_flooding_summary
Arguments:
  session_id: "basic"

Returns a sorted list of flooded nodes with peak overflow rates and total flood volumes.

4. Extract a time series#

Tool: analysis_get_time_series
Arguments:
  session_id: "basic"
  element_type: "node"
  element_id: "J3"
  variable: "depth"

Returns a TimeSeries object with timestamps and depth values for node J3 across all reporting periods.

5. Export results#

Tool: analysis_export_results
Arguments:
  session_id: "basic"
  output_path: "/models/results.csv"
  format: "csv"

6. Close the session#

Tool: lifecycle_close_model
Arguments:
  session_id: "basic"

Example 2: What-If Scenario Analysis#

Compare a baseline simulation against an alternative with increased rainfall.

1. Run the baseline#

Tool: lifecycle_open_model
Arguments:
  inp_path: "/models/site_drainage.inp"
  session_id: "baseline"

Tool: lifecycle_run_simulation
Arguments:
  session_id: "baseline"

2. Clone and modify#

Tool: hotstart_clone_session
Arguments:
  source_id: "baseline"
  target_id: "high_rain"

Tool: forcing_set_rainfall_override
Arguments:
  session_id: "high_rain"
  gage_id: "RG1"
  rainfall: 2.5

3. Run the alternative#

Tool: lifecycle_run_simulation
Arguments:
  session_id: "high_rain"

4. Compare results#

Tool: analysis_compare_scenarios
Arguments:
  session_a: "baseline"
  session_b: "high_rain"
  element_type: "node"
  variable: "depth"

Returns per-element peak differences and summary statistics (mean, max, min of absolute differences).

5. Review flooding differences#

Tool: analysis_get_flooding_summary
Arguments:
  session_id: "baseline"

Tool: analysis_get_flooding_summary
Arguments:
  session_id: "high_rain"

Compare the two summaries to identify nodes with increased flooding.

6. Clean up#

Tool: lifecycle_close_model
Arguments:
  session_id: "baseline"

Tool: lifecycle_close_model
Arguments:
  session_id: "high_rain"

Example 3: Programmatic Model Building#

Create a simple drainage network entirely through the building tools.

1. Create an empty model#

Tool: building_create_model
Arguments:
  session_id: "new_model"

2. Set simulation options#

Tool: building_set_option
Arguments:
  session_id: "new_model"
  option: "FLOW_UNITS"
  value: "CFS"

Tool: building_set_option
Arguments:
  session_id: "new_model"
  option: "ROUTING_MODEL"
  value: "DYNWAVE"

3. Add nodes#

Tool: building_add_node
Arguments:
  session_id: "new_model"
  node_id: "J1"
  node_type: "junction"
  invert_elev: 100.0
  max_depth: 6.0
  x: 0.0
  y: 100.0

Tool: building_add_node
Arguments:
  session_id: "new_model"
  node_id: "J2"
  node_type: "junction"
  invert_elev: 95.0
  max_depth: 6.0
  x: 200.0
  y: 100.0

Tool: building_add_node
Arguments:
  session_id: "new_model"
  node_id: "OUT1"
  node_type: "outfall"
  invert_elev: 90.0
  x: 400.0
  y: 100.0

5. Add a subcatchment#

Tool: building_add_subcatchment
Arguments:
  session_id: "new_model"
  subcatch_id: "S1"
  area: 10.0
  imperv_pct: 50.0
  slope: 0.5
  width: 500.0
  outlet_node: "J1"

6. Add a rain gage and time series#

Tool: building_add_gage
Arguments:
  session_id: "new_model"
  gage_id: "RG1"

Tool: building_add_timeseries
Arguments:
  session_id: "new_model"
  name: "design_storm"
  times: [0, 0.5, 1.0, 1.5, 2.0, 2.5, 3.0]
  values: [0.1, 0.5, 1.2, 2.0, 1.2, 0.5, 0.1]

7. Validate and write#

Tool: building_validate_model
Arguments:
  session_id: "new_model"

Tool: building_write_model
Arguments:
  session_id: "new_model"
  output_path: "/models/new_drainage.inp"

8. Open the new model and test#

Tool: lifecycle_open_model
Arguments:
  inp_path: "/models/new_drainage.inp"
  session_id: "test_run"

Tool: lifecycle_run_simulation
Arguments:
  session_id: "test_run"

Verify that the simulation completes with acceptable continuity errors.