From 1679623fb90c5bc195af545481a800a5f3d08c94 Mon Sep 17 00:00:00 2001 From: Brian Leach Date: Wed, 4 Mar 2026 19:06:38 -0600 Subject: [PATCH] feat: Add Claude Code and OpenClaw AI skill Single SKILL.md with dual frontmatter for both Claude Code and OpenClaw, covering all 33 bambu-mcp MCP tools with safety rules, tool reference, workflows, and troubleshooting. - skill/SKILL.md: AI skill file - install-skill.sh: Symlinks skill/ into ~/.claude/skills/ and/or ~/.openclaw/skills/ - README.md: AI Skill section with install and ClawHub publish docs Co-Authored-By: Claude Opus 4.6 --- README.md | 31 ++++++ install-skill.sh | 51 +++++++++ skill/SKILL.md | 272 +++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 354 insertions(+) create mode 100755 install-skill.sh create mode 100644 skill/SKILL.md diff --git a/README.md b/README.md index a88fe39..295d008 100644 --- a/README.md +++ b/README.md @@ -221,6 +221,37 @@ The certificate can be overridden via `BAMBU_APP_PRIVATE_KEY` and `BAMBU_APP_CER 2. Rotate LAN access codes periodically 3. Never commit `.env` files (already in `.gitignore`) +## AI Skill + +The `skill/` directory contains a `SKILL.md` that teaches AI assistants (Claude Code, OpenClaw) how to use this MCP server — safety rules, tool reference, workflows, and troubleshooting. + +### Install locally + +```bash +# Both Claude Code and OpenClaw +./install-skill.sh + +# Claude Code only +./install-skill.sh claude + +# OpenClaw only +./install-skill.sh openclaw +``` + +This symlinks `skill/` into `~/.claude/skills/bambu` and/or `~/.openclaw/skills/bambu`. + +### Publish to ClawHub + +To make the skill available to all OpenClaw users via [ClawHub](https://clawhub.ai): + +```bash +npm i -g clawhub +clawhub login +clawhub publish ./skill --slug bambu --name "Bambu Lab 3D Printer" --version 1.0.0 --changelog "Initial release" +``` + +Users can then install it with `clawhub install bambu`. + ## Acknowledgments - **Community researchers** who [extracted the X.509 certificate](https://hackaday.com/2025/01/19/bambu-connects-authentication-x-509-certificate-and-private-key-extracted/) — making this possible diff --git a/install-skill.sh b/install-skill.sh new file mode 100755 index 0000000..de6841c --- /dev/null +++ b/install-skill.sh @@ -0,0 +1,51 @@ +#!/usr/bin/env bash +# Install the bambu skill by symlinking into Claude Code and/or OpenClaw. +# Usage: +# ./install-skill.sh # install both +# ./install-skill.sh claude # Claude Code only +# ./install-skill.sh openclaw # OpenClaw only + +set -euo pipefail + +SKILL_DIR="$(cd "$(dirname "$0")" && pwd)/skill" + +if [ ! -f "${SKILL_DIR}/SKILL.md" ]; then + echo "Error: ${SKILL_DIR}/SKILL.md not found" >&2 + exit 1 +fi + +install_link() { + local target_dir="$1" + local link="${target_dir}/bambu" + + mkdir -p "${target_dir}" + + if [ -L "${link}" ]; then + rm "${link}" + elif [ -e "${link}" ]; then + echo "Error: ${link} already exists and is not a symlink" >&2 + return 1 + fi + + ln -s "${SKILL_DIR}" "${link}" + echo "Installed: ${link} -> ${SKILL_DIR}" +} + +target="${1:-both}" + +case "${target}" in + claude) + install_link "${HOME}/.claude/skills" + ;; + openclaw) + install_link "${HOME}/.openclaw/skills" + ;; + both) + install_link "${HOME}/.claude/skills" + install_link "${HOME}/.openclaw/skills" + ;; + *) + echo "Usage: $0 [claude|openclaw|both]" >&2 + exit 1 + ;; +esac diff --git a/skill/SKILL.md b/skill/SKILL.md new file mode 100644 index 0000000..055c412 --- /dev/null +++ b/skill/SKILL.md @@ -0,0 +1,272 @@ +--- +name: bambu +description: "Bambu Lab 3D printer control via bambu-mcp MCP server: printer status, print jobs, camera snapshots, AI vision monitoring, AMS filament management, MakerWorld downloads, G-code, temperature control. Use when the user asks about 3D printing, Bambu Lab, filament, AMS, print jobs, slicer, MakerWorld, nozzle, bed temperature, or print monitoring." +argument-hint: "[status|snapshot|monitor|stop]" +homepage: "https://github.com/schwarztim/bambu-mcp" +license: MIT +metadata: + { + "openclaw": + { + "emoji": "🖨️", + "tags": ["3d-printer", "bambu-lab", "mqtt", "camera", "ams", "filament", "makerworld", "mcp"], + "requires": { "bins": ["node"] }, + "install": + [ + { + "id": "npm", + "kind": "shell", + "command": "npm install -g bambu-mcp", + "bins": ["bambu-mcp"], + "label": "Install bambu-mcp MCP server", + }, + ], + }, + } +--- + +# Bambu Lab 3D Printer + +Control and monitor Bambu Lab 3D printers via the `bambu-mcp` MCP server. Provides local MQTT control, camera snapshots, AI vision monitoring, AMS filament management, MakerWorld integration, and more. + +**Requires**: The `bambu-mcp` MCP server must be running and configured. All tools below are MCP tools. + +## When to Use + +- User asks about 3D printer status, temperatures, or progress +- User wants to start, pause, stop, or monitor a print +- User asks about filament, AMS trays, or spool changes +- User wants a camera snapshot or to enable timelapse +- User asks about MakerWorld models or wants to download/print one +- User mentions Bambu Lab, P1S, P1P, X1C, A1, or any Bambu printer +- User asks about G-code, nozzle temp, bed temp, or print speed +- User wants AI vision monitoring for print failure detection + +## When NOT to Use + +- General 3D modeling or CAD questions (not printer control) +- Non-Bambu printers (Prusa, Ender, Voron, etc.) +- Slicer profile tuning beyond what OrcaSlicer CLI supports + +## Safety Rules + +**CRITICAL — always follow these:** + +1. **Never stop or pause a print without explicit user confirmation.** A stopped print cannot be resumed and wastes filament/time. +2. **Never send G-code without understanding what it does.** Blocked commands: `M112` (emergency stop), `M502` (factory reset), `M500`/`M501` (EEPROM), `M997` (firmware update), `M999` (restart). +3. **Temperature limits are enforced** — nozzle max 300°C, bed max 120°C. +4. **Use `printer_get_cached_status` for frequent checks.** Only call `printer_get_status` (full push) at most once every 5 minutes — it can overload the printer. +5. **MQTT connection is exclusive** — only one client at a time. If connection fails, suggest closing BambuStudio, OrcaSlicer, or Home Assistant first. +6. **Confirm before starting prints** — verify filament type/color matches, bed type is correct, and the user is ready. + +## Quick Commands + +### `/bambu status` +Check printer status: get connection state, print progress, temperatures, AMS filament, and errors. + +**Steps:** +1. Call `printer_get_cached_status` (fast) or `printer_get_status` (full refresh) +2. Report: print state, progress %, current/target temps, active filament, errors +3. If not connected, prompt user for IP, access code, and serial number to call `mqtt_connect` + +### `/bambu snapshot` +Capture a live camera image from the printer. + +**Steps:** +1. Call `camera_snapshot` (uses MQTT-connected printer by default) +2. Display the saved JPEG path to the user +3. Read the image file to show it + +### `/bambu monitor` +Start AI vision monitoring to detect print failures automatically. + +**Steps:** +1. Confirm MQTT is connected and a print is running +2. Call `monitor_start` with reasonable defaults (60s interval, 3 strikes, min layer 2) +3. Report monitor config to user +4. Periodically check `monitor_status` when asked + +### `/bambu stop` +Stop the current print (requires confirmation). + +**Steps:** +1. Call `printer_get_cached_status` to show current print state and progress +2. **Ask user to confirm** — warn that stopping is irreversible +3. Only after explicit confirmation, call `printer_stop` + +## MCP Tools Reference + +### Connection (must do first) + +| Tool | Purpose | +|------|---------| +| `mqtt_connect` | Connect to printer via local MQTT. Requires: host (IP), password (LAN access code), device_id (serial). | +| `mqtt_disconnect` | Disconnect from printer. | + +### Status & Info + +| Tool | Purpose | +|------|---------| +| `printer_get_cached_status` | Fast — returns last cached status. Use for frequent polling. Includes `_age_seconds`. | +| `printer_get_status` | Full refresh — requests new data push. Rate limit: once per 5 min. | +| `printer_get_version` | Get firmware and module versions. | +| `ams_filament_mapping` | Show what filament is in each AMS slot (type, color, remaining %). | + +### Print Control + +| Tool | Purpose | +|------|---------| +| `printer_print_file` | Start printing a file on the SD card. Supports .3mf and .gcode. Use `ams_mapping` for color-to-slot assignment. 3MF requires Developer Mode. | +| `printer_pause` | Pause current print. | +| `printer_resume` | Resume a paused print. | +| `printer_stop` | Stop current print. **Irreversible — always confirm first.** | +| `printer_set_speed` | Set speed: profiles (`silent`=50%, `standard`=100%, `sport`=125%, `ludicrous`=166%) or manual 1-166%. | +| `printer_send_gcode` | Send raw G-code. Dangerous commands blocked. Temp limits enforced. | +| `skip_objects` | Skip specific objects in a multi-object print by ID. | + +### Filament / AMS + +| Tool | Purpose | +|------|---------| +| `ams_change_filament` | Switch to AMS tray 0-3. Optionally set target nozzle temp. | +| `ams_unload_filament` | Unload filament from extruder. | + +### Camera + +| Tool | Purpose | +|------|---------| +| `camera_snapshot` | Capture JPEG from chamber camera via TLS on port 6000. | +| `camera_record` | Enable/disable camera recording. | +| `camera_timelapse` | Enable/disable timelapse for current print. | + +### Vision Monitoring + +| Tool | Purpose | +|------|---------| +| `monitor_start` | Start AI print monitoring. Captures snapshots + runs vision analysis on interval. 3-strike system before emergency stop. | +| `monitor_status` | Check monitor state: cycle count, last verdict, strike count, failure status. | +| `monitor_stop` | Stop monitoring (does NOT stop the print). | + +Requires one of: `AZURE_OPENAI_API_KEY`, `OPENAI_API_KEY`, or `ANTHROPIC_API_KEY`. + +### File Transfer & Slicing + +| Tool | Purpose | +|------|---------| +| `ftp_upload_file` | Upload .gcode/.3mf/.stl to printer SD card via FTPS (port 990). | +| `slice_3mf` | Slice a 3MF with OrcaSlicer CLI. Auto-detects if already sliced. | + +### MakerWorld + +| Tool | Purpose | +|------|---------| +| `makerworld_download` | Download 3MF from makerworld.com. Handles Cloudflare blocks with browser-assisted fallback. | +| `makerworld_print` | Download from MakerWorld → slice → upload → print in one step. | + +### Hardware & Misc + +| Tool | Purpose | +|------|---------| +| `set_temperature` | Set nozzle or bed temp safely (enforces limits). | +| `set_nozzle` | Set nozzle diameter (0.2, 0.4, 0.6, 0.8 mm). | +| `led_control` | Control chamber or logo LED (`on`/`off`). Nodes: `chamber_light`, `work_light`. | + +### Cloud API (optional, requires `BAMBU_LAB_COOKIES`) + +| Tool | Purpose | +|------|---------| +| `get_user_profile` | Get Bambu Lab cloud account info. | +| `list_printers` | List printers registered to cloud account. | +| `get_printer_status` | Cloud-based status (prefer local MQTT instead). | +| `sign_message` | Sign message with X.509 cert for authenticated communication. | + +## Common Workflows + +### Check Printer Status +``` +1. printer_get_cached_status (or printer_get_status for fresh data) +2. Report: gcode_state, print progress, temps, AMS, errors +3. If IDLE → "Printer is idle and ready" + If RUNNING → "Printing [file] — X% complete, ~Y min remaining" + If PAUSE → "Print is paused at X%" + If FAILED → "Print failed — [error details]" +``` + +### Start a Print from Local File +``` +1. ftp_upload_file — upload .gcode or .3mf to printer +2. ams_filament_mapping — check what filament is loaded +3. Confirm with user: file, filament, bed type +4. printer_print_file — start the print +5. Optionally: monitor_start — enable AI monitoring +``` + +### Print from MakerWorld +``` +1. makerworld_download — download 3MF (may need browser assist for Cloudflare) +2. slice_3mf — slice if not already sliced +3. ftp_upload_file — upload to printer +4. printer_print_file — start printing + OR use makerworld_print to do all steps at once +``` + +### Monitor a Running Print +``` +1. monitor_start — begin AI vision monitoring (default: 60s interval, 3 strikes) +2. monitor_status — check latest verdict and strike count +3. camera_snapshot — take a manual snapshot to inspect visually +4. monitor_stop — stop monitoring when print finishes or user requests +``` + +### Manage Filament +``` +1. ams_filament_mapping — see what's loaded in each tray (type, color, remaining %) +2. ams_change_filament — switch to a different tray (0-3) +3. ams_unload_filament — unload current filament +``` + +## Status Interpretation + +### `gcode_state` Values +- `IDLE` — Printer is idle, ready for new jobs +- `RUNNING` — Actively printing +- `PAUSE` — Print is paused (can resume) +- `FINISH` — Print completed successfully +- `FAILED` — Print failed (check `print_error`) +- `PREPARE` — Preparing to print (heating, leveling) + +### Temperatures +- **Nozzle**: PLA ~200-220°C, PETG ~230-250°C, ABS ~240-260°C +- **Bed**: PLA ~55-60°C, PETG ~70-80°C, ABS ~90-110°C +- **Chamber**: Relevant for ABS/ASA (enclosed chamber helps) + +### AMS Tray Data +- `tray_type`: Filament type (PLA, PETG, ABS, TPU, etc.) +- `tray_color`: Hex color `#RRGGBB` +- `remain`: Remaining filament percentage (0-100) +- `tray_now`: Currently active tray number + +### Speed Levels +- `spd_lvl`: 1=silent, 2=standard, 3=sport, 4=ludicrous +- `spd_mag`: Actual speed percentage (50-166) + +## Troubleshooting + +### "MQTT connection failed" +- Check printer IP is correct and reachable (`ping `) +- Verify LAN access code from printer touchscreen (Network → LAN Access Code) +- Close competing clients: BambuStudio, OrcaSlicer, Home Assistant +- Only one MQTT connection allowed per printer + +### "Cloudflare blocked" (MakerWorld) +- Use browser-assisted download: `makerworld_download` returns step-by-step instructions +- Or manually download in browser and provide the file path via `download_path` parameter + +### "Developer Mode required" (3MF printing) +- Enable on printer: Settings → LAN Only → Developer Mode +- Only needed for .3mf files; .gcode works without it + +### Stale cached status +- `_age_seconds` in cached status shows data freshness +- If age > 60s, consider calling `printer_get_status` for a fresh push +- If age > 300s, printer may have disconnected