# Reported issues for usgs-water-mcp-server Pod holds 14 of 14 GitHub reports that passed its relevance review. This can include external user reports, maintainer-confirmed bugs, and concrete feature gaps. Treat them as evidence to inspect, not a count of distinct defects. Back to [usgs-water-mcp-server](/mcp/usgs-water-mcp-server). ## Most discussed ### fix(nwis): a truncated 200 response escapes as a raw SyntaxError instead of upstream_error ### Server version 0.2.5 ### mcp-ts-core version 0.13.6 ### Runtime Bun ### Runtime version 1.4.0 ### Transport stdio ### OS macOS ### Description `getReadings` and `getSeries` in `src/services/nwis/nwis-service.ts` call `JSON.parse` on the NWIS body unguarded. NWIS sometimes answers HTTP 200 with a body cut off mid-document, so `JSON.parse` throws a raw `SyntaxError`. `classifyNwisFailure` maps only `McpError` codes and returns `null` for it, and the caller gets a generic internal… [Read the thread](https://github.com/cyanheads/usgs-water-mcp-server/issues/46) · 2026-09-25 · closed · 1 comment ### fix(nwis): the -999999 no-data sentinel is reported as a measurement and ranked record-low ### Server version 0.2.5 ### mcp-ts-core version 0.13.6 ### Runtime Bun ### Runtime version 1.4.0 ### Transport stdio ### OS macOS ### Description NWIS reports a reading it cannot provide as `-999999`, the series' `variable.noDataValue`, with a qualifier giving the reason (`Ssn` seasonal, `Dis` discontinued, `Dry`, `Rat` rating in development, `Eqp` equipment). `parseWaterml` in `src/services/nwis/nwis-service.ts` never reads `noDataValue`, so the sentinel passes through as a… [Read the thread](https://github.com/cyanheads/usgs-water-mcp-server/issues/45) · 2026-09-25 · closed · 1 comment ### fix(water_get_conditions): a value outside p25–p75 is classified normal or unknown when an outer percentile is blank ### Server version 0.2.5 ### mcp-ts-core version 0.13.6 ### Runtime Bun ### Runtime version 1.4.0 ### Transport stdio ### OS macOS ### Description `classifyPercentile` in `water-get-conditions.tool.ts` tests each band only when both of its bounds are present, and the `normal` band never checks its upper bound. NWIS leaves `p05_va`, `p10_va`, and `p95_va` blank on short records, so a value above p75 is reported as `normal` ("25th–75th percentile"), and a value below p25 as… [Read the thread](https://github.com/cyanheads/usgs-water-mcp-server/issues/44) · 2026-09-25 · closed · 1 comment ### fix(nwis): WaterML parser drops every method block after the first; water_get_series returns the first daily statistic ### Server version 0.2.5 ### mcp-ts-core version 0.13.6 ### Runtime Bun ### Runtime version 1.4.0 ### Transport stdio ### OS macOS ### Description `parseWaterml` in `src/services/nwis/nwis-service.ts` reads only `ts.values[0]`. A WaterML `timeSeries` carries one `values[]` block per method (sensor), so every block after the first is dropped. Separately, the daily-values service returns one `timeSeries` per statistic code, and `water_get_series` answers with `seriesList[0]` whatever… [Read the thread](https://github.com/cyanheads/usgs-water-mcp-server/issues/43) · 2026-09-25 · closed · 1 comment ### bug(water_get_series,water_find_sites): supplied canvas_id is resolved after the NWIS fetch and ignored when the result fits inline ### Server version 0.2.4 ### mcp-ts-core version 0.13.6 ### Runtime Bun ### Runtime version Bun 1.4.x ### Transport stdio ### Description Both canvas producers handle a supplied `canvas_id` only inside the branch that stages data, after the NWIS fetch. Two consequences: - A `canvas_id` that is expired or never minted costs a full upstream round trip before `canvas_not_found` is raised. - When the result fits inline (no spill, no truncation), the supplied `canvas_id` is never looked… [Read the thread](https://github.com/cyanheads/usgs-water-mcp-server/issues/40) · 2026-09-22 · closed · 1 comment ### bug(water_get_series,water_find_sites): errors[] omits the canvas reasons acquire() throws ### Server version 0.2.4 ### mcp-ts-core version 0.13.6 ### Runtime Bun ### Runtime version Bun 1.4.x ### Transport stdio ### Description `water_get_series` and `water_find_sites` call `canvas.acquire(input.canvas_id, ctx)` uncaught, but neither declares the reasons it throws in `errors[]`. A `canvas_id` that is well-formed but expired or never minted returns `canvas_not_found` (-32001); omitting `canvas_id` while the tenant is at its active-canvas cap… [Read the thread](https://github.com/cyanheads/usgs-water-mcp-server/issues/39) · 2026-09-19 · closed · 1 comment ### feat(water_find_sites): validate the NWIS major-filter requirement locally instead of relaying the raw 400 `water_find_sites` forwards a request with no major filter straight to NWIS, which rejects it, and the raw upstream text is relayed: ``` NWIS rejected the request: HTTP Status 400 - no major-filter pairs supplied by user, server=[vaas01] ``` A call with only `siteType` (or only `parameterCd`) is enough to trigger it — NWIS requires one "major filter" (`bbox`, `stateCd`, `countyCd`, or `huc` in this tool's surface). The generic `invalid_request` recovery hint makes it worse: "Read the NWIS… [Read the thread](https://github.com/cyanheads/usgs-water-mcp-server/issues/37) · 2026-08-21 · closed · 1 comment ### bug(water_find_sites): major-filter rule unenforced and undocumented; countyCd/bbox descriptions mislead ### Server version 0.2.2 ### mcp-ts-core version 0.10.14 ### Runtime Bun ### Runtime version Bun 1.3.x ### Transport stdio ### Description NWIS accepts **exactly one** major filter per `/nwis/site/` request — one of `stateCd`, `countyCd`, `huc`, `bBox` in this tool's surface. `water_find_sites` neither enforces nor documents that, and the `countyCd` description recommends the one pairing NWIS rejects outright ("Use with stateCd for clarity"). | Gap | Effect | |:---|:---| |… [Read the thread](https://github.com/cyanheads/usgs-water-mcp-server/issues/36) · 2026-08-18 · closed · 1 comment ## Most recent ### ux(water_find_sites): truncation notice exposes CANVAS_PROVIDER_TYPE env var ### Server version 0.2.4 ### mcp-ts-core version 0.13.6 ### Runtime Bun ### Runtime version Bun 1.4.0 ### Transport stdio ### Description The truncated/no-canvas branch of `water_find_sites`'s enrichment notice names the operator-set `CANVAS_PROVIDER_TYPE` env var. #2 removed it from tool descriptions and #8 removed it from the `canvas_disabled` error; this is the one remaining agent-facing occurrence, and it reaches both `structuredContent` (the enrichment field) and `content[]`… [Read the thread](https://github.com/cyanheads/usgs-water-mcp-server/issues/35) · 2026-08-13 · closed · 1 comment ### ux(canvas): staged-data notices name only water_dataframe_query, omitting water_dataframe_describe ### Use case `water_get_series` and `water_find_sites` both stage their full result set to a DataCanvas table and return `canvas_id` + `table_name`. The runtime `notice` each emits on that path names `water_dataframe_query` and stops there — `water_dataframe_describe`, the only tool that exposes the staged table's columns, is never named in the response. An agent reading the notice goes to SQL with no column names, and then either guesses them or abandons the canvas and re-calls the producing… [Read the thread](https://github.com/cyanheads/usgs-water-mcp-server/issues/34) · 2026-08-13 · closed · 1 comment ### feat(water_list_parameters): search the full USGS parameter-code catalog, not the 11-entry table ### Use case Every tool's `parameterCd` description sends callers to `water_list_parameters`, which serves 11 codes duplicated across `water-list-parameters.tool.ts` and `water-parameters.resource.ts`. USGS publishes 19,617 (as of 2026-09-25). Turbidity, nitrate, chlorophyll, suspended sediment, and salinity have no entry, and nothing says the list is partial. Related: #32 (OGC API port), #30 (its `parameterName` join can reuse this reader) ### Proposed behavior ```ts {}… [Read the thread](https://github.com/cyanheads/usgs-water-mcp-server/issues/31) · 2026-08-10 · closed · 1 comment ### feat(water_find_sites): add limit/offset so matches past the 500-site cap are reachable without DataCanvas ### Use case `water_find_sites` caps inline results at 500 with no escape hatch in either direction. Without DataCanvas enabled — the default for stdio and `.mcpb` installs — a match set past 500 has no retrieval path at all: `stateCd: "RI"` alone matches 4,000+ sites, and the filter set runs out long before the cap does. A caller who wants ten gages in a state also has no way to ask for fewer than 500. Related: #6 (added the cap; pagination was left open) ### Proposed behavior Add… [Read the thread](https://github.com/cyanheads/usgs-water-mcp-server/issues/29) · 2026-08-10 · closed · 1 comment ### bug(canvas): staged table names omit query dimensions, so a reused canvas_id silently replaces prior data ### Server version 0.2.2 ### mcp-ts-core version 0.10.14 ### Runtime Bun ### Runtime version Bun 1.3.x ### Transport stdio ### Description Both canvas producers build a table name from a subset of the query, so two different queries can land on the same name. `registerTable` is `DROP TABLE IF EXISTS` + `CREATE TABLE`, so reusing a `canvas_id` — which both tools advertise as the way to accumulate results — replaces the earlier table in place with no warning in the response. | Tool |… [Read the thread](https://github.com/cyanheads/usgs-water-mcp-server/issues/28) · 2026-08-10 · closed · 1 comment ### bug(water_get_series): canvas preview drops the newest records, the no-canvas path drops the oldest ### Server version 0.2.2 ### mcp-ts-core version 0.10.14 ### Runtime Bun ### Runtime version Bun 1.3.x ### Transport stdio ### Description `water_get_series` truncates from opposite ends depending on whether DataCanvas is enabled. Without a canvas the handler returns `ts.values.slice(-SPILLOVER_THRESHOLD)` — the **most recent** 500 records. With a canvas, `spillover()` fills its preview from the head of the source by construction, so `values` holds the **oldest** records that fit the… [Read the thread](https://github.com/cyanheads/usgs-water-mcp-server/issues/27) · 2026-08-10 · closed · 1 comment The remaining reports are on [the project's issue tracker](https://github.com/cyanheads/usgs-water-mcp-server/issues).