wsdot-mcp-server

---

概览

通过 WSDOT 查询华盛顿州的道路和渡轮信息。查看山口、行程时间、收费、边境等待时间、警报和交通摄像头，并追踪渡轮时刻表、船舶位置和码头空间。

工具

工具	描述
wsdot_get_mountain_passes	WA 所有山口的当前状况：状态、道路状况、牵引力规定、温度和海拔。
wsdot_search_alerts	当前有效的公路警报——事故、施工、封路——可按州道路线、WSDOT 区域和里程桩范围筛选。
wsdot_get_travel_times	WA 指定公路走廊（I-5、I-90、SR 520 等）的当前行程时间与平均行程时间，以及拥堵延误。
wsdot_get_toll_rates	WA 快速车道和收费设施的动态收费费率——SR 99、SR 167 HOT、I-405 Express、SR 509、SR 520——可按路线筛选。
wsdot_get_border_waits	WA/加拿大所有陆路边境口岸的当前车辆等待时间。
wsdot_search_cameras	公路摄像头元数据和图像 URL，可按州道路线、区域、里程桩范围和标题关键词筛选。
wsdot_get_ferry_terminals	所有 WSF 渡轮码头的数字 ID（用于查询时刻表和空位）及坐标。
wsdot_get_ferry_routes	指定日期运营的 WSF 航线——航线 ID、缩写、描述及其服务的码头对，可用于发现航线、查询时刻表和交叉查询渡轮警报。
wsdot_get_ferry_schedule	指定 WSF 航线的出发时间——可选择今天剩余班次或未来全天模式——以及每个班次的船只、装载规则和备注。
wsdot_get_vessel_locations	所有运营中的 WSF 船只的实时 AIS 位置、速度、航向、预计到达时间和停靠状态。
wsdot_get_terminal_space	WSF 码头后续班次可供现场购票和预订的车辆空间。
wsdot_get_ferry_alerts	当前有效的 WSF 服务中断信息和公告，以及受影响的航线 ID。

功能参考

wsdot_get_mountain_passes _工具

• 无需输入——一次调用即可获取 WA 全部 16 个山口（Snoqualmie、Stevens、White、Blewett、Cayuse 等）的当前状况
• 每个山口都包含道路状况、天气、温度、海拔，以及最多两项按方向区分的牵引力/通行限制

---

wsdot_search_alerts _工具

• 可选参数 stateRoute、region（Northwest、Olympic、Southwest、South Central、North Central、Eastern）和 startMilepost / endMilepost——警报影响范围与所选范围重叠时即匹配；全部省略则返回全州所有警报。按 alertId 排序，支持分页（默认 20 条，最多 500 条）
• 未知区域会返回 invalid_region，起始里程桩大于结束里程桩会返回 invalid_milepost_range；两者都会提供恢复提示

---

wsdot_get_travel_times _工具

• route 为可选参数——路线（"I-5"、"SR 520"）会返回在该路线测量的所有走廊；其他文本则匹配走廊名称（"Everett"）；支持分页（默认 50 条，最多 500 条）
• 每条走廊都会报告当前和平均行程时间（分钟）——当前值高于平均值表示拥堵，两者之差即为延误。若查询方向上的可逆快速车道走廊已关闭，则不返回相关数值，而不是报告为零

---

wsdot_get_toll_rates _工具

• 覆盖 SR 99（WSDOT 隧道）、SR 167 HOT 车道、I-405 Express 车道、SR 509 收费路段和 SR 520 大桥。stateRoute 为可选参数，与公布的路线标识匹配（"I-405"、"SR 520"）；没有收费设施的路线会返回空页，并在提示中列出收费路线。支持分页（默认 50 条，最多 500 条）
• 每行以 startLocationName → endLocationName 路段开头。stateRoute 是数据源中的未格式化零填充编号（"099"），travelDirection 是数据源中的代码；SR 99、SR 509 和 SR 520 的方向均由各自设施固定——请根据路段两端判断方向

---

wsdot_get_border_waits _工具

• 无输入 — crossings[] 中有 11 条车道记录，覆盖 I-5（Peace Arch）、SR 543（Pacific Highway）、SR 539（Lynden）和 SR 9（Sumas）：每个地点各有一条普通车道和一条 Nexus 车道，SR 539 和 SR 543 另有卡车车道
• crossingName 是路线代码（I5、SR543Trucks），location.description 是易读的名称；当前没有数据的车道会省略 waitTimeInMinutes

---

wsdot_search_cameras _工具

• 可选 stateRoute、region 代码（NW、SW、OL、ER、SC、NC、OS 表示 Oregon TripCheck 摄像头，WA 表示机场摄像头）、startMilepost / endMilepost 和 titleContains（匹配所有单词，顺序不限）。按 cameraId 排序并分页（默认 50 条，最多 500 条）
• 返回元数据和图像 URL，不返回图像字节（摄像头图像受 WSDOT 版权保护）。未知区域会报错 invalid_region，起止范围颠倒则报错 invalid_milepost_range

---

wsdot_get_ferry_terminals _工具

• 无输入 — 返回全部 20 个 WSF 码头，每个码头都包含数字 ID、缩写和纬度/经度
• 将名称（“Bainbridge Island”、“Seattle”）解析为 wsdot_get_ferry_schedule 和 wsdot_get_terminal_space 所需的 ID

---

wsdot_get_ferry_routes _工具

• 可选 tripDate（YYYY-MM-DD，默认今天）；如果日期超出 WSF 已发布的范围，则报错 invalid_date 并说明该范围
• 每条路线都包含其 ID（即 wsdot_get_ferry_alerts 的 impactedRouteIds）、缩写、描述和 terminalPairs — 当天 wsdot_get_ferry_schedule 接受的出发 → 到达码头配对

---

wsdot_get_ferry_schedule _工具

• 必须提供 departingTerminalId 和 arrivingTerminalId（取自 wsdot_get_ferry_routes 中的 terminalPairs）；可选 tripDate（默认今天）和 remainingOnly（仅显示未来航次，且仅限当天）
• 每个航次都包含 ISO 8601 UTC 格式的 departureTime / arrivalTime（tripDate 是太平洋时区的服务日期）、vesselId、loadingRule，以及指向该配对 annotations 的索引。没有取消标记 — WSF 会移除已取消的航次，因此请检查 wsdot_get_ferry_alerts
• 当天没有时刻表的配对会报错 invalid_terminal_pair，没有航次的日期会报错 invalid_date，不会返回空时刻表

---

wsdot_get_vessel_locations _工具

• 无输入 — 返回所有在役 WSF 船只的位置、速度、航向、预计到达时间和靠泊状态
• 位置可能延迟 30–60 秒；未投入服务的船只可能缺少许多字段，而处于任务间隙的船只会将 opRouteAbbrev 报告为 none reported

---

wsdot_get_terminal_space _工具

• 可选 departingTerminalId（取自 wsdot_get_ferry_terminals），否则返回所有码头；按码头分页（默认 5 个，最多 20 个），并包含所返回码头的每个航次
• driveUpSpaceCount 是关键字段 — 数值为零表示无需预约的车道已满，超额预订航次的上游计数为负时会按零处理。arrivingTerminalIds 可用于串接 wsdot_get_ferry_schedule

---

wsdot_get_ferry_alerts _工具

• 无输入 — 返回当前有效的 WSF 中断、延误和公告，每条都包含 alertTitle、一行的 alertDescription 和完整的 bulletinText（替代航次等详细信息仅出现在正文中）
• impactedRouteIds 对应 wsdot_get_ferry_routes；affectsAllRoutes: true 表示影响整个船队的警报，此时路线列表为空意味着影响所有路线

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔的身份验证（none / jwt / oauth）、可切换的存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及支持可选 OpenTelemetry 跟踪的结构化日志。

WSDOT 特定功能：

• 双 API 集成 — WSDOT Traffic API 和 WSF Ferry API 共用一个 WSDOT_ACCESS_CODE
• 工具描述内置跨工具链接 — 渡轮工具会指向 wsdot_get_ferry_terminals / wsdot_get_ferry_routes，以便在查询前解析 ID
• 两个 API 的响应结构经过统一规范化 — 上游缺失的字段会作为可选字段呈现，而不是省略或设为默认值
• 稳定分页 — 上游的预警和摄像头数据流可能以不止一种行顺序返回相同数据，因此会按 ID 排序，确保给定偏移量对应的结果可复现
• 分页列表工具接受 offset / limit；当响应达到 24,000 字节预算时，也会提前结束当前页，并在提示中注明下一个偏移量
• 路线筛选器支持常见输入形式 — "I-90"、"90"、"090"、"SR 520" — 每个文本筛选器最多接受 200 个字符

适合 Agent 使用的输出：

• 类型化错误 — invalid_access_code 和 api_unavailable 错误会附带明确的恢复提示，用于区分配置错误与上游暂时性故障
• driveUpSpaceCount: 0 和拥堵变化字段（delayInMinutes）为 Agent 提供可操作的信息，无需解析字符串
• 从 HTML 转换为纯文本 — 上游返回的预警说明、航行备注和公告都是 HTML，输出时会转换为文本，链接以内联形式 链接文本 (url) 显示
• 保留不完整数据 — 上游缺失的字段会呈现为 null/undefined，而不是合成默认值（例如省略的 waitTimeInMinutes、缺失的 arrivalTime）
• content[] 和 structuredContent 携带相同的值，而不仅是相同的字段 — false 标记、空列表以及坐标对中已填充的一半都会呈现，不会从某些客户端读取的 Markdown 内容中消失；空白或仅含空格的上游字符串在两者中都会省略，非空字符串则会先去除首尾空白再返回

开始使用

公共托管实例

https://wsdot.caseyjhand.com/mcp 提供公共实例 — 无需安装。该实例支持 Streamable HTTP；每个客户端的配置格式各不相同。

对于 Claude Code：

claude mcp add --transport http wsdot-mcp-server https://wsdot.caseyjhand.com/mcp

对于 Cline（cline_mcp_settings.json）：

{
  "mcpServers": {
    "wsdot-mcp-server": {
      "type": "streamableHttp",
      "url": "https://wsdot.caseyjhand.com/mcp"
    }
  }
}

对于 Cursor（mcp.json）：

{
  "mcpServers": {
    "wsdot-mcp-server": {
      "url": "https://wsdot.caseyjhand.com/mcp"
    }
  }
}

Claude Desktop 可在“设置”→“连接器”中添加远程服务。

自托管 / 本地部署

将以下内容添加到 MCP 客户端配置文件中。你需要 WSDOT Traveler API 访问码 — 请在 wsdot.wa.gov/Traffic/api/ 注册。

{
  "mcpServers": {
    "wsdot-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/wsdot-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "WSDOT_ACCESS_CODE": "your-access-code"
      }
    }
  }
}

也可以使用 npx（无需 Bun）：

{
  "mcpServers": {
    "wsdot-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/wsdot-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "WSDOT_ACCESS_CODE": "your-access-code"
      }
    }
  }
}

也可以使用 Docker：

{
  "mcpServers": {
    "wsdot-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "WSDOT_ACCESS_CODE=your-access-code",
        "ghcr.io/cyanheads/wsdot-mcp-server:latest"
      ]
    }
  }
}

对于 Streamable HTTP，设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 WSDOT_ACCESS_CODE=your-access-code bun run start:http
# Server listens at http://localhost:3010/mcp

先决条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• WSDOT Traveler API 访问码。在 wsdot.wa.gov/Traffic/api/ 注册 — 注册免费。

安装

1. 克隆仓库：

git clone https://github.com/cyanheads/wsdot-mcp-server.git

2. 进入目录：

cd wsdot-mcp-server

3. 安装依赖项：

bun install

4. 配置环境：

cp .env.example .env
# edit .env and set WSDOT_ACCESS_CODE

配置

启动时会通过 src/config/server-config.ts 中的 Zod 模式验证所有配置。主要环境变量：

变量	描述	默认值
WSDOT_ACCESS_CODE	必填。 WSDOT Traveler API 访问码。请在 wsdot.wa.gov/Traffic/api/ 注册。	—
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_HTTP_HOST	HTTP 服务主机名。	127.0.0.1
MCP_HTTP_ENDPOINT_PATH	HTTP 端点路径。	/mcp
MCP_PUBLIC_URL	用于 TLS 终止型反向代理部署的公共源地址。	—
MCP_SESSION_MODE	会话处理方式：auto、stateful 或 stateless。模式默认值 auto 会解析为有状态；此服务会显式设置为 stateless。	stateless
MCP_AUTH_MODE	身份验证方式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（debug、info、notice、warning、error）。	info
LOGS_DIR	日志文件目录（仅限 Node.js）。	<project-root>/logs
STORAGE_PROVIDER_TYPE	存储后端：in-memory、filesystem、supabase、cloudflare-kv/r2/d1。	in-memory
LOG_TOOL_FAILURE_PAYLOADS	记录每次失败工具调用的参数和结果（仅对键名进行脱敏）。	false
OTEL_ENABLED	启用 OpenTelemetry 插桩（跨度、指标、完成日志）。	false
OTEL_EXPORTER_OTLP_ENDPOINT	OTLP 基础 URL；追踪数据发送到 /v1/traces，指标发送到 /v1/metrics。	—
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	选择启用 OTLP 日志导出；基础端点不会启用此功能。	—

完整的可选覆盖项列表请参阅 .env.example。

运行服务

本地开发

• 构建并运行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t wsdot-mcp-server .
docker run --rm -e WSDOT_ACCESS_CODE=your-access-code -p 3010:3010 wsdot-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/wsdot-mcp-server。默认会安装 OpenTelemetry 对等依赖；构建时使用 --build-arg OTEL_ENABLED=false 可省略这些依赖。

项目结构

目录	用途
src/index.ts	createApp() 入口点——注册全部 12 个工具并初始化服务。
src/config	使用 Zod 解析并验证服务专用环境变量。
src/mcp-server/tools	工具定义（*.tool.ts）——6 个交通工具、6 个渡轮工具。
src/services/traffic	WSDOT Traffic API 服务（山口、警报、行程时间、收费标准、边境等待时间、摄像头）。
src/services/ferry	WSF Ferry API 服务（码头、路线、时刻表、船舶位置、舱位、警报）。
tests/	单元测试和集成测试，结构与 src/ 相对应。

开发指南

开发指南和架构规则请参阅 CLAUDE.md。简而言之：

• 处理程序抛出异常，由框架捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求范围的日志，使用 ctx.state 进行租户范围的存储
• 在 src/index.ts 的 createApp() 数组中注册新工具
• 包装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出模式；切勿编造缺失字段

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0——详情请参阅 LICENSE。