MeshCue Forge

The hardware compiler — describe it, build it, print it.

forge.meshcue.com

MeshCue Forge is an open-source MCP server that turns natural language hardware descriptions into complete, buildable projects: circuits, firmware, 3D-printable enclosures, PCB files, and documentation — all from a single spec.

How It Works

"ESP32-S3 board with OLED, 3 LEDs, 2 buttons, and a buzzer"
    |
    v  meshforge-describe
    |
  MHDL Spec (single source of truth)
    |
    v  meshforge-build
    |
    +-- diagram.json       (Wokwi circuit — simulate in browser)
    +-- main.ino           (Arduino firmware — ready to compile)
    +-- platformio.ini     (Build config)
    +-- enclosure.scad     (OpenSCAD — 3D printable case)
    +-- bom.csv            (Bill of materials)
    +-- PINOUT.md          (GPIO reference)
    +-- ASSEMBLY.md        (Step-by-step build guide)
    +-- PRINT_GUIDE.md     (3D print settings)

Quick Start

Install

npm install @meshcue/forge

Add to Claude Code

Add to your Claude Code MCP settings:

{
  "mcpServers": {
    "meshcue-forge": {
      "command": "node",
      "args": ["node_modules/@meshcue/forge/dist/index.js"]
    }
  }
}

Use It

Just describe what you want to build:

"Use meshcue forge to design an ESP32-S3 board with an OLED display, 3 status LEDs, 2 buttons, and a buzzer for a mesh networking node"

MeshCue Forge generates everything you need to simulate, build, and 3D print the device.

MCP Tools

Tool	Description
meshforge-describe	Natural language to MHDL spec
meshforge-build	MHDL to all build artifacts
meshforge-validate	Design Rule Checks (DRC)
meshforge-iterate	Patch spec + rebuild

MHDL — Hardware Description Language

MHDL is the single source of truth for a hardware project. One YAML/JSON file describes the entire device:

meta:
  name: MeshCue Node
  version: 1.0.0

board:
  mcu:
    family: esp32-s3
  components:
    - id: oled
      type: oled
    - id: led_green
      type: led
  connections:
    - from: mcu.oled_sda
      to: oled.sda

firmware:
  framework: arduino
  entrypoint: main.ino

enclosure:
  type: snap-fit
  cutouts:
    - type: oled-window
      wall: front
    - type: usb-c
      wall: back

MHDL is git-friendly (text-based diffs), team-friendly (one file everyone works from), and AI-friendly (structured enough for generation, readable enough for humans).

Validation (DRC)

Every build runs automatic Design Rule Checks:

• Pin conflict detection — no two components on the same GPIO
• I2C address collision — no duplicate bus addresses
• Power budget check — total draw vs. supply capacity
• Connection integrity — all pin references are valid
• Enclosure fit — cutouts reference real components
• Mounting alignment — holes are within board bounds

Pluggable Backends

MeshCue Forge uses a pluggable backend architecture:

Stage	Default Backend	Alternatives
Circuit	Wokwi JSON	Fritzing, SPICE
Firmware	Arduino	MicroPython, ESP-IDF
Enclosure	OpenSCAD	CadQuery, FreeCAD
PCB	KiCad	EasyEDA

Supported Hardware

MCUs

ESP32, ESP32-S3, ESP32-C3, Arduino Uno/Nano/Mega, RP2040, STM32, ATtiny85

Components

LEDs, buttons, OLED/LCD displays, buzzers, sensors (DHT22), motors, relays, transistors, resistors, capacitors

Enclosure Types

Snap-fit, screw-close, slide-on, friction-fit, open-frame

Flagship: MeshCue Node

The MeshCue Node — a dedicated mesh networking hardware device — was designed and built entirely using MeshCue Forge. See the examples/meshcue-node directory for the complete project.

npx tsx examples/meshcue-node/build.ts

Development

git clone https://github.com/tinkclaw/meshcue-forge.git
cd meshcue-forge
npm install
npm run build
npm run dev  # watch mode

Run tests:

npx tsx test.ts

Contributing

MeshCue Forge is MIT licensed and welcomes contributions:

• New component templates — add support for more sensors, displays, etc.
• Backend plugins — MicroPython firmware, FreeCAD enclosures, EasyEDA PCBs
• Board templates — pre-built MHDL specs for common projects
• Validation rules — more DRC checks

Architecture

MeshCue Forge follows a linear pipeline with validation at every stage:

Natural Language Input
    |
    v  meshforge-describe (keyword NL parser)
    |
  MHDL Spec (YAML/JSON — single source of truth)
    |
    v  meshforge-validate (Design Rule Checks)
    |
    v  meshforge-build (parallel backend execution)
    |
    +-- Circuit Stage     -> diagram.json (Wokwi)
    +-- Firmware Stage    -> main.ino + platformio.ini (Arduino)
    +-- Enclosure Stage   -> enclosure.scad (OpenSCAD / CadQuery / Zoo / LLaMA-Mesh)
    +-- PCB Stage         -> pcb.py (SKiDL) or .kicad_pcb (KiCad)
    +-- BOM Stage         -> bom.csv
    +-- Docs Stage        -> PINOUT.md, ASSEMBLY.md, PRINT_GUIDE.md
    +-- Viz Stage         -> 3D model / video (Hunyuan3D / Cosmos / LLaMA-Mesh)

The meshforge-iterate tool allows patching an existing spec and re-running the pipeline without starting from scratch.

Backend Configuration

Each pipeline stage has a default backend and optional alternatives. Backends are selected via environment variables or per-spec overrides.

Stage	Env Variable	Default	Alternatives	Requirements
Enclosure	FORGE_ENCLOSURE_BACKEND	openscad	cadquery, zoo-cad, llama-mesh	OpenSCAD: none (generates .scad). CadQuery: Python 3 + cadquery pip package. Zoo: ZOO_CAD_API_KEY. LLaMA-Mesh: LLAMA_MESH_ENDPOINT.
PCB	FORGE_PCB_BACKEND	skidl	kicad	SKiDL: generates Python script (execution needs Python + skidl). KiCad: KICAD_PATH pointing to kicad-cli.
Visualization	FORGE_VIZ_BACKEND	hunyuan3d	cosmos, llama-mesh	All generate placeholders in offline mode. Online mode requires the respective *_ENDPOINT env var.
Circuit	(not configurable)	Wokwi JSON	--	None
Firmware	(not configurable)	Arduino	--	None (generates source; compilation requires Arduino CLI or PlatformIO)

See .env.example for all environment variables.

Troubleshooting

"Python not found" or CadQuery backend fails

• Set PYTHON_PATH to your Python 3 interpreter (e.g., PYTHON_PATH=/usr/local/bin/python3).
• Ensure cadquery is installed: pip3 install cadquery.

"KiCad not installed" or PCB generation fails with kicad backend

• Install KiCad 9 from kicad.org.
• Set KICAD_PATH to the CLI binary (e.g., KICAD_PATH=/usr/bin/kicad-cli on Linux, KICAD_PATH=/Applications/KiCad/KiCad.app/Contents/MacOS/kicad-cli on macOS).

Zoo Text-to-CAD returns errors

• Verify your API key is valid: curl -H "Authorization: Bearer $ZOO_CAD_API_KEY" https://api.zoo.dev/user.
• Check that ZOO_CAD_ENDPOINT is set correctly (default: https://api.zoo.dev).

Enclosure cutouts don't match components

• Ensure componentRef in each cutout matches a component id in the board section.
• Run meshforge-validate to catch mismatches before building.

Build succeeds but firmware won't compile

• MeshCue Forge generates source code, not compiled binaries. You need Arduino CLI or PlatformIO installed to compile.
• Check that all libraries listed in the MHDL spec are available in your Arduino/PlatformIO environment.

"I2C address collision" validation error

• Two components share the same I2C address. Change the address in the component's properties.i2cAddress field, or use different I2C bus pins.

OpenSCAD rendering is slow

• OpenSCAD .scad files are generated instantly. Rendering to STL requires OpenSCAD installed locally (OPENSCAD_PATH).
• For faster iteration, preview in the OpenSCAD GUI before exporting.

Contributing

MeshCue Forge is MIT licensed and welcomes contributions.

Adding a New Backend

1. Create a new file in the appropriate src/backends/ directory (e.g., src/backends/enclosure/freecad.ts).
2. Implement the backend interface matching the existing pattern (see openscad.ts or cadquery.ts as reference).
3. Register the backend in the stage's factory/registry.
4. Add the backend identifier to the relevant type union in src/schema/mhdl.ts.
5. Update src/config.ts to detect the new backend's capabilities.
6. Add tests covering the new backend's output.

Running Tests

npm run build          # Compile TypeScript
npm test               # Run all tests
npx tsx test.ts        # Run integration tests
npm run typecheck      # Type-check without emitting
npm run lint           # ESLint
npm run format:check   # Prettier check

Submitting PRs

1. Fork the repo and create a feature branch from main.
2. Follow the existing code style (TypeScript strict mode, ESLint + Prettier).
3. Include tests for new functionality.
4. Run npm run typecheck && npm run lint && npm test before submitting.
5. Keep PRs focused: one backend, one feature, or one fix per PR.

Contribution Ideas

• New component templates -- add support for more sensors, displays, actuators.
• Backend plugins -- MicroPython firmware, FreeCAD enclosures, EasyEDA PCBs.
• Board templates -- pre-built MHDL specs for common projects.
• Validation rules -- more DRC checks (thermal analysis, signal integrity).
• MHDL schema extensions -- new fields for advanced use cases.

MeshCue Connect

MeshCue Connect is the patient communication layer — it closes the loop between medical devices, clinics, patients, and families.

Multi-Tenant Clinic Model

MeshCue Connect operates as a clinic-owned multi-tenant platform:

• Clinics register and own their channels — each clinic brings their own Africa's Talking or Twilio credentials, their own phone numbers, and their own short codes. MeshCue never owns or controls a clinic's communication channels.
• MeshCue is the routing platform, not the phone number owner — the platform routes messages, manages consent, and handles triage logic. Clinics retain full ownership of their patient data and API keys.
• Patient data is scoped per-clinic — a patient registered at Clinic A is not visible to Clinic B. Each clinic manages their own patient roster, consent records, and message history.

Subscription Tiers

	Free	Basic	Professional	Enterprise
Patients	50	500	2,000	Unlimited
Devices	5	50	200	Unlimited
Messages/month	500	5,000	20,000	Unlimited
SMS	Yes	Yes	Yes	Yes
USSD	—	Yes	Yes	Yes
WhatsApp	—	—	Yes	Yes
Voice/IVR	—	—	Yes	Yes
Custom integration	—	—	—	Yes
Price	Free	$29/mo	$99/mo	$299/mo

Free tier is forever free for community health clinics in developing countries. Apply for a grant-funded upgrade.

Supported Channels

Channel	Provider	Notes
SMS	Africa's Talking	Works on any phone, any network. No internet needed.
USSD	Africa's Talking	Zero data cost. Patients dial *123# to report symptoms, request appointments, check results.
WhatsApp	WhatsApp Business API	Rich messages with images, documents, and interactive buttons.
Voice/IVR	Africa's Talking or Twilio	Automated voice calls for critical alerts. Supports text-to-speech in 9 languages.

Languages

9 languages supported: English, French, Swahili, Kinyarwanda, Lingala, Kirundi, Portuguese, Arabic, Spanish. Language is set per-patient and auto-detected from incoming messages.

MCP Tools

Tool	Description
meshcue-clinic-register	Register a new clinic with name, location, and language
meshcue-clinic-setup-sms	Configure a clinic's SMS provider (Africa's Talking or Twilio)
meshcue-clinic-setup-whatsapp	Configure a clinic's WhatsApp Business API credentials
meshcue-clinic-setup-voice	Configure a clinic's Voice/IVR provider
meshcue-clinic-test-channel	Send a test message through a clinic's configured channel
meshcue-clinic-dashboard	View clinic stats: patients, devices, messages, channel health
meshcue-connect-alert	Send a critical alert to patient + family + nurse based on device reading
meshcue-connect-send	Send a message to a specific phone number via any channel
meshcue-connect-register	Register a patient under a clinic with phone, language, emergency contacts, and consent
meshcue-connect-inbox	Retrieve incoming messages for a clinic (symptoms, replies, opt-outs)

Configuration

Platform-level environment variables are documented in .env.example. Individual clinics configure their own API keys via MCP tools — no environment variables needed per clinic.

• MESHCUE_DEFAULT_CHANNEL — Platform default delivery channel (sms, whatsapp, voice)
• MESHCUE_DEFAULT_LANGUAGE — Platform default language code (en, fr, sw, rw, ln, rn, pt, ar, es)
• MESHCUE_MAX_RETRIES — Number of delivery retries before escalation
• MESHCUE_ESCALATION_PHONE — Platform-level fallback phone number for critical alerts when all clinic contacts fail

Known Limitations

• Keyword-based NL parsing: The meshforge-describe tool uses keyword matching, not a full NLU model. Complex or ambiguous descriptions may produce incomplete specs. Iterate with meshforge-iterate to refine.
• Arduino-only firmware generation: Only Arduino/C++ firmware is generated currently. MicroPython and ESP-IDF support are planned but not yet implemented.
• No compiled output: Forge generates source files (.ino, .scad, .py), not compiled binaries or rendered STLs. You need the respective toolchains installed locally to compile/render.
• Wokwi-only circuit output: Circuit diagrams are generated in Wokwi JSON format only. Fritzing and SPICE export are planned.
• 2-layer PCB only: SKiDL backend currently generates 2-layer PCBs. 4-layer support is defined in the schema but not yet implemented.
• AI backends require external servers: Zoo Text-to-CAD, LLaMA-Mesh, Hunyuan3D, and Cosmos all require external API endpoints. Without them, Forge operates in offline mode with template-based generation.
• Limited component library: While many common components are supported, some specialized parts (e.g., specific sensor models) may need to be defined as custom type with manual pin configuration.

License

MIT

---

Built by TinkClaw | forge.meshcue.com | Powering the MeshCue decentralized mesh network.