# NECB MCP adaptation for OpenStudio

Release **1.2.1-necb.1** provides the OpenStudio MCP server with a dedicated,
pinned NRCAN/NRC standards bundle for Canadian NECB workflows. This is an
independent adaptation of OpenStudio(R)-MCP, not an official NRC/NREL release.

## Build

Docker Desktop must be running in Linux-container mode. From this folder:

```powershell
docker build --platform linux/amd64 -t openstudio-mcp-necb:latest .
```

This builds directly from the official OpenStudio 3.11.0 image. No existing
`openstudio-mcp:dev` image or files outside this folder are required. Internet
access is required for the pinned SDK image, measure archives, standards and gems.
The supported/tested platform for this Canadian release is Linux amd64.

## Connect Codex

Create three data directories outside this source checkout:

```powershell
New-Item -ItemType Directory -Force C:/openstudio-data/inputs,C:/openstudio-data/runs,C:/openstudio-data/measures
```

Merge [examples/codex-config.toml](examples/codex-config.toml) into your existing
`~/.codex/config.toml`. Replace its three host paths with your own absolute paths;
keep `/inputs`, `/runs` and `/measures` as the container paths. Restart the MCP
connection after building or replacing the image. The example uses Docker
directly and does not require the Codex CLI to be installed on PATH.

Codex configuration fields follow the
[official MCP documentation](https://developers.openai.com/codex/mcp).
The example gives synchronous NECB calls a 1,500-second tool timeout.

## Canadian tools and defaults

- `get_necb_capabilities`: installed versions, source revision, prototypes and defaults.
- `create_necb_building`: create Canadian prototype geometry and apply its NECB rules.
- `apply_necb_ruleset`: apply Canadian rules to an existing classified model.

The last two tools default to `thermal_bridging_option="none"`, `use_kiva=true`
and `terrain="City"`. Explicit arguments override these defaults. `none` skips
TBD bridge calculations; Kiva can be disabled with `use_kiva=false` to select
NRC's documented crash workaround. Terrain is set before sizing and in the
final model. Returned assumptions and foundation counts make these choices visible.

Ask the MCP host to call `get_necb_capabilities`. Expect `available=true`,
`kiva_default=true`, `thermal_bridging_default="none"`, and `terrain_default="City"`.
For MediumOffice creation, use `building_type="MediumOffice"`,
`template="NECB2020"` and a Toronto EPW path under `/inputs` with matching DDY
and STAT files. Save with `save_osm_model`; after reloading, `validate_model`
should report `terrain="City"`, `terrain_defaulted=false`. It warns on terrain drift.

## Versions and validation

OpenStudio SDK 3.11.0 / EnergyPlus 25.2; Canadian standards source commit
`327689b0fe76331d781120ebc81d0f444f2546ba` from `nrcan_nrc` (version 0.8.4).
The Canadian Ruby bundle and exact Python versions have separate lockfiles.
The original SDK/ASHRAE bundle remains separate.

```powershell
docker run --rm -e RUN_OPENSTUDIO_INTEGRATION=1 -e MCP_SERVER_CMD=openstudio-mcp -e OSMCP_SANDBOX=auto openstudio-mcp-necb:latest bash -lc "cd /repo && pytest -vv tests/test_necb.py tests/test_validate_model.py tests/test_skill_registration.py tests/test_skill_docs.py"
```

See [release notes](RELEASE.md) for validation evidence and limitations,
[Canadian implementation](docs/canadian-necb.md) for details, and
[NRC source review](docs/nrc-server-comparison.md) for the Kiva/gem decisions.
Ruleset application and successful simulation do not certify NECB compliance.