Contam MCP

CONTAM Plugin

Use this skill when the user wants to inspect, diagnose, clone, batch-run, co-simulate, upgrade, compare, analyze, or export CONTAM projects through the contam MCP server.

Setup

• The plugin starts the MCP server through scripts/start-contam-mcp.ps1.
• The plugin also ships scripts/Invoke-ContamProjectGuard.ps1 for local PRJ hygiene, input checks, output cleanup, result-profile updates, and XLog triage.
• The current official CONTAM release checked for this workflow is CONTAM 3.4.0.8, with command-line tools such as ContamX 3.4.0.3. Re-check the official NIST release page before changing executable assumptions.
• CONTAM_PLUGIN_ROOT is set by the launcher when the plugin runs from this repository.
• CONTAM_HOME may point to the directory containing CONTAM executables.
• CONTAM_CHINESE_HOME may point to an extracted contam_chinese release; when set, the launcher uses those localized executables unless explicit tool paths override them.
• Optional executable overrides: CONTAMX_PATH, CONTAMW_PATH, PRJUP_PATH, SIMREAD_PATH, SIMCOMP_PATH.
• The server targets command-line tools such as contamx3.exe, prjup.exe, simread.exe, and simcomp.exe; do not assume GUI automation through contamw3.exe.

Standard Flow

1. Confirm the installation before running a case:
   • discover_contam_installation
   • discover_contam_api_stack
2. Find candidate project and result files:
   • list_contam_case_files
3. Inspect the project before edits or simulation:
   • inspect_contam_project
   • diagnose_contam_project
4. If references are wrong, update only the requested fields:
   • update_contam_project_references
5. For baseline/intervention studies, clone scenarios before running:
   • create_contam_case_variant
   • run_contam_case_matrix
6. When a PRJ can run but needs ContamW-visible layout, apply SketchPad data before GUI review:
   • apply_contam_sketchpad_layout
7. Before asking the user to open or run in ContamW, use the project guard script for local checks:
   • scripts/Invoke-ContamProjectGuard.ps1 -ProjectPath <file.prj> -Mode InputCheck -ResultProfile GuiSafeResults -CleanOutputs -RequireSingleProject
8. For paper-style API workflows, use contamxpy when available:
   • inspect_contamxpy_project
   • run_contamxpy_cosimulation
9. Run or upgrade the project:
   • run_contam_simulation
   • upgrade_contam_project
10. Compare, export, or quickly triage results:

• compare_contam_sim_results
• export_contam_sim_text
• analyze_contam_text_results

Project Guard Flow

Use Invoke-ContamProjectGuard.ps1 whenever a generated or modified PRJ is expected to open in ContamW or be handed to another user.

Typical commands:

.\scripts\Invoke-ContamProjectGuard.ps1 `
  -ProjectPath "<case>\model.prj" `
  -Mode InputCheck `
  -ResultProfile GuiSafeResults `
  -CleanOutputs `
  -RequireSingleProject

For a command-line full run:

.\scripts\Invoke-ContamProjectGuard.ps1 `
  -ProjectPath "<case>\model.prj" `
  -Mode Run `
  -ResultProfile GuiSafeResults

Use this flow before GUI work:

1. Keep case-specific data outside the plugin, for example case-spec.json, layout.json, inputs/*.csv, and ERRORS.md in the case folder.
2. Avoid local absolute paths in shared PRJ files; prefer relative case-local references so another user can move the case folder.
3. Keep only one active .prj in a case folder unless the user explicitly wants scenarios; remove failed variants and stale result files.
4. Repair UTF-8 BOM if present. CONTAM expects the format line at byte 0; PowerShell writes can accidentally break this.
5. Run InputCheck after every PRJ edit. A ContamX input check passing means the text structure is readable; it does not prove SketchPad geometry is GUI-valid.
6. Run full simulation from command line to separate solver failures from ContamW GUI result handoff failures.
7. Inspect the newest .xlog; trust Simulation completed successfully. over a GUI impression that the console "closed".
8. If a manual ContamW run reports CONTAMX.EXE: simulation terminated abnormally but command-line ContamX exits 0 and writes a successful XLog, treat it as a GUI result handoff/loading issue, not a solver issue.

For generated models that are meant to match a hand-built ContamW reference, pass structural expectations into the guard:

.\scripts\Invoke-ContamProjectGuard.ps1 `
  -ProjectPath "<case>\model.prj" `
  -Mode InputCheck `
  -ExpectedZoneCount 9 `
  -ExpectedPathCount 49 `
  -ExpectedAmbientPathCount 40 `
  -ExpectedInterzonePathCount 9 `
  -MinimumAmbientPathsPerZone 1

Use the expected counts from the reference case, not from the generated model. A model can pass ContamX input checks while still being too simplified for the user's intended ContamW case.

Reference PRJ Learning Flow

When the user provides a hand-built ContamW .prj as a reference for a generated project, treat the hand-built file as the structural source of truth before changing generation logic.

1. Compare section counts first: zones, source/sink elements, flow elements, flow paths, source/sinks, schedules, and wind pressure profiles.
2. Compare flow path inventory by class: zone-to-ambient paths, interzone paths, vertical or stair paths, and paths with wind pressure profile fields enabled.
3. Preserve every real opening represented in the reference model. Do not collapse multiple facade leaks, doors, windows, supplies, and exhausts into one generic ambient path per room unless the user explicitly asks for a simplified model.
4. Preserve inter-floor/stair connectivity as explicit paths. If the reference uses a stair or vertical connection, do not replace it with same-floor hall links just to make the SketchPad layout easier.
5. If the reference has no wind pressure profiles and uses neutral exterior path fields, do not introduce WPC profiles merely because they look more physical. Add WPC only when the case definition, weather study, or user request requires it.
6. Renaming zones, flow elements, schedules, and sources is useful for readability, but after renaming verify that source/sink rows, initial concentrations, schedule ids, and zone ids still point to the same physical rooms.
7. For GUI-facing cases, prefer a complete path inventory plus simpler, valid SketchPad geometry over a visually clean drawing that hides or omits airflow paths.

Recent lesson from a two-floor SF6/COMIS-style comparison: the hand-built reference had 9 zones, 18 flow elements, and 49 flow paths (40 ambient and 9 interzone), while a generated GUI variant had 9 zones, 20 flow elements, and 27 flow paths (20 ambient and 7 interzone). The useful correction is not to copy the case values into the plugin, but to force generated workflows to carry over the reference model's path inventory and check ambient/interzone counts explicitly.

Case Matrix Flow

Use run_contam_case_matrix when the user needs a complete case workflow from an existing .prj:

1. Keep the original project as the baseline source.
2. Create one named folder per scenario.
3. Apply only supported .prj reference changes when requested: weatherFile, contaminantFile, continuousValuesFile, discreteValuesFile, wpcFile, ewcFile.
4. Run testInputOnly first for new or uncertain cases.
5. Run full simulations after references and input checks pass.
6. Use analyze_contam_text_results for quick .xlog or simread text triage, then write separate post-processing scripts for final charts or paper tables when needed.

SketchPad Layout Flow

Use apply_contam_sketchpad_layout when an existing .prj already has simulation records but needs a ContamW-visible drawing.

1. Inspect the project first to confirm zones, paths, source/sinks, and levels exist.
2. Convert the user's verbal description, hand sketch, paper plan, or screenshot into a small layout spec.
3. Use rectangles for simple rooms, clockwise orthogonal polygon points for jogged rooms, and explicit wallSegments for shared partitions that are visible in the sketch.
4. Let the tool generate wall corner/tee/cross icons, zone icons, source/sink icons, and SketchPad size/scale metadata.
5. Put all essential real doors, windows, supply/exhaust openings, and sources in explicit pathIcons or sourceSinkIcons. If a path is hidden and the user saves/runs from ContamW, ContamW may rewrite the PRJ from SketchPad state and drop that path.
6. Put each airflow path icon on the wall that matches its PRJ direction field. A wrong side commonly produces Building Check messages such as The same zone is on both sides of the wall that the path is on.
7. Avoid crowded or ambiguous tee/cross wall nodes. If ContamW draws long unintended wall lines or reports undefined zones, replace the layout with simpler closed room rectangles and valid shared-wall door icons.
8. Be cautious with wall icon type 20 in generated layouts. It can be valid in official projects, but in some generated wall graphs it triggered ContamW GUI crashes; prefer simpler wall graphs or side-specific stable nodes and verify manually.
9. For GUI review or screenshots, set cleanDisplay: true so pseudo-geometry is hidden and unplaced/helper paths are omitted. Use hideAirflowPathIcons: true only for a read-only screenshot pass, not for a model that the user will save or run from ContamW.
10. Prefer writing to outputPath for a first pass.
11. Run the project guard InputCheck after layout changes, then ask the user to manually open in ContamW for Building Check screenshots if needed.

Treat this as template-based SketchPad generation, not proof that ContamW will exactly reproduce a paper figure. Complex floor-plan tracing, curved geometry, and publication-style airflow diagrams still need dedicated post-processing or manual GUI checks.