ref-project-reference

Deephaven MCP Repository Reference

Architecture and Key Files

• src/deephaven_mcp/mcp_systems_server/server.py — Multiplexed systems server entry point (main()); CLI parsing, transport selection, PSK resolution.
• src/deephaven_mcp/mcp_systems_server/_lifespan.py — FastMCP lifespan factory: builds MultiSystemRegistry from ConfigTree, starts one Evictor per child registry.
• src/deephaven_mcp/auth/middleware/_psk.py — PSKMiddleware: Starlette middleware gating inbound HTTP requests on a single shared PSK (X-Deephaven-PSK header). Mounted by the systems server's HTTP transport; reusable by other MCP servers.
• src/deephaven_mcp/auth/credentials/ — Outbound credential dataclasses passed to CorePlusSessionFactory.from_credentials.
• src/deephaven_mcp/mcp_systems_server/_tools/ — MCP tool modules. All registered on the single multiplexed server: session, table, script, session_community, session_enterprise, catalog, pq. Shared helpers in shared.py. Tools that name a system take a system argument; tools that take an id (<type>:<system>:<name>) parse the system out of it. There is no mcp_reload tool — config changes require a restart.
• src/deephaven_mcp/mcp_docs_server/ — Docs MCP server for documentation Q&A.
• src/deephaven_mcp/config/ — General-purpose config primitives reusable by any MCP server: _file_loader.py (async JSON5 reader + ConfigurationError wrapping), _templating.py (${env:VAR} / ${env:VAR:-default} / ${file:PATH} placeholder engine), _data_root.py (resolve_data_root — the sole reader of DH_AI_DATA_DIR, keyed on sys.platform for the per-OS default), _config_dir.py (the config/ subdir under that root), _store.py (ConfigStore — file-level read/modify/write that the dhcli config authoring verbs go through, so they never need a full-tree load), _dir_permissions.py (verify_config_directory_permissions — the startup policy: existence/is-dir checks, refuse-to-start, and aggregation of audit violations into one ConfigurationError; the per-OS audit mechanics are delegated to _platform.dir_permissions.audit_tree).
• src/deephaven_mcp/_platform/ — OS abstraction layer (HAL): the single home for code that branches on os.name. _os_support.py (leaf module — SUPPORTED_OS_NAMES = frozenset({"posix", "nt"}) plus unsupported_os_error(component), the one dispatch-error factory every site uses), fsutil.py (advisory file locking, atomic private writes, Windows-retry filesystem helpers), spawn.py (spawn_detached detached-process launcher — start_new_session on POSIX, creationflags on Windows, fail-fast InternalError otherwise), dir_permissions.py (harden_private_dir + audit_tree, with per-OS _harden_*/_audit_* impls). The package __init__.py is docstring-only and imports no submodules (cycle-safety); submodules import the contract from the leaf ._os_support. Note: sys.platform-keyed path/venv resolution (config/_data_root.py, resource_manager/_launcher.py) is a different axis and intentionally stays in its domain modules.
• src/deephaven_mcp/config/schema/ — Pydantic section schemas for the whole product (consumed by both the systems server and the dhcli CLI): the per-section schema/loader modules _server.py (ServerConfig + DaemonProcessConfig), _cli.py (CliConfig and the nested groups it composes — OutputConfig, DaemonControlConfig, RequestConfig, DocsConfig, ContextConfig, plus their timeout and policy types), _community.py, _enterprise.py (each owns its umbrella schema and load_<section> function), plus the tool-tunable schemas _response_limits.py (ResponseLimits) and _pq_config.py (PqToolsConfig) embedded by the community/enterprise schemas.
• src/deephaven_mcp/config/tree.py — ConfigTree (mirrors the on-disk layout server.json, cli.json, community/, enterprise/ one-for-one; the canonical aggregator type) and ConfigTreeLoader (walks the configuration directory and produces a validated ConfigTree). Lives at the top of the config package so both cli and mcp_systems_server depend on it without depending on each other; config/__init__.py stays primitives-only so import deephaven_mcp.config does not pull in the schema graph.
• src/deephaven_mcp/resource_manager/_registry_multi.py — MultiSystemRegistry: composite registry over one community child + one enterprise child per configured system; routes session-id reads to the correct child.
• src/deephaven_mcp/cli/ — The dhcli CLI (click + Pattern B). _main.py (root group), _commands/{daemon,tool,session,system,table,catalog,pq,docs,config,context,agents,self_cmd}.py (noun groups; daemon for daemon lifecycle, tool is the raw MCP escape hatch, config reads and authors the local config tree, the runtime nouns session/system/table/catalog/pq wrap specific MCP tools, docs connects directly to the docs MCP server (no daemon), context manages the sticky default id, agents emits machine-readable CLI metadata, self_cmd is the self noun group for tool self-management — today the completion verb printing shell tab-completion scripts), _async.py (run_async async-to-sync adapter), _errors.py (CliError + ErrorCode registry), _help.py (HelpSpec help vocabulary, build_help rendering, and the HelpfulMeta metadata base), _command.py (HelpfulCommand / HelpfulGroup, carrying the runtime-load hook and the --agents injection), _manifest.py (the agents manifest builders: build_manifest / build_summary_tree / describe_command), _params.py (the CLI-wide blank-value guard and NonBlankPath), _format.py (human/json/json-pretty/yaml renderers), _echo.py (printing a payload in the active output mode — echo_payload(runtime, ...) reads runtime.config.cli.output.format; echo_payload_no_runtime(ctx, ...) reads the root -o for callers that run before the config load, i.e. needs_runtime=False verbs and the eager --agents callback), _runtime.py (resolved Runtime context on ctx.obj), _context.py (ContextStore persisting the sticky default id to <runtime_dir>/context.json, plus the resolve_context_value / require_context_value / require_context_target resolution helpers and the single-sourced CONTEXT_HINT / CONTEXT_RISK_* help strings), _daemon/ (daemon-lifecycle package: _lifecycle.py orchestration core get_or_start_daemon(ctx, ...) -> DaemonRegistryEntry / stop_daemon(directory, *, kill_after_seconds); commands build the DaemonContext from a Runtime via DaemonContext.from_runtime(runtime) and read tunables from runtime.config.cli.daemon; the OS-specific spawn mechanic is delegated to _platform.spawn.spawn_detached), _mcp_client.py (loopback HTTP client). Async handlers must be wrapped with @run_async — see ref-python-coding-practices rule 15 and the cli-command-add skill.
• src/deephaven_mcp/daemon_registry.py — Shared wire contract between the CLI and a local daemon process. DaemonRegistryEntry (Pydantic model for daemon.json with field-level invariants — Literal["127.0.0.1"] host, port range, AwareDatetime started_at, etc.; the recorded (pid, create_time_ns, process_name) triple is exposed as a ProcessIdentity via the .identity property, and DaemonRegistryEntry.is_live() is the single PID-reuse-safe liveness predicate shared by the CLI lifecycle and the server's registry-publish refusal), DaemonDirectory (typed handle to <runtime_dir>/daemon/ exposing registry_path/lock_path/log_path and atomic registry CRUD via tempfile.mkstemp), RegistryCorruptError, and filename constants. Imported by both mcp_systems_server (daemon entry point writes the registry) and cli (spawn/poll/stop reads it; reachable via runtime.daemon_dir).
• src/deephaven_mcp/_processes.py — Portable process primitives (no os.name branch; stays top-level rather than under _platform). ProcessIdentity value object: a frozen (pid, create_time_ns) pair that anchors all PID-reuse-safe operations on a process. Provides is_alive(), send_signal_safely(sig) -> SignalOutcome (DELIVERED/GONE/DENIED/RECYCLED), and capture(pid, process_name) for first-publish capture. The recorded create_time_ns is compared by integer equality (no float drift). Replaces the _capture_create_time / _send_sigterm / _force_kill / _process_still_running helpers that previously had to trade a raw (pid, create_time) tuple by hand at every call site. The OS-dispatched detached-process launcher that used to live here moved to _platform.spawn.spawn_detached.
• src/deephaven_mcp/mcp_systems_server/_idle.py — Generic idle-shutdown machinery: IdleTimer (monotonic-clock data), ActivityMiddleware (Starlette middleware bumping the timer), idle_watcher (lifespan coroutine that calls a supplied exit_fn on expiry). Opted into via make_lifespan(..., idle=IdleWatcher(...)); daemon mode always sets it.
• scripts/ — Test clients and utilities.
• tests/ — Comprehensive test suite with high line coverage on src/deephaven_mcp/ (run tests-run for the current count and report).
• pyproject.toml — Project configuration and dependencies, including the supported Python floor (requires-python). The rule for consuming it is ref-python-coding-practices rule 16 (Python version floor).