dsh-plugin-weather

Global weather + air quality, callable at any time inside DeepSeek Harness.

Temperature · feels-like · humidity · UV index · sunrise/sunset · wind · PM2.5 / AQI — plus a 1–16 day forecast. Powered by Open-Meteo. No API key, no signup, no SDK.

What you get

Two agent-callable tools. Ask in natural language and the model picks the right one:

Every current-condition answer carries the full field set:

• Temperature, apparent (feels-like) temperature, humidity, dew point

• UV index with its level (Low / Moderate / High / Very high / Extreme)

• Sunrise / sunset / daylight duration in the location's own timezone

• Wind: 16-point compass name + degrees + speed + gusts

• Precipitation, rain/showers/snowfall, cloud cover, pressure, WMO weather description

• Air quality: PM2.5, PM10, O₃, NO₂, SO₂, CO, US AQI and European AQI, each with its category

Every daily row carries: date + weekday, weather, min/max temperature, min/max feels-like, precipitation probability and amount, max UV + level, dominant wind, sunrise/sunset. Multi-day answers add a trend line (temperature range, wettest day, UV peak).

Related MCP server: Weather MCP Server

Use it with other agents (Claude Code, Codex, Cursor, Gemini CLI, …)

The weather logic is agent-agnostic; only the registration layer is DSH-specific. The same core serves every runtime, so behaviour cannot drift between them:

Grab the code once:

git clone https://github.com/whaoran1018-cmd/dsh-plugin-weather.git
# or install globally so `dsh-weather` / `dsh-weather-mcp` land on PATH:
npm i -g github:whaoran1018-cmd/dsh-plugin-weather

Claude Code

claude mcp add dsh-weather -- node /absolute/path/to/dsh-plugin-weather/bin/mcp-server.mjs

or commit a project-scoped .mcp.json:

{
  "mcpServers": {
    "dsh-weather": {
      "command": "node",
      "args": ["/absolute/path/to/dsh-plugin-weather/bin/mcp-server.mjs"],
      "env": { "WEATHER_LANG": "zh" }
    }
  }
}

Codex CLI

~/.codex/config.toml:

[mcp_servers.dsh-weather]
command = "node"
args = ["/absolute/path/to/dsh-plugin-weather/bin/mcp-server.mjs"]

Cursor / Windsurf / Cline

.cursor/mcp.json (or the equivalent settings file):

{
  "mcpServers": {
    "dsh-weather": { "command": "node", "args": ["/absolute/path/to/dsh-plugin-weather/bin/mcp-server.mjs"] }
  }
}

Gemini CLI

~/.gemini/settings.json:

{
  "mcpServers": {
    "dsh-weather": { "command": "node", "args": ["/absolute/path/to/dsh-plugin-weather/bin/mcp-server.mjs"] }
  }
}

Any agent that can run a command

dsh-weather 上海 --days 7
dsh-weather "New York" --units imperial --json | jq '.current.uvIndex'
dsh-weather --lat -6.21 --lon 106.85 --date 2026-10-07 --json

Then tell the agent about it (AGENTS.md / CLAUDE.md / system prompt):

For any weather question, run dsh-weather <city> --json (add --days N for a multi-day forecast) instead of guessing: it returns current conditions, a 3-day outlook and air quality.

OpenAI / Anthropic function calling

node bin/schemas.mjs openai      # or: anthropic | mcp | dsh
# ready-made: schema/openai-tools.json, schema/anthropic-tools.json

All surfaces take the same config through the environment: WEATHER_DEFAULT_LOCATION, WEATHER_LANG, WEATHER_UNITS, WEATHER_PROVIDER, plus WEATHER_TOOL_PREFIX to namespace MCP tool names (e.g. WEATHER_TOOL_PREFIX=weather_ → weather_get_weather).

Install

1. Via the DSH plugin manager (recommended)

Ask the agent (or use the Plugins page):

plugin_manager { "action": "install_bundle", "target": "github:whaoran1018-cmd/dsh-plugin-weather" }

The plugin manager installs the package, adds it to dsh.profile.bundles, and activates it. Reload/restart DSH once if the tools do not appear immediately (see Three DSH facts below).

2. Into an existing profile by hand

cd ~/.dsh/profiles/<profile>
pnpm add link:C:/path/to/dsh-plugin-weather      # or "file:", or a published version

Then add "dsh-plugin-weather" to dsh.profile.bundles in that profile's package.json. The package ships its own cordis.patch.yml, so the Loader inserts the plugin row automatically.

3. Copy-in (no package manager)

Copy the folder to ~/.dsh/profiles/<profile>/plugins/dsh-plugin-weather and append to the profile's cordis.patch.yml:

- insert:
    - id: weather
      name: 'dsh-plugin-weather'

Keep the folder out of dot-directories: DSH's watcher ignores **/.*.

Usage

Just ask:

• "What's the weather in Shanghai?" / "上海现在天气怎么样"

• "Is it going to rain this week in New York?" / "上海未来 7 天"

• "Air quality in Jakarta" / "雅加达空气好不好"

• "What time is sunrise tomorrow?" / "明天几点日出"

• "Hourly forecast for Oct 7" (the model passes date: "2026-10-07")

• "UV index at 31.23,121.47" (raw coordinates work too)

Each call returns two blocks: a human-readable summary (localised, with levels and emoji) and the complete JSON, so the model can reason about exact numbers.

Options

Plugin config

Set from the plugin settings UI, or in the profile's cordis.patch.yml under the row's config:

Languages

Summaries are localized — weather descriptions, all 16 compass points, UV levels, US/EU AQI categories, weekdays, every label, note and error message.

Pick one wherever it suits you:

• DSH plugin config: language: ja in the config block of the plugin row (or the settings UI).

• Per call: both tools accept language — get_weather { location: "上海", language: "de" }.

• MCP: WEATHER_LANG=es in the server's env.

• CLI: dsh-weather 上海 --lang ko.

Aliases work too (zh-CN, pt_BR, ES, …); anything unrecognized falls back to English. Machine-readable fields never change with the language: JSON keys stay English, and localized values always come with a stable key — uvLevel: { key: "low", label: "低" }, usAqiCategory: { key: "moderate", label: "中等" }, windDirection: { compass: "NNW", label: "西北偏北" }.

How it resolves things

• Location: explicit coordinates → location (city via Open-Meteo geocoding; "lat,lon" parsed directly) → configured defaultLocation → public IP (ipwho.is → freeipapi.com → ip-api.com). When the result came from IP, the answer says so — IP geolocation is city-level and can be skewed by VPN/proxy. City lookup is script-aware: Open-Meteo only finds "上海" with a CJK language and "서울" with Korean, so the plugin falls back across scripts (requested → en → zh → ja → ko) instead of returning "not found".

• Weather: Open-Meteo forecast API, with wttr.in as a fallback source (fewer fields, no air quality).

• Air quality: Open-Meteo Air Quality (CAMS).

• All HTTP goes through Node's built-in node:https with a timeout, one retry and a small TTL cache — no runtime HTTP dependency is bundled.

Development

dsh-plugin-weather/
├── lib/
│   ├── index.js      # plugin entry: name / inject / Config / apply
│   ├── tools.js      # the two ToolDefinitions (the schema subset matters!)
│   ├── service.js    # orchestration: resolve place → fetch → summarize
│   ├── geo.js        # coordinates, geocoding, IP fallback
│   ├── openmeteo.js  # forecast + air-quality providers, normalization
│   ├── wttr.js       # fallback provider
│   ├── format.js     # human-readable summary (locale templates)
│   ├── codes.js      # WMO weather codes, compass, UV/AQI levels (semantic layer)
│   ├── i18n.js       # locale registry, t(), alias resolution, English fallback
│   ├── locales/      # one catalog per language: en (reference) + 8 more
│   ├── http.js       # dependency-free JSON client (timeout/retry/cache)
│   ├── config.js     # schemastery config schema
│   └── harness.js    # load the tool definitions without DSH (MCP/CLI re-use)
├── bin/
│   ├── mcp-server.mjs # MCP stdio server (Claude Code, Codex, Cursor, Gemini, …)
│   ├── cli.mjs        # one-shot CLI (`dsh-weather 上海 --days 7 --json`)
│   └── schemas.mjs    # print tool schemas as openai / anthropic / mcp / dsh
├── schema/            # generated: openai-tools.json, anthropic-tools.json
├── test/
│   ├── selftest.mjs   # 213 checks: DSH contract + live data
│   ├── mcp-test.mjs   # drives the MCP server over real stdio JSON-RPC
│   ├── cli-test.mjs   # drives the CLI end to end
│   └── i18n-test.mjs  # locale parity (+ 9-language rendering), 171 checks
└── tools/
    ├── verify.ps1               # local install + verification helper
    ├── verify-schema-subset.mjs # runs DSH's REAL schema validator on our tools
    └── export-schemas.mjs       # regenerates schema/*.json

npm install                 # only dependency: @deepseek-ai/schemastery
npm test                    # offline contract test (no network)
npm run test:all            # offline: contract + MCP + CLI + locales + DSH schema validator
npm run test:live           # contract + MCP + CLI + locales against real Open-Meteo
npm run test:all:live       # everything above in one go
npm run export:schemas      # regenerate schema/openai-tools.json + anthropic-tools.json

Adding a language: copy lib/locales/en.js, translate the values (keep the keys, order and {placeholders}), add an import + the code to LANGUAGES in lib/i18n.js — test/i18n-test.mjs then verifies parity, value-table completeness and rendering for you.

Three DSH facts worth knowing (learned the hard way)

1. Tool schemas live in a narrow subset. Only type, oneOf, properties, required, additionalProperties, items, enum, const plus the annotations description, title, default, examples are accepted, and oneOf needs ≥ 2 branches. minimum / pattern / minLength make the whole plugin row fail activation with unsupported JSON schema: …. tools/verify-schema-subset.mjs runs the real validator, so this cannot regress silently. (MCP clients accept richer schemas — the shared subset simply keeps one definition valid everywhere.)

2. Editing a host plugin's code does not hot-reload in a running desktop profile (verified: a changed default stayed unchanged until the process reloaded, while pointing the patch at a new URL took effect immediately — module cache, not code). Reload/restart DSH after editing lib/. The MCP and CLI surfaces have no such cache: they run the files on disk.

3. Do not declare @deepseek-ai/dsh-* peer dependencies unless you pin them to the exact running version. DSH's compatibility gate compares those peers with the runtime version and will refuse to install the plugin otherwise. This package declares no DSH peers (only @deepseek-ai/schemastery, which the gate ignores) and relies on the injected tools service.

License and data attribution

Code: MIT.

Data sources — please keep the attribution when you publish or redistribute:

• Weather, forecast, geocoding: Open-Meteo — free for non-commercial use, CC BY 4.0

• Air quality: Open-Meteo Air Quality API (CAMS)

• Fallback weather: wttr.in

• IP location: ipwho.is, freeipapi.com, ip-api.com

Respect each provider's terms and rate limits; identical requests are cached for 5 minutes by default.

中文说明见 README.zh-CN.md。