Skip to main content
Glama

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:

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:

Related MCP server: COMSOL MCP Server

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:

.\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

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.

CONTAM_plugin can use the localized executables distributed by contam_chinese.

After extracting a contam_chinese release package, link it for the current PowerShell session:

.\scripts\link-contam-chinese.ps1 -Path "<extracted-contam-chinese-release>"

Or persist it for your Windows user:

.\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:

npm run privacy:check

Run the basic plugin launcher check with:

npm run plugin:check

Run official regression cases with:

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

Available Tools

15 tools
advance_contam_bridge_sessionC

Use this when you want to send control/weather adjustments to a running bridge session and optionally advance ContamX to a new simulation time.

Inputs: sessionId (required), targetTimeSeconds, advanceBySeconds, requestConcentrations, +26 more.

close_contam_bridge_sessionA

Use this when you want to end an active ContamX bridge-mode session and release the spawned process and socket.

Inputs: sessionId (required).

compare_contam_sim_resultsC

Use this when you want to compare two CONTAM .sim result files with simcomp.

Inputs: firstSimPath (required), secondSimPath (required), verbosity, timeoutSeconds.

diagnose_contam_projectB

Use this when a CONTAM project fails to run and you want to inspect referenced support files and nearby candidate matches.

Inputs: projectPath (required), workingDirectory, searchRecursively, maxMatchesPerReference.

discover_contam_installationA

Use this when you need to confirm where CONTAM is installed and which executables this MCP server can access.

Inputs: no named parameters.

export_contam_sim_textB

Use this when you need to run simread on a .sim file and you already know the response-script text needed for the interactive prompts.

Inputs: simPath (required), responsesText, responsesFilePath, timeoutSeconds.

get_contam_bridge_sessionB

Use this when you want to inspect the metadata or last-known state of an active ContamX bridge session.

Inputs: sessionId (required).

get_contam_program_helpA

Use this when you want the built-in command-line usage text for a CONTAM executable before deciding which tool or arguments to use.

Inputs: program (required).

inspect_contam_projectA

Use this when you want a quick structural summary of a CONTAM .prj file before editing or running it.

Inputs: projectPath (required).

list_contam_bridge_entitiesB

Use this when you want a concise list of the names and ids available inside an active ContamX bridge session.

Inputs: sessionId (required), category.

list_contam_case_filesC

Use this when you want to find CONTAM project files, result files, or weather files in a directory tree before running a simulation.

Inputs: directory, recursive, extensions, maxResults.

run_contam_simulationB

Use this when you want to validate or run a CONTAM .prj model with ContamX and collect the generated files.

Inputs: projectPath (required), workingDirectory, timeoutSeconds, testInputOnly, +3 more.

start_contam_bridge_sessionB

Use this when you want to launch ContamX in bridge mode and keep an interactive socket session open across multiple MCP calls.

Inputs: projectPath (required), workingDirectory, windFromBridge, volumeFlowBridge, +1 more.

update_contam_project_referencesC

Use this when you need to edit the referenced weather, contaminant, or library files inside a CONTAM .prj file.

Inputs: projectPath (required), weatherFile, contaminantFile, continuousValuesFile, +4 more.

upgrade_contam_projectC

Use this when you need to upgrade an older .prj file to a newer CONTAM project format using prjup.

Inputs: projectPath (required), targetVersion, createBackup, timeoutSeconds.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 15 tools

    Disambiguation5/5

    Every tool has a clearly distinct purpose with no ambiguity. The tools cover different aspects of CONTAM workflow (installation discovery, project inspection, simulation running, bridge session management, file operations) with precise action-target pairs that prevent misselection.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern with 'contam' prefix (e.g., discover_contam_installation, run_contam_simulation). The naming is perfectly predictable throughout the set, using snake_case uniformly with clear action verbs.

    Tool Count5/5

    15 tools is well-scoped for a CONTAM simulation server, covering installation, project management, simulation execution, bridge sessions, and file operations. Each tool earns its place in the domain without being excessive or insufficient.

    Completeness5/5

    The toolset provides complete lifecycle coverage for CONTAM projects: discovery, inspection, updating, running simulations, managing bridge sessions, comparing results, and diagnosing issues. No obvious gaps exist for the stated simulation workflow domain.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers