# bridgemcp-server-weather

[![CI](https://github.com/Arsie-codes/bridgemcp-server-weather/actions/workflows/ci.yml/badge.svg)](https://github.com/Arsie-codes/bridgemcp-server-weather/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/bridgemcp-server-weather.svg)](https://pypi.org/project/bridgemcp-server-weather/)
[![Python](https://img.shields.io/pypi/pyversions/bridgemcp-server-weather.svg)](https://pypi.org/project/bridgemcp-server-weather/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

The official BridgeMCP reference server — weather data via [Open-Meteo](https://open-meteo.com/).

**No API key required.**

This server demonstrates the recommended architecture for production-quality BridgeMCP servers. It is the first official server in the BridgeMCP ecosystem and is intended as a reference for all future official servers.

---

## Tools

| Tool | Description |
|------|-------------|
| `get_current_weather` | Current temperature, humidity, wind, precipitation, and conditions |
| `get_forecast` | Multi-day forecast (1–16 days) with highs/lows, precipitation, and sunrise/sunset |
| `get_weather_summary` | Plain-language summary optimized for AI context windows |

All tools accept:
- City name: `"London"`
- City + country: `"Paris, France"`
- Coordinates: `"51.5074,-0.1278"`

---

## Installation

```bash
pip install bridgemcp-server-weather
```

For running as an MCP server (required for `bridgemcp-weather` CLI):

```bash
pip install 'bridgemcp-server-weather[mcp]'
```

---

## Usage

### As an MCP server (stdio — for Claude Desktop, Cursor, etc.)

```bash
bridgemcp-weather
```

### As an MCP server (HTTP/SSE — for network clients)

```bash
bridgemcp-weather --http
bridgemcp-weather --http --host 0.0.0.0 --port 9000
```

### Programmatic use

```python
from bridgemcp_weather import create_app

app = create_app()

# Call tools directly (useful in tests and scripts)
result = await app.acall("get_current_weather", location="Tokyo")
print(result["temperature_c"])  # 22.5

# Run as MCP server
app.run()
```

### Claude Desktop configuration

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "weather": {
      "command": "bridgemcp-weather"
    }
  }
}
```

---

## Architecture

This server is the reference implementation for BridgeMCP server architecture.

```
bridgemcp_weather/
├── __init__.py       # Public API: create_app, WeatherPlugin
├── _version.py       # Single version source of truth
├── server.py         # BridgeMCP app + WeatherPlugin + CLI entry point
├── client.py         # Pure async HTTP layer (no BridgeMCP types)
├── geocoding.py      # Open-Meteo geocoding (city name → lat/lon)
├── models.py         # Pydantic models + WMO code descriptions
└── exceptions.py     # WeatherError, WeatherAPIError, GeocodingError
```

### Key design decisions

**`WeatherPlugin` owns the httpx client lifecycle.**
The `httpx.AsyncClient` is opened in `on_startup` and closed in `on_shutdown`. This is the correct BridgeMCP pattern for any plugin that owns async resources. The client is never a module-level global.

**Tools are registered in `WeatherPlugin.setup()` (synchronously).**
The BridgeMCP adapter builds the MCP server before startup hooks run. All tools must be registered before `app.run()` is called. `setup()` is the correct place.

**The HTTP layer contains no BridgeMCP types.**
`client.py` and `geocoding.py` accept an `httpx.AsyncClient` and raise `WeatherError` subclasses. They know nothing about BridgeMCP, `InvocationContext`, or MCP protocol types. This makes the HTTP layer independently testable and reusable.

**Tools return `dict` from `model.model_dump()`.**
Tools never return JSON strings. Pydantic models are dumped to dicts at the tool boundary, preserving type information for BridgeMCP's schema generation.

---

## Development

```bash
git clone https://github.com/Arsie-codes/bridgemcp-server-weather
cd bridgemcp-server-weather
pip install -e '.[dev]'

# Run tests
pytest tests/ -v

# Lint and format
ruff check bridgemcp_weather tests
black bridgemcp_weather tests
pyright bridgemcp_weather
```

---

## Ecosystem

| Package | Description |
|---------|-------------|
| [bridgemcp-py](https://pypi.org/project/bridgemcp-py/) | The BridgeMCP framework |
| [bridgemcp-logging](https://pypi.org/project/bridgemcp-logging/) | Official logging plugin |
| bridgemcp-server-weather | This package — official weather reference server |

---

# Official BridgeMCP Ecosystem

## Framework

- **BridgeMCP**
  https://github.com/Arsie-codes/bridgemcp

## Official Plugins

- **bridgemcp-logging**
  https://github.com/Arsie-codes/bridgemcp-logging

## Official Servers

- **bridgemcp-server-weather**
  https://github.com/Arsie-codes/bridgemcp-server-weather

More official plugins and servers are currently under development.

## License

MIT — see [LICENSE](LICENSE).