From bf4b0e2f5276f4ff4b599d5d793b7170df52a7c3 Mon Sep 17 00:00:00 2001
From: Ryan Malloy <ryan@supported.systems>
Date: Wed, 17 Sep 2025 07:08:15 -0600
Subject: [PATCH] Replace code examples with actual MCP tool interfaces

- Update 'Embedded Broker Management' to show mqtt_spawn_broker tool call
- Replace 'MQTT Client Integration' with real MCP tool examples
- Add Configuration Options section emphasizing MCP tools as primary interface
- Show practical tool calls instead of unused Python code examples
- Clarify that MCP clients control broker and connection management
---
 README.md | 121 ++++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 99 insertions(+), 22 deletions(-)

diff --git a/README.md b/README.md
index 8b9de03..d9dcba9 100644
--- a/README.md
+++ b/README.md
@@ -72,6 +72,34 @@ claude mcp add task-buzz -- uvx mcmqtt
 claude mcp test task-buzz
 ```
 
+## ⚙️ Configuration Options
+
+**Primary Interface: MCP Tools** - mcmqtt is designed for MCP clients to manage connections and brokers dynamically via tool calls.
+
+### Optional CLI & Environment Configuration
+
+For startup configuration (when MCP clients need default connectivity):
+
+**CLI Options:**
+```bash
+uvx mcmqtt --transport stdio          # Default: STDIO mode for MCP
+uvx mcmqtt --transport http           # HTTP mode for web integration
+uvx mcmqtt --mqtt-host broker.local   # Connect to existing broker
+uvx mcmqtt --auto-connect             # Auto-connect on startup
+```
+
+**Environment Variables:**
+```bash
+export MQTT_BROKER_HOST="mqtt.example.com"
+export MQTT_BROKER_PORT="1883"
+export MQTT_CLIENT_ID="mcmqtt-server"
+export MQTT_USERNAME="user"
+export MQTT_PASSWORD="pass"
+uvx mcmqtt  # Uses environment config
+```
+
+**MCP clients control everything else** - broker spawning, connections, subscriptions, and message handling via tool calls.
+
 ## 🛠️ Core Features
 
 ### 🏃‍♂️ FastMCP MQTT Tools
@@ -86,37 +114,86 @@ claude mcp test task-buzz
 
 ### 🔧 Embedded Broker Management
 
-```python
-from mcmqtt.broker import BrokerManager
+**MCP clients can spawn MQTT brokers on-demand using the `mqtt_spawn_broker` tool:**
 
-# Spawn a broker programmatically
-manager = BrokerManager()
-broker_info = await manager.spawn_broker(
-    name="my-broker",
-    port=1883,
-    max_connections=100
-)
-
-print(f"Broker running at: {broker_info.url}")
+```bash
+# MCP Tool Call Example
+{
+  "tool": "mqtt_spawn_broker",
+  "arguments": {
+    "name": "agent-coordination-broker",
+    "port": 1883,
+    "host": "127.0.0.1",
+    "max_connections": 100,
+    "websocket_port": 9001
+  }
+}
 ```
 
+**Response:**
+```json
+{
+  "broker_id": "agent-coordination-broker-1726567890",
+  "host": "127.0.0.1",
+  "port": 1883,
+  "websocket_port": 9001,
+  "status": "running",
+  "mqtt_url": "mqtt://127.0.0.1:1883",
+  "websocket_url": "ws://127.0.0.1:9001"
+}
+```
+
+**Instant broker spawning** - no Docker, no setup, just call the tool and get a running MQTT broker!
+
 ### 📡 MQTT Client Integration
 
-```python
-from mcmqtt.mqtt import MQTTClient
-from mcmqtt.mqtt.types import MQTTConfig
+**Connect to any MQTT broker using MCP tools:**
 
-config = MQTTConfig(
-    broker_host="localhost",
-    broker_port=1883,
-    client_id="my-client"
-)
+```bash
+# Connect to broker
+{
+  "tool": "mqtt_connect",
+  "arguments": {
+    "broker_host": "mqtt.example.com",
+    "broker_port": 1883,
+    "client_id": "my-agent",
+    "username": "user",
+    "password": "pass"
+  }
+}
 
-client = MQTTClient(config)
-await client.connect()
-await client.publish("sensors/temperature", "23.5")
+# Publish messages 
+{
+  "tool": "mqtt_publish",
+  "arguments": {
+    "topic": "sensors/temperature",
+    "payload": "23.5",
+    "qos": 1,
+    "retain": false
+  }
+}
+
+# Subscribe to topics
+{
+  "tool": "mqtt_subscribe",
+  "arguments": {
+    "topic": "sensors/+",
+    "qos": 1
+  }
+}
+
+# Get messages
+{
+  "tool": "mqtt_get_messages",
+  "arguments": {
+    "topic": "sensors/temperature",
+    "limit": 10
+  }
+}
 ```
 
+**Zero coding required** - just call MCP tools and coordinate with any MQTT infrastructure!
+
 ## 🏗️ Architecture Excellence
 
 This isn't your typical monolithic MQTT library. mcmqtt features a **clean modular architecture**: