> **Disclaimer:** This is an independent, community-built project and is
> **not affiliated with, endorsed by, or supported by KegLand or
> RAPT.io**. RAPT, RaptPill, and KegLand are trademarks of their
> respective owners, referenced here solely to describe compatibility.
> This software is provided **as is**, with no warranty of any kind — see
> [`LICENSE`](./LICENSE) for full terms, including an additional
> plain-language disclaimer specific to this project's use of an
> unsupported third-party API.

# RAPT.io MCP Server

An MCP (Model Context Protocol) server for monitoring and controlling
KegLand RAPT devices — Fermentation Chambers and RaptPill hydrometers —
via the RAPT.io API.

> ⚠️ **Read-only by default.** The RAPT.io API is unsupported and
> undocumented for most mutating operations (see
> [Security & API usage notes](#security--api-usage-notes) below). This
> server refuses all `POST` requests to the RAPT.io API unless an
> operator explicitly opts in via `RAPTIO_MCP_READ_ONLY=false`.

## Features

### Fermentation Chamber

- List all fermentation chambers
- Get status (temperature, heating/cooling, PID, run times)
- Get telemetry history
- *(when `RAPTIO_MCP_READ_ONLY=false`)* Set target temperature, enable/disable PID, configure PID parameters

### RaptPill (Hydrometer)

- List all RaptPills
- Get status (gravity, temperature, battery level)
- Get telemetry history

### General

- List all bonded devices
- Manage/view fermentation profiles

> Several previously-available control tools (heating/cooling/fan/light
> toggles, hysteresis, compressor/mode-switch delay) have been **removed**
> pending verification of the underlying API endpoint. See
> [Removed tools](#removed-tools) below.

## Installation

### Requirements

- Python 3.11+
- [uv](https://docs.astral.sh/uv/) (recommended) or pip

### With uv

```bash
uv sync --frozen
```

### With pip

```bash
pip install -e .
```

## Authentication

This server authenticates to the RAPT.io API using your RAPT.io **username**
and an **API Secret** (not your account password).

1. Log in to the [RAPT Portal](https://app.rapt.io).
2. Navigate to **My Account → API Secrets**
   (<https://app.rapt.io/account/apisecrets>).
3. Click **Add API Secret** and record the value immediately — it is
   hashed server-side and cannot be retrieved again later.

> Do **not** use your actual account password for `RAPT_API_SECRET`. The
> API Secret is a separate, independently revocable credential — if it
> leaks, you can rotate it from the portal without touching your real
> account login.

## Configuration

Set the following environment variables:

| Variable | Required | Default | Description |
|---|---|---|---|
| `RAPT_USERNAME` | yes | — | RAPT.io account email |
| `RAPT_API_SECRET` | yes | — | API Secret generated at [app.rapt.io/account/apisecrets](https://app.rapt.io/account/apisecrets) |
| `RAPTIO_MCP_AUTH_TOKEN` | yes | — | Shared-secret bearer token that MCP clients must send as `Authorization: Bearer <token>` |
| `RAPTIO_MCP_READ_ONLY` | no | `true` | When `true` (default), all mutating (`set_*`) tool calls are refused before reaching the RAPT.io API. Set to `false` to allow the documented mutating endpoints (see [Security & API usage notes](#security--api-usage-notes)) |
| `RAPTIO_MCP_ALLOWED_HOSTS` | recommended | *(unset — validation disabled)* | Comma-separated list of allowed `Host` header values (DNS-rebinding protection) |
| `RAPTIO_MCP_ALLOWED_ORIGINS` | recommended | *(unset — validation disabled)* | Comma-separated list of allowed `Origin` header values |
| `RAPTIO_MCP_HOST` | no | `0.0.0.0` | Bind address |
| `RAPTIO_MCP_PORT` | no | `8000` | Bind port |
| `RAPTIO_MCP_LOG_LEVEL` | no | `INFO` | Python logging level |

## Usage

### Run directly (Streamable HTTP)

```bash
RAPT_USERNAME="you@example.com" \
RAPT_API_SECRET="your-api-secret" \
RAPTIO_MCP_AUTH_TOKEN="$(openssl rand -hex 32)" \
  uv run raptio-mcp
```

The server listens on `http://<RAPTIO_MCP_HOST>:<RAPTIO_MCP_PORT>/mcp`
(Streamable HTTP transport, stateless, JSON responses). All requests to
`/mcp` require the bearer token above. `/healthz` is unauthenticated and
intended for orchestrator liveness/readiness probes.

### Connecting an MCP client

Configure your MCP client to use the Streamable HTTP transport, e.g.:

```bash
claude mcp add --transport http raptio http://localhost:8000/mcp \
  --header "Authorization: Bearer <your RAPTIO_MCP_AUTH_TOKEN>"
```

> Earlier versions of this server used the stdio transport (for local
> subprocess use with Claude Desktop/Claude Code). As of `0.2.0` the
> server runs exclusively over Streamable HTTP, which requires the bearer
> token above — there is no longer an implicit trust boundary from
> process ownership, so authentication is mandatory.

## Available Tools

| Tool | Description | Mode |
|---|---|---|
| `get_bonded_devices` | List all bonded devices | read-only |
| `get_bonded_device` | Get a single device | read-only |
| `get_bonded_device_telemetry` | Get device telemetry | read-only |
| `get_fermentation_chambers` | List all fermentation chambers | read-only |
| `get_fermentation_chamber` | Get chamber status | read-only |
| `get_fermentation_chamber_telemetry` | Get chamber temperature history | read-only |
| `set_fermentation_chamber_temperature` | Set target temperature | mutating — requires `RAPTIO_MCP_READ_ONLY=false` |
| `set_fermentation_chamber_pid_enabled` | Enable/disable PID control | mutating — requires `RAPTIO_MCP_READ_ONLY=false` |
| `set_fermentation_chamber_pid` | Configure PID parameters | mutating — requires `RAPTIO_MCP_READ_ONLY=false` |
| `get_hydrometers` | List all RaptPills | read-only |
| `get_hydrometer` | Get RaptPill status | read-only |
| `get_hydrometer_telemetry` | Get gravity/temperature history | read-only |
| `get_profiles` | List all fermentation profiles | read-only |
| `get_profile` | Get profile details | read-only |
| `get_profile_types` | List available profile types | read-only |

While `RAPTIO_MCP_READ_ONLY=true` (default), the three mutating tools are
still listed (so their schemas remain discoverable) but every call
returns an explicit error instead of reaching the RAPT.io API.

### Removed tools

The following tools existed in earlier versions but have been **removed**
pending verification:

- `set_fermentation_chamber_heating_enabled`
- `set_fermentation_chamber_cooling_enabled`
- `set_fermentation_chamber_fan_enabled`
- `set_fermentation_chamber_light_enabled`
- `set_fermentation_chamber_cooling_hysteresis`
- `set_fermentation_chamber_heating_hysteresis`
- `set_fermentation_chamber_compressor_delay`
- `set_fermentation_chamber_mode_switch_delay`

They all relied on `POST /api/FermentationChambers/UpdateFermentationChamber`,
an endpoint that does **not** appear in RAPT.io's published API
specification (<https://api.rapt.io/swagger/v1/swagger.json>) and has no
documented concurrency behavior. They will be reinstated only after the
endpoint's existence and safety have been confirmed against a live
account. (`set_fermentation_chamber_light_enabled` also previously sent
incorrect enum values — `On`/`Off`/`Auto` instead of the correct
`AlwaysOn`/`AlwaysOff`/`Automatic` — and will need that fix applied
before reinstatement too.)

## Security & API usage notes

The RAPT.io public API is explicitly described by KegLand as
**unsupported**:

> "Access to the Api is unsupported. This means you will not get
> assistance from KegLand with regards to any issues you may encounter
> while using the Api... if you destroy a device through misuse of the
> Api, it will void your warranty... The Api (endpoints, parameters,
> response models etc.) is subject to change without notice."
> — <https://docs.rapt.io/integrations/api-secrets>

Given this, the server defaults to a conservative posture:

- **Read-only by default** (`RAPTIO_MCP_READ_ONLY=true`) — no request
  that could change device state is sent unless explicitly enabled.
- **Only officially-documented endpoints are used** for mutations —
  `SetTargetTemperature`, `SetPIDEnabled`, `SetPID` — all confirmed
  present in RAPT.io's own published Swagger spec.
- **Undocumented endpoints are not used** — see [Removed tools](#removed-tools).
- **Authentication is mandatory** on the HTTP transport (`RAPTIO_MCP_AUTH_TOKEN`),
  since Streamable HTTP removes the implicit trust boundary that the
  previous stdio-subprocess model provided for free.
- **All mutating tool calls are audit-logged** (tool name, arguments,
  outcome) to the server's structured logs.

If you choose to set `RAPTIO_MCP_READ_ONLY=false`, you are opting into
sending commands to physical brewing/fermentation hardware over an
API that KegLand may change or restrict without notice, and any damage
or account restriction resulting from that use is your responsibility
per KegLand's own terms above.

## Authentication flow details

Internally, the server exchanges your `RAPT_USERNAME` and
`RAPT_API_SECRET` for a short-lived bearer token via OAuth2 Resource
Owner Password Credentials grant against `https://id.rapt.io/connect/token`,
per RAPT.io's documented flow. Tokens are cached in memory and refreshed
automatically ~30 seconds before expiry.

## License

MIT