CONTAM_plugin

# CONTAM Plugin `CONTAM Plugin` is a Windows-first public toolkit for using CONTAM from AI coding agents and MCP-capable desktop tools. It combines three layers in one repository: - a local `stdio` MCP server for CONTAM command-line tools and ContamX bridge sessions - a Codex plugin wrapper with workflow guidance for project creation, diagnosis, and simulation - guard scripts for PRJ hygiene, ContamW-safe result settings, and optional `contam_chinese` linkage The project is designed for public use. It helps an agent inspect `.prj` models, diagnose missing references, run simulations, compare outputs, generate simple ContamW SketchPad layouts, and separate solver failures from ContamW GUI result-display problems. ## Quick Use Through MCP For most users, the easiest setup is an `npx`-launched local MCP server: ```text command: npx args: -y --package github:summer521521/CONTAM_plugin contam-mcp ``` The binary name remains `contam-mcp` because it launches the MCP server component. The repository and Codex plugin are named `CONTAM_plugin`. Host-specific setup examples are in: - [Host Setup Guide](docs/HOSTS.md) - [Codex Windows App Setup](docs/CODEX_WINDOWS_APP.md) - [Five-Minute Quickstart](docs/QUICKSTART.md) ## Codex Plugin Use This repository can also be used as a Codex plugin source because the repository root contains: - `.codex-plugin/plugin.json` - `.mcp.json` - `skills/contam-mcp/SKILL.md` - `scripts/start-contam-plugin-mcp.ps1` - `scripts/Invoke-ContamProjectGuard.ps1` The plugin adds a CONTAM workflow skill that tells Codex to: - inspect before editing - keep case-specific data outside the plugin repository - run ContamX input checks before GUI work - keep only one active PRJ in a case folder unless scenarios are intentional - use GUI-safe output settings when the user will run from ContamW - record ContamW Building Check errors and fixes in case-local notes ## Main Capabilities - discover bundled or configured CONTAM executables - list `.prj`, `.sim`, `.wth`, `.ctm`, and related files - inspect project metadata and external references - diagnose broken project references - update supported `.prj` file references - clone baseline projects into named scenario folders - create and optionally run small case matrices - apply generated ContamW SketchPad layout data for rectangular rooms, zones, path icons, and source/sink icons - run `contamx3.exe` and collect outputs - run a PRJ guard for encoding, result profile, stale-output cleanup, XLog triage, and basic count checks - discover and use optional `contamxpy` bindings for paper-style ContamX API co-simulation - discover Rhino/Grasshopper ANT availability for model-creation workflows - upgrade old `.prj` files with `prjup.exe` - compare `.sim` files with `simcomp.exe` - export `simread` text output - summarize generic CONTAM text outputs for quick result triage - start, inspect, advance, and close ContamX bridge sessions ## Project Guard Before handing a generated PRJ to another user or asking someone to run it in ContamW, run: ```powershell .\scripts\Invoke-ContamProjectGuard.ps1 ` -ProjectPath "<case>\model.prj" ` -Mode InputCheck ` -ResultProfile GuiSafeResults ` -CleanOutputs ` -RequireSingleProject ``` For a command-line full run: ```powershell .\scripts\Invoke-ContamProjectGuard.ps1 ` -ProjectPath "<case>\model.prj" ` -Mode Run ` -ResultProfile GuiSafeResults ``` The guard does not prove a hand-drawn SketchPad layout is perfect, but it catches common project-sharing and simulation issues before the GUI step. ## Link With contam_chinese `CONTAM_plugin` can use the localized executables distributed by [`contam_chinese`](https://github.com/summer521521/contam_chinese). After extracting a `contam_chinese` release package, link it for the current PowerShell session: ```powershell .\scripts\link-contam-chinese.ps1 -Path "<extracted-contam-chinese-release>" ``` Or persist it for your Windows user: ```powershell .\scripts\link-contam-chinese.ps1 -Path "<extracted-contam-chinese-release>" -User ``` The launcher honors these variables in order: - explicit tool overrides such as `CONTAMX_PATH` - `CONTAM_HOME` - `CONTAM_CHINESE_HOME` - bundled executables in this repository Use `contam_chinese` for localized ContamW and Chinese help. Use `CONTAM_plugin` for MCP automation, project checks, simulation workflows, and report-oriented result extraction. ## Repository Layout - `.codex-plugin/`: Codex plugin manifest - `.mcp.json`: MCP server launch definition for plugin hosts - `skills/`: Codex workflow skill for CONTAM work - `scripts/`: launch, guard, localization-link, setup, and maintenance scripts - `contam-mcp/`: MCP server source, developer guide, and regression scripts - `docs/`: public quickstart and host setup guides - `.github/workflows/`: GitHub Actions workflows - repository root: bundled CONTAM executables and supporting DLLs ## Privacy And CI This repository includes a privacy check that scans tracked files for personal filesystem paths before public sharing: ```powershell npm run privacy:check ``` Run the basic plugin launcher check with: ```powershell npm run plugin:check ``` Run official regression cases with: ```powershell npm run regression:official ``` ## Example Prompts - `Call discover_contam_installation and confirm CONTAM is available.` - `List CONTAM case files in this folder.` - `Inspect this PRJ file and summarize its references and date range.` - `Run a test input only check for this PRJ.` - `Make this PRJ safe for ContamW Building Check and result review.` - `Run this PRJ and list the generated outputs.` - `Apply a rectangular SketchPad layout to this PRJ so ContamW opens with visible rooms and icons.` - `Run a small case matrix from this baseline model.` - `Analyze this CONTAM xlog or simread text export.` - `Discover whether contamxpy and ANT are available.` - `Start a CONTAM bridge session for this project.` - `Advance the active bridge session by 300 seconds and return path flow updates.` ## References - [contam_chinese](https://github.com/summer521521/contam_chinese) - [NIST CONTAM Download Page](https://www.nist.gov/el/energy-and-environment-division-73200/nist-multizone-modeling/software/contam/download) - [NIST CONTAM Software Page](https://www.nist.gov/services-resources/software/contam) - [NIST TN 1887r1](https://doi.org/10.6028/NIST.TN.1887r1) - [Model Context Protocol](https://modelcontextprotocol.io/)