usgs-water-mcp-server
Query real-time and historical USGS water data from ~8,000 stream gages and groundwater wells.
我该使用它吗
质量与安全性
A
基于对工具定义和协议合规性的自动分析。
上下文开销
~10,024token 数（工具定义）
~16.3 KB典型响应大小
对注意力有显著影响（占 128k 上下文窗口的 7.83%）
这是每次将服务器的工具加载到模型上下文窗口时所消耗的大致 token 数。数值越高，可用于其他任务的注意力就越少。
安装
一键安装
将以下内容添加到你的 `claude_desktop_config.json` 文件中：
{
"mcpServers": {
"usgs-water-mcp-server": {
"command": "bun",
"args": [
"@cyanheads/usgs-water-mcp-server"
]
}
}
}可运行的软件包
npm@cyanheads/usgs-water-mcp-server
0.2.6streamable-http远程端点
https://usgs-water.caseyjhand.com/mcpstreamable-http它能做什么
工具清单
工具（7）
🟢 只读🟡 写入🔴 删除⚪ 未知
🟢water_list_parameters(group)
List well-known USGS parameter codes with human-readable names, units, and thematic domain — a static, built-in catalog. Use this first to discover that 00060 = "Discharge" (ft³/s), 00065 = "Gage height" (ft), 00010 = "Temperature, water" (°C), 72019 = "Depth to water level" (ft), etc. Filter by group to narrow results.
输入模式
{
"type": "object",
"properties": {
"group": {
"default": "all",
"description": "Filter by thematic domain: \"streamflow\", \"groundwater\", \"temperature\", \"meteorological\", \"water-quality\", or \"all\" (default) for the full catalog.",
"type": "string",
"enum": [
"streamflow",
"groundwater",
"temperature",
"meteorological",
"water-quality",
"all"
]
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}输出模式
{
"type": "object",
"properties": {
"parameters": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "5-digit USGS parameter code (e.g. \"00060\")."
},
"name": {
"type": "string",
"description": "Human-readable parameter name (e.g. \"Discharge\")."
},
"unit": {
"type": "string",
"description": "Unit of measure (e.g. \"ft³/s\", \"ft\", \"°C\")."
},
"group": {
"type": "string",
"enum": [
"streamflow",
"groundwater",
"temperature",
"meteorological",
"water-quality"
],
"description": "Thematic domain grouping for filtering."
}
},
"required": [
"code",
"name",
"unit",
"group"
],
"additionalProperties": false,
"description": "A USGS parameter code entry with name, unit, and domain group."
},
"description": "Matching parameter records with code, name, unit, and group."
},
"total": {
"type": "number",
"description": "Number of parameters returned."
},
"error": {
"description": "Present when the call failed. Absent on success.",
"type": "object",
"properties": {
"code": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"description": "Machine-readable failure mode."
},
"recovery": {
"description": "Actionable next step for the caller.",
"type": "object",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"additionalProperties": {}
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"additionalProperties": {}
}
},
"required": [
"code",
"message"
],
"additionalProperties": {}
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"parameters",
"total"
]
},
{
"required": [
"error"
]
}
]
}🟢water_find_sites(bbox, stateCd, countyCd, huc, siteType, ...)
Find USGS water monitoring sites by bounding box, state, county, or HUC watershed code, filtered by site type and parameter availability. Returns site numbers, names, coordinates, types, altitude, and (in expanded mode) drainage area. Call this first — water_get_readings, water_get_series, and water_get_conditions all require a site number. Supply exactly one major filter — bbox, stateCd, countyCd, or huc; siteType, parameterCd, and hasDataTypeCd only narrow within it and cannot stand alone. Page through matches with limit/offset (500 per page); truncated=true means matches remain after the returned window and upstreamTotal holds the full count. When the match set exceeds 500 and DataCanvas is enabled, the complete set also stages to a canvas (canvas_id/table_name) — inspect it with water_dataframe_describe, then retrieve it with water_dataframe_query.
输入模式
{
"type": "object",
"properties": {
"bbox": {
"description": "Bounding box as \"west,south,east,north\" in decimal degrees (e.g. \"-77.5,38.5,-76.5,39.5\" for the DC metro area). One of the four major filters — bbox, stateCd, countyCd, and huc are mutually exclusive with each other, and exactly one must be supplied.",
"type": "string",
"pattern": "^-?\\d+(\\.\\d+)?(,-?\\d+(\\.\\d+)?){3}$"
},
"stateCd": {
"description": "2-character US state abbreviation (e.g. \"VA\", \"WA\"). Returns all sites in the state for the given filters. Major filter — supply exactly one of bbox, stateCd, countyCd, huc.",
"type": "string",
"pattern": "^[A-Za-z]{2}$"
},
"countyCd": {
"description": "FIPS county code(s) as bare 5-digit numbers — state and county digits concatenated, no separator (e.g. \"51013\" for Arlington, VA). Comma-separate up to 20 (e.g. \"51059,51061\"). The 5 digits already encode the state, so the code stands alone. Major filter — supply exactly one of bbox, stateCd, countyCd, huc.",
"type": "string",
"pattern": "^\\d{5}(,\\d{5}){0,19}$"
},
"huc": {
"description": "Hydrologic Unit Code (HUC) scoping results to a watershed. Either a 2-digit major HUC (e.g. \"02\" for the Mid-Atlantic region) or an 8-digit minor HUC (e.g. \"02070008\" for the Middle Potomac). NWIS accepts no other lengths. Major filter — supply exactly one of bbox, stateCd, countyCd, huc.",
"type": "string",
"pattern": "^(\\d{2}|\\d{8})$"
},
"siteType": {
"description": "Site type filter. Common codes: \"ST\" (stream), \"GW\" (groundwater well), \"LK\" (lake/reservoir), \"SP\" (spring), \"AT\" (atmosphere), \"OC\" (ocean), \"ES\" (estuary). Comma-separate multiple types (e.g. \"ST,GW\").",
"type": "string"
},
"parameterCd": {
"description": "5-digit parameter code to require at each returned site (e.g. \"00060\" for discharge). Use water_list_parameters to discover codes. Comma-separate multiple codes with no spaces (e.g. \"00060,00065\").",
"type": "string",
"pattern": "^\\d{5}(,\\d{5})*$"
},
"hasDataTypeCd": {
"description": "Require sites with data of this type. Common values: \"iv\" (real-time/instantaneous), \"dv\" (daily values), \"gw\" (groundwater). Comma-separate multiple types.",
"type": "string"
},
"siteOutput": {
"default": "basic",
"description": "\"basic\" returns core identification fields. \"expanded\" adds drainage area, altitude, contributing area, and other metadata.",
"type": "string",
"enum": [
"basic",
"expanded"
]
},
"limit": {
"default": 500,
"description": "Maximum sites to return inline, 1–500. Default 500 (the inline cap).",
"type": "integer",
"minimum": 1,
"maximum": 500
},
"offset": {
"default": 0,
"description": "Number of matching sites to skip before returning results. Page through matches beyond the inline cap by advancing offset by limit. Default 0.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"canvas_id": {
"description": "Canvas ID from a prior call to add this match set as a table on an existing canvas rather than creating a new one. Each distinct filter set gets its own table name, so re-running the identical query replaces its own table while a different query adds another alongside it. Applies only when the match set exceeds the inline cap and DataCanvas is enabled. Omit to start a fresh canvas.",
"type": "string",
"pattern": "^[A-Za-z0-9_-]{10}$"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}输出模式
{
"type": "object",
"properties": {
"sites": {
"type": "array",
"items": {
"type": "object",
"properties": {
"siteNumber": {
"type": "string",
"description": "USGS site number (8–15 digits). Used by all other water tools."
},
"siteName": {
"type": "string",
"description": "Human-readable USGS site name (e.g. \"POTOMAC RIVER AT LITTLE FALLS, MD\")."
},
"siteType": {
"type": "string",
"description": "USGS site type code (e.g. \"ST\"=stream, \"GW\"=groundwater well, \"LK\"=lake/reservoir)."
},
"latitude": {
"type": "number",
"description": "Decimal latitude in WGS 84."
},
"longitude": {
"type": "number",
"description": "Decimal longitude in WGS 84."
},
"stateCd": {
"description": "2-digit FIPS state code (e.g. \"51\" for Virginia). Populated only when siteOutput=\"expanded\"; absent in basic mode.",
"type": "string"
},
"countyCd": {
"description": "3-digit FIPS county code within the state (zero-padded, e.g. \"013\"). Populated only when siteOutput=\"expanded\"; absent in basic mode.",
"type": "string"
},
"hucCd": {
"description": "Hydrologic Unit Code of the watershed containing this site; width varies (8-digit HUC8 and 12-digit HUC12, e.g. \"020700081005\", are both common — do not assume a fixed width), and absent when NWIS assigns none. Do not pass it straight back to the huc filter (which takes 2 or 8 digits); HUCs nest, so its first 8 digits are the containing HUC8 that filter accepts.",
"type": "string"
},
"drainageArea": {
"description": "Total drainage area in square miles. Populated only when siteOutput=\"expanded\"; absent in basic mode.",
"type": "number"
},
"altitude": {
"description": "Altitude of the gage datum in feet above sea level (NAVD 88 or NGVD 29). Present in both basic and expanded modes when USGS records an altitude for the site.",
"type": "number"
},
"contributingArea": {
"description": "Contributing drainage area in square miles (may differ from drainageArea for regulated basins). Populated only when siteOutput=\"expanded\"; absent in basic mode.",
"type": "number"
}
},
"required": [
"siteNumber",
"siteName",
"siteType",
"latitude",
"longitude"
],
"additionalProperties": false,
"description": "A USGS monitoring site with location, type, and available data."
},
"description": "The requested window of matching USGS monitoring sites — the slice starting at offset, at most limit long (500 max). upstreamTotal holds the full match count; canvas_id/table_name point to the staged full set when it exceeded the cap and DataCanvas is enabled."
},
"total": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "Number of sites returned inline in this response — at most limit, and 0 when offset is at or past upstreamTotal."
},
"truncated": {
"type": "boolean",
"description": "True when matches remain after the returned window (offset + total < upstreamTotal) — false on the last page, and false for a window starting past the end of the match set, where the notice names the valid offset range instead. Advance offset by limit for the next page, narrow filters (add bbox, countyCd, huc, siteType, parameterCd, or hasDataTypeCd), or when canvas_id is present read the staged set with water_dataframe_describe then water_dataframe_query."
},
"upstreamTotal": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "Total number of sites matching the query upstream, before limit/offset windowing. Equals total when the whole match set fits in one window."
},
"canvas_id": {
"description": "Canvas ID for the DataCanvas holding the full, uncapped match set. Present only when the match set exceeded the 500-site cap and DataCanvas is enabled. Pass to water_dataframe_describe then water_dataframe_query to retrieve sites beyond the inline cap.",
"type": "string"
},
"table_name": {
"description": "DuckDB table name in the canvas holding all matching sites. Present when canvas_id is present. Use as the FROM target in water_dataframe_query SQL.",
"type": "string"
},
"filters": {
"type": "object",
"properties": {
"stateCd": {
"description": "State filter applied, if any.",
"type": "string"
},
"countyCd": {
"description": "County FIPS filter applied, if any.",
"type": "string"
},
"siteType": {
"description": "Site type filter applied, if any.",
"type": "string"
},
"parameterCd": {
"description": "Parameter code filter applied, if any.",
"type": "string"
},
"bbox": {
"description": "Bounding box filter applied, if any.",
"type": "string"
},
"huc": {
"description": "HUC watershed filter applied, if any.",
"type": "string"
},
"hasDataTypeCd": {
"description": "Data type filter applied, if any.",
"type": "string"
},
"siteOutput": {
"type": "string",
"enum": [
"basic",
"expanded"
],
"description": "Site output mode used (basic or expanded)."
}
},
"required": [
"siteOutput"
],
"additionalProperties": false,
"description": "Filters applied to this query."
},
"notice": {
"description": "Advisory about the returned window: the staged canvas and how to read it, the filters to narrow by, the window actually returned, the valid offset range when the request landed past the end of the match set, or the fact that a supplied canvas_id went unused because nothing was staged.",
"type": "string"
},
"error": {
"description": "Present when the call failed. Absent on success.",
"type": "object",
"properties": {
"code": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"description": "Machine-readable failure mode. Declared by this tool: `no_sites_found`: No sites match the given geographic and filter criteria. `missing_major_filter`: None of bbox, stateCd, countyCd, or huc was supplied. NWIS scopes every site query by exactly one of them; siteType, parameterCd, and hasDataTypeCd only narrow within that scope. `conflicting_major_filters`: More than one of bbox, stateCd, countyCd, and huc was supplied. NWIS accepts exactly one per request. `invalid_request`: NWIS rejected the request. Filter formats are pattern-validated and the major-filter rule is enforced before the call, so this surfaces a well-formed value NWIS still refused — an unknown state, county, HUC, parameter, or site-type code. `upstream_error`: NWIS returned a 5xx error or the request timed out. `canvas_not_found`: The supplied canvas_id names a canvas that never existed or has expired. Raised before the NWIS request, so no upstream call is spent on it. `canvas_capacity_exhausted`: canvas_id was omitted and a fresh canvas was needed to stage the match set, but this tenant already holds the maximum number of active canvases. Other values are possible when a failure originates below the handler.",
"examples": [
"no_sites_found",
"missing_major_filter",
"conflicting_major_filters",
"invalid_request",
"upstream_error",
"canvas_not_found",
"canvas_capacity_exhausted"
]
},
"recovery": {
"description": "Actionable next step for the caller.",
"type": "object",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"additionalProperties": {}
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"additionalProperties": {}
}
},
"required": [
"code",
"message"
],
"additionalProperties": {}
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"sites",
"total",
"truncated",
"upstreamTotal",
"filters"
]
},
{
"required": [
"error"
]
}
]
}🟢water_get_readings(sites, parameterCd, period)
Get the latest instantaneous (~15-min, real-time) values for up to 100 USGS sites in one call — per-site, per-parameter records with timestamp, value, unit, and provisional/approved qualifiers. Each series returns only its 10 most recent records (totalValues reports the true count; truncated=true if any were capped); use water_get_series for a full date-range series. Sites NWIS returns nothing for are listed in missingSites, not dropped silently. Use water_find_sites first to discover site numbers and available parameters.
输入模式
{
"type": "object",
"properties": {
"sites": {
"minItems": 1,
"maxItems": 100,
"type": "array",
"items": {
"type": "string",
"pattern": "^\\d{8,15}$",
"description": "A USGS site number (8–15 digits, e.g. \"01646500\")."
},
"description": "One or more USGS site numbers to query. Maximum 100 per call."
},
"parameterCd": {
"description": "Parameter codes to return. Omit to get all parameters available at each site. Use water_list_parameters to discover codes.",
"type": "array",
"items": {
"type": "string",
"pattern": "^\\d{5}$",
"description": "A 5-digit USGS parameter code (e.g. \"00060\" for discharge)."
}
},
"period": {
"default": "PT2H",
"description": "ISO 8601 duration for the lookback period (e.g. \"PT2H\" = last 2 hours, \"P1D\" = last 1 day, \"P7D\" = last 7 days). Default: \"PT2H\" (last 2 hours of readings). Widening it raises totalValues, but each series still returns only its 10 most recent records — use water_get_series to retrieve a full series.",
"type": "string",
"pattern": "^P(?!$)(\\d+Y)?(\\d+M)?(\\d+W)?(\\d+D)?(T(?=\\d)(\\d+H)?(\\d+M)?(\\d+(\\.\\d+)?S)?)?$"
}
},
"required": [
"sites"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}输出模式
{
"type": "object",
"properties": {
"readings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"siteNumber": {
"type": "string",
"description": "USGS site number (8–15 digits, e.g. \"01646500\")."
},
"siteName": {
"type": "string",
"description": "Human-readable USGS site name (e.g. \"POTOMAC RIVER AT LITTLE FALLS, MD\")."
},
"parameterCd": {
"type": "string",
"description": "5-digit parameter code (e.g. \"00060\" for discharge)."
},
"parameterName": {
"type": "string",
"description": "Human-readable parameter name with units (e.g. \"Streamflow, ft³/s\")."
},
"unitCode": {
"type": "string",
"description": "Unit of measure for the values in this series (e.g. \"ft3/s\", \"ft\", \"°C\")."
},
"values": {
"type": "array",
"items": {
"type": "object",
"properties": {
"dateTime": {
"type": "string",
"description": "ISO 8601 date-time of this observation."
},
"value": {
"type": "string",
"description": "Measured value as a string (empty string means no data for that interval)."
},
"qualifiers": {
"type": "array",
"items": {
"type": "string",
"description": "A USGS data qualifier code (e.g. \"P\" = provisional, \"A\" = approved)."
},
"description": "Data qualifier codes for this value."
}
},
"required": [
"dateTime",
"value",
"qualifiers"
],
"additionalProperties": false,
"description": "A single instantaneous reading for this site and parameter."
},
"description": "Time-ordered value records for this site and parameter, capped at the most recent 10. Compare with totalValues to see whether the period held more; use water_get_series for the full series."
},
"totalValues": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "Number of value records NWIS returned for this site and parameter over the requested period, before the 10-record cap. Equals values.length when nothing was capped."
}
},
"required": [
"siteNumber",
"siteName",
"parameterCd",
"parameterName",
"unitCode",
"values",
"totalValues"
],
"additionalProperties": false,
"description": "Time series result for one site+parameter combination."
},
"description": "Time series per site+parameter combination."
},
"total": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "Total number of site+parameter time series returned."
},
"truncated": {
"type": "boolean",
"description": "True when at least one series held more than 10 records and was capped. Per-series counts are in readings[].totalValues; use water_get_series for the full series."
},
"missingSites": {
"type": "array",
"items": {
"type": "string",
"description": "A requested USGS site number that returned no time series."
},
"description": "Requested site numbers NWIS returned no series for — the site may not exist, or may not measure the requested parameter(s) in the requested period. Empty when every requested site returned data. Verify these with water_find_sites."
},
"query": {
"type": "object",
"properties": {
"sites": {
"type": "array",
"items": {
"type": "string"
},
"description": "Site numbers queried."
},
"parameterCd": {
"description": "Parameter codes requested, if filtered.",
"type": "array",
"items": {
"type": "string"
}
},
"period": {
"type": "string",
"description": "Lookback period applied (ISO 8601 duration)."
}
},
"required": [
"sites",
"period"
],
"additionalProperties": false,
"description": "Query parameters used for this request."
},
"error": {
"description": "Present when the call failed. Absent on success.",
"type": "object",
"properties": {
"code": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"description": "Machine-readable failure mode. Declared by this tool: `no_data_for_parameter`: NWIS returned no time series — the site(s) may not exist, or may not have data for the requested parameter(s) in the requested period. NWIS returns the same empty response for both cases. `invalid_request`: NWIS rejected the request. Input formats are validated against NWIS-accepted patterns before the call, so this surfaces a value that is well-formed but unacceptable upstream. `upstream_error`: NWIS returned a 5xx error or the request timed out. Other values are possible when a failure originates below the handler.",
"examples": [
"no_data_for_parameter",
"invalid_request",
"upstream_error"
]
},
"recovery": {
"description": "Actionable next step for the caller.",
"type": "object",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"additionalProperties": {}
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"additionalProperties": {}
}
},
"required": [
"code",
"message"
],
"additionalProperties": {}
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"readings",
"total",
"truncated",
"missingSites",
"query"
]
},
{
"required": [
"error"
]
}
]
}🟢water_get_series(site, parameterCd, startDate, endDate, seriesType, ...)
Get a daily or instantaneous time series for one USGS site and parameter over a date range, as time-ordered value records. Large sets (>500 records) return the most recent records inline with truncated=true — the last 500 without DataCanvas, and with DataCanvas enabled the complete series also spills to a canvas (canvas_id/table_name): inspect the staged table with water_dataframe_describe, then read the full series with water_dataframe_query. Use water_find_sites and water_list_parameters to resolve inputs.
输入模式
{
"type": "object",
"properties": {
"site": {
"type": "string",
"pattern": "^\\d{8,15}$",
"description": "USGS site number (8–15 digits, e.g. \"01646500\" for Potomac River at Little Falls). Use water_find_sites to discover valid site numbers."
},
"parameterCd": {
"type": "string",
"pattern": "^\\d{5}$",
"description": "A single 5-digit USGS parameter code (e.g. \"00060\" for discharge, \"00065\" for gage height). One code per call — this tool returns one series. Use water_list_parameters to discover available codes."
},
"startDate": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "Start date in YYYY-MM-DD format (e.g. \"2024-01-01\")."
},
"endDate": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "End date in YYYY-MM-DD format (e.g. \"2024-12-31\")."
},
"seriesType": {
"default": "daily",
"description": "\"daily\" returns one value per day (DV service, typically mean/max/min). \"instantaneous\" returns ~15-minute readings (IV service). Default: \"daily\". Use \"instantaneous\" for high-resolution analysis.",
"type": "string",
"enum": [
"daily",
"instantaneous"
]
},
"canvas_id": {
"description": "Canvas ID from a prior call to add this series as a table on an existing canvas rather than creating a new one. Each distinct site, parameter code, series type, and date range gets its own table name, so re-running the identical query replaces its own table while a different query adds another alongside it. Applies only when the series spills to a canvas. Omit to start a fresh canvas.",
"type": "string",
"pattern": "^[A-Za-z0-9_-]{10}$"
}
},
"required": [
"site",
"parameterCd",
"startDate",
"endDate"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}输出模式
{
"type": "object",
"properties": {
"siteNumber": {
"type": "string",
"description": "USGS site number (8–15 digits, e.g. \"01646500\")."
},
"siteName": {
"type": "string",
"description": "Human-readable USGS site name."
},
"parameterCd": {
"type": "string",
"description": "5-digit USGS parameter code (e.g. \"00060\" for discharge)."
},
"parameterName": {
"type": "string",
"description": "Human-readable parameter name with units (e.g. \"Streamflow, ft³/s\")."
},
"unitCode": {
"type": "string",
"description": "Unit of measure for all values in this series (e.g. \"ft3/s\", \"ft\")."
},
"seriesType": {
"type": "string",
"enum": [
"daily",
"instantaneous"
],
"description": "\"daily\" = one value per day (DV service); \"instantaneous\" = ~15-minute readings (IV service)."
},
"values": {
"type": "array",
"items": {
"type": "object",
"properties": {
"dateTime": {
"type": "string",
"description": "ISO 8601 date or date-time of this observation."
},
"value": {
"type": "string",
"description": "Measured value as a string (empty string means no data for that interval)."
},
"qualifiers": {
"type": "array",
"items": {
"type": "string",
"description": "A USGS data qualifier code (e.g. \"P\" = provisional, \"A\" = approved)."
},
"description": "Data qualifier codes for this value."
}
},
"required": [
"dateTime",
"value",
"qualifiers"
],
"additionalProperties": false,
"description": "A single value record with date-time, value, and qualifiers."
},
"description": "Time-ordered value records, oldest first within the slice. Holds every record when truncated is false; when truncated, the most recent records only — the last 500 without DataCanvas, or the last N that fit the inline preview budget when the full series is staged on a canvas."
},
"totalRecords": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "Total number of records in the upstream result set (before any truncation)."
},
"truncated": {
"type": "boolean",
"description": "True when the result exceeds 500 records and only the most recent were returned inline. When canvas_id is present, inspect the staged table with water_dataframe_describe then read the full series with water_dataframe_query; otherwise narrow the date range."
},
"canvas_id": {
"description": "Canvas ID for the DataCanvas holding the full time series. Present only when truncated=true and DataCanvas is enabled. Pass to water_dataframe_describe then water_dataframe_query.",
"type": "string"
},
"table_name": {
"description": "DuckDB table name in the canvas holding all records. Present when canvas_id is present. Use as the FROM target in water_dataframe_query SQL.",
"type": "string"
},
"query": {
"type": "object",
"properties": {
"site": {
"type": "string",
"description": "Site number queried."
},
"parameterCd": {
"type": "string",
"description": "Parameter code queried."
},
"startDate": {
"type": "string",
"description": "Start date applied (YYYY-MM-DD)."
},
"endDate": {
"type": "string",
"description": "End date applied (YYYY-MM-DD)."
},
"seriesType": {
"type": "string",
"enum": [
"daily",
"instantaneous"
],
"description": "Series type used."
}
},
"required": [
"site",
"parameterCd",
"startDate",
"endDate",
"seriesType"
],
"additionalProperties": false,
"description": "Query parameters used for this request."
},
"notice": {
"description": "Advisory about this result: the staged canvas table and how to read it, the advice to narrow the date range when the series was truncated with no canvas available, or the fact that a supplied canvas_id went unused because nothing was staged.",
"type": "string"
},
"error": {
"description": "Present when the call failed. Absent on success.",
"type": "object",
"properties": {
"code": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"description": "Machine-readable failure mode. Declared by this tool: `no_data_for_range`: The site and parameter combination has no data in the requested date range. `invalid_date_range`: endDate is before startDate, or a date passes the YYYY-MM-DD shape check but is not a real calendar date. `invalid_request`: NWIS rejected the request. Input formats are validated against NWIS-accepted patterns before the call, so this surfaces a value that is well-formed but unacceptable upstream. `upstream_error`: NWIS returned a 5xx error or the request timed out. `canvas_not_found`: The supplied canvas_id names a canvas that never existed or has expired. Raised before the NWIS request, so no upstream call is spent on it. `canvas_capacity_exhausted`: canvas_id was omitted and a fresh canvas was needed to stage the series, but this tenant already holds the maximum number of active canvases. Other values are possible when a failure originates below the handler.",
"examples": [
"no_data_for_range",
"invalid_date_range",
"invalid_request",
"upstream_error",
"canvas_not_found",
"canvas_capacity_exhausted"
]
},
"recovery": {
"description": "Actionable next step for the caller.",
"type": "object",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"additionalProperties": {}
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"additionalProperties": {}
}
},
"required": [
"code",
"message"
],
"additionalProperties": {}
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"siteNumber",
"siteName",
"parameterCd",
"parameterName",
"unitCode",
"seriesType",
"values",
"totalRecords",
"truncated",
"query"
]
},
{
"required": [
"error"
]
}
]
}🟢water_get_conditions(site, parameterCd)
Get a USGS site's current reading ranked against its full period-of-record daily-mean percentiles for the same calendar day — a "how unusual is this" percentileClass (record-high to record-low), not a flood-stage or drought determination (this tool fetches no authoritative thresholds). The reading is instantaneous but the percentiles are daily-mean, so the ranking is approximate (see historicalContext.comparisonBasis). When the record is too short to rank, returns the reading with historicalContext=null instead of an error. Use water_find_sites and water_list_parameters to resolve inputs.
输入模式
{
"type": "object",
"properties": {
"site": {
"type": "string",
"pattern": "^\\d{8,15}$",
"description": "USGS site number (8–15 digits, e.g. \"01646500\" for Potomac River at Little Falls). Use water_find_sites to discover valid site numbers."
},
"parameterCd": {
"type": "string",
"pattern": "^\\d{5}$",
"description": "5-digit USGS parameter code (e.g. \"00060\" for discharge, \"00065\" for gage height). Use water_list_parameters to discover codes."
}
},
"required": [
"site",
"parameterCd"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}输出模式
{
"type": "object",
"properties": {
"siteNumber": {
"type": "string",
"description": "USGS site number (8–15 digits, e.g. \"01646500\")."
},
"siteName": {
"type": "string",
"description": "Human-readable USGS site name."
},
"parameterCd": {
"type": "string",
"description": "5-digit USGS parameter code that was queried (e.g. \"00060\")."
},
"parameterName": {
"type": "string",
"description": "Human-readable parameter name with units (e.g. \"Streamflow, ft³/s\")."
},
"unitCode": {
"type": "string",
"description": "Unit of measure for currentValue and the historical percentiles (e.g. \"ft3/s\", \"ft\")."
},
"currentValue": {
"type": "string",
"description": "Most recent observed value as a string. Empty string when no data is available for the current period."
},
"currentDateTime": {
"type": "string",
"description": "ISO 8601 date-time of the most recent observation."
},
"qualifiers": {
"type": "array",
"items": {
"type": "string",
"description": "A USGS data qualifier code (e.g. \"P\" = provisional)."
},
"description": "Data qualifier codes for the current reading."
},
"historicalContext": {
"anyOf": [
{
"type": "object",
"properties": {
"percentileClass": {
"type": "string",
"enum": [
"record-high",
"above-normal",
"normal",
"below-normal",
"low",
"record-low",
"unknown"
],
"description": "Classification relative to the full period-of-record: record-high (≥ p95), above-normal (p75–p95), normal (p25–p75), below-normal (p10–p25), low (p05–p10), record-low (< p05). See percentileLabel for the threshold in plain language."
},
"percentileLabel": {
"type": "string",
"description": "Plain-language threshold for percentileClass (e.g. \"25th–75th percentile\"). The record-high and record-low classes mark percentile-of-record extremes (≥ p95 / < p05), not verified all-time records — this field says so where the class name does not."
},
"p05": {
"description": "5th percentile value in unitCode for this calendar month+day, based on the period of record. Null if that threshold is unavailable.",
"type": [
"number",
"null"
]
},
"p10": {
"description": "10th percentile value in unitCode for this calendar month+day. Null if unavailable.",
"type": [
"number",
"null"
]
},
"p25": {
"description": "25th percentile (lower quartile) in unitCode. Null if unavailable.",
"type": [
"number",
"null"
]
},
"p50": {
"description": "Median (50th percentile) in unitCode for this calendar month+day. Null if unavailable.",
"type": [
"number",
"null"
]
},
"p75": {
"description": "75th percentile (upper quartile) in unitCode. Null if unavailable.",
"type": [
"number",
"null"
]
},
"p95": {
"description": "95th percentile value in unitCode for this calendar month+day. Null if unavailable.",
"type": [
"number",
"null"
]
},
"periodOfRecord": {
"type": "string",
"description": "Range of years used to compute the percentile statistics (e.g. \"1930–2025\")."
},
"comparisonBasis": {
"type": "string",
"description": "Fixed disclosure that percentileClass ranks an instantaneous reading against approved daily-mean percentiles — a cross-granularity approximation, not a flood-stage or drought determination. Present whenever historicalContext is non-null."
}
},
"required": [
"percentileClass",
"percentileLabel",
"p05",
"p10",
"p25",
"p50",
"p75",
"p95",
"periodOfRecord",
"comparisonBasis"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Historical percentile context for the observation's calendar day. Non-null only when historicalContextStatus is \"available\"; see that field for why it is otherwise absent."
},
"historicalContextStatus": {
"type": "string",
"enum": [
"available",
"no_matching_day",
"no_record",
"unavailable"
],
"description": "Why historicalContext is or is not populated. 'available': percentiles for the observation's calendar day are present. 'no_matching_day': the stat table has rows but none for that calendar day. 'no_record': the stat table is empty — a new site, or a record too short to compute percentiles. 'unavailable': the statistics service call failed — a transient upstream error, not a statement about the site's record; retry shortly."
},
"note": {
"description": "Informational note explaining why historicalContext is null or incomplete. Absent when full historical context is available.",
"type": "string"
},
"error": {
"description": "Present when the call failed. Absent on success.",
"type": "object",
"properties": {
"code": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"description": "Machine-readable failure mode. Declared by this tool: `no_data_for_parameter`: NWIS returned no IV data — the site may not exist, or may not measure the requested parameter. NWIS returns the same empty response for both cases. `invalid_request`: NWIS rejected the request. Input formats are validated against NWIS-accepted patterns before the call, so this surfaces a value that is well-formed but unacceptable upstream. `upstream_error`: NWIS IV or stat endpoint returned a 5xx error or timed out. Other values are possible when a failure originates below the handler.",
"examples": [
"no_data_for_parameter",
"invalid_request",
"upstream_error"
]
},
"recovery": {
"description": "Actionable next step for the caller.",
"type": "object",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"additionalProperties": {}
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"additionalProperties": {}
}
},
"required": [
"code",
"message"
],
"additionalProperties": {}
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"siteNumber",
"siteName",
"parameterCd",
"parameterName",
"unitCode",
"currentValue",
"currentDateTime",
"qualifiers",
"historicalContext",
"historicalContextStatus"
]
},
{
"required": [
"error"
]
}
]
}🟢water_dataframe_query(canvas_id, sql)
Run a read-only SQL SELECT against water data tables staged on a DataCanvas by water_get_series or water_find_sites. Workflow: run water_get_series or water_find_sites (get canvas_id + table_name) → water_dataframe_describe (confirm the table and its columns) → water_dataframe_query (SQL analysis). Only SELECT statements are permitted. At most 10,000 rows are returned; a query matching more is capped and the response sets truncated=true — scope with WHERE/LIMIT, and use SELECT COUNT(*) or water_dataframe_describe to learn the true match count. Requires DataCanvas to be enabled on this server instance. Returns an error if DataCanvas is not available.
输入模式
{
"type": "object",
"properties": {
"canvas_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{10}$",
"description": "Canvas ID returned by water_get_series or water_find_sites. Identifies the canvas holding the data."
},
"sql": {
"type": "string",
"description": "Read-only SELECT statement. Reference the table by the table_name from water_get_series or water_find_sites; columns vary by source table, so run water_dataframe_describe first for the exact schema. Example: SELECT date_time, value FROM water_series_01646500_00060 ORDER BY date_time DESC LIMIT 10"
}
},
"required": [
"canvas_id",
"sql"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}输出模式
{
"type": "object",
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {},
"additionalProperties": {},
"description": "A result row whose keys are the selected column names and values are the corresponding cell values."
},
"description": "Result rows returned (up to 10,000). Column names match the SELECT clause."
},
"row_count": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "Number of rows returned in the rows array (up to the 10,000-row cap), not the total matched by the query. When truncated is true the cap was reached, so row_count equals the returned count and undercounts the true total. To get the true match count run SELECT COUNT(*) with the same filter, or call water_dataframe_describe for the full row count of the staged table; page large results with LIMIT/OFFSET."
},
"truncated": {
"type": "boolean",
"description": "True when the query matched more rows than the 10,000-row cap and the result was capped — rows and row_count then cover only the first 10,000 matches, and the rest are not in this response. False means rows and row_count are the complete result for this query. When true, narrow the query with WHERE, page with LIMIT/OFFSET, or run SELECT COUNT(*) with the same filter for the true total."
},
"error": {
"description": "Present when the call failed. Absent on success.",
"type": "object",
"properties": {
"code": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"description": "Machine-readable failure mode. Declared by this tool: `canvas_disabled`: DataCanvas is not enabled on this server instance. `canvas_not_found`: The canvas_id does not exist or has expired. `table_not_found`: The SQL names a table that is not staged on this canvas — it may have expired, or was never created. `system_catalog_access`: The SQL reads a database system catalog (information_schema, pg_catalog, sqlite_master, duckdb_*) instead of a staged table. `invalid_sql`: The SQL is not a read-only SELECT, contains disallowed functions, is syntactically invalid, or failed on the staged data (a cast or conversion the engine could not apply). Other values are possible when a failure originates below the handler.",
"examples": [
"canvas_disabled",
"canvas_not_found",
"table_not_found",
"system_catalog_access",
"invalid_sql"
]
},
"recovery": {
"description": "Actionable next step for the caller.",
"type": "object",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"additionalProperties": {}
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"additionalProperties": {}
}
},
"required": [
"code",
"message"
],
"additionalProperties": {}
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"rows",
"row_count",
"truncated"
]
},
{
"required": [
"error"
]
}
]
}🟢water_dataframe_describe(canvas_id)
List tables and columns staged on a DataCanvas by water_get_series or water_find_sites. Call this after water_get_series or water_find_sites returns a canvas_id to discover the exact table name and column types before writing a query. Then pass the table name to water_dataframe_query. Requires DataCanvas to be enabled on this server instance. Returns an error if DataCanvas is not available.
输入模式
{
"type": "object",
"properties": {
"canvas_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{10}$",
"description": "Canvas ID returned by water_get_series or water_find_sites. Identifies the canvas to describe."
}
},
"required": [
"canvas_id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}输出模式
{
"type": "object",
"properties": {
"tables": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Table or view name — use as the FROM target in SQL."
},
"kind": {
"type": "string",
"enum": [
"table",
"view"
],
"description": "Whether this is a base table or a SQL view."
},
"row_count": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "Approximate row count for this table (DuckDB estimate; may differ from exact count)."
},
"columns": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Column name."
},
"type": {
"type": "string",
"description": "DuckDB column type (e.g. VARCHAR, DOUBLE)."
},
"nullable": {
"type": "boolean",
"description": "True if the column allows NULL values."
}
},
"required": [
"name",
"type",
"nullable"
],
"additionalProperties": false,
"description": "A column in this table."
},
"description": "Column schema for this table."
}
},
"required": [
"name",
"kind",
"row_count",
"columns"
],
"additionalProperties": false,
"description": "A staged canvas table or view."
},
"description": "Tables and views on this canvas."
},
"canvas_id": {
"type": "string",
"description": "The canvas ID that was described — pass to water_dataframe_query."
},
"error": {
"description": "Present when the call failed. Absent on success.",
"type": "object",
"properties": {
"code": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"description": "Machine-readable failure mode. Declared by this tool: `canvas_disabled`: DataCanvas is not enabled on this server instance. `canvas_not_found`: The canvas_id does not exist or has expired. Other values are possible when a failure originates below the handler.",
"examples": [
"canvas_disabled",
"canvas_not_found"
]
},
"recovery": {
"description": "Actionable next step for the caller.",
"type": "object",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"additionalProperties": {}
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"additionalProperties": {}
}
},
"required": [
"code",
"message"
],
"additionalProperties": {}
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"tables",
"canvas_id"
]
},
{
"required": [
"error"
]
}
]
}社区
证据
最近观测
已验证未记录版本7 个工具
已验证未记录版本7 个工具