README.md

---
sdk: docker
emoji: 🚀
colorFrom: red
colorTo: green
sdk_version: 6.22.0
---
# PCSWMM Engineering MCP — Rev1
---
title: PCSWMM Engineering Optimizer
emoji: 🌧️
colorFrom: blue
colorTo: green
sdk: gradio
app_file: app.py
pinned: false
tags:
  - mcp-server
  - civil-engineering
  - stormwater
  - optimization
---
A local-first engineering copilot and Calgary SWMR service for consultants who use **PCSWMM**.

This package is a product-specific derivative of `SWMM6 Report Engineering Automation Rev31`. It is **not** the universal uploaded-INP product. Its public MCP tool surface begins with the active PCSWMM Engineering SDK package.

## Product boundary

| Product | Intended user | Public starting point |
|---|---|---|
| SWMM6 Report MCP | Consultant without PCSWMM | Upload an EPA SWMM `.inp` |
| PCSWMM Engineering MCP | Consultant working in PCSWMM | Connect the active PCSWMM SDK package |

The independent SWMM execution engine is retained internally for verification, reconciliation, and auditability. Generic standalone model upload is intentionally not exposed as an MCP tool.

## Architecture

```text
Active PCSWMM project
        │
        │ PCSWMM Engineering SDK package
        ▼
PCSWMM Engineering MCP (localhost)
        ├── validate active project identity
        ├── independently execute exact INP
        ├── reconcile PCSWMM and worker evidence
        ├── deterministic QA/QC
        ├── Calgary screening
        ├── baseline/revision impact review
        ├── City comment response matrix
        └── SWMR DOCX + audit ZIP
```

## Start locally

### Windows

```bat
start_pcswmm_mcp.bat
```

### PowerShell

```powershell
.\start_pcswmm_mcp.ps1
```

Default endpoint:

```text
http://127.0.0.1:8765/mcp
```

Health check:

```text
http://127.0.0.1:8765/health
```

The default binding is localhost only. Do not expose this service directly to the internet.

## Required first tool

```text
connect_active_pcswmm_project
```

The package should contain:

- PCSWMM project name and exact model filename;
- active scenario and result context;
- PCSWMM SDK version;
- exact INP text for independent verification;
- object inventory and unit metadata;
- deterministic PCSWMM findings;
- baseline and revised snapshots when applicable;
- revision comparison and impact assessment;
- source-model SHA-256 when available.

## Public MCP tools

### Connection and verification

- `connect_active_pcswmm_project`
- `validate_active_pcswmm_project`
- `get_active_pcswmm_project`
- `run_independent_pcswmm_verification`
- `review_active_pcswmm_model`

### Results

- `get_pcswmm_node_results`
- `get_pcswmm_link_results`
- `get_pcswmm_subcatchment_results`
- `get_pcswmm_timeseries`

### Revision and submissions

- `review_pcswmm_revision`
- `configure_pcswmm_submission`
- `set_pcswmm_city_comments`
- `build_pcswmm_city_response_matrix`
- `get_pcswmm_submission_readiness`

### Reporting

- `set_pcswmm_report_details`
- `set_pcswmm_report_configuration`
- `attach_pcswmm_figure`
- `generate_pcswmm_swmr`

### Session control

- `list_pcswmm_sessions`
- `close_pcswmm_session`

## First-submission workflow

```text
connect_active_pcswmm_project(auto_verify=false)
→ review_active_pcswmm_model
→ configure_pcswmm_submission(first_submission)
→ set_pcswmm_report_details
→ get_pcswmm_submission_readiness
→ generate_pcswmm_swmr
```

## Revised-submission workflow

```text
PCSWMM baseline/revised snapshots and impact assessment
→ connect_active_pcswmm_project(revised_submission)
→ review_pcswmm_revision
→ set_pcswmm_city_comments
→ build_pcswmm_city_response_matrix
→ review_active_pcswmm_model
→ get_pcswmm_submission_readiness
→ generate_pcswmm_swmr
```

## Engineering control philosophy

1. PCSWMM is the live design workspace and primary source of design context.
2. The local worker independently executes the exact INP for verification.
3. PCSWMM and worker values are kept as separate evidence until reconciled.
4. AI is optional and may explain deterministic findings; it does not calculate hydraulics.
5. Reports remain engineer-review drafts until professionally authenticated.

## Included skills

- `analyze-pcswmm-models` — primary PCSWMM MCP orchestration skill.
- `review-calgary-2011-stormwater` — Calgary evidence and criteria review.

The generic `automate-swmm-modeling` skill is not active in this product release because Rev1 is read-only with respect to the live PCSWMM model. Live design editing should be introduced only with explicit approval, rollback, and revision-snapshot controls.


## Rev1.5 native PCSWMM mode

PCSWMM is the required simulation backend. OpenSWMM verification is optional and disabled by default. First/model-only submissions do not require revision evidence. A PCSWMM-native SWMR draft and audit ZIP can be generated without OpenSWMM; when optional verification results exist, the full reconciled report engine is used.

## Rev1.8 deterministic evidence-folder bridge

The existing MCP can now consume the local evidence package written by the PCSWMM-native extraction SDK. No new report engine or parallel workflow is introduced.

New tools:

- `connect_deterministic_calgary_evidence`
- `generate_calgary_swmr_from_evidence`

One-command local workflow:

```text
Engineer runs PCSWMM
→ native SDK writes evidence/<project_timestamp>/
→ generate_calgary_swmr_from_evidence(evidence_dir=...)
→ existing deterministic review
→ existing Calgary SWMR DOCX + audit ZIP
```

Example MCP request:

```json
{
  "evidence_dir": "C:\\Users\\razaa\\MCP\\PCSWMM_SWMR\\evidence\\Valleyfield_to-be_dual_system_20260804T151411Z",
  "project_name": "Valleyfield To-Be Dual System",
  "client": "",
  "consultant": "",
  "prepared_by": "",
  "submission_type": "model_only_review",
  "include_model_appendix": true
}
```

The bridge imports the normalized evidence, hashes, selected tables, result catalog, missing-information register, agentic findings, and selected primary figures. It does not rerun or modify the PCSWMM model.


## Rev1.9 — PySWMM backend

The existing PCSWMM-engineering MCP now accepts deterministic evidence generated by
the independent PySWMM Calgary SWMR Evidence App. No duplicate MCP server or report
engine is introduced. Use either:

- `connect_pyswmm_calgary_evidence`, then the normal review/readiness/report tools; or
- `generate_calgary_swmr_from_pyswmm_evidence` for the one-command draft workflow.

The generic `connect_deterministic_calgary_evidence` tool remains supported.