hcl-mcp — Human-Centric Lighting MCP Server

A literature-grounded human-centric-lighting (HCL) engine exposed as a local Model Context Protocol server. It computes CIE S 026 α-opic and circadian metrics, reconstructs a physical spectral sky from an EPW, drives the per-channel Radiance daylight/electric/glare pipeline, and estimates light-driven alertness — all callable from any MCP client in natural language.

The spectral and circadian methods implement published models directly: Bird & Riordan 1986 (SPECTRL2 clear sky), Nann & Riordan 1991 (SEDES1 cloud modifier), CIE S 026:2018 (α-opic action spectra), Amundadottir 2016 (nvRD alertness), Inanici, Brennan & Clark 2015 (3-/9-channel). Full citation map and grounding-status index: docs/literature-bibliography.md.

Version 0.1.0 · Python ≥ 3.11 · License MIT Optional engines Radiance 6.1a (daylight / electric / glare / native spectral) · Daysim (sub-hourly weather) · SMARTS (spectral oracle)

The pure-Python spectral core has zero runtime dependency on Radiance or Daysim — it always runs. The simulation layers follow a strict run-or-emit contract: if the binary is present they execute; if not, they return the exact command sequence they would have run.

Install in two lines

In Claude Code:

/plugin marketplace add akontadakis/hcl-mcp
/plugin install hcl-mcp@hcl-mcp

Restart Claude Code and the 47 tools are live, together with the running-hcl-studies skill. You need uv on your PATH; Radiance stays optional. Other hosts and the manual route are under Installation.

• Key Features

• What It Computes

• Installation

• The run/emit contract

• Capabilities

• Usage Examples

• Architecture

• Dataflow

• Project Structure

• Configuration

• External Engines

• Troubleshooting

• Validation & Accuracy Caveats

• Documentation

• References & License

Related MCP server: ladybug-tools-mcp

Key Features

• 🌈 Spectral foundation — SPD → 3-/9-channel bins; the full CIE S 026 α-opic suite (S/M/L-cone, rhodopic, melanopic E / ELR / EDI), photopic / melanopic / neuropic equivalent illuminance, CCT + Duv, mel-DER, EML.

• 🌌 Physical spectral sky from EPW — radiative transfer instead of CIE-D-series templates: a pure-Python Bird SPECTRL2 clear-sky engine plus the SEDES1 cloud bridge, driven by EPW-derived atmosphere (AOD / PWV / ozone) and solar geometry, resampled to 1 nm over 380–780 nm. The clear-sky engine is selectable (engine="spectrl2" default | "smarts"), and Radiance 6.x gensdaymtx is exposed as its own native tool. Four atmospheric refinements are opt-in and every default reproduces the base physics byte-for-bit.

• ☀️ Spectral daylight simulation — colored Perez sky/sun plus the per-channel Radiance pipeline: point-in-time grids, fisheye eye-level images, 2-phase annual Daylight-Coefficient (DDS) runs with circadian dosimetry, climate-based metrics (DA/cDA/UDI, sDA/ASE), CIE-overcast Daylight Factor, and LM-83-12 sDA/ASE with blinds actually operated.

• 💡 Electric lighting — IESNA LM-63 photometry, ies2rad conversion, EnergyPlus-faithful daylight-responsive controls and energy savings, glare via evalglare (UGR/DGP), and EN 12464-1 task interpretation.

• 🧠 Circadian alertness — the nvRD non-visual direct-response model (Amundadottir 2016) with an automatic annual → alertness bridge driven by Daysim sub-hourly weather.

• ✅ Compliance — mel-EDI / EML verdicts against WELL v2 L03, Brown 2022, ISO/CIE 8995-1:2025 and EN 17037, plus EN 12464-1:2021 task lighting. Each verdict carries its threshold, citation and measurement convention.

• 📐 OBJ/CAD geometry import — a real Wavefront .obj room becomes a per-channel Radiance scene with per-group spectral materials, true-north orientation, derived sensors (work-plane grid, seated and standing eye observers, DGP views), a ground↔sky albedo bridge, drop-in luminaires, and a provenance manifest. Unmapped groups hard-fail — no silent generic material.

• 🧭 Guided studio journey — hcl_studio runs a full study end to end (goal → fixture design via recommend_fixtures → simulate → build_report) with a resumable brief.

• 🔬 Verifiable — a built-in validate() self-test anchors constants against CIE S 026 published values, and every constant is documented against the source line it came from.

What It Computes

Installation

→ Full manual for macOS / Windows / Linux across five clients: INSTALL.md. The summary below is the short version.

Requirements

External engines are optional — see External Engines.

Claude Code — plugin (two lines)

This repository is also a Claude Code plugin marketplace, so one install registers the server and the running-hcl-studies skill:

/plugin marketplace add akontadakis/hcl-mcp
/plugin install hcl-mcp@hcl-mcp

Restart Claude Code and check with /mcp. The plugin launches uvx --from git+https://github.com/akontadakis/hcl-mcp hcl-mcp and declares no environment variables — the server inherits your shell's, so put HCL_RADIANCE_BIN / RAYPATH in your shell profile, or use the CLI method below, which takes --env. Manage it later with /plugin.

Claude Code (CLI)

claude mcp add hcl-mcp -- uvx --from git+https://github.com/akontadakis/hcl-mcp hcl-mcp

uvx fetches, builds and caches the server on first run. Add variables with --env (repeatable), e.g. --env HCL_RADIANCE_BIN=/usr/local/radiance/bin. Use -s user to register globally.

Claude Desktop / other MCP clients

{
  "mcpServers": {
    "hcl-mcp": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/akontadakis/hcl-mcp", "hcl-mcp"],
      "env": {
        "HCL_WORK_ROOT": "/ABSOLUTE/PATH/TO/work",        // optional: where sim files are written
        "HCL_RADIANCE_BIN": "/usr/local/radiance/bin",    // optional: Radiance bin dir if not on PATH
        "HCL_DAYSIM_BIN": "/ABSOLUTE/PATH/TO/daysim/bin"  // optional: Daysim bin dir
      }
    }
  }
}

Remove the // comments — JSON does not allow them. VS Code uses servers (not mcpServers) and needs "type": "stdio"; see INSTALL.md.

⚠️ Running from a local clone? Use uv tool install . (the launch command is then just hcl-mcp), not uv run --directory …. uv run's implicit sync can leave the editable install in a state where the bare interpreter cannot import the src/-layout packages, and the server dies with ModuleNotFoundError: hcl_core. See INSTALL.md Method B.

Development setup

uv sync --extra dev      # runtime + pytest
uv run pytest -q         # full test suite

The run/emit contract

Every tool that touches Radiance or Daysim takes run: bool = True and behaves identically:

• run=True and the binary is available → it executes and returns results.

• run=False, or the binary is missing → it does not execute and returns {"ran": false, "commands": [ ...exact ordered shell lines... ], "reason": ...}.

So you can design and inspect a full pipeline — sky generation, octree compilation, ray tracing, matrix multiplication — on any machine, then run the identical commands where an engine exists. Call validate(), radiance_status() and daysim_status() first to see which layers will execute.

Capabilities

47 tools · 14 resources · 13 prompts. The server registers 51 tool names: the 47 plus four verb-object aliases (get_reference, list_presets, import_weather, run_validation) for clearer AI tool selection.

→ Every tool with its full signature, semantics and honesty notes: docs/operating-guide.md §4. Resources and prompts: §5.

Two things worth knowing before you read any result:

• quality_presets makes the ambient-accuracy/runtime trade-off explicit rather than inherited. low (-ab 0) has no interreflection, so DA/sDA/UDI are meaningless there while ASE stays exact; high (-ab 3) is the floor for anything reportable. On one validated annual run the preview-grade default returned sDA 77.78% where a converged solve returned 100.00% on identical geometry — hence the convergence_warning that annual_daylight now attaches.

• Advisories. Any tool returning a dict may carry an advisories list — absent entirely when there is nothing to flag. Each entry is {code, severity, message, field?} with severity error (result probably unusable), warn (usable but easy to misreport) or info (a default was applied). They are reporting, not physics: each rule re-reads a field the tool already computed. The nine codes are MEL_DER_BINNED, SPECTRAL_TRANSPORT_SHIFT, ELECTRIC_EXCEEDS_LUMEN_BOUND, ALBEDO_NOT_MEASURED, DOSE_THRESHOLD_IS_DEFAULT, ZONE_WEIGHT_REMAINDER, GEOMETRY_HEALTH_UNCLEAN, NVRD_ZERO_DIVERGENCE and RADIANCE_DROPS_IES_CANDELA_SCALE; each is defined in docs/operating-guide.md and docs/technical-reference.md, and ADR-0005 explains why they attach at the registration seam. Known v1 gap: advisories attach only to dict results, so multi-point circadian_metrics (which returns a list) carries none — check mel_der_source per point by hand there.

Usage Examples

These show the underlying tool calls. In an MCP client you just ask in natural language ("What's the melanopic EDI of D65 and does it pass WELL v2?") and the model picks the tools. channel_type: 0 = 3-channel, 1 = 9-channel. spd accepts a .spd file path, SPD text, or (wavelength, value) rows.

1 · SPD → circadian metrics + compliance (pure Python — no engine needed)

{ "tool": "presets",          "arguments": { "name": "D65" } }
{ "tool": "spd_to_channels",  "arguments": { "spd": "<SPD data from step 1>", "channel_type": 1 } }
{ "tool": "alpha_opic",       "arguments": { "channels": [0.10,0.12,0.20,0.30,0.35,0.33,0.25,0.18,0.12], "channel_type": 1 } }
{ "tool": "compliance",       "arguments": { "mel_edi": 250, "standard": "well_v2_l03" } }

2 · Annual climate-based daylight metrics (reuse one named sensor set across the daylight tools)

{ "tool": "sensors", "arguments": {
    "action": "create", "name": "wp",
    "grid": { "interior": [0.25, 5.75, 0.25, 3.75], "floor_z": 0.0, "workplane_h": 0.8 } } }
{ "tool": "annual_daylight", "arguments": {
    "channel_scenes": [{ "materials": "materials.rad", "geometry": "room.rad", "sky_color": [0.9, 0.95, 1.0] }],
    "wea": "athens.wea", "sensor_set": "wp", "channel_type": 0,
    "da_threshold": 300, "sda_da_fraction": 0.5, "ase_threshold": 1000, "ase_hours": 250, "run": true } }
{ "tool": "daylight_factor", "arguments": {
    "scene_sets": ["materials.rad", "room.rad"], "sensor_set": "wp", "run": true } }

annual_daylight returns per-point DA/cDA/UDI plus spatial sDA/ASE (ASE via its own direct-only -ab 0 pass — the two lux matrices are not interchangeable); daylight_factor adds the CIE-overcast DF %.

3 · Guided studio journey — design the fixtures, then grade the result (the front door)

Say "design human-centric lighting for a 6×4×3 m office targeting WELL mel-EDI 250 and run a study." The hcl_studio prompt conducts all 8 phases; the design and reporting steps are pure Python and always run.

{ "tool": "recommend_fixtures", "arguments": {
    "length_m": 6, "width_m": 4, "height_m": 3, "mount_height_m": 2.8,
    "target_em_lux": 500, "target_mel_edi": 250 } }
{ "tool": "build_report", "arguments": { "study": "office_a", "brief": "<accumulated brief>" } }

→ Colored sky + grid, annual circadian dose, electric design + glare, and the full studio walkthrough: docs/operating-guide.md §3.

Architecture

Five modules in four layers. Imports point downward only, so knowing which layer a tool lives in tells you what it needs to run.

┌──────────────────────────────────────────────────────────────────────────┐
│  hcl_mcp/      Thin FastMCP server — 47 tools, 14 resources, 13 prompts. │  ← pure protocol
│                Maps tools onto the modules below; no business logic.     │
├─────────────────────────────────┬────────────────────────────────────────┤
│  hcl_radiance/                  │  hcl_daysim/                           │  ← ONE layer, two peers
│  Radiance adapter: detect       │  Daysim adapter (ds_shortterm /        │    (not stacked)
│  binaries → build commands →    │  epw2wea). Sub-hourly weather for      │    each needs its own
│  run-or-emit → parse. Native    │  the alertness bridge.                 │    engine; Daysim is
│  gensdaymtx · OBJ import.       │  Build-from-source.                    │    build-from-source
│              └───── annual nvRD borrows the .wea generator ─────┘        │  ← the one lateral edge
├─────────────────────────────────┴────────────────────────────────────────┤
│  hcl_core/     Pure-Python spectral math (≤401-pt arrays, plain loops).  │  ← always runs,
│                CIE S 026 α-opic, channels, circadian metrics,            │     zero engine deps
│                compliance, nvRD model, spectral reconstruction, and the  │
│                physical EPW→spectral-sky pipeline (SPECTRL2 + SEDES1).   │
├──────────────────────────────────────────────────────────────────────────┤
│  hcl_platform/ Cross-platform path, text-I/O and executable resolution.  │  ← stdlib only
└──────────────────────────────────────────────────────────────────────────┘

The separation is enforced, not conventional: tests/test_module_layering.py walks src/ and fails the suite on any import above a module's layer. hcl_core has zero dependency on the Radiance/Daysim binaries — the property that makes the spectral core portable. The one caveat is the optional SMARTS oracle (hcl_core/spectral_engine/smarts.py), the single core path that shells out, capability-gated on $SMARTSPATH. All Radiance/Daysim subprocess transport lives in hcl_radiance / hcl_daysim; the MCP layer holds no business logic.

Dataflow

Every tool is a node in one of six pipelines. All inputs reduce to a small set of canonical artifacts — an SPD, a channel vector, a Radiance scene, an EPW, an IES luminaire — and the pipelines converge on circadian metrics, a compliance verdict, or a report.

  A · SPECTRAL CORE   (hcl_core — pure Python, always runs)
  SPD ─┬─ spd_to_channels ─► channels[3|9] ─┬─ alpha_opic ───────► α-opic E/ELR/EDI, mel-EDI ─┐
  preset┘  (or exact SPD ─────────────────► )├─ circadian_metrics ► photopic/melanopic lux, EML ├─► compliance
                                             └─ spectral_metrics ─► CCT/Duv, mel-DER, EML↔EDI ┘   └─► PASS/FAIL + citations

  B · DAYLIGHT SIMULATION   (hcl_radiance — run-or-emit)
  channels ─► colored_sky ─► sky.rad ─┐
  scene (.rad materials + geometry) ──┼─► run_grid  ─► oconv → rtrace -I ×channel ─► grid HCL metrics
                                      ├─► run_image ─► rpict ×channel ───────────► melanopic luminance maps
  weather (.wea) ─────────────────────┴─► run_annual ─► 2-phase DDS ─────────────► annual mel-EDI ─► dosimetry

  C · PHYSICAL SPECTRAL SKY   (hcl_core; native variant run-or-emit)
  EPW + (m,d,h) ─► atmosphere + solar geometry ─► SPECTRL2 + SEDES1 ─► SpectralSkyRecord
                                                  ─► channels · reconstruction · emitters · α-opic

  D · ELECTRIC LIGHTING   (hcl_core analysis + hcl_radiance render)
  IES (LM-63) ─┬─ ies_analyze ──────────────────────► photometric report
               └─ ies_to_radiance ─► colored_luminaire ─┐
  scene + sky ──────────────────────────────────────────┴─► glare_ugr ─► UGR/DGP + glare sources
  illuminance @ points ─► lighting_controls ─► daylight_savings ──────► savings (kWh/m²·yr)

  E · CIRCADIAN ALERTNESS   (hcl_daysim sub-hourly → hcl_core nvRD)
  EPW ─► generate_subhourly_wea ─► .wea ─► annual_nvrd ─┬─ reconstruct_spectrum ─► per-nm SPD
                                                        └─ nvrd ─► R_D(t) + cumulative dose

  F · GUIDED STUDIO JOURNEY   (hcl_studio prompt orchestrates)
  goal ─► recommend_fixtures ─► save_brief ─► [run B / D sims] ─► build_report ─► report.{md,html}

Three properties hold across all six: the core path always runs; the simulation paths run-or-emit; and physics is computed once, then consumed — the SpectralSkyRecord is frozen sky-truth and nothing downstream recomputes it.

→ Pipeline C stage by stage, with boundary data structures and per-symbol source map: docs/spectral-sky-methodology.md §3 and docs/spectral-sky-as-built.md.

Project Structure

hcl-mcp/
├── src/
│   ├── hcl_core/         # Pure-Python spectral math (the verifiable asset)
│   │                     #   α-opic integrals · action spectra · SPD binning · CCT/Duv
│   │                     #   compliance · nvRD · spectral reconstruction · daylight metrics
│   │                     #   LM-83 + Klems · IES · lighting controls · fixture design
│   │                     #   EPW → atmosphere/solar geometry → SPECTRL2 + SEDES1 → sky record
│   │   └── spectral_engine/   # pluggable clear-sky engines: spectrl2 (pure Python) · smarts (gated)
│   ├── hcl_radiance/     # Radiance adapter: detect → build commands → run-or-emit → parse
│   │                     #   grid · image · annual DDS · three-phase LM-83 · OBJ import
│   │                     #   sensors · glare · native gensdaymtx
│   ├── hcl_daysim/       # Daysim adapter: epw2wea, ds_shortterm, build-from-source
│   ├── hcl_mcp/          # FastMCP server: tools, resources, prompts, advisories, studio
│   └── hcl_platform/     # Cross-platform paths, text I/O, executable resolution (stdlib only)
├── tests/                # Unit + layering + capability-gated live tests
├── hcl_validation/       # End-to-end validation kit driven through real chat tool-calls
├── docs/                 # Methodology, technical reference, ADRs, engine build guides
├── skills/               # running-hcl-studies (auto-loaded by the Claude Code plugin)
├── .claude-plugin/       # Plugin marketplace + plugin manifest
└── .mcp.json             # Server declaration used by the plugin

hcl_validation/ is the complement to tests/: tests/ verifies the Python math in isolation, the kit exercises the whole MCP surface the way a user drives it — every tool called live, every resource read, every prompt rendered. Start at its README.md, then GUIDE.md and TEST-PLAN.md.

Configuration

All environment variables are optional.

work_dir precedence: explicit tool argument → HCL_WORK_ROOT → first MCP client root → ~/hcl_work.

External Engines

→ Get-source → build → set-env → verify checklist for all three: docs/engines-install.md.

Troubleshooting

Validation & Accuracy Caveats

This toolkit is honest about what is proven versus what is latent. Read this before trusting a live run. Canonical wording lives in docs/spectral-sky-as-built.md §9 and docs/technical-reference.md §12–13.

Verified

• ✅ The spectral math. validate() anchors K_D65 against CIE S 026 published values (within 0.05%), checks weight-sum and scale-invariance properties, and confirms mel-DER(D65) ≈ 1.0. Two deliberate fixes over the Lark source are applied (Python-2 integer division; a 3-channel bin-ordering misalignment).

• ✅ The grid daylight pipeline. A unit-radiance hemisphere reproduces 562.345 lux = 179 × π on both the 3- and 9-channel paths under live Radiance.

• ✅ OBJ geometry import — live-checked on Radiance 6.1a: the obj2rad → xform → oconv → rtrace round-trip, a north-rotation round-trip, an IES-luminaire octree build, and the colored-by-material annotate render.

• ✅ The offline spectral stack. EPW → atmosphere/solar geometry → SPECTRL2 → SEDES1 → SpectralSkyRecord → artifacts is unit-tested end to end; the SPECTRL2 constants are transcribed verbatim from the NREL spectrl2_2.c source.

First live runs, not calibrated baselines

• ⚠️ gensdaymtx and SMARTS. SMARTS agrees with the Python SPECTRL2 engine to ~2% direct / ~7% diffuse, r≈0.99 (docs/spectral-engine-comparison.md). Neither is validated against measured sky spectra.

• ⚠️ The physical_sky flip. First live execution 2026-07-18 measured 50.03% physical coverage — daylight timesteps carry EPW-derived spectra, night timesteps fall back to the template by design — with a time-resolved sun throughout.

• ⚠️ annual_daylight / daylight_factor / daylight_savings / sensors. All ran live on a realistic office plus Athens IWEC. Two identical preview-grade runs gave sDA 66.7% and 82.2% — Radiance's ambient calculation is stochastic, so preview-grade sDA is not reproducible. ASE was bit-identical across runs, since its direct-only pass has no ambient sampling. Use quality="high" for anything you intend to quote.

• ⚠️ The electric path. First end-to-end live run 2026-07-18. It exposed a Radiance build defect, not an hcl-mcp one: a custom 6.1a build's compiled source_corr dropped the ies2rad A1 candela-scale multiplier, so IES luminaires under-emitted ~14×, which also collapsed UGR to 0. Patching source.cal gave a realistic 494 lux average and UGR 19.24 / DGP 0.199. Do not fold A1 into colored_luminaire — that double-scales on a stock Radiance. Sky paths are unaffected.

Known limits

• ⚠️ R_D (alertness) is relative only. The nvRD intensity response was fit from nighttime electric-light studies; daytime adaptation is unvalidated, and an unexplained channel→irradiance constant biases the absolute value (it cancels in ELR/EDI ratios but not in the nonlinear sigmoid).

• ⚠️ The SEDES1 cloud CCM carries real spectral-shape uncertainty. Only the always-on energy rescale is exact. Per-wavelength regression uncertainty is surfaced as ccm_sigma; the CCM can be locally re-fit (docs/recalibrating-cloud-ccm.md). The opt-in SEDES2 tabulated alternative closes the digitization caveat but remains a German-site fit, and its independent variable is NGH, not Kt — it is not a drop-in.

• ⚠️ Spectral physics is opt-in. Without physical_sky=True the enhanced reconstruction uses the reference-sky template with an air-mass-colored sun. The seam is wired, not on by default.

• ⚠️ lm83_method_conformant is always false by design. §§2.2.8–2.2.11 are out of scope, so glazing runs at raw tvis, biasing sDA up. Read conditions.departures before quoting.

• ⚠️ The OBJ carries no spectral data. Reflectances are user-assigned; .mtl is a hint. The measured-SPD path exists, but the shipped catalog is illustrative scalars pending data.

• 📐 Accuracy envelope (Lark, Pierson 2023): daylight mel-EDI within ±20%, validated for neutral-colored interiors — chromatic or strongly inter-reflecting scenes degrade. 3-channel is an approximation; 9-channel is recommended, and the exact-from-SPD α-opic path is provided for validation.

Documentation

References & License

The load-bearing authorities. The complete map, with grounding status per claim, is in docs/literature-bibliography.md.

Acknowledgements & License

hcl-mcp is released under the MIT License — © 2026.

It is an independent implementation grounded in primary scientific literature that derives certain spectral algorithms from Lark Spectral Lighting (Mehlika Inanici et al., University of Washington; ZGF Architects LLP; EPFL; Oregon State University; Eindhoven University of Technology) — a prior implementation of the same science — and invokes the Radiance (LBNL) and Daysim (NRC / Fraunhofer ISE) engines as external subprocesses. It bundles no Lark, Radiance, or Daysim binaries.

The Lark algorithms are distributed under a Modified 3-Clause BSD License; its copyright notice is retained, and this product is named hcl-mcp (not "Lark") in compliance with that license. Radiance, Daysim and all Python dependencies (fastmcp — Apache-2.0; mcp, pydantic — MIT; colour-science — BSD-3-Clause) retain their own licenses.

→ Full attributions and license texts: THIRD-PARTY-NOTICES.md.