# AIoT MCP Server

Artificial intelligence Internet of Things (AIoT) is a new paradigm of IoT. It is a combination of artificial intelligence and IoT.

MQTT is particularly well-suited for AIoT networks for several key reasons:

1. Its publish/subscribe pattern allows for flexible, decoupled communication between AI agents and IoT devices
2. The lightweight protocol minimizes network overhead, perfect for resource-constrained IoT devices
3. Topic-based hierarchical structure enables natural organization of device groups and capabilities
4. Retained messages maintain device state, allowing AI agents to quickly understand system context
5. Last Will and Testament (LWT) feature helps detect offline devices automatically

This repo demonstrates a MCP server which fetches device context from MQTT broker for MCP client to use.

## AIoT Agent Network Protocol

Agents MUST use the following MQTT topic convention:

- `$ai/{DOMAIN}/{GROUP}/d/{DEVICE_ID}`: Topic pattern for device registration and discovery
- `$ai/{DOMAIN}/{GROUP}/r/{RULE_ID}`: Topic pattern for rule registration and discovery

Agents MUST register clients or rules as retained messages on the corresponding topics.
Agents MUST use readable text to describe the device or rule.
Agents MAY use natural language to describe the device or rule.

This is ALL.

<img width="736" alt="image" src="https://github.com/user-attachments/assets/8f42b23a-d1ae-4aa0-9486-a79c00efda73" />


## Prompt

The assistant's prompt is defined in `assistant-prompt.md`. This file contains the instructions and capabilities given to the AI assistant for interacting with IoT devices through MQTT.

## Tools

### Discover

Discovers devices and rules in a group using MQTT topic filter. When querying the status of a group, provide the device GROUP as the argument.

Example request:
```json
{
  "group": "room1"
}
```

Example response:
```json
[
  {
    "topic": "$ai/room1/123",
    "message": "I am a temperature sensor..., I publish ... to topic room1/123/status"
  },
  {
    "topic": "$ai/room1/456",
    "message": "I am an air conditioner..., I subscribe to topic room1/456/command, expect payload to be on/off"
  }
]
```

### Publish

Publishes a message to a device using MQTT topic and payload.

Example request:
```json
{
  "topic": "room1/456/command",
  "payload": "on",
  "qos": 0,
  "retain": false
}
```

### Query

Queries a specific topic for its current state.

Example request:
```json
{
  "topic": "room1/123/status"
}
```

## Configuration

The server can be configured using environment variables:

- `MQTT_BROKER_URL`: MQTT broker URL (default: mqtt://127.0.0.1:1883)
- `MQTT_USERNAME`: MQTT username (optional)
- `MQTT_PASSWORD`: MQTT password (optional)

## Running The Server

Claude Desktop configuration:

```json
{
  "mcpServers": {
    "aiot": {
      "command": "npx",
      "args": [ "tsx", "/path/to/this/repo/src/index.ts" ]
    }
  }
}
```