hms-commander-mcp 0.1.0__tar.gz

hms_commander_mcp-0.1.0/.github/workflows/candidate-content-api.yml

@@ -0,0 +1,39 @@
+name: Candidate content API qualification
+on:
+  pull_request:
+  workflow_dispatch:
+permissions:
+  contents: read
+jobs:
+  candidate:
+    name: content-api (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    env:
+      CI: '1'
+      PYTHONUNBUFFERED: '1'
+      PYTHONFAULTHANDLER: '1'
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Install MCP candidate and declared test dependencies
+        run: python -m pip install ".[test]"
+      - name: Install exact merged upstream content API candidate
+        # Separate from the released PyPI minimum/current compatibility matrix.
+        # A source commit is qualification evidence, not a published-support claim.
+        run: python -m pip install --force-reinstall --no-deps "hms-commander @ git+https://github.com/gpt-cmdr/hms-commander.git@4b71b4f137331a5f391873edfd87c281be24767e"
+      - name: Require candidate public API before qualification
+        run: python -c "from hms_commander import HmsText; assert HmsText is not None"
+      - name: Qualify public synthetic and maintained SDK contracts
+        timeout-minutes: 10
+        run: python -m pytest tests -q
+      - name: Record exact dependency and source identities
+        run: |
+          python -m pip check
+          python -m pip freeze

hms_commander_mcp-0.1.0/.github/workflows/dependency-review.yml

@@ -0,0 +1,55 @@
+name: Propose dependency refresh
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '23 8 * * 1'
+permissions:
+  contents: read
+jobs:
+  propose:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+      actions: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - run: python -m pip install 'packaging>=24'
+      - name: Compare stable PyPI metadata and prepare candidate
+        run: python scripts/propose_dependency_update.py --apply
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dependency-review
+          path: dependency-review.json
+      - name: Open update PR if compatible lower bounds changed
+        env:
+          GH_TOKEN: ${{ github.token }}
+        shell: bash
+        run: |
+          if git diff --quiet -- pyproject.toml; then exit 0; fi
+          branch='maintenance/dependency-refresh'
+          # Refresh this owned branch's tracking ref so --force-with-lease works
+          # on repeated runs from a shallow default-branch checkout.
+          if git ls-remote --exit-code --heads origin "$branch" >/dev/null 2>&1; then
+            git fetch origin "$branch:refs/remotes/origin/$branch"
+          fi
+          git checkout -B "$branch"
+          git config user.name 'github-actions[bot]'
+          git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
+          git add pyproject.toml
+          git commit -m 'Propose compatible dependency refresh'
+          git push --force-with-lease origin "$branch"
+          python - <<'PY'
+          from pathlib import Path
+          Path('pr-body.md').write_text('Proposes current stable versions within existing dependency ranges. Review the metadata artifact, exact compatibility evidence and wheel/sdist metadata before merge. No runtime upgrades, range widening, merge or publication are performed.\n')
+          PY
+          if ! gh pr view "$branch" --json number >/dev/null 2>&1; then
+            gh pr create --head "$branch" --title 'Propose compatible dependency refresh' --body-file pr-body.md --draft
+          fi
+          # GITHUB_TOKEN-created PRs do not trigger ordinary pull_request CI.
+          gh workflow run package-compatibility.yml --ref "$branch"

hms_commander_mcp-0.1.0/.github/workflows/package-compatibility.yml

@@ -0,0 +1,81 @@
+name: Package compatibility candidates
+on:
+  workflow_dispatch:
+  pull_request:
+  push:
+    branches: [main]
+permissions:
+  contents: read
+jobs:
+  package:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ['3.10', '3.11', '3.12']
+        dependencies: [minimum, latest-compatible]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install minimum dependency candidates
+        if: matrix.dependencies == 'minimum'
+        run: |
+          python - <<'PY' > minimum-constraints.txt
+          from pathlib import Path
+          import re
+          text = Path('pyproject.toml').read_text()
+          for package in ('mcp', 'hms-commander'):
+              match = re.search(r'"' + re.escape(package) + r'>=([^,"]+)', text)
+              print(package + '==' + match.group(1))
+          PY
+          python -m pip install -c minimum-constraints.txt ".[test]"
+      - name: Install latest compatible dependency candidates
+        if: matrix.dependencies == 'latest-compatible'
+        run: python -m pip install --upgrade ".[test]"
+      - name: Public API, bounded-read and official SDK stdio contracts
+        run: python -m pytest tests -q
+      - name: Record resolved versions and resolver consistency
+        run: |
+          python -m pip check
+          python -m pip freeze > resolved-versions.txt
+      - name: Build wheel and source distribution
+        run: |
+          python -m pip install build
+          python -m build
+      - name: Inspect wheel dependency and entrypoint metadata
+        run: |
+          python - <<'PY'
+          from pathlib import Path
+          import zipfile
+          wheel = next(Path('dist').glob('*.whl'))
+          with zipfile.ZipFile(wheel) as archive:
+              for name in archive.namelist():
+                  if name.endswith(('METADATA', 'entry_points.txt')):
+                      print(archive.read(name).decode())
+          PY
+      - uses: actions/upload-artifact@v4
+        with:
+          name: package-${{ matrix.python }}-${{ matrix.dependencies }}
+          path: |
+            dist/
+            resolved-versions.txt
+
+  windows-policy:
+    runs-on: windows-latest
+    timeout-minutes: 10
+    env:
+      PYTHONUNBUFFERED: '1'
+      PYTHONFAULTHANDLER: '1'
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - run: python -m pip install ".[test]"
+      - name: Native Windows handle containment and approved text reads
+        timeout-minutes: 3
+        run: >-
+          python -X faulthandler -c "import faulthandler,pytest; faulthandler.dump_traceback_later(30, repeat=True); raise SystemExit(pytest.main(['tests/test_native_policy.py', '-vv', '-s', '-o', 'faulthandler_timeout=30']))"

hms_commander_mcp-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+.pytest_cache/

hms_commander_mcp-0.1.0/AGENTS.md

@@ -0,0 +1,24 @@
+# HMS Commander MCP agent contract
+
+This repository owns a constrained informational server. Preserve read-only,
+low-dependency, non-spatial/non-gridded output and subagent-only client routing.
+Only explicit typed tools are registered. Do not reflect the domain library into
+MCP. Do not add model execution, setters, cloning, exports, downloads, generic
+file/SQL/code readers, geometry, DSS/HDF/SQLite or gridded data. Use public HMS
+library APIs; domain parsers remain upstream. No global project state.
+
+Read README.md and COMPATIBILITY.md before changes. Keep stdout for MCP wire
+traffic, logs on stderr, configured roots enforced, and byte/row/character/time
+limits enforced with explicit counts/truncation. Per-request objects and workers
+must not retain a prior project's state. Do not accept terms or infer suitability
+from successful parsing. Annotations and client roots are not access controls.
+
+HEC is primary for documented HEC-HMS methods and terminology. State supported
+project capabilities and reproducible observations directly, with their scope.
+Maintain an objective independent third-party voice and passive official HEC
+references. Repository editorial standards do not apply to users' external work.
+
+Dependency update PRs need minimum/latest contract and wheel/sdist evidence.
+Preserve user pins; no runtime pip install, unattended merge/publish, or dependency
+range widening without qualification. Do not run tests, model engines or user
+project processing unless the task authorizes that work.

hms_commander_mcp-0.1.0/CLAUDE.md

@@ -0,0 +1,3 @@
+@AGENTS.md
+
+Shared behavior lives in AGENTS.md; do not duplicate it here.

hms_commander_mcp-0.1.0/COMPATIBILITY.md

@@ -0,0 +1,46 @@
+# Compatibility evidence and release prerequisites
+
+Qualification date: October 4, 2026. Package identities and MCP protocol revision
+are separate. Minimum and latest-compatible stable releases were identical on
+this date: official MCP SDK **2.3.0**, HMS Commander **0.3.1**.
+
+| Dependency/environment | Evidence |
+|---|---|
+| Official MCP SDK 2.3.0 | Typed schemas, actionable errors and stdio auto/legacy modes passed locally |
+| Published HMS Commander 0.3.1 | Linux public standalone getter contracts passed on real repository text fixtures |
+| Companion HmsText source, unreleased | Content API and upstream fixture contracts passed locally; not published evidence |
+| Linux CPython 3.11.2 | Read-only/path/encoding/bounds/timeout/concurrency/status and package checks passed |
+| Linux Python 3.10.21/3.11.16/3.12.14 | Six minimum/latest-compatible jobs passed: 31 tests and1 optional-network skip each; pipcheck and builds passed |
+| Windows CPython 3.11.9 | Native file-policy subset passed 12 tests with no skips; full domain adapter not qualified |
+
+See [VALIDATION.md](VALIDATION.md) for exact checks, source provenance and limits.
+A resolver range is not proof that every version has passed qualification.
+
+Current-release transition permits approved basin/met/control/gage reads on
+Linux using existing public getters and sealed memfd snapshots. This is a
+compatibility bridge, not a second domain parser. HmsText replaces it through
+capability detection. The transition omits gage type because the current public
+getter can default a missing source `Type` to `Precipitation`; MCP does not present
+that default as an observation. Empty met/control getter records are also omitted; this does not establish
+that the source lacks a named section header. HmsPrj.initialize is excluded because even with DSS loading
+disabled it invokes SQLite/CRS discovery. No heavy extras are requested, but base
+HMS dependencies remain installed.
+
+Project/run reads and all Windows domain reads require the upstream HmsText
+release. Publish it before claiming those capabilities against PyPI or raising
+the wrapper minimum. Windows CI currently qualifies secure text I/O and path
+policy separately, not the unreleased full domain adapter. Native link denial
+can be skipped if the host lacks link privileges; inspect CI skips before release.
+No binary, GIS, Java or engine case is included in MCP qualification.
+
+CI exercises declared minimum and latest-compatible public dependencies,
+functional contracts and wheel/sdist builds. Latest/minimum behavior and updated
+metadata must be reviewed before changing ranges or publishing. Preserve user
+pins; no runtime auto-upgrade, unattended merge or publication.
+
+Remote evidence: [run 37165170753](https://github.com/gpt-cmdr/hms-commander-mcp/actions/runs/37165170753),
+source head 8e04b3c, all 7 jobs successful. Windows policy coverage includes traversal,
+extensions/streams, unconfigured roots, NUL/oversize inputs, real text reads and
+leaf link denial. It does not establish Windows HmsText domain/stdio behavior.
+The earlier cancelled Windows run had no retrievable diagnostic log; its stall
+cause remains unconfirmed.

hms_commander_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CLB Engineering Corporation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hms_commander_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.5
+Name: hms-commander-mcp
+Version: 0.1.0
+Summary: Bounded read-only HEC-HMS text information through MCP
+Author: CLB Engineering Corporation
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: hms-commander<0.5,>=0.3.1
+Requires-Dist: mcp<3,>=2.3.0
+Requires-Dist: packaging>=24
+Requires-Dist: pydantic<3,>=2.12
+Provides-Extra: test
+Requires-Dist: jsonschema>=4.20; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# 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](https://www.hec.usace.army.mil/confluence/hmsdocs).
+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](https://rascommander.info/hms/) and their required
+extras outside MCP.
+
+## Install and configure
+
+This candidate is developed in public and has not been published to PyPI. From
+its checkout:
+
+```sh
+python -m pip install .
+hms-commander-mcp --root /absolute/path/to/project
+```
+
+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:
+
+```json
+{
+  "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.
+
+## Tools and budgets
+
+| Tool | Contract |
+|---|---|
+| `server_info` | Installed package/library/SDK versions, capabilities, approved fields, limits; optional `check_updates: true` fetches bounded stable PyPI metadata |
+| `read_hms_sections` | Typed `request` object with root, relative file, matching kind, optional exact name/type, fields, offset, limit, character budget, and deadline |
+
+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:
+
+```json
+{
+  "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 new public `HmsText.parse_sections(content,
+file_type)` API proposed in the companion HMS library change. It delegates
+existing library parsing and performs no file I/O or project initialization.
+Project/run reads require publication of that upstream API; the server does not
+copy parsers or fall back to private methods.
+
+On current PyPI **hms-commander 0.3.1**, Linux can read 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 the upstream HmsText release.
+
+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.
+The native Windows file-policy subset passed 12 tests on Python 3.11.9. Full
+Windows domain reads still need the upstream HmsText release and separate domain/
+stdio qualification; do not infer those from file-policy results. 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
+
+Dependency candidates: `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](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. 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. Publication of HmsText precedes claiming cross-platform project/run reads.
+
+## Specification and sources
+
+Implemented against the official [Python SDK v2](https://py.sdk.modelcontextprotocol.io/),
+its [tool contracts](https://py.sdk.modelcontextprotocol.io/servers/tools/),
+[structured output](https://py.sdk.modelcontextprotocol.io/servers/structured-output/),
+and [stdio specification](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/stdio).
+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 baseline inspected: [hms-commander 0.3.1](https://pypi.org/project/hms-commander/0.3.1/).
+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
+
+On Linux CPython 3.11.2, 31 current-release/wheel contracts and 39 companion-source
+contracts passed, including SDK stdio auto/legacy modes and bounded read-only
+behavior. One explicitly enabled live PyPI metadata check passed. Linux minimum/latest CI passed on Python 3.10.21/3.11.16/3.12.14;
+the native Windows Python 3.11.9 file-policy subset passed 12 tests without skips.
+Full Windows domain/stdio qualification remains separate. [Validation details](VALIDATION.md) distinguish published
+0.3.1 compatibility from unreleased HmsText source evidence.

hms_commander_mcp-0.1.0/README.md

@@ -0,0 +1,175 @@
+# 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](https://www.hec.usace.army.mil/confluence/hmsdocs).
+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](https://rascommander.info/hms/) and their required
+extras outside MCP.
+
+## Install and configure
+
+This candidate is developed in public and has not been published to PyPI. From
+its checkout:
+
+```sh
+python -m pip install .
+hms-commander-mcp --root /absolute/path/to/project
+```
+
+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:
+
+```json
+{
+  "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.
+
+## Tools and budgets
+
+| Tool | Contract |
+|---|---|
+| `server_info` | Installed package/library/SDK versions, capabilities, approved fields, limits; optional `check_updates: true` fetches bounded stable PyPI metadata |
+| `read_hms_sections` | Typed `request` object with root, relative file, matching kind, optional exact name/type, fields, offset, limit, character budget, and deadline |
+
+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:
+
+```json
+{
+  "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 new public `HmsText.parse_sections(content,
+file_type)` API proposed in the companion HMS library change. It delegates
+existing library parsing and performs no file I/O or project initialization.
+Project/run reads require publication of that upstream API; the server does not
+copy parsers or fall back to private methods.
+
+On current PyPI **hms-commander 0.3.1**, Linux can read 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 the upstream HmsText release.
+
+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.
+The native Windows file-policy subset passed 12 tests on Python 3.11.9. Full
+Windows domain reads still need the upstream HmsText release and separate domain/
+stdio qualification; do not infer those from file-policy results. 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
+
+Dependency candidates: `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](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. 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. Publication of HmsText precedes claiming cross-platform project/run reads.
+
+## Specification and sources
+
+Implemented against the official [Python SDK v2](https://py.sdk.modelcontextprotocol.io/),
+its [tool contracts](https://py.sdk.modelcontextprotocol.io/servers/tools/),
+[structured output](https://py.sdk.modelcontextprotocol.io/servers/structured-output/),
+and [stdio specification](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/stdio).
+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 baseline inspected: [hms-commander 0.3.1](https://pypi.org/project/hms-commander/0.3.1/).
+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
+
+On Linux CPython 3.11.2, 31 current-release/wheel contracts and 39 companion-source
+contracts passed, including SDK stdio auto/legacy modes and bounded read-only
+behavior. One explicitly enabled live PyPI metadata check passed. Linux minimum/latest CI passed on Python 3.10.21/3.11.16/3.12.14;
+the native Windows Python 3.11.9 file-policy subset passed 12 tests without skips.
+Full Windows domain/stdio qualification remains separate. [Validation details](VALIDATION.md) distinguish published
+0.3.1 compatibility from unreleased HmsText source evidence.