bldr

A lightweight, language-agnostic build daemon that exposes your project's build flows as MCP (Model Context Protocol) tools, letting an AI assistant like Claude drive builds, check status, and react to results without any project-specific plumbing.

Homepage: bldr-ecbf6d.gitlab.io (Next.js site in site/, built by bldr itself via bldr --project site/bldr.toml --flow build and published to GitLab Pages by .gitlab-ci.yml)

What it does

• Runs as a single long-lived process managing one or more projects.

• Each project is described by a bldr.toml that declares stages, flows, and optional capability plugins.

• Stages are shell commands; flows are ordered lists of stages.

• The daemon exposes FastMCP tools so an MCP client can trigger and monitor builds, manage worktrees, and invoke plugin actions.

• State is persisted in SQLite (XDG data dir) so build history survives restarts. Any record that was "running" at restart is marked "interrupted" -- the daemon never reports stale in-progress state.

• Per-project async locks mean projects build concurrently without stepping on each other.

• Projects can be added and removed at runtime via add_project / remove_project.

Related MCP server: xcsift-mcp

Architecture

                       one daemon, many projects
  MCP client (Claude) --> FastMCP tools (project-routed) --> ProjectRegistry
                                     |                            |
                               /status endpoint            per-project:
                               (GET, JSON)                 ProjectState + Lock
                                                           pipeline (flow runner)
                                                           runner (async shell)
                                                           plugins (Capabilities)
                                                                  |
                                                           SQLite (XDG data dir)

Concepts

Stages

A stage is a named shell command declared in [stages.<name>]:

Flows

A flow is an ordered list of stage names. When request_build is called:

• If nothing is running, the flow starts immediately.

• If the current stage is interruptible, the running flow is cancelled and the new flow starts.

• If the current stage is non-interruptible, the new request is queued and starts as soon as that stage finishes.

Plugins (Capabilities)

A plugin is a Python Capability subclass registered under [plugins.<key>] in bldr.toml. Plugins can:

• Start and stop background services (start() / stop()).

• Contribute named stage handlers used inside flows.

• Register MCP tools available to the AI client.

Worktrees

Worktrees are parallel isolated builds of the same project, backed by Git worktrees. Each worktree appears in the registry as <project>::<name> and gets its own plugin instances (with ephemeral ports to avoid conflicts).

MCP Tools

All project-scoped tools require a project argument (the value of name in [project]). There is no single-project mode; projects are always addressed by name.

Core tools

Worktree tools

Plugin tools

These tools are registered by their respective plugins and are only available when the project declares that plugin in its bldr.toml.

Configuration

Each project requires a bldr.toml. All paths are resolved relative to the config file unless absolute.

[project]
name = "my-app"
# root defaults to the directory containing bldr.toml.
root = "."

# Flows are ordered lists of stage names.
[flows]
build   = ["clean", "compile", "package"]
test    = ["clean", "compile", "test_suite"]
release = ["clean", "compile", "package", "artifact_publish"]

# Each stage must have a cmd. Other fields are optional.
[stages.clean]
cmd           = "rm -rf build dist"
interruptible = true        # default

[stages.compile]
cmd           = "make -j4"
interruptible = false       # queues new requests until this stage finishes
timeout       = 120         # seconds; omit to disable

[stages.package]
cmd           = "make dist"

[stages.test_suite]
cmd           = "pytest -q"
timeout       = 300
# cwd = "../other-dir"   # per-stage working directory override

# -- Plugins --

# artifact_http: copy build outputs to a served directory.
# Adds an "artifact_publish" stage handler and a "list_artifacts" MCP tool.
[plugins.artifact_http]
dir       = "artifacts"              # relative to project root
port      = 9099                     # 0 = ephemeral port
bind      = ["127.0.0.1"]
keep      = 10                       # prune oldest beyond this count
artifacts = ["build/my-app.tar.gz", "build/index.html"]

# web_serve: serve a build directory with Cache-Control: no-store.
# Adds a "serve" MCP tool.
[plugins.web_serve]
build_dir = "build"
port      = 8100
bind      = ["127.0.0.1"]

# screenshot: headless-browser screenshots via Playwright.
# Adds "screenshot_build" and "compare_screenshot" MCP tools.
[plugins.screenshot]
viewport       = [412, 915]   # [width, height] in pixels (default)
out_dir        = "screenshots"
diff_threshold = 0.01         # fraction of changed pixels to count as mismatch
noise          = 30           # per-channel delta below which a pixel is "same"

# demo_deploy: copy a build directory into a target git repo and commit.
# Adds a "demo_deploy" stage handler and a "request_demo_deploy" MCP tool.
[plugins.demo_deploy]
build_dir         = "build"
target_repo       = "/path/to/pages-repo"
target_subdir     = "."           # subdirectory inside target_repo
base_href         = "/my-app/"    # patches <base href> in index.html
page_title        = "My App"      # patches <title>
page_description  = "My demo"     # patches <meta name="description">
commit_message    = "Deploy demo via bldr"
branch            = "main"

Key rules:

• Every stage name referenced in a flow must have a [stages.<name>] entry OR be provided by a plugin's stage_handlers().

• An unknown or broken plugin is logged and skipped; it does not crash the daemon.

Built-in Plugins

artifact_http

Copies matched glob patterns from the project root into a served directory, renames each by the name template, prunes the oldest files beyond keep, and serves the directory over plain HTTP (with no index.html, the default Python http.server directory listing). Bind it to a LAN/VPN address and any machine can browse the directory and download artifacts.

The name template builds each published filename from these placeholders: {name} (original basename), {stem}, {ext} (incl. the dot), {project}, {branch} (sanitized), {sha} (short git hash), {ts} (YYYYMMDD-HHMMSS). The default "{name}" keeps the basename (each build overwrites the last). A template like "{project}-{branch}-{ts}-{sha}{ext}" makes every build a distinct file, so the whole build history accumulates and stays browsable over HTTP (bounded by keep). Different artifact kinds (e.g. .apk and .aab) are kept apart by {ext}. The git branch/sha are read from the project root, so a worktree publishes under its own branch.

Stage handler: artifact_publish -- copies + renames matching files, logs their URLs. MCP tool: list_artifacts(project) -- returns sorted filenames in the directory.

web_serve

Serves a build directory with Cache-Control: no-store so browsers always fetch the latest build. Restarts the server each time the serve tool is called.

MCP tool: serve(project) -- restarts the server and returns its URL(s).

screenshot

Uses Playwright (Chromium, headless) to capture screenshots and run pixel-diff regression checks. Requires playwright and Pillow to be installed.

MCP tools:

• screenshot_build(project, url, wait_seconds, width, height) -- captures and saves a PNG.

• compare_screenshot(project, url, baseline_name, save_baseline, diff_threshold, wait_seconds, width, height) -- compares to a saved baseline; saves a diff image on mismatch.

demo_deploy

Copies a build directory into a separate git repository (e.g. a GitLab Pages repo), optionally patches index.html (base href, title, description), commits the change, and optionally pushes.

Stage handler: demo_deploy -- deploys without pushing (commit only). MCP tool: request_demo_deploy(project, push=False) -- deploy on demand; set push=True to also push to the remote.

Security note: artifact_http and web_serve are unauthenticated static file servers. They default to loopback (127.0.0.1). Setting a non-loopback bind address (e.g. 0.0.0.0) exposes served files to anyone on the network -- use that option only on trusted networks.

Plugin authoring

Subclass Capability, implement the hooks you need, then call register_capability with an optional module-level tool registrar.

from bldr.plugins.base import Capability, register_capability


class MyPlugin(Capability):
    name = "my_plugin"

    def __init__(self, project_config, options: dict):
        super().__init__(project_config, options)
        # project_config.root is the absolute path to the project directory.
        # options is the dict from [plugins.my_plugin] in bldr.toml.
        self.port = int(options.get("port", 8080))

    async def start(self) -> None:
        # Start a background service (e.g. an HTTP server). Optional.
        pass

    async def stop(self) -> None:
        # Tear down the background service. Optional.
        pass

    def stage_handlers(self) -> dict:
        # Return a mapping of stage name -> async callable.
        # The pipeline calls: await handler(registered_project, build_record)
        async def my_stage(rp, rec) -> None:
            rp.state.log("running my_stage")
        return {"my_stage": my_stage}


def register_tools(mcp, lookup):
    # MCP tools are registered once per plugin TYPE, not per project instance.
    # Use lookup(project, "my_plugin") to resolve the per-project capability.
    @mcp.tool()
    async def my_tool(project: str) -> dict:
        cap = lookup(project, "my_plugin")
        if cap is None:
            return {"error": f"project '{project}' has no my_plugin"}
        return {"port": cap.port}


register_capability("my_plugin", MyPlugin, register_tools)

The register_tools(mcp, lookup) function is called once at daemon startup. The lookup(project, cap_name) helper resolves the named capability for any registered project. Tool names must be globally unique across all plugins.

Running

# Start with one project pre-loaded
bldr --project path/to/bldr.toml

# Start with multiple projects
bldr --project proj-a/bldr.toml --project proj-b/bldr.toml

# Start empty; add projects via the add_project MCP tool at runtime
bldr

# Custom host/port (default: 127.0.0.1:7900)
bldr --host 0.0.0.0 --port 8000 --project bldr.toml

The --project flag is repeatable and optional. Projects can also be registered and removed at runtime via the add_project and remove_project MCP tools.

TUI monitor

bldr-tui is a live, interactive monitor (Textual). It polls the daemon's /status endpoint and shows a multi-pane view for the selected project:

• a status bar (stage icon/color, current message, elapsed time, pending),

• a streaming build log and web-server log,

• a projects/worktrees pane (status, port, branch, commit; worktrees nested under their parent),

• a build-history pane.

bldr-tui                          # connects to http://127.0.0.1:7900
bldr-tui --url http://host:8000   # custom daemon address

Keys: j/k select project/worktree, b build (prompts for flow), w new worktree, d remove worktree, r refresh, c clear, n toggle desktop notifications, a toggle browser auto-reload (reloads pages of a Chrome started with --remote-debugging-port=9222 when a build finishes), R reload now, q quit. Actions are performed over MCP. Requires textual (a dependency); the view refreshes every 1.5 s.

CLI client (bldr-cli)

bldr-cli is a command-line client for the daemon's MCP tools: each tool is a subcommand, positional args fill the tool's parameters in schema order, key=value sets a named one, and values are JSON-coerced (numbers, booleans, null, arrays, objects). Output is pretty-printed JSON; pass -j/--json for compact single-line output.

bldr-cli --help                         # usage + all tools + aliases
bldr-cli tools                          # list tools and their parameters
bldr-cli ls                             # list_projects
bldr-cli st kairos                      # get_status kairos (pretty)
bldr-cli build kairos web               # request_build project=kairos flow=web
bldr-cli request_demo_deploy kairos push=true
bldr-cli screenshot_build kairos http://127.0.0.1:8010
bldr-cli -j ls                          # compact JSON (scripting)

Aliases: ls=list_projects, st/status=get_status, build=request_build, add=add_project, rm=remove_project. The daemon URL defaults to $BLDR_URL or http://127.0.0.1:7900/mcp (override with --url).

Status endpoint

GET /status on the daemon returns a JSON snapshot of all projects -- the same data the TUI polls. Useful for scripting or health checks.

Bundled example

example-project/ exercises the full pipeline without any external toolchain:

example-project/
  bldr.toml        # build + release flows, artifact_http plugin
  build.sh         # copies site/ into build/
  site/
    index.html

Flows:

• build -- runs clean then build_site (produces build/index.html).

• release -- runs clean, build_site, then artifact_publish (copies the file into artifacts/ and serves it over HTTP on an ephemeral port).

cd example-project
bldr --project bldr.toml
# then call request_build("example-site", "release", "manual test") via MCP

Testing

pip install -e ".[dev]"
pytest

70 tests covering the pipeline, registry, plugins, worktrees, CLI, TUI, and end-to-end integration.