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

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:

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.

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 tier is forever free for community health clinics in developing countries. Apply for a grant-funded upgrade.

Supported Channels

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

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.