@waelio/builder

Utilising all the tools to build websites, according to blueprints.

Architecture

The builder repo contains:

• Builder Server — Express webhook server + UI that scaffolds projects from blueprint payloads and hosts generated Siforge ready-sites
• Readysites — Five framework-specific starter templates (Nest, Next, Nitro, Nuxt, PHP/Laravel)
• Agent Server — MCP-compatible agent launcher using @waelio/agent backed by Ollama

Quick Start

Install dependencies

pnpm install

Run the builder server

pnpm dev

Build for production

pnpm build
pnpm start

Start the MCP server

pnpm mcp

Start the local agent UI

pnpm agent

Useful development commands

pnpm mcp:dev
pnpm agent:dev
pnpm coder:dev
pnpm typecheck
pnpm test

Start Ollama with GPU

For optimal performance, start Ollama with GPU acceleration enabled:

# Use GPU (macOS Metal, NVIDIA CUDA, AMD ROCm)
OLLAMA_NUM_GPU=1 ollama serve

# Or use all GPUs if you have multiple
OLLAMA_NUM_GPU=-1 ollama serve

Available Scripts

Script	Description
pnpm dev	Start dev server with hot-reload (tsx)
pnpm build	Compile TypeScript to dist/
pnpm start	Run compiled production build
pnpm clean	Remove dist/ directory
pnpm mcp	Run the compiled MCP server
pnpm mcp:dev	Run the MCP server from source with watch
pnpm agent	Run the compiled agent backend server
pnpm agent:dev	Run the agent backend server from source with watch
pnpm coder:dev	Run the local coder from source with watch

Readysites

Each readysite is an independent project under readysites/. They have their own package.json and dependencies.

Starting All Readysites

# Install each project's dependencies first (one-time)
cd readysites/nest  && pnpm install --ignore-workspace && pnpm approve-builds @nestjs/core unrs-resolver
cd readysites/next  && pnpm install --ignore-workspace && pnpm approve-builds sharp unrs-resolver
cd readysites/nuxt  && pnpm install  # uses its own pnpm-workspace.yaml with catalogs
cd readysites/nitro && pnpm install --ignore-workspace

# Start all on separate ports
PORT=3000 pnpm run dev                                              # Builder
cd readysites/nest  && PORT=3001 pnpm run start:dev                 # Nest
cd readysites/next  && npx next dev -p 3002                         # Next
cd readysites/nuxt  && npx nuxt dev --port 3003                     # Nuxt
cd readysites/nitro && npx nitro dev --port 3004                    # Nitro

Port Map

Service	Port	URL	Framework
Builder	3000	http://localhost:3000	Express + tsx
Nest	3001	http://localhost:3001	NestJS 11
Next	3002	http://localhost:3002	Next.js 16 (Turbo)
Nuxt	3003	http://localhost:3003	Nuxt 4 + Vite 8
Nitro	3004	http://localhost:3004	Nitro 2
Agent	3005	http://localhost:3005	@waelio/agent PWA
PHP	8000	http://localhost:8000	Laravel (Docker)

PHP / Laravel (Docker)

The PHP readysite runs via Docker Compose:

cd readysites/php/agent-app
docker compose up -d    # Starts PHP-FPM + Nginx on port 8000

Blueprint Webhook API

POST /webhooks/blueprints

Scaffolds one or more projects from a blueprint payload and builds hosted ready-site artifacts under readysites/ready-sites/.

Request:

{
  "projects": [{ "name": "my-app" }, { "name": "dashboard" }]
}

Response (202):

{
  "message": "Blueprint accepted",
  "projects": ["/path/to/projects/my-app", "/path/to/projects/dashboard"],
  "sites": [
    {
      "name": "my-app",
      "projectPath": "/path/to/projects/my-app",
      "readySitePath": "/path/to/readysites/ready-sites/my-app",
      "url": "http://localhost:3000/ready-sites/my-app/"
    }
  ]
}

The webhook also accepts Siteforge-style single-site payloads when projects is omitted. The first non-empty value from project.name, project.title, site.name, site.site_name, site.domain, site_name, or siteName is used as the project name.

Each scaffolded project gets:

• Template files from templates/project-template/
• gent.md — agent scaffold descriptor
• waelio.tools.json — CLI tools configuration
• Required files: ABOUT, CONTACT, CASL.AUTH, MONGODB, ORM, SEO
• A hosted Siforge ready-site at /ready-sites/<project-name>/

Agent PWA Server (HTTP)

The waelio-agent-server.js serves the @waelio/agent PWA and acts as a backend adapter between the agent's web-based chat UI and your local Ollama instance.

• Serves the @waelio/agent PWA as static files on port 3005.
• Translates /run_sse requests into Ollama /api/chat calls.
• Lists available Ollama models via /models → Ollama /api/tags.

To start the PWA backend standalone:

AGENT_PORT=3005 node waelio-agent-server.js

Then open http://localhost:3005 in your browser to chat with the agent UI.

---

Model Context Protocol (MCP) Server

The actual Model Context Protocol (MCP) server runs on stdio transport and exposes project scaffolding and Ollama generation tools directly to AI clients like Cursor or Claude Desktop.

Configuration for AI Clients (Claude Desktop / Cursor)

To register this MCP server, add the following to your mcp_config.json (or claude_desktop_config.json):

1. Local Development (Absolute Path)

{
  "mcpServers": {
    "waelio-builder": {
      "command": "node",
      "args": [
        "/Users/waelio/Code/GitHub/waelio/builder/dist/src/mcp-server.js"
      ],
      "env": {
        "OLLAMA_URL": "http://127.0.0.1:11434",
        "OLLAMA_MODEL": "qwen3:8b"
      }
    }
  }
}

2. Via NPM (Global Command)

Once published or globally linked, you can run the binary directly:

{
  "mcpServers": {
    "waelio-builder": {
      "command": "npx",
      "args": ["-y", "@waelio/builder", "waelio-builder-mcp"],
      "env": {
        "OLLAMA_URL": "http://127.0.0.1:11434",
        "OLLAMA_MODEL": "qwen3:8b"
      }
    }
  }
}

Project Structure

builder/
├── src/
│   ├── index.ts              # Express server + webhook endpoint
│   └── project-scaffold.ts   # Project scaffolding logic
├── dist/                     # Compiled JS output (gitignored)
├── public/
│   └── index.html            # Builder UI
├── templates/
│   └── project-template/     # Base template for scaffolded projects
├── readysites/
│   ├── nest/                 # NestJS starter
│   ├── next/                 # Next.js starter
│   ├── nitro/                # Nitro starter
│   ├── nuxt/                 # Nuxt 4 starter
│   └── php/                  # Laravel + Docker starter
├── waelio-agent-server.js    # MCP agent launcher (Ollama)
├── package.json
└── tsconfig.json

Environment Variables

Variable	Default	Description
PORT	3000	Builder server port
WAELIO_BUILDER_ROOT	process.cwd()	Override repo root path
WAELIO_BUILDER_URL	http://localhost:3000	Public builder URL for MCP ready-site links
WAELIO_MODEL	ollama	Agent model backend
OLLAMA_URL	http://127.0.0.1:11434	Ollama API endpoint
OLLAMA_MODEL	llama3:70b	Model to use with Ollama

License

GPL-3.0-or-later