convez.ai
MCP ServerAutomaçãoAvançado
andresparraarze

ForgeLab — IR JSON para Design Multiferra

andresparraarze/ForgeLab

IR JSON universal para agentes criarem designs em KiCad, FreeCAD e glTF

Ver no GitHub
BomPluginScore · de 0 a 100

MCP server que fornece uma representação intermediária JSON agnóstica para AI agents criarem e transformarem arquivos de design (KiCad, FreeCAD, glTF) sem tocar em formatos proprietários. Funciona como um compilador universal de design, permitindo workflows multi-ferramenta onde agentes operam inteiramente em JSON.

Instalação

$npx convez-ai andresparraarze/ForgeLab

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
3
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 2 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Gerar esquemáticos e PCBs com agentes IA via KiCad
  • Criar modelos 3D parametrizados (FreeCAD) por prompt
  • Automatizar workflows de design multiferra sem SDKs proprietários

Veredito

Projeto ambicioso em pré-alpha que ataca um problema real — permitir agentes IA operarem designs sem proprietários. A arquitetura IR+compilador é sólida, mas está ainda cru (v0.5.0, faltam exportadores). Recomendado para quem quer explorar ou contribuir em design automation.

README

A tradução para o português deste README ainda está na fila.

ForgeLab

The LLVM of design. A universal, JSON-based design interchange format and compiler that lets AI agents create, read, and transform design files across tools and domains — without ever touching proprietary file formats.

CI License: Apache 2.0 Python Spec Status

ForgeLab defines a JSON intermediate representation (IR) that sits between AI agents and design software. Any tool can import its native files into ForgeLab IR; any tool can export ForgeLab IR back to its native format. Agents operate entirely in ForgeLab JSON — no proprietary formats, no special training.

native file ──import──▶ ForgeLab IR ──transform──▶ ForgeLab IR ──export──▶ native file
                          ▲                                        │
                          └──────────── AI agents ─────────────────┘
                                   (pure JSON, no proprietary formats)

Table of Contents

Why ForgeLab

  • JSON-native for AI. The IR is plain JSON, so any LLM or agent can emit and consume it directly — no custom file writers, no proprietary SDKs, no special training.
  • Tool-agnostic. Importers and exporters plug into a shared IR. Add a tool once and it interoperates with every other tool ForgeLab supports.
  • Versioned for the long haul. Every document declares a forgelab_version, so tooling can reason about compatibility as the spec evolves.
  • Typed where it counts. Domain vocabularies (e.g. hardware: components, nets, board constraints) are validated Pydantic models that serialize into a generic, universal node graph.

Tool support

DomainToolImportExportNotes
HardwareKiCad✅✅.kicad_pcb round-trip (components/nets/board)
HardwareAltium🚧🚧stub — contributions welcome
HardwareGerber🚧🚧stub — contributions welcome
Mechanical CADFreeCAD✅✅.FCStd round-trip (parts/bodies/features/sketch dimensions)
Mechanical CADFusion 360🚧🚧stub
3D / GameglTF (.gltf)✅✅.gltf round-trip (meshes/materials/scene hierarchy)
3D / GameBlender✅✅via glTF interchange; native .blend 🚧
3D / GameUnreal Engine🚧🚧stub

✅ implemented · 🚧 stub (base classes in place, awaiting implementation)

Install

Requires Python 3.11+.

git clone https://github.com/andresparraarze/ForgeLab
cd ForgeLab
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,api]"

ForgeLab has no heavy runtime dependencies — just Pydantic and FastAPI. The KiCad support parses the .kicad_pcb S-expression format directly, so no KiCad installation is required (same for FreeCAD: .FCStd is parsed with the standard library).

Optional extras, install what you need:

ExtraEnablesPulls in
agentForgeAgent (natural language → ForgeDocument)anthropic
apirunning the REST serviceuvicorn
authOAuth 2.0 protection for the REST API / MCP HTTPpyjwt, cryptography, python-multipart
mcpthe MCP server (forgelab-mcp)mcp
pip install -e ".[mcp,agent]"   # e.g. everything an MCP-connected agent needs

Use ForgeLab from your agent

The MCP server is the fastest way to put ForgeLab in an agent's hands. Three ways to connect, from easiest to most manual:

1. One line (Claude Code):

curl -fsSL https://raw.githubusercontent.com/andresparraarze/ForgeLab/main/scripts/install-claude-code.sh | bash

Checks Python, creates a venv in ~/.forgelab, installs forgelab[mcp,agent], registers the MCP server with Claude Code, and sets up ~/forgelab-output as the export directory. Done.

2. forgelab init (any agent): if you already have ForgeLab installed, run the interactive setup — it asks which agent you use and where exports should go, then registers the server (Claude Code) or prints the exact config block to paste (Hermes / OpenClaw / anything else):

forgelab init

3. Paste a bootstrap prompt: let your agent set itself up. docs/agent-bootstrap.md has copy-paste prompts for Hermes, OpenClaw, and any MCP-compatible agent that install ForgeLab, register the server, and verify the tools with list_domains.

Updating: once installed, upgrade to the latest version with one command — it refreshes the ~/.forgelab install from GitHub and prints the new spec version:

forgelab update

For manual setup, the per-client details follow. The examples use stdio (local, no auth); for a shared/remote server, run forgelab-mcp --transport streamable-http behind OAuth (see MCP server) and register it as an HTTP MCP server instead. generate_document needs ANTHROPIC_API_KEY in the server's environment; everything else works without it.

Claude Code

Register the server with the claude mcp CLI (use the venv's absolute path so it works regardless of the shell's environment):

claude mcp add forgelab -- /path/to/ForgeLab/.venv/bin/forgelab-mcp --transport stdio

Or add it to .mcp.json in your project to share it with your team:

{
  "mcpServers": {
    "forgelab": {
      "command": "/path/to/ForgeLab/.venv/bin/forgelab-mcp",
      "args": ["--transport", "stdio"],
      "env": { "ANTHROPIC_API_KEY": "sk-..." }
    }
  }
}

Then ask Claude Code things like "generate a blinky LED board and export it to KiCad" — it will chain generate_document → export_document and hand you the .kicad_pcb content.

Hermes

Hermes speaks MCP over Streamable HTTP. Run the server with auth enabled, mint a token from the built-in dev authorization server (or your IdP), and point Hermes at the endpoint:

FORGELAB_AUTH_ENABLED=true forgelab-mcp --transport streamable-http --port 8001

Configure the Hermes MCP connection with:

  • URL: http://your-host:8001/mcp
  • Authorization: Bearer <token> — get one via POST /oauth/token on the REST API (see Authentication), requesting the scopes the agent needs (forge:read forge:export forge:generate).

For local/trusted Hermes deployments that support stdio servers, the forgelab-mcp --transport stdio command works there too.

OpenClaw

OpenClaw consumes MCP servers via its standard MCP configuration. For a local setup, register the stdio command:

{
  "mcpServers": {
    "forgelab": {
      "command": "/path/to/ForgeLab/.venv/bin/forgelab-mcp",
      "args": ["--transport", "stdio"]
    }
  }
}

For a remote OpenClaw deployment, use the OAuth-protected HTTP endpoint exactly as in the Hermes setup: URL http://your-host:8001/mcp plus a bearer token with the appropriate forge:* scopes.

What the agent gets

Whichever client you use, the agent sees the same eight tools:

ToolWhat it doesScope (HTTP)
list_domains, list_formatsdiscover supported domains and format toolsforge:read
get_domain_schema, get_promptJSON Schema + prompt templates per domainforge:read
validate_documentvalidate a ForgeLab documentforge:read
export_document, import_fileIR ↔ native files (KiCad, glTF, FreeCAD)forge:export
generate_documentnatural language → validated ForgeDocumentforge:generate

Over stdio everything is available locally; over HTTP each tool requires its scope on the bearer token. generate_document needs ANTHROPIC_API_KEY set on the server and returns a clear error if it is missing.

Multi-tool workflows

ForgeLab is designed to sit next to tool-specific MCP servers (KiCad MCP, Blender MCP, FreeCAD MCP, Unreal MCP): ForgeLab generates and compiles the design, the tool MCP opens it. The handoff is a file on disk:

  • export_document takes an optional output_path. When provided, ForgeLab writes the exported file to disk and returns {"tool", "path", "bytes_written"} instead of inline content — the agent passes path straight to the tool MCP.
  • FORGELAB_OUTPUT_DIR sets the default output directory: a bare filename ("blinky.kicad_pcb") is written there. Unset, bare filenames go to the current working directory. Absolute paths and paths containing directories are used as-is.

A single .mcp.json wiring ForgeLab together with tool MCPs into one shared folder:

{
  "mcpServers": {
    "forgelab": {
      "command": "/path/to/ForgeLab/.venv/bin/forgelab-mcp",
      "args": ["--transport", "stdio"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-...",
        "FORGELAB_OUTPUT_DIR": "/home/you/designs"
      }
    },
    "kicad": {
      "command": "kicad-mcp",
      "env": { "KICAD_PROJECT_DIR": "/home/you/designs" }
    },
    "blender": { "command": "blender-mcp" },
    "freecad": { "command": "freecad-mcp" },
    "unreal":  { "command": "unreal-mcp" }
  }
}

(The tool-MCP commands and env vars above are placeholders — use the install instructions of whichever KiCad/Blender/FreeCAD/Unreal MCP server you run, and point it at the same directory as FORGELAB_OUTPUT_DIR.)

Example prompt to Claude Code:

"Design a blinky LED board with one resistor and one LED, then open it in KiCad."

The agent's tool-call chain:

  1. forgelab.generate_document(prompt="a blinky LED board…", domain="hardware") → validated ForgeDocument (JSON).
  2. forgelab.export_document(document=…, tool="kicad", output_path="blinky.kicad_pcb") → {"path": "/home/you/designs/blinky.kicad_pcb", "bytes_written": …}.
  3. kicad.open_project(path="/home/you/designs/blinky.kicad_pcb") (or the equivalent tool on your KiCad MCP) — the board opens in KiCad.

The same chain works for the other domains: domain="threed" + tool="gltf" → Blender MCP imports the .gltf; domain="mechanical" + tool="freecad" → FreeCAD MCP opens the .FCStd; Unreal consumes glTF exports the same way.

Quickstart

Build IR with the AI SDK

The AI SDK takes a natural-language prompt to a validated, ready-to-compile ForgeDocument — natural language to a real KiCad file in ~10 lines:

from forgelab.sdk import ForgeAgent
from forgelab.exporters.hardware.kicad import KiCadExporter

agent = ForgeAgent()                                    # reads ANTHROPIC_API_KEY
doc = agent.design("a blinky LED board with one resistor and one LED",
                   domain="hardware")                   # NL -> validated ForgeDocument
with open("blinky.kicad_pcb", "wb") as f:
    f.write(KiCadExporter().from_ir(doc))               # -> real KiCad file

ForgeAgent forces Claude to emit ForgeLab JSON through a per-domain JSON Schema, then validates it before returning. Requires the optional extra: pip install "forgelab[agent]".

The lower-level building blocks are independent and provider-agnostic:

from forgelab.sdk import domain_schema, system_prompt, few_shot, validate_llm_output

domain_schema("hardware")        # tight JSON Schema for structured-output / tools
system_prompt("threed")          # ready-made system prompt for any LLM
few_shot("threed")               # (request, valid-JSON) examples
validate_llm_output(raw_text, domain="hardware")  # clean + parse + validate, or raise

And the original primitives still work for hand-built documents:

from forgelab.sdk import new_document, dump, load

doc = new_document(domain="hardware", name="blinky")
restored = load(dump(doc))
assert restored == doc

Round-trip a KiCad board

Import a real .kicad_pcb, work with it as JSON, and export a functional board back out:

from forgelab.importers.hardware.kicad import KiCadImporter
from forgelab.exporters.hardware.kicad import KiCadExporter

source = open("examples/hardware/blinky.kicad_pcb", "rb").read()

doc = KiCadImporter().to_ir(source)          # .kicad_pcb -> ForgeDocument
components = [n.id for n in doc.nodes if n.type == "component"]
print(components)                            # ['R1', 'D1']

kicad_bytes = KiCadExporter().from_ir(doc)   # ForgeDocument -> .kicad_pcb

# The round-trip is stable: import -> export -> import is an identity over the IR.
assert KiCadImporter().to_ir(kicad_bytes) == doc

Round-trip a glTF scene

Import a .gltf 3D scene, work with the geometry as JSON, and export it back:

from forgelab.importers.threed.gltf import GltfImporter
from forgelab.exporters.threed.gltf import GltfExporter

source = open("examples/threed/cube.gltf", "rb").read()

doc = GltfImporter().to_ir(source)           # .gltf -> ForgeDocument
objects = [n.id for n in doc.nodes if n.type == "object"]
print(objects)                               # ['Cube']

gltf_bytes = GltfExporter().from_ir(doc)     # ForgeDocument -> .gltf

# The round-trip is stable: import -> export -> import is an identity over the IR.
assert GltfImporter().to_ir(gltf_bytes) == doc

Mesh geometry is fully decoded into plain JSON arrays (positions, indices) — no opaque binary buffers — so an agent can read and edit the scene directly.

Round-trip a FreeCAD model

Import a FreeCAD .FCStd mechanical model, work with the feature tree as JSON, and export it back:

from forgelab.importers.mechanical import FreeCADImporter
from forgelab.exporters.mechanical import FreeCADExporter

source = open("examples/mechanical/box-with-hole.FCStd", "rb").read()

doc = FreeCADImporter().to_ir(source)         # .FCStd -> ForgeDocument
features = [n.id for n in doc.nodes if n.type in ("pad", "pocket")]
print(features)                               # ['Pad', 'Pocket']

fcstd_bytes = FreeCADExporter().from_ir(doc)  # ForgeDocument -> .FCStd

# The round-trip is stable: import -> export -> import is an identity over the IR.
assert FreeCADImporter().to_ir(fcstd_bytes) == doc

The parametric feature tree — parts, bodies, sketches with dimensions, pads (extrusions) and pockets (cuts) — is captured as plain JSON nodes with link references, so an agent can read and edit the model directly. Parsing uses only the standard library (zipfile + xml.etree), so no FreeCAD installation is required.

Exported .FCStd files use FreeCAD's real document schema and open directly in FreeCAD — shapes recompute from the parametric definitions on load (validated against FreeCAD 1.1). The importer also reads genuine FreeCAD-authored files (canonical subset: parts, bodies, sketches with line/circle geometry and dimensional constraints, pads, pockets — Origin planes/axes and other unmodeled objects are skipped). The IR round-trip identity is preserved via a ForgeLab.Document.xml sidecar entry that FreeCAD ignores.

Run the compiler service

ForgeLab also ships as a compiler-as-a-service so agents can call it over HTTP:

uvicorn forgelab.api.app:app --reload
MethodPathPurpose
GET/healthLiveness + spec version
GET/specForgeDocument JSON Schema
POST/validateValidate a ForgeLab document
POST/export/{tool}Export IR to a tool's format

Authentication (optional)

The REST API and the MCP server's HTTP transport can be protected with OAuth 2.0. It is off by default. Enable it with environment variables:

export FORGELAB_AUTH_ENABLED=true       # turn auth on
export FORGELAB_AUTH_MODE=dev           # built-in dev issuer (HS256)
# or point at an external IdP:
# export FORGELAB_AUTH_MODE=jwks
# export FORGELAB_AUTH_ISSUER=https://your-idp/
# export FORGELAB_AUTH_AUDIENCE=forgelab
# export FORGELAB_AUTH_JWKS_URL=https://your-idp/.well-known/jwks.json

Get a token from the built-in dev server and call a protected endpoint:

TOKEN=$(curl -s -X POST localhost:8000/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=forgelab-dev -d client_secret=forgelab-dev-secret \
  -d scope="forge:read" | jq -r .access_token)

curl -s -X POST localhost:8000/validate \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d @doc.forge.json

Scopes: forge:read (validate/spec/schema), forge:export (import/export), forge:generate (AI generation). Install with pip install "forgelab[auth]".

MCP server (optional)

ForgeLab ships an MCP server so agents (Claude Code, Hermes, OpenClaw) can use it directly. Install the extra and run it:

pip install "forgelab[mcp]"

# Local (stdio, no auth):
forgelab-mcp --transport stdio

# Remote (Streamable HTTP, OAuth-protected — reuses FORGELAB_AUTH_* config):
FORGELAB_AUTH_ENABLED=true forgelab-mcp --transport streamable-http --port 8001

Tools: validate_document, get_domain_schema, get_prompt, list_domains, list_formats (scope forge:read); export_document, import_file (forge:export); generate_document (forge:generate). Over stdio all tools are available locally; over HTTP each tool requires its scope on the bearer token. generate_document needs a server-side ANTHROPIC_API_KEY and returns a clear error if it is unset. For HTTP discovery metadata you may also set FORGELAB_MCP_ISSUER_URL (the OAuth authorization server) and FORGELAB_MCP_RESOURCE_URL (this server's public URL).

How it works

A ForgeLab document is a small typed envelope — forgelab_version, domain, meta — wrapping a generic graph of Node objects. Domain vocabularies layer on top of that graph: a hardware board, for example, is a board node plus net and component nodes, each carrying a validated typed payload in its props.

.kicad_pcb ──▶ KiCadImporter ──▶ ForgeDocument ──▶ KiCadExporter ──▶ .kicad_pcb
                                   (validate / transform)

Importers and exporters depend only on the spec and on shared format primitives (forgelab.formats, e.g. the S-expression parser) — never on each other. That keeps every tool an independent, testable plugin and makes adding the next one a contained change.

Repository layout

forgelab/
├── spec/        # IR models (Pydantic v2), versioning, JSON Schema export, domain vocabularies
├── core/        # validate(), registry, compiler pipeline, errors
├── formats/     # shared, zero-dependency format primitives (S-expression, glTF, FCStd)
├── importers/   # tool → IR  (base ABC + per-domain packages; KiCad, glTF, FreeCAD implemented)
├── exporters/   # IR → tool  (base ABC + per-domain packages; KiCad, glTF, FreeCAD implemented)
├── sdk/         # AI agent helpers (schemas, prompts, validation, ForgeAgent)
├── auth/        # shared OAuth 2.0 (token verification, dev authorization server, scopes)
├── mcp/         # MCP server (stdio + OAuth-protected Streamable HTTP)
├── api/         # FastAPI compiler-as-a-service
└── cli.py       # `forgelab init` agent setup
scripts/         # one-line Claude Code installer
docs/            # agent bootstrap prompts, design specs and plans
examples/        # real sample designs (one native file + generated .forge.json per domain)
tests/           # pytest suite, including all three round-trip guarantees

Spec versioning

Every document carries a forgelab_version. Compatibility is major-based: a document validates against any library sharing its major version. The current spec is v0.5.0 (SPEC_VERSION in forgelab/spec/version.py). Any change to the ForgeDocument root or a breaking change to a domain vocabulary bumps the version — see CONTRIBUTING.md and CHANGELOG.md.

Project status

Pre-alpha (v0.1 of the library, v0.5.0 of the spec). The IR, validator, compiler pipeline, API, three end-to-end round-trips — the KiCad .kicad_pcb (hardware), the glTF .gltf (3D / game), and the FreeCAD .FCStd (mechanical CAD) importer/exporter pairs — the AI SDK (schema export, prompt templates, output validation, and a Claude-backed ForgeAgent), the OAuth 2.0 auth module, and the MCP server (stdio + Streamable HTTP) all work and are covered by tests. The remaining tool integrations are scaffolded stubs awaiting implementation. APIs may change before 1.0.

Roadmap

  • Core IR, validator, registry, and compiler pipeline
  • AI SDK and FastAPI compiler service
  • Typed hardware vocabulary + S-expression format primitive
  • KiCad .kicad_pcb importer/exporter round-trip
  • 3D / Game: Blender via glTF round-trip (meshes, materials, scene hierarchy)
  • Hardware: Gerber and Altium
  • Mechanical CAD: FreeCAD .FCStd importer/exporter round-trip
  • Shared OAuth 2.0 auth (scopes, dev authorization server, JWKS verification)
  • MCP server (stdio + OAuth-protected Streamable HTTP) for Claude Code / Hermes / OpenClaw
  • Multi-tool workflow support (export_document output_path + FORGELAB_OUTPUT_DIR)
  • Zero-friction agent setup (one-line installer, forgelab init CLI, agent bootstrap prompts)
  • Publish to PyPI so pip install forgelab works without cloning the repo
  • Mechanical CAD: Fusion 360
  • 3D / Game: Unreal Engine, glTF textures/animations, and .glb binary container
  • Transform passes (e.g. design-rule checks, layer remaps) over the IR
  • HTTP /import endpoint and a CLI

Contributing

Contributions are welcome — see CONTRIBUTING.md. The highest-leverage starting point is implementing an importer/exporter for one tool against the Importer/Exporter base classes; the KiCad pair is a complete worked example to model new tools on.

ruff check . && ruff format --check . && pyright && pytest

License

Apache 2.0.

Ver o original no GitHub

Bom para

Relacionados