lbnl-eta/energyplus-mcp

1. Purpose and boundary

This repo is a Python-based Model Context Protocol (MCP) server for EnergyPlus. Its job is to expose building-model operations as tools to external MCP clients; it does not implement a UI or store persistent app state. The primary domain objects are EnergyPlus IDF models, weather EPW files, and simulation outputs.

2. Top-level request flow

An MCP client connects to the server over either stdio or streamable HTTP. The server accepts tool calls, routes them through a tool registry, and then delegates to EnergyPlus-specific orchestration code. Results are returned directly to the client, usually as structured text/data plus generated files in the workspace.

3. Protocol layer

server.py is the main MCP entrypoint and likely hosts the FastMCP application. This layer is the contract boundary with clients: it defines the 35 tools, handles initialization, and exposes server management capabilities such as status and logs.

4. HTTP transport and auth boundary

http_app.py and auth.py define the optional authenticated HTTP transport used for remote-style deployments and local testing. This is a separate boundary from stdio: HTTP requests go through bearer-token validation and health-check endpoints before reaching the MCP handler.

5. Configuration and EnergyPlus installation detection

config.py centralizes environment-driven configuration such as EPLUS_IDD_PATH, sample/output paths, transport mode, host/port, and HTTP token settings. It also encodes the coupling to the installed EnergyPlus distribution, including the default version and installation layout, so the server can run in Docker or on a local machine.

6. Core EnergyPlus orchestration

energyplus_tools.py is the main service layer that performs the actual work behind tools: loading models, validating them, modifying IDF content, running simulations, and collecting results. This is the most important internal boundary: higher layers speak MCP, while this layer speaks EnergyPlus model and filesystem operations.

7. Domain-focused utility modules

The utils/ package contains specialized helpers for EnergyPlus object families and outputs:

- people_utils.py, lights_utils.py, electric_equipment_utils.py for load objects

- schedules.py for schedule inspection/modification

- output_variables.py and output_meters.py for output discovery/configuration

- diagrams.py for HVAC visualization

- path_utils.py for resolving files safely across repo/workspace boundaries

These modules keep domain-specific logic out of the transport and orchestration layers.

8. Data sources and file-based workflow

The repo is centered on files on disk rather than a database or external service. sample_files/ provides small IDFs and EPWs used by tools and tests, while illustrative examples/ contains larger reference models and their EnergyPlus output artifacts. Typical flow is: load IDF → inspect/modify → run simulation with EPW → inspect generated outputs.

9. Simulation and output artifacts

EnergyPlus runs generate a broad set of outputs: .err, .csv, .eso, .eio, .rdd, .mtd, .mdd, diagrams, and HTML reports. The tools layer appears to surface both simulation execution and post-processing, including plots and loop diagrams, so the output directory is part of the operational architecture.

10. Operational modes

The repository supports three runtime patterns: local stdio MCP, Docker-based stdio MCP, and HTTP MCP with tokens. The devcontainer/Dockerfile bakes in EnergyPlus 26.1.0, making the container image the deployment boundary for clients that want a self-contained runtime.

11. Testing and validation

tests/ covers configuration transport behavior, auth behavior, server behavior, and EnergyPlus integration-related paths. This suggests the most important failure modes are startup/configuration, authorization, and tool availability rather than business logic persistence.

12. Diagramming takeaway

For an architecture diagram, the most accurate shape is: MCP client → transport/auth layer → MCP server/tool registry → EnergyPlus orchestration → domain utilities + filesystem/EnergyPlus engine. The only external runtime dependency that materially affects the architecture is the EnergyPlus installation, which is required for model parsing, simulation, and output generation.