sprucelab

Agent-first surface for Sprucelab. One install ships a typed CLI and an MCP server — both wrapping the same public HTTP API. Drop in whichever transport your agent host speaks.

pip install sprucelab

Two transports, one package

sprucelab — typed CLI

For terminal-resident agents (Claude Code, Aider, anything that drives a shell) and humans at the prompt. Every command supports --json for machine-readable output; mutations support --dry-run where applicable.

sprucelab auth register --token <YOUR_KEY> --url https://www.sprucelab.io
sprucelab projects list --json
sprucelab files upload ./models/foo.ifc --project-id <uuid> --wait
sprucelab verify --model-id <uuid> --dry-run

Agents move through sprucelab faster than humans do — the rendering is for humans; agents read the JSON. Once an agent has worked out the right sequence of calls, the same commands run unattended from cron / GitHub Actions / Airflow without burning tokens — that's the whole point of headless-first. The AI budget stays reserved for actual reasoning work (claim extraction, type classification, verification), not for re-deriving the same script every run. See sprucelab --help for the full command tree.

sprucelab-mcp — MCP server over stdio

For host-resident agents (Claude Desktop, Cursor, Continue, …) that launch tools as subprocesses and call them as typed tool calls.

{
  "mcpServers": {
    "sprucelab": {
      "command": "sprucelab-mcp",
      "env": {
        "SPRUCELAB_API_URL": "https://www.sprucelab.io",
        "SPRUCELAB_API_TOKEN": "your-token-here"
      }
    }
  }
}

The MCP server is a thin wrapper over the same HTTP surface the CLI talks to — the one advertised at https://www.sprucelab.io/api/capabilities/. No custom protocol, no surprises. If a tool fails, the error body is the literal API response.

Auth

Read-only discovery (capabilities, agent_tools_manifest, EIR catalog, EIR presets) works without auth on either transport. Everything else needs a token.

Get one via the web app at https://www.sprucelab.io/agents, then either:

sprucelab auth register --token <YOUR_KEY> --url https://www.sprucelab.io

…or set SPRUCELAB_API_TOKEN in the MCP env block above. The CLI and the MCP server read the same token store.

For experimentation, the public sandbox token (read-only) is published on https://www.sprucelab.io/agents.

MCP tools

Read-only discovery (no auth):

Projects + EIR (Bearer):

Models + types + verification (Bearer):

Files (Bearer):

Issues + scopes (Bearer):

Webhooks (Bearer):

Local-dev surface (sprucelab dev …)

The CLI also ships a dev subcommand that bypasses the API and talks directly to a local Django install — for working on Sprucelab, not against prod. Same agent-first invariants (--json everywhere, --dry-run on mutations).

sprucelab dev env                                        # repo + service status
sprucelab dev db stats --json                            # row counts for key tables
sprucelab dev db materials --project <uuid> --top 15     # top materials per project
sprucelab dev seed materials --project <uuid> --dry-run  # preview seed plan
sprucelab dev test tsc                                   # frontend type-check
sprucelab dev test e2e materials --headed                # Playwright smoke

Powered by

Sprucelab's IFC extraction layer is powered by ifcfast — 25–47× faster than ifcopenshell on production IFCs. See https://www.sprucelab.io/benchmarks.