jarvis-mcp-server

Standalone MCP server(s) for Jarvis. It currently hosts a time server (in the time_server/ package) that reports the current local time for a city, and is structured to grow more tool domains over time — each added as its own package alongside time_server/.

Unlike a stdio MCP server (which a client launches as a subprocess), it runs as an independent network process over Streamable HTTP, so it has its own lifecycle and can be reached by the MCP Inspector, a CLI client, or a Cloud Run deployment.

Tools

| Tool | Args | Returns | |---|---|---| | get_current_time | city: str | Current local time + timezone for the city | | get_weather_digest | period: str (e.g. 24h, 7d), city: str (default Tokyo) | Aggregated weather digest for a city (JSON) | | get_weather_readings | city: str (default Tokyo), period: str (≤ 7 days) | Compact per-day weather report (JSON) — input to the anomaly pipeline | | detect_weather_anomalies | weather_report: str (a get_weather_readings report) | Deterministic anomaly report (JSON) | | send_telegram_alert | anomaly_report: str (a detect_weather_anomalies report), notify_when_clear: bool (default false) | Sends a Telegram alert if anomalies exist; with notify_when_clear=true also sends an "all clear" message when none (JSON result) | | add_city | city: str | Start collecting weather for a city; returns the tracked-city list | | remove_city | city: str | Stop collecting a city (its history is kept); returns the tracked-city list | | list_cities | — | The cities currently being collected | | echo | text: str | The input unchanged (connectivity smoke-test) |

get_current_time is a two-hop pipeline: Open-Meteo geocoding (city → lat/lon) → TimeAPI.io (lat/lon → local time). Both APIs are free and need no key. If the network is unavailable it falls back to the system UTC clock, so a call never hard-fails.

Tokyo weather digest (a scheduled agent)

The weather_digest/ package runs a continuous agent: while the server is up, a background thread collects the current weather once an hour for every tracked city (Open-Meteo, with a mock fallback when offline) and stores each reading in SQLite (weather_measurements table). The scheduler starts with the server (via the ASGI lifespan) and stops cleanly on shutdown — it runs independently of any tool call.

Tracked cities are managed at runtime. Tokyo is tracked by default; add_city / remove_city / list_cities change the set live (no restart). add_city does one immediate collection so a new city has data right away; remove_city only stops future collection — the city's stored history is preserved (re-adding resumes with it intact). The set is persisted in a tracked_cities table, so it survives restarts.

get_weather_digest(period, city) aggregates the stored readings over a window (city defaults to Tokyo):

{
  "city": "Tokyo", "period": "24h", "sample_count": 36,
  "average_temperature": 19.0, "min_temperature": 12.7, "max_temperature": 24.1,
  "most_common_condition": "overcast", "rainfall_occurrences": 7,
  "temperature_trend": "rising",
  "window_start": "...", "window_end": "..."
}

On a fresh/empty database the store auto-seeds 7 days of realistic hourly mock readings (multiple conditions, rainfall, diurnal temperature swing), so a digest is demoable immediately — before the hourly scheduler has collected anything live.

| Env var | Default | Purpose | |---|---|---| | WEATHER_DB_PATH | weather_digest/weather.db | SQLite file location | | WEATHER_CITY | Tokyo | Default city (always tracked + seeded); add more via add_city | | WEATHER_COLLECT_INTERVAL_S | 3600 | Seconds between collections (lower for demos) |

Cloud Run note: with --min-instances 0 the service scales to zero when idle, so the hourly collection only runs while an instance is alive. The seed data keeps the digest meaningful regardless; set --min-instances 1 for uninterrupted hourly collection.

Weather-anomaly pipeline (three chained tools)

A realistic workflow built from three tools the LLM chains automatically:

get_weather_readings → detect_weather_anomalies → send_telegram_alert

"Analyze Tokyo weather for the last week. If unusual weather conditions are detected, send a Telegram alert."

get_weather_readings(city, period) reads the stored measurements and rolls

them up server-side into a compact per-day report (mean/min/max temperature and rainy fraction per UTC day). The raw rows never leave the server, so the data the model relays to the next tool stays tiny. period is capped at 7 days.

detect_weather_anomalies(weather_report) applies deterministic rules to

that report and lists any anomalies. It accepts only a get_weather_readings report — a raw-readings array, a missing marker, too many day-buckets, or an oversized payload are rejected in code (not just by the prompt), so a large array can never be relayed in. Rules (thresholds overridable via ANOMALY_* env vars):

| Anomaly | Trigger | Default | |---|---|---| | rapid_temperature_rise / _drop | max/min day-over-day mean Δ | ±6 °C | | high_temperature_variability | window max − min | 18 °C | | high_rainfall_frequency | mean daily rainy fraction | 40 % | | unusually_dry | mean daily rainy fraction (≥ 3 days) | 5 % | | prolonged_bad_weather | consecutive mostly-rainy days | 3 days | | warming_trend / cooling_trend | first-half vs second-half mean Δ | ±4 °C |

send_telegram_alert(anomaly_report, notify_when_clear=false) sends a

Telegram message only if anomalies were found (otherwise it skips). Pass notify_when_clear=true to also send a reassuring "all clear" message when no anomalies were detected — handy for a scheduled all-is-well check-in. If Telegram is not configured it reports that without failing. Uses the Telegram Bot API over stdlib urllib (no new dependency); the bot token is never logged or returned.

| Env var | Default | Purpose | |---|---|---| | TELEGRAM_BOT_TOKEN | _(unset)_ | Bot token from @BotFather. Unset → sends are skipped with not configured. | | TELEGRAM_CHAT_ID | _(unset)_ | Chat/channel id to deliver alerts to. | | ANOMALY_* | _(rule defaults)_ | Override any threshold above, e.g. ANOMALY_RAPID_TEMP_DELTA_C=8. |

To get a TELEGRAM_CHAT_ID: message your bot, then open https://api.telegram.org/bot<token>/getUpdates and read result[].message.chat.id.

Run locally

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python -m time_server.server          # serves http://0.0.0.0:8080/mcp

Configuration (env vars)

| Var | Default | Purpose | |---|---|---| | HOST | 0.0.0.0 | Bind address | | PORT | 8080 | Bind port (Cloud Run injects this) | | TRANSPORT | streamable-http | streamable-http \| sse \| stdio | | MCP_API_KEY | _(unset)_ | If set, every request (except /healthz) must send a matching X-API-Key. Unset → open server (local/Inspector only). | | LOG_LEVEL | INFO | Server log verbosity |

Security

Auth: set MCP_API_KEY; clients must send it as the X-API-Key header.

Comparison is constant-time and the key is never logged. Leaving it unset logs a loud warning and runs the server open — fine for local Inspector testing, never for a public deployment.

Health: GET /healthz is unauthenticated (for Cloud Run / curl probes).

Test with the MCP Inspector

In a second terminal (server still running):

npx @modelcontextprotocol/inspector

In the Inspector UI:

Transport Type: Streamable HTTP
URL: http://localhost:8080/mcp
Connect → open the Tools tab → run get_current_time with city = London.

Automated checks

python tests/smoke_http.py      # end-to-end over Streamable HTTP (server must be up)
pytest -q                       # offline unit tests (no network, no server)

Deployment

See DEPLOY.md for the Cloud Run build/deploy commands, secret setup, and how scaling / cold starts work.

Roadmap

[x] Standalone Streamable HTTP server + tools (get_current_time, get_weather_digest)
[x] Scheduled weather-digest agent (hourly collection → SQLite → aggregation)
[x] Runtime-managed multi-city collection (add_city / remove_city / list_cities)
[x] Weather-anomaly pipeline (get_weather_readings → detect_weather_anomalies → send_telegram_alert)
[x] Local test via MCP Inspector
[x] JarvisCLI client wired (auth-aware, degrades cleanly when down/unauthorized)
[x] API-key auth middleware (pure-ASGI, constant-time, /healthz exempt)
[x] Dockerfile (slim, non-root, port 8080)
[x] Cloud Run deploy guide

Jarvis MCP Server