Initialize or refresh the model map cache for EnergyPlus models.

Scans a directory for EnergyPlus model files (.epJSON, .sql, .htm) and creates a cached model map for efficient access. Call this first before accessing model data.

Args: directory: Directory containing EnergyPlus model files. Defaults to 'DEFUALT_DIRECTORY'.

Returns: Status message confirming successful initialization.

Retrieve all available EnergyPlus models and their metadata.

Returns detailed information about all discovered EnergyPlus models, including their unique identifiers for use with other tools.

Args: directory: Directory parameter (currently ignored, uses default directory).

Returns: List of dictionaries containing model information: - model_id: Unique identifier for use with other tools - codename: Model standard (e.g., 'ASHRAE901') - prototype: Building type (e.g., 'HotelLarge', 'Warehouse') - codeyear: Code year (e.g., 'STD2025') - city: Location (e.g., 'Buffalo', 'Tampa') - label: HVAC system type (e.g., 'gshp', 'vav_ac_blr') - file paths for epJSON, SQL, and HTML files

Retrieve a specific HTML table from an EnergyPlus model using a tuple query.

Args: id: The model_id of the EnergyPlus model (obtain from get_available_models). query_tuple: A tuple containing (zone/component, report_name, table_name) to identify the specific table to retrieve.

Returns: JSON string containing the requested table data with columns and rows.

Retrieve a specific RDD file from an EnergyPlus model using ID. Useful in debugging.

Args: id: The model_id of the EnergyPlus model (obtain from get_available_models).

Returns: Plain text output of RDD file, which shows available output reports.

Retrieve a specific Error file from an EnergyPlus model using ID. Useful in debugging.

Args: id: The model_id of the EnergyPlus model (obtain from get_available_models).

Returns: Plain text output of EPlus error file

List available hourly timeseries variables in the SQL output for a specific model.

Discovers all hourly timeseries data available in a model's SQL output database, providing variable names and RDD IDs needed to extract specific timeseries data.

Args: id: The model_id of the EnergyPlus model (obtain from get_available_models).

Returns: Available hourly timeseries variables including: - Variable names (e.g., 'Zone Air Temperature', 'HVAC Electric Power') - RDD IDs for use with get_timeseries_report_by_rddid - Units and key values for each variable

Search for specific objects in epJSON data structure.

Searches through the epJSON model data to find objects matching the specified criteria. Useful for finding specific components, systems, or zones within the building model.

Args: model_id: The model_id of the EnergyPlus model object_type: Specific EnergyPlus object type (e.g., "Coil:Cooling:WaterToAirHeatPump:EquationFit") object_name: Specific object name (e.g., "ROOM_1_FLR_3 COOLING COIL") search_pattern: Pattern to search for in object names (e.g., "ROOM_1_FLR_3") case_sensitive: Whether to perform case-sensitive search

Returns: Dictionary containing: - search_results: Matching objects organized by type - search_criteria: The search parameters used - search_stats: Statistics about the search results

Get detailed properties of a specific EnergyPlus object.

Retrieves all properties and values for a specific object in the epJSON model, providing complete configuration details for analysis.

Args: model_id: The model_id of the EnergyPlus model object_type: EnergyPlus object type object_name: Specific object name

Returns: Dictionary containing: - object_type: The EnergyPlus object type - object_name: The specific object name - properties: All object properties and their values - property_count: Number of properties - model_id: The model identifier

List all objects of a specific type in the epJSON model.

Retrieves all objects of a specified EnergyPlus object type, providing an overview of all components of that type in the building model.

Args: model_id: The model_id of the EnergyPlus model object_type: EnergyPlus object type to list

Returns: Dictionary containing: - object_type: The requested object type - object_count: Number of objects found - objects: All objects of the specified type with their properties - model_id: The model identifier

Search for all objects related to a specific component or pattern.

Finds all objects in the epJSON model that contain a specific pattern in their names, useful for analyzing all components related to a particular zone, system, or equipment.

Args: model_id: The model_id of the EnergyPlus model search_pattern: Pattern to search for (e.g., "ROOM_1_FLR_3")

Returns: Dictionary containing: - search_pattern: The pattern that was searched for - total_matches: Total number of matching objects - related_objects: Objects organized by type, with counts and details - model_id: The model identifier

Retrieve hourly timeseries data for a specific variable from an EnergyPlus model.

Extracts complete hourly timeseries data for a specific variable using its RDD (Report Data Dictionary) ID, providing timestamped values for analysis.

Args: model_id: The model_id of the EnergyPlus model (obtain from get_available_models). rddid: A list of RDD IDs (integers) for the desired variables (obtain from get_sql_available_hourlies).

Returns: List of timestamped records, each containing: - dt: Timestamp for the data point - Value: Numeric value for the variable - Name: Variable name (e.g., 'Zone Air Temperature') - KeyValue: Zone or component identifier - Units: Units of measurement

Example: First use get_sql_available_hourlies to find the RDD ID for 'Zone Air Temperature', then use that ID with this tool.

Get comprehensive usage instructions for the EnergyPlus MCP server.

Returns detailed documentation about how to use all available tools, including workflow guidance, data structures, and best practices.

Returns: Complete usage instructions and documentation for the MCP server.

Search for HTML tables containing specific keywords in their names.

Filters available HTML tables based on keyword matches in table names, report names, or other metadata. Useful for finding specific types of tables like 'cooling', 'heating', 'energy', etc.

Args: id: The model_id of the EnergyPlus model (obtain from get_available_models). keywords: List of keywords to search for (e.g., ['cooling', 'coil', 'capacity']) case_sensitive: Whether to perform case-sensitive search (default: False)

Returns: Dictionary containing: - matching_tables: List of tables that match the keywords - search_keywords: The keywords that were searched for - total_matches: Number of matching tables found - search_stats: Statistics about the search - model_id: The model identifier

Examples: # Find cooling-related tables search_html_tables_by_keyword(model_id, ['cooling', 'coil'])

# Find energy consumption tables
search_html_tables_by_keyword(model_id, ['energy', 'consumption'])

# Case-sensitive search for specific terms
search_html_tables_by_keyword(model_id, ['DX', 'VAV'], case_sensitive=True)

Common Keyword Categories:

Energy & Consumption: ['energy', 'consumption', 'end use', 'site energy', 'source energy', 'electricity', 'natural gas', 'fuel', 'annual', 'monthly', 'utility', 'cost', 'performance']

Cooling Systems: ['cooling', 'coil', 'capacity', 'chiller', 'dx cooling', 'sensible cooling', 'latent cooling', 'peak cooling', 'cooling tower', 'evaporative cooler', 'refrigeration']

Heating Systems: ['heating', 'boiler', 'heat pump', 'heating coil', 'heat recovery', 'sensible heating', 'peak heating', 'furnace', 'baseboard', 'radiant heating', 'heat exchanger']

HVAC Components: ['fan', 'pump', 'air loop', 'plant loop', 'zone equipment', 'terminal unit', 'ahu', 'air handler', 'vav', 'cav']

Building Envelope: ['window', 'wall', 'roof', 'floor', 'construction', 'material', 'thermal bridge', 'infiltration', 'ventilation']

Lighting & Equipment: ['lighting', 'electric equipment', 'gas equipment', 'occupancy', 'schedule', 'internal load', 'plug load']

Execute a pandas query on the cached DataFrame.

Args: file_hash (str): Hash of the loaded parquet file to query. query (str): The pandas query to execute.

Returns: str: Formatted result of the query.

Execute multi-line pandas operations on the cached DataFrame.

Args: file_hash (str): Hash of the loaded parquet file to query. query (str): Multi-line Python code to execute.

Returns: str: Formatted result or status message.

Notes: Does not accept import statements or print statements.

Execute pandas operations on timeseries data from an EnergyPlus model.

Retrieves timeseries data for a specific variable and executes pandas operations on it. The dataframe is available as 'df' in your query.

Args: model_id: The model_id of the EnergyPlus model (obtain from get_available_models). rddid: A list of RDD IDs for the desired variable (obtain from get_sql_available_hourlies). query: Pandas query to execute (e.g., "df.describe()", "df['Value'].mean()")

Returns: String representation of the query result with formatted output.

Examples: # Get basic statistics execute_pandas_on_timeseries(model_id, rddid, "df.describe()")

# Get hourly averages by month
execute_pandas_on_timeseries(model_id, rddid, "df.groupby(df['dt'].dt.month)['Value'].mean()")

# Find peak values
execute_pandas_on_timeseries(model_id, rddid, "df.loc[df['Value'].idxmax()]")

Execute multi-line pandas code on timeseries data from an EnergyPlus model.

Retrieves timeseries data for a specific variable and executes multi-line pandas code on it. The dataframe is available as 'df' in your code. Use 'result = ...' to return values.

Args: model_id: The model_id of the EnergyPlus model (obtain from get_available_models). rddid: List of RDD IDs for the desired variables (obtain from get_sql_available_hourlies). code: Multi-line Python code to execute

Returns: String representation of the result or execution status.

Examples: # Complex analysis with multiple steps code = ''' df['hour'] = df['dt'].dt.hour df['month'] = df['dt'].dt.month monthly_peaks = df.groupby('month')['Value'].max() result = monthly_peaks ''' execute_multiline_pandas_on_timeseries(model_id, rddid, code)

Execute pandas operations on HTML table data from an EnergyPlus model.

Retrieves an HTML table and executes pandas operations on it. The dataframe is available as 'df' in your query.

Args: id: The model_id of the EnergyPlus model (obtain from get_available_models). query_tuple: A tuple containing (zone/component, report_name, table_name) to identify the table. query: Pandas query to execute (e.g., "df.describe()", "df.sum()")

Returns: String representation of the query result with formatted output.

Examples: # Get summary statistics execute_pandas_on_html_table(model_id, query_tuple, "df.describe()")

# Find maximum values
execute_pandas_on_html_table(model_id, query_tuple, "df.max()")

# Filter data
execute_pandas_on_html_table(model_id, query_tuple, "df[df > 1000]")

Execute multi-line pandas code on HTML table data from an EnergyPlus model.

Retrieves an HTML table and executes multi-line pandas code on it. The dataframe is available as 'df' in your code. Use 'result = ...' to return values.

Args: id: The model_id of the EnergyPlus model (obtain from get_available_models). query_tuple: A tuple containing (zone/component, report_name, table_name) to identify the table. code: Multi-line Python code to execute

Returns: String representation of the result or execution status.

Examples: # Complex table analysis code = ''' # Convert numeric columns numeric_cols = df.select_dtypes(include=[np.number]).columns df_numeric = df[numeric_cols]

# Calculate totals and percentages
totals = df_numeric.sum()
percentages = (df_numeric / totals) * 100

result = percentages
'''
execute_multiline_pandas_on_html_table(model_id, query_tuple, code)