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:
| Tool | What it returns |
|---|
get_weather | Current conditions + air quality, plus a 3-day outlook by default (days: 0 for current only) |
get_weather_forecast | 1–16 day daily forecast; optional hourly rows (next 48 h, or exactly one chosen date) |
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).
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:
| Surface | Entry point | Works with |
|---|
| DSH plugin | cordis.patch.yml + lib/index.js | DeepSeek Harness (this plugin's origin) |
| MCP server (stdio) | bin/mcp-server.mjs | Claude Code, Codex CLI, Cursor, Windsurf, Gemini CLI, Cline, Zed, ChatGPT desktop, DSH — anything that speaks MCP |
| One-shot CLI | bin/cli.mjs (dsh-weather) | Any agent that can run a shell command (Aider, Codex exec, Claude Code's Bash tool, CI, cron, you) |
| Tool schemas | bin/schemas.mjs, schema/*.json | OpenAI / Anthropic / any function-calling framework |
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
| Parameter | Applies to | Notes |
|---|
location | both | City name (Chinese or English) or "lat,lon". Falls back to config defaultLocation, then public-IP location. |
latitude / longitude | both | Explicit coordinates; take precedence over location. |
units | both | metric (°C / km/h / mm) or imperial (°F / mph / inch). |
includeAirQuality | both | Defaults to the plugin config (true). |
days | both | 0–16. get_weather defaults to 3, get_weather_forecast to 5. |
includeHourly | forecast | Hourly rows from now, capped at 48. |
date | forecast | YYYY-MM-DD. Returns that day's 24 hourly rows; auto-widens the window to 16 days when needed. |
Plugin config
Set from the plugin settings UI, or in the profile's cordis.patch.yml under the row's config:
| Key | Default | Meaning |
|---|
defaultLocation | "" | Used when no location is given. Empty = public-IP lookup. |
language | en | Summary language — see Languages. |
units | metric | metric or imperial. |
includeAirQuality | true | Attach the air-quality block. |
cacheTtlSeconds | 300 | Local cache for identical requests; 0 disables. |
requestTimeoutMs | 15000 | Per-request upstream timeout. |
provider | auto | auto falls back to wttr.in if Open-Meteo fails; open-meteo never falls back. |
Languages
Summaries are localized — weather descriptions, all 16 compass points, UV levels, US/EU AQI categories,
weekdays, every label, note and error message.
| Code | Language | Code | Language | Code | Language |
|---|
zh | 中文 | ko | 한국어 | it | Italiano |
en | English (default) | pt | Português | fr | Français |
es | Español | ja | 日本語 | de | Deutsch |
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)
- 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.)
- 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.
- 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:
Respect each provider's terms and rate limits; identical requests are cached for 5 minutes by default.
中文说明见 README.zh-CN.md。
