mcp-server-dalux

MCP server for the Dalux Build API — the official API covering Dalux Field (tasks, safety issues, forms/checklists, inspection & test plans) and Dalux Box (document file areas, folders, files, version sets).

What it can do

Read (always on): projects, project users, tasks/approvals/safety issues + incremental change feed + attachments, forms + attachments, inspection/test plans (items, zones, registrations), work packages, file areas/folders/files, version sets, file download (size-capped), companies (project + account catalog), and dalux_search_capabilities for tool discovery.

Write (opt-in via DALUX_ENABLE_WRITES=true): file upload (3-step chunked flow), create/update companies, create/update projects.

Not possible through the Dalux API at all (as of Build API 4.15): creating or updating tasks and forms (Field data is read-only), user management, webhooks (poll the incremental change feeds instead), and BIM/model/geometry queries.

Auth

One X-API-KEY header. Keys are issued per API identity under Company profile → Settings → API identities, expire after a chosen validity period, and are scoped by the user groups the identity is assigned per project. API access itself is activated by Dalux support / your Customer Success Manager (requires a company license).

Configuration

See .env.example. Required: DALUX_API_KEY. Optional: DALUX_BASE_URL (defaults to https://field.dalux.com/service/api), DALUX_TIMEOUT_MS, DALUX_ENABLE_WRITES, DALUX_AUDIT_LOG (JSONL audit trail; identifiers are hashed).

Run

npm install
npm run dev          # stdio transport
npm run dev:http     # streamable HTTP on :3000/mcp (stateless)
npm test

Docker images are published to ghcr.io/borgels/mcp-server-dalux on every push to main.

Pagination

Dalux lists use opaque links only. Tools return { items, pagesFetched, nextPage, endOfIncrementalStream }; pass nextPage back as pageLink to continue. For incremental lists (tasks changes, forms, files), endOfIncrementalStream=true means you have caught up — keep the link and poll it later for deltas. Links are validated to stay on the API origin.