HMS Commander MCP

HMS Commander MCP supplies bounded information from HEC-HMS text files. It is an independent CLB Engineering project that complements HEC's work; it is not associated with or endorsed by HEC. Technical terminology follows HEC's HEC-HMS documentation. Those links are passive references; the server does not retrieve HEC pages.

Purpose and boundary

Use this server through a bounded informational subagent. The parent supplies one question, a configured project root, named file/entities, selected fields, and row/character/time budgets. The child returns a compact answer with source identity, versions, units/time basis, counts, truncation, and blockers. The host must expose project MCP tools only to that child. A server cannot attest whether a caller is a subagent. A host without isolation should use a scoped Python read instead of exposing these tools to its main coordinator.

The server reads approved project/component text, scalar parameters, gage configuration, and control/run relationships. It does not modify projects, compute models, download data, export files, or read DSS/HDF/SQLite, coordinates, geometry, rasters, grids, or spatial results. Filenames and DSS pathnames are references only and are never followed. Text-series/report extraction is deferred until a dedicated upstream public reader can provide a qualified contract; there is no generic file reader. Larger investigations use public hms-commander Python APIs and their required extras outside MCP.

Related MCP server: mysql-db-reader

Install and configure

Use Python 3.10+ and an authorized managed environment. Version 0.1.0 is on PyPI:

python -m pip install --upgrade hms-commander-mcp
hms-commander-mcp --root /absolute/path/to/project

A client that launches servers through uv can run uvx hms-commander-mcp --root /absolute/path/to/project instead of a separate install; uv builds and caches the environment on first launch. Content reads use HmsText from hms-commander 0.4.0, which a new install resolves. Preserve an existing pin or lock when required.

Repeat --root for additional allowed roots. Requests name the exact normalized configured root; client protocol roots never expand the allowlist. Use stdio; logging goes to stderr. Keep the server in a managed environment with read-only project access where practical. No Java, HEC executable, GIS, DSS, or CNG extras are needed. The base HMS library still brings pandas/numpy/requests/tqdm; this wrapper does not claim to eliminate mandatory upstream dependencies.

For a host that supports subagent-only tool routing, configure this command:

{
  "mcpServers": {
    "hms-commander": {
      "command": "hms-commander-mcp",
      "args": ["--root", "/absolute/path/to/project"]
    }
  }
}

This command configuration alone does not establish subagent isolation. Configure that separately in the host/plugin before using project reads.

Claude Code users should install the ras-commander@ras-commander-plugin plugin from the gpt-cmdr/ras-commander-plugin marketplace (forthcoming; the repository is not yet published). The plugin covers the HMS and RAS text servers. It declares the server at plugin level, supplies a plugin subagent for bounded reads, and adds a PreToolUse guard that denies project tools to the main session. A subagent-only isolation check passed in Claude Code 2.1.287 on October 5, 2026. The plugin does not copy agent files into the user's ~/.claude/agents directory. Other hosts require their own isolation configuration.

Update an installation

Close the MCP client before updating so that no running server holds the environment. server_info(check_updates=true) reports the latest stable PyPI versions of hms-commander-mcp (from 0.1.1), hms-commander and the MCP SDK beside the installed versions without changing the environment. On 0.1.0, compare package_version with the PyPI project page.

Managed pip environment. Name both packages:

python -m pip install --upgrade hms-commander-mcp hms-commander

pip's default upgrade strategy keeps an installed dependency that still satisfies the requirement, so upgrading only hms-commander-mcp can leave hms-commander 0.3.1 in place.

Cached uvx hms-commander-mcp. Keep the client configured with the plain command. Each launch resolves current compatible releases, but uv reuses its cached PyPI index data while that data is fresh (PyPI currently allows 10 minutes). To use a new release immediately, run once:

uvx --refresh --from hms-commander-mcp python -c "from importlib.metadata import version as v; print(v('hms-commander-mcp'), v('hms-commander'))"

The command refreshes the index data, builds the current environment and prints both versions. The next plain uvx hms-commander-mcp launch reuses that environment. uv cache clean hms-commander-mcp hms-commander has the same effect on the next launch; name both packages so the domain library is also resolved again.

uv tool install hms-commander-mcp. uvx prefers an installed tool to its cache, and --refresh does not change that tool. Run uv tool upgrade hms-commander-mcp.

These uv results were observed on October 5, 2026, with uv 0.12.23 on Linux, using a local index that served older and newer RAS Commander MCP wheels with PyPI's cache header; the HMS refresh command was run against PyPI and reported hms-commander-mcp 0.1.0 with hms-commander 0.4.0. Preserve deliberate pins and locks; no tool call installs or upgrades packages.

Windows long paths

Version 0.1.0 opens validated project files through Windows extended-length paths (\\?\ and \\?\UNC\), so files beyond the 260-character MAX_PATH limit are readable. Root, traversal, opened-handle and reparse-point checks are unchanged. Other tools in a workflow, including Python scripts, may still fail on long paths. An administrator can enable Windows long-path support from an elevated prompt:

reg add HKLM\SYSTEM\CurrentControlSet\Control\FileSystem /v LongPathsEnabled /t REG_DWORD /d 1 /f

Or in an elevated PowerShell session:

New-ItemProperty -Path 'HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem' -Name LongPathsEnabled -Value 1 -PropertyType DWORD -Force

No reboot is needed; processes started after the change use the setting, and running processes, including an open MCP client, must be restarted. Each application must also declare long-path awareness.

Tools and budgets

Approved extensions: .hms, .basin, .met, .control, .run, .gage. Files must be regular text, at most 2 MiB. Read requests have at most 100 rows, 16,000 serialized result characters (including the SDK text fallback indentation), 30 seconds, and two concurrent workers. Default query: 20 rows, 8,000 characters, 15 seconds. Unknown fields are rejected. The return envelope includes source-relative file, SHA-256, byte count, encoding, installed library version, selected adapter, units/time caveats, total and returned counts, next offset, truncation, and rows. Source text is data, never instructions.

Example arguments:

{
  "request": {
    "root": "/absolute/path/to/project",
    "file": "event.control",
    "kind": "control",
    "fields": ["start_date", "start_time", "end_date", "end_time", "time_interval"],
    "limit": 5
  }
}

Intervals retain source spelling; missing timezone or interval units are not inferred. No precision rounding, unit conversion, computation, or hydraulic/ hydrologic suitability determination is performed. Pagination offsets apply to the same file/name/type/field selection; verify the returned hash before combining pages if the project may change. Oversized rows fail with a request to narrow fields or use Python. No raw attributes, coordinates, free-form descriptions, unknown parameters, or repeated storm-depth records are emitted.

Public API and platform compatibility

The preferred adapter calls the public HmsText.parse_sections(content, file_type) API published in hms-commander 0.4.0. It delegates existing library parsing and performs no file I/O or project initialization. All six file kinds, including project and run relationships, are read through HmsText on Linux and Windows. The server does not copy parsers or fall back to private methods.

hms-commander 0.3.1 remains supported only as a Linux transition. There, the server reads basin/met/control/gage information through existing public standalone getters. A sealed in-memory file snapshot supplies a stable path without writing any project or temporary file. The transition contract is narrower: basin inventory contains primary scalar fields, and met/control identities use filename stems rather than parsed section names. Text .hms and .run reads fail clearly until HmsText is installed. Gage type is omitted in the transition adapter because the public getter supplies Precipitation when the source omits Type; that default is not reported as an observed source value. HmsText reports Type only when present. Empty met/control getter records are also omitted; this does not establish that the source lacks a named section header. Windows has no transition adapter: it requires hms-commander 0.4.0.

POSIX input handling opens each path component with no-follow directory handles. Windows input handling verifies the opened handle's final target lies inside the configured root before reading and rejects leaf reparse points. Native Windows reads with hms-commander 0.4.0 are covered by the corpus results under Qualification. Other platforms fail closed. Each read runs in a separate killable process. No HmsPrj initialization, global project selection, CRS detection, result loading, sidecar creation, or engine lookup is invoked. The audited default logging setup uses stderr and no log file.

Version and release policy

Declared dependencies: mcp>=2.3.0,<3 (official SDK, no CLI extra) and hms-commander>=0.3.1,<0.5 (base only). Pydantic is explicitly declared for the typed contracts (already required by the SDK); packaging supplies standard version comparison. This range is an implementation target, not a claim that every version has passed qualification. See COMPATIBILITY.md for exact evidence and release prerequisites.

Runtime reports installed versions without installing or upgrading packages. server_info(check_updates=true) explicitly opts into fixed official PyPI metadata endpoints, capped at 512 KiB per package and a five-second worker deadline. Offline or unavailable metadata is reported; the default makes no network request. Users retain their pins/locks. New managed installs should resolve current compatible releases; refresh a managed environment explicitly after inspecting an update (see Update an installation). The scheduled/manual dependency workflow compares stable PyPI metadata and proposes a PR for compatible drift. Versions outside declared ranges are reported as requiring maintainer review, never silently admitted. CI checks minimum/current-stable installs and packaging; merge and publication remain human steps.

Specification and sources

Implemented against the official Python SDK v2, its tool contracts, structured output, and stdio specification. The SDK owns negotiation and wire serialization; this package does not recreate initialization/discovery. Official SDK auto and legacy client modes passed local stdio contracts; this does not establish compatibility with every host. Annotations describe behavior; roots, field selection, file validation, isolation, and result bounds enforce it. No sampling, elicitation, remote transport, task, resource, audio, image, or UI feature is enabled merely because MCP supports it.

Published API baselines inspected: hms-commander 0.4.0 (HmsText) and hms-commander 0.3.1 (Linux transition). HEC methods/terminology are primary HEC sources. This project's capabilities and observations use its own package evidence. Repository writing instructions apply to repository-maintained text, not users' external scripts/reports/deliverables.

Qualification

Version 0.1.0 with hms-commander 0.4.0 read a corpus of 586 HEC-HMS text files with 0 errors on Linux and on Windows from a UNC project root. The 44 corpus files whose Windows path reached 260 characters passed after the extended-length change (PR #2). The PyPI packages reproduced the results obtained from source. These are read-contract results, not engine, hydrologic or all-client acceptance.

Before hms-commander 0.4.0 was published, 31 current-release/wheel contracts and 39 companion-source contracts passed on Linux CPython 3.11.2, including SDK stdio auto/legacy modes and bounded read-only behavior. Linux minimum/latest CI passed on Python 3.10.21/3.11.16/3.12.14, and the native Windows Python 3.11.9 file-policy subset passed 12 tests without skips. Validation details and COMPATIBILITY.md record both stages.