halton-iot-mcp-server/README.md

MCP Server for Halton IoT Data API - run with npx or Docker

# Halton IoT MCP Server

An MCP (Model Context Protocol) server for the [Halton IoT Data API](https://api.halton.io/index.html). This server allows AI assistants to interact with Halton's IoT systems, retrieving sensor data, system information, and more.

## 🚀 Quick Start

### One-Command Setup

```bash
npx @haltongroup/halton-iot-mcp-setup
```

This will prompt for your API token (from [api.halton.io](https://api.halton.io)) and configure VS Code automatically.

### Or Manual Setup (VS Code UI)

1. **Cmd/Ctrl+Shift+P** → **"MCP: Add Server"**
2. Select **Docker** as the type
3. Enter image: `ghcr.io/haltongroup/haltoniotmcp:latest`
4. Add env var: `HALTON_API_TOKEN` = your token from [api.halton.io](https://api.halton.io)

---


## Features

- 🔌 **System Discovery**: List and inspect IoT systems
- 📊 **Time Series Data**: Get aggregated sensor data (hourly default)
- 🔍 **Variable Search**: Search for specific sensors/variables

## Available Tools

| Tool | Description |
|------|-------------|
| `get_all_systems` | Get information about all accessible IoT systems |
| `get_systems` | Get information about specific systems |
| `get_system_variables` | List all variables (sensors) for systems |
| `search_variables` | Search for variables by keywords |
| `get_aggregate_data` | Get aggregated time series data (min/max/avg, hourly default) |
| `get_aggregate_data_multiple` | Get aggregated data for multiple variables |
| `get_last_value` | Get the most recent value for a variable |
| `get_last_values_multiple` | Get recent values for multiple variables |

## Example Questions

Once connected, ask GitHub Copilot:
- "What Halton systems do I have access to?"
- "Show me the airflow data for the last 24 hours"
- "What's the current UV lamp status?"
- "List all sensors on Hood 1"

---


## Alternative Setup Methods

### Per-Project Config

Create `.vscode/mcp.json` in your project:

```json
{
  "servers": {
    "halton-iot": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "HALTON_API_TOKEN", "ghcr.io/haltongroup/haltoniotmcp:latest"],
      "env": {
        "HALTON_API_TOKEN": "your-token-here"
      }
    }
  }
}
```

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "halton-iot": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "HALTON_API_TOKEN", "ghcr.io/haltongroup/haltoniotmcp:latest"],
      "env": {
        "HALTON_API_TOKEN": "your-token-here"
      }
    }
  }
}
```

### Docker MCP Gateway

See [DOCKER_MCP.md](DOCKER_MCP.md) for Docker MCP Gateway setup.

---


## Development

#### Build and run with Docker:

```bash
# Build the Docker image
docker build -t halton-iot-mcp .

# Run directly
docker run -e HALTON_API_TOKEN="your-token" halton-iot-mcp
```

#### Configure with Docker MCP:

1. Build and tag the image:
```bash
docker build -t halton-iot-mcp:latest .
```

2. Create a local catalog entry (`~/.docker/mcp/catalogs/custom.yaml`):
```yaml
servers:
  halton-iot:
    name: "Halton IoT"
    description: "Access Halton IoT systems and sensor data"
    image: halton-iot-mcp:latest
    secrets:
      - name: HALTON_API_TOKEN
        description: "Halton IoT API Token"
```

3. Enable the server:
```bash
docker mcp catalog add custom ~/.docker/mcp/catalogs/custom.yaml
docker mcp server enable halton-iot
```

4. Configure the secret:
```bash
docker mcp secret set halton-iot HALTON_API_TOKEN "your-token"
```

5. Run the gateway:
```bash
docker mcp gateway run
```

## Example Queries

Once connected, you can ask the AI assistant things like:

- "List all available IoT systems"
- "What sensors are available on system FI02728?"
- "Get the temperature readings for the last 24 hours from system US02145"
- "Show me the airflow data aggregated by hour"
- "What was the last recorded value for ConnectionStatus?"

## API Reference

This MCP server wraps the [Halton IoT API v2](https://api.halton.io/index.html). For detailed API documentation, refer to:

- Swagger UI: https://api.halton.io/index.html
- OpenAPI Spec: http://api.halton.io/v2/swagger.json

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Watch mode (rebuild on changes)
npm run dev
```

## License

MIT