Ryan Malloy
d0e84c782c
- Remove complex auto-broker startup logic - Clean CLI: uvx mcmqtt just works in STDIO mode - MCP tools handle broker spawning dynamically - Updated README for zero-configuration experience - Ready for publication with clean architecture
278 lines
6.9 KiB
Markdown
278 lines
6.9 KiB
Markdown
# 🚀 mcmqtt - FastMCP MQTT Server
|
|
|
|
**The most powerful FastMCP MQTT integration server on the planet** 🌍
|
|
|
|
[](https://pypi.org/project/mcmqtt/)
|
|
[](https://python.org)
|
|
[](LICENSE)
|
|
[](#testing)
|
|
[](#coverage)
|
|
|
|
> **Enabling MQTT integration for MCP clients with embedded broker support and fractal agent orchestration**
|
|
|
|
## ✨ Key Features
|
|
|
|
- 🔥 **FastMCP Integration**: Native Model Context Protocol server with MQTT tools
|
|
- ⚡ **Embedded MQTT Brokers**: Spawn brokers on-demand with zero configuration
|
|
- 🏗️ **Modular Architecture**: Clean, testable, maintainable codebase
|
|
- 🧪 **Comprehensive Testing**: 70+ tests with 96%+ coverage on core modules
|
|
- 🌐 **Cross-Platform**: Designed for Linux, macOS, and Windows (TODO: Test on additional platforms)
|
|
- 🔧 **CLI & Programmatic**: Use via command line or integrate into your code
|
|
- 📡 **Real-time Coordination**: Perfect for agent swarms and distributed systems
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### Installation
|
|
|
|
**Recommended: Use `uvx` for instant execution** (no installation needed):
|
|
|
|
```bash
|
|
# Run directly with uvx (recommended)
|
|
uvx mcmqtt --help
|
|
|
|
# Start STDIO server for MCP clients
|
|
uvx mcmqtt
|
|
|
|
# HTTP mode for web integration
|
|
uvx mcmqtt --transport http --port 8080
|
|
```
|
|
|
|
**If you insist on traditional installation**:
|
|
|
|
```bash
|
|
# Install with uv
|
|
uv add mcmqtt
|
|
|
|
# Or use pip
|
|
pip install mcmqtt
|
|
```
|
|
|
|
### Instant MQTT Magic
|
|
|
|
```bash
|
|
# Start FastMCP MQTT server (default STDIO mode) - Just works!
|
|
uvx mcmqtt
|
|
|
|
# HTTP mode for web integration
|
|
uvx mcmqtt --transport http --port 8080
|
|
|
|
# Connect to existing broker (optional)
|
|
uvx mcmqtt --mqtt-host mqtt.example.com --mqtt-port 1883
|
|
```
|
|
|
|
### MCP Integration
|
|
|
|
Add to your Claude Code MCP configuration:
|
|
|
|
```bash
|
|
# Add mcmqtt as an MCP server (zero configuration!)
|
|
claude mcp add task-buzz -- uvx mcmqtt
|
|
|
|
# Test the connection
|
|
claude mcp test task-buzz
|
|
```
|
|
|
|
## 🛠️ Core Features
|
|
|
|
### 🏃♂️ FastMCP MQTT Tools
|
|
|
|
- `mqtt_connect` - Connect to MQTT brokers
|
|
- `mqtt_publish` - Publish messages with QoS support
|
|
- `mqtt_subscribe` - Subscribe to topics with wildcards
|
|
- `mqtt_get_messages` - Retrieve received messages
|
|
- `mqtt_status` - Get connection and statistics
|
|
- `mqtt_spawn_broker` - Create embedded brokers instantly
|
|
- `mqtt_list_brokers` - Manage multiple brokers
|
|
|
|
### 🔧 Embedded Broker Management
|
|
|
|
```python
|
|
from mcmqtt.broker import BrokerManager
|
|
|
|
# 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}")
|
|
```
|
|
|
|
### 📡 MQTT Client Integration
|
|
|
|
```python
|
|
from mcmqtt.mqtt import MQTTClient
|
|
from mcmqtt.mqtt.types import MQTTConfig
|
|
|
|
config = MQTTConfig(
|
|
broker_host="localhost",
|
|
broker_port=1883,
|
|
client_id="my-client"
|
|
)
|
|
|
|
client = MQTTClient(config)
|
|
await client.connect()
|
|
await client.publish("sensors/temperature", "23.5")
|
|
```
|
|
|
|
## 🏗️ Architecture Excellence
|
|
|
|
This isn't your typical monolithic MQTT library. mcmqtt features a **clean modular architecture**:
|
|
|
|
```
|
|
mcmqtt/
|
|
├── cli/ # Command-line interface & argument parsing
|
|
├── config/ # Environment & configuration management
|
|
├── logging/ # Structured logging setup
|
|
├── server/ # STDIO & HTTP server runners
|
|
├── mqtt/ # Core MQTT client functionality
|
|
├── mcp/ # FastMCP server integration
|
|
├── broker/ # Embedded broker management
|
|
└── middleware/ # Broker middleware & orchestration
|
|
```
|
|
|
|
### 🧪 Testing Excellence
|
|
|
|
- **70+ comprehensive tests** covering all modules
|
|
- **96%+ code coverage** on refactored components
|
|
- **Robust mocking** for reliable CI/CD
|
|
- **Edge case coverage** for production reliability
|
|
|
|
## 🌟 Use Cases
|
|
|
|
### 🤖 AI Agent Coordination
|
|
|
|
Perfect for coordinating Claude Code subagents via MQTT:
|
|
|
|
```bash
|
|
# Parent agent publishes tasks
|
|
mcmqtt-publish --topic "agents/tasks" --payload '{"task": "analyze_data", "agent_id": "worker-1"}'
|
|
|
|
# Worker agents subscribe and respond
|
|
mcmqtt-subscribe --topic "agents/tasks" --callback process_task
|
|
```
|
|
|
|
### 📊 IoT Data Collection
|
|
|
|
```bash
|
|
# Collect sensor data
|
|
mcmqtt-subscribe --topic "sensors/+/temperature" --format json
|
|
|
|
# Forward to analytics
|
|
mcmqtt-publish --topic "analytics/temperature" --payload "$sensor_data"
|
|
```
|
|
|
|
### 🔄 Microservice Communication
|
|
|
|
```bash
|
|
# Service mesh communication
|
|
mcmqtt --mqtt-host service-mesh.local --client-id user-service
|
|
```
|
|
|
|
## ⚙️ Configuration
|
|
|
|
### Environment Variables
|
|
|
|
```bash
|
|
export MQTT_BROKER_HOST=localhost
|
|
export MQTT_BROKER_PORT=1883
|
|
export MQTT_CLIENT_ID=my-client
|
|
export MQTT_USERNAME=user
|
|
export MQTT_PASSWORD=secret
|
|
export MQTT_USE_TLS=true
|
|
```
|
|
|
|
### Command Line Options
|
|
|
|
```bash
|
|
mcmqtt --help
|
|
|
|
Options:
|
|
--transport [stdio|http] Server transport mode
|
|
--mqtt-host TEXT MQTT broker hostname
|
|
--mqtt-port INTEGER MQTT broker port
|
|
--mqtt-client-id TEXT MQTT client identifier
|
|
--auto-broker Spawn embedded broker
|
|
--log-level [DEBUG|INFO|WARNING|ERROR]
|
|
--log-file PATH Log to file
|
|
```
|
|
|
|
## 🚦 Development
|
|
|
|
### Requirements
|
|
|
|
- Python 3.11+
|
|
- UV package manager (recommended)
|
|
- FastMCP framework
|
|
- Paho MQTT client
|
|
|
|
### Setup
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://git.supported.systems/MCP/mcmqtt.git
|
|
cd mcmqtt
|
|
|
|
# Install dependencies
|
|
uv sync
|
|
|
|
# Run tests
|
|
uv run pytest
|
|
|
|
# Build package
|
|
uv build
|
|
```
|
|
|
|
### Testing
|
|
|
|
```bash
|
|
# Run all tests
|
|
uv run pytest tests/
|
|
|
|
# Run with coverage
|
|
uv run pytest --cov=src/mcmqtt --cov-report=html
|
|
|
|
# Test specific modules
|
|
uv run pytest tests/unit/test_cli_comprehensive.py -v
|
|
```
|
|
|
|
## 📈 Performance
|
|
|
|
- **Lightweight**: Minimal memory footprint
|
|
- **Fast**: Async/await throughout for maximum throughput
|
|
- **Scalable**: Handle thousands of concurrent connections
|
|
- **Reliable**: Comprehensive error handling and retry logic
|
|
|
|
## 🤝 Contributing
|
|
|
|
We love contributions! This project follows the "campground rule" - leave it better than you found it.
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch
|
|
3. Add tests for new functionality
|
|
4. Ensure all tests pass
|
|
5. Submit a pull request
|
|
|
|
## 📄 License
|
|
|
|
MIT License - see [LICENSE](LICENSE) for details.
|
|
|
|
## 🙏 Credits
|
|
|
|
Created with ❤️ by [Ryan Malloy](mailto:ryan@malloys.us)
|
|
|
|
Built on the shoulders of giants:
|
|
- [FastMCP](https://github.com/jlowin/fastmcp) - Modern MCP framework
|
|
- [Paho MQTT](https://github.com/eclipse/paho.mqtt.python) - Reliable MQTT client
|
|
- [AMQTT](https://github.com/Yakifo/amqtt) - Pure Python MQTT broker
|
|
|
|
---
|
|
|
|
**Ready to revolutionize your MQTT integration?** Install mcmqtt today! 🚀
|
|
|
|
```bash
|
|
uvx mcmqtt --transport stdio --auto-broker
|
|
```
|