ref-configuration-conventions

Configuration Conventions

Reference for how the Deephaven MCP servers consume runtime configuration. Read this before adding a new tunable, refactoring a config model, or wiring an environment variable into the code.

Authoritative end-user reference: docs/CONFIGURATION.md. This skill is the internal-to-the-codebase counterpart and explains how to extend the configuration safely. The only configuration-location env var the server itself reads is DH_AI_DATA_DIR (consumed by deephaven_mcp.config.resolve_data_root); the log level comes from PYTHONLOGLEVEL (see docs/ENV.md). Every other tunable lives in the JSON tree.

Architecture in one sentence

Configuration lives in JSON5 files under DH_AI_DATA_DIR, is shaped by Pydantic v2 models (which double as the wire- format schema and the runtime types), and pulls in env-vars or file contents through a templating engine that runs before Pydantic validation.

The six rules

1. JSON is the single source of truth

Every tunable lives in one of the JSON files described in docs/CONFIGURATION.md. The only exception is the DH_AI_DATA_DIR env var itself, which tells the server where to find the JSON tree.

Do not add ad-hoc os.environ[...] reads — anywhere. Tool code, session helpers, registries, factories, and CLI command code are all covered; the CLI is not a carve-out (its own env surface and the click envvar= equivalent are governed by cli-command-add's anti-patterns). If a new knob needs to be exposed to operators, add it to the appropriate Pydantic schema and (when relevant) to the *_settings / *_systems documentation in docs/CONFIGURATION.md.

2. Pydantic models carry the schema defaults AND the field documentation

2a. Defaults at the field declaration

When a JSON field is optional, encode the default at the field declaration site:

class CommunitySessionCreationDefaults(RedactableSchema):
    heap_size_gb: Annotated[float, Field(gt=0)] = 4.0
    """JVM heap size in gigabytes for the worker process."""

    startup_retries: Annotated[int, Field(ge=0)] = 3
    """Number of times the launcher retries worker creation."""