Ryan Malloy
eb524b8c1d
BREAKING CHANGES: - Package renamed from mcp-arduino-server to mcp-arduino - Command changed to 'mcp-arduino' (was 'mcp-arduino-server') - Repository moved to git.supported.systems/MCP/mcp-arduino NEW FEATURES: ✨ Smart client capability detection and dual-mode sampling support ✨ Intelligent WireViz templates with component-specific circuits (LED, motor, sensor, button, display) ✨ Client debug tools for MCP capability inspection ✨ Enhanced error handling with progressive enhancement patterns IMPROVEMENTS: 🧹 Major repository cleanup - removed 14+ experimental files and tests 📝 Consolidated and reorganized documentation 🐛 Fixed import issues and applied comprehensive linting with ruff 📦 Updated author information to Ryan Malloy (ryan@supported.systems) 🔧 Fixed package version references in startup code TECHNICAL DETAILS: - Added dual-mode WireViz: AI generation for sampling clients, smart templates for others - Implemented client capability detection via MCP handshake inspection - Created progressive enhancement pattern for universal MCP client compatibility - Organized test files into proper structure (tests/examples/) - Applied comprehensive code formatting and lint fixes The server now provides excellent functionality for ALL MCP clients regardless of their sampling capabilities, while preserving advanced features for clients that support them. Version: 2025.09.27.1
📚 MCP Arduino Server Documentation
Complete documentation for the Model Context Protocol (MCP) Arduino Server
🚀 Quick Links
| Document | Description |
|---|---|
| Quick Start Guide | Get up and running in 5 minutes |
| Serial Monitor Guide | Complete serial monitoring tutorial |
| API Reference | Detailed API documentation |
| Architecture | Circular buffer technical details |
📖 Documentation Structure
🎯 Getting Started
- Quick Start Guide - Installation and first sketch
- Configuration Guide - Environment variables and settings
- Examples - Sample code and common patterns
🔧 How-To Guides
- Serial Integration Guide - Step-by-step serial monitoring
- ESP32 Development - ESP32-specific workflows
- Debugging Guide - Using debug tools effectively
📘 Reference
- Serial Monitor API - Complete tool reference
- Arduino Tools API - Sketch and library management
- WireViz API - Circuit diagram generation
🏗️ Architecture
- Circular Buffer Architecture - Memory management design
- System Architecture - Overall system design
- MCP Integration - How MCP protocol is used
🎓 By Use Case
For Arduino Developers
- Start with Quick Start Guide
- Learn serial monitoring with Serial Integration Guide
- Reference Serial Monitor API for specific tools
For ESP32 Developers
- Install ESP32 support: ESP32 Guide
- Use high-speed serial: Serial Integration Guide
- Debug with dual-core support: Debugging Guide
For System Integrators
- Understand Architecture
- Configure via Configuration Guide
- Review Circular Buffer Architecture for scaling
🔍 Features by Category
📡 Serial Communication
- Real-time monitoring with cursor-based streaming
- Full parameter control (baudrate, parity, flow control)
- Circular buffer with automatic memory management
- Multiple concurrent readers support
- Auto-reconnection and error recovery
🎛️ Arduino Management
- Sketch creation, compilation, and upload
- Board detection and management
- Library installation and search
- ESP32 and Arduino board support
🔌 Circuit Design
- WireViz diagram generation from natural language
- YAML-based circuit definitions
- Automatic component detection
🐛 Debugging
- GDB integration for hardware debugging
- Breakpoint management
- Memory inspection
- Interactive and automated modes
📊 Performance & Scaling
| Scenario | Buffer Size | Data Rate | Memory Usage |
|---|---|---|---|
| Basic Debugging | 1,000 | < 10 Hz | ~100 KB |
| Normal Monitoring | 10,000 | < 100 Hz | ~1 MB |
| High-Speed Logging | 100,000 | < 1 kHz | ~10 MB |
| Data Analysis | 1,000,000 | Any | ~100 MB |
🔧 Configuration Reference
Essential Environment Variables
# Required
ARDUINO_SKETCHES_DIR=~/Documents/Arduino_MCP_Sketches
# Serial Monitor
ARDUINO_SERIAL_BUFFER_SIZE=10000 # Buffer size (100-1000000)
# Optional
ARDUINO_CLI_PATH=/usr/local/bin/arduino-cli
WIREVIZ_PATH=/usr/local/bin/wireviz
LOG_LEVEL=INFO
ENABLE_CLIENT_SAMPLING=true
🆘 Troubleshooting Quick Reference
| Issue | Solution | Documentation |
|---|---|---|
| "Port busy" | Use exclusive=True or check lsof |
Serial Guide |
| "Permission denied" | Add user to dialout group |
Configuration |
| High memory usage | Reduce buffer size | Buffer Architecture |
| Missing data | Check drop rate, increase buffer | Buffer Architecture |
| ESP32 not detected | Install ESP32 core | ESP32 Guide |
📝 Documentation Standards
All documentation follows these principles:
- Clear Structure: Organized by user journey and use case
- Practical Examples: Real code that works
- Progressive Disclosure: Start simple, add complexity
- Cross-References: Links between related topics
- Visual Aids: Diagrams, tables, and formatted output
🤝 Contributing
To contribute documentation:
- Follow existing formatting patterns
- Include working examples
- Test all code snippets
- Update this index when adding new docs
- Ensure cross-references are valid
📈 Version History
| Version | Date | Changes |
|---|---|---|
| 1.2.0 | 2024-01 | Added circular buffer with cursor management |
| 1.1.0 | 2024-01 | Enhanced serial parameters support |
| 1.0.0 | 2024-01 | Initial release with basic serial monitoring |
🔗 External Resources
For questions or issues, please visit the GitHub repository