ifcx-mcp

# IFCX MCP A [Model Context Protocol](https://modelcontextprotocol.io) server for creating IFC5 / IFCX building information models through AI assistants. You don't interact with this server directly. You connect it to an MCP client such as [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Claude Desktop](https://claude.ai/download), or any other MCP-compatible client, and then use natural language to author BIM models. The project targets the IFCX examples and tooling style used in the IFC5 development work: alpha JSON `.ifcx`, post-alpha tiered `index.ifcx` with NDJSON tables, and zipped post-alpha `.ifcx` packages. ## What It Can Do The server keeps IFCX drafts in memory while it is running. A client can then drive the model through a normal authoring flow: 1. Create a model with standard IFCX imports and provenance. 2. Add `Project > Site > Building > Storey > Space`. 3. Create reusable type nodes, such as wall, window, and pipe segment types. 4. Create element occurrences and attach them to the spatial tree. 5. Instantiate occurrences from types. 6. Attach mesh, BRep, curve, and procedural geometry hints. 7. Use richer authoring factories for walls from axes, windows with voids, pipe networks with ports, and storey grids. 8. Add material, PBR material data, current IFC5 standard properties, classifications, bSDD references, and georeferencing. 9. Create patch layers and explain their effect. 10. Validate references, cycles, mesh indices, IFClite IFCX parsing, and IDS rules. 11. Preview a viewer-shaped tree and export glTF / Three.js preview artifacts. 12. Write alpha JSON, tiered IFCX, or zipped post-alpha IFCX. 13. Dry-run or perform a layer-version publish to an IFCX layer API. ## Install ```bash git clone https://github.com/louistrue/ifcx-mcp.git cd ifcx-mcp npm install npm run build ``` ## MCP Client Configuration Add the server to your MCP client using stdio transport. Change the path to wherever you cloned the repository. **Claude Code** (`~/.claude/settings.json` or project `.mcp.json`): ```json { "mcpServers": { "ifcx": { "command": "node", "args": ["/path/to/ifcx-mcp/dist/server.js"] } } } ``` **Claude Desktop** (`claude_desktop_config.json`): same format. The server starts automatically when the MCP client launches. For local development without an MCP client: ```bash npm run dev ``` ## Usage Guide Once the server is connected to your MCP client, you author models through natural language. The AI assistant translates your requests into the appropriate tool calls. ### Creating a Model > "Create an IFCX model called Campus" Initializes an in-memory draft with standard IFC imports and provenance tracking. ### Building Spatial Structure > "Add a project with a site, a building called HQ, and two storeys: Ground Floor at 0m and First Floor at 3.5m" Creates the full `IfcProject > IfcSite > IfcBuilding > IfcBuildingStorey` hierarchy. ### Adding Elements > "Create a concrete wall type with 200mm thickness, then place exterior walls around a 20x12m rectangle on the ground floor" You can work at different levels of detail: - **Low-level** — create a type, then elements, then attach geometry separately. - **Rich factories** — create walls from axis lines, windows with automatic void cutting, pipe networks with distribution ports, or storey grids, all in one step. ### Attaching Geometry Four geometry representations are supported: - **Mesh** — vertices and face indices (triangulated surfaces). - **Procedural** — extrude, sweep, revolve, or boolean hints. - **BRep** — OCCT BREP or STEP AP242 payloads. - **Curves** — polylines, arcs, circles, B-splines, or composite curves. ### Adding Metadata > "Classify all walls as Uniclass Ss_25_10_30 and resolve via bSDD" - **Materials** with optional PBR data (roughness, metalness, color). - **Classifications** (CCI, NL-SfB, Uniclass) with live bSDD resolution. - **Georeferencing** via EPSG codes or WKT. - **Patch layers** for delta/change tracking over a base model. ### Validating > "Validate my model" Runs a multi-stage pipeline: schema validation, composition checks, reference integrity, geometry sanity, and adapter-level IFClite/IFCX-core checks. You can also run IDS validation and convert issues into BCF topics. For export checks, use `ifcx_validate_ifc5_compliance`. That tool validates the sanitized IFC5 alpha output shape against the current IFC5 development schema/import conventions. The older `ifcx_validate_viewer_compatibility` name is kept as an alias for existing clients, but the buildingSMART viewer is not treated as the target spec. ### Previewing > "Show me a preview of the model" Returns a viewer-shaped tree and scene summary. You can also export: - **glTF** — `scene.gltf` + `scene.bin` for any 3D viewer. - **Three.js** — self-contained `index.html` you can open in a browser. ### Exporting > "Write the model in tiered format to ./output/" Three output formats are available: alpha JSON (single `.ifcx`), tiered (`index.ifcx` + NDJSON tables), and zipped post-alpha (`.ifcx` ZIP package). ### Planning > "Plan a model for a hospital wing with mechanical systems" The planner analyzes your intent and returns a step-by-step authoring plan with IDs, layers, types, geometry tiers, and an ordered tool-call recipe — without modifying any draft. ### Typical Conversation ``` You: Create an IFCX model for a small school campus You: Add a site, one building with 2 storeys (ground at 0m, first at 4m) You: Create a concrete wall type, then place exterior walls around a 20x12m rectangle on the ground floor You: Add 4 windows evenly spaced on the south wall You: Add a DHW pipe network running east-west at ceiling level You: Classify all walls as Uniclass Ss_25_10_30 and resolve via bSDD You: Add georeferencing for Zurich (EPSG:2056) You: Validate the model and show me any issues You: Export a Three.js preview so I can check it in the browser You: Write the final model in tiered format to ./output/ ``` ### Things to Know - **Everything is in-memory.** Export your model before stopping the server. - **Session IDs** identify drafts. You can have multiple models open at once. - **bSDD lookups** are cached locally in `.ifcx-mcp-cache/bsdd/`. - **Publishing is safe by default** — dry-run mode unless you explicitly pass `dryRun: false`. - Ask to "list my drafts" or "show the model tree" at any time to see current state. ## Tools ### Drafts - `ifcx_capabilities` Report the available IFCX and IFClite adapter capabilities. - `ifcx_plan_model` Plan an authoring run from natural-language or structured intent. It returns IDs, layers, imports, types, elements, geometry tiers, schemas, write targets, and an ordered tool-call recipe. It does not mutate a draft. - `ifcx_create_model` Create an empty IFCX alpha draft with standard IFCX imports and provenance. - `ifcx_list_drafts` List drafts currently held by the running server process. ### IFC Structure - `ifcx_create_spatial_structure` Create a project/site/building/storey tree, optionally with a space. - `ifcx_create_type` Create a reusable type node, for example `IfcWallType`, `IfcWindowType`, or `IfcPipeSegmentType`. - `ifcx_create_element` Create an element occurrence with class, name, recognized IFC5 properties, material, placement, and an optional parent attachment. Legacy `properties` and `quantity` inputs are normalized into direct `bsi::ifc::prop::*` attributes when the current schema supports them. - `ifcx_instantiate_type` Create an occurrence that inherits from an existing type node. ### Geometry - `ifcx_create_geometry_mesh` Create a body node from `points` and `faceVertexIndices`, then attach it to an owner element. - `ifcx_create_geometry_proc` Create a procedural geometry hint, such as `extrude`, `sweep`, `revolve`, or `boolean`. - `ifcx_create_geometry_brep` Attach an OCCT BREP or STEP AP242 BRep payload to a node. - `ifcx_create_geometry_curve` Attach a polyline, arc, circle, B-spline, or composite curve payload to a node. ### Rich Factories - `ifcx_create_wall_from_axis` Create a wall occurrence from a start/end axis, including direct IFC5 length/height properties, mesh body, material, and optional type inheritance. - `ifcx_create_window_with_void` Create a window occurrence and a procedural void hint tied to its host wall. - `ifcx_create_pipe_network_with_ports` Create a pipe sweep with start/end `IfcDistributionPort` nodes. - `ifcx_create_storey_grid` Create an `IfcGrid` with X/Y curve axes attached to a storey. ### Metadata Layers - `ifcx_create_material` Add material and optional PBR material data to a node. - `ifcx_create_classification_layer` Attach CCI, NL-SfB, bSDD, or other classification references. - `ifcx_resolve_bsdd_classification` Resolve IFC/bSDD classification data from cache, from live bSDD when `allowLive: true`, or as a deterministic offline URI. - `ifcx_create_georeference_layer` Add EPSG coordinate attributes and optional WKT CRS text. - `ifcx_create_patch_layer` Create a delta layer over an existing draft. The patch imports the base draft ID and contains only the requested changes. ### Validation And Preview - `ifcx_validate_created_model` Check missing references, repeated path opinions, cycles, missing local schemas, and mesh index sanity. Pass `engine: "ifcx-core"` or `engine: "ifc-lite"` to also run the IFClite IFCX parser/adapter. - `ifcx_validate_ifc5_compliance` Check the sanitized alpha export against the current IFC5 development imports and attribute shapes. Standard imported schemas stay imported; local schemas are only required for non-standard extension attributes. - `ifcx_validate_ids` Validate a draft against IDS XML using `@ifc-lite/ids`. The server builds an IFCX-backed accessor for entity type, properties, classifications, materials, and parents. - `ifcx_create_bcf_from_validation` Convert an IDS validation report into a serializable BCF topic summary using `@ifc-lite/bcf`. - `ifcx_preview_created_model` Return a composed, viewer-shaped tree plus summary counts and geometry bounds. ### Write And Publish - `ifcx_write_alpha` Write a single alpha JSON `.ifcx`. - `ifcx_write_tiered` Write `index.ifcx` plus NDJSON attribute tables. - `ifcx_write_zipped` Write a zipped post-alpha `.ifcx` package containing `index.json` and NDJSON tables. - `ifcx_write_bcf_from_ids` Validate a draft against IDS XML and write a `.bcfzip` issue package. - `ifcx_write_bcf_from_validation` Write a `.bcfzip` issue package from an existing IDS validation report. - `ifcx_export_preview_gltf` Export a simple glTF preview folder with `scene.gltf`, `scene.bin`, and `preview-manifest.json`. - `ifcx_export_preview_threejs` Export a Three.js preview folder with `index.html` and the glTF scene. - `ifcx_publish_layer_version` Publish a zipped draft to an IFCX layer API. This defaults to dry-run unless `dryRun: false` is passed. ### Layer History - `ifcx_explain_layer_history` Explain which node opinions introduced or overrode children, inherits, and attributes. - `ifcx_explain_patch_effect` Compare a base draft and patch draft, then report added, removed, and changed nodes/attributes. Some older tool names are kept as aliases while the interface settles, such as `ifcx_export_alpha`, `ifcx_export_tiered`, `ifcx_add_mesh_geometry`, and `ifcx_validate_draft`. ## Resources The server also exposes MCP resources: - `ifcx://drafts` Current in-memory draft summaries. - `ifcx://draft/{sessionId}/tree` Viewer-shaped composed tree for one draft. - `ifcx://draft/{sessionId}/scene` Scene summary with tree, mesh/procedural counts, and bounds. ## Integration Test The integration test [test/mcp-elaborate.test.ts](test/mcp-elaborate.test.ts) drives the complete authoring workflow through MCP calls. It creates a two-storey model with walls, windows, domestic hot water pipes, ports, mesh geometry, procedural geometry, BRep and curve payloads, a storey grid, material/PBR data, classifications, bSDD resolution, georeferencing, a patch layer, preview resources, glTF/Three.js preview artifacts, and all three IFCX write formats. ```bash npm run test:mcp ``` ## Output Formats Alpha JSON: ```text model.ifcx ``` Tiered: ```text index.ifcx ifcx.geom.mesh.ndjson ifcx.geom.brep.ndjson ifcx.geom.curve.ndjson ifcx.geom.proc.ndjson ifcx.semantics.ndjson ``` Zipped post-alpha: ```text model-post-alpha.ifcx ``` Preview: ```text scene.gltf scene.bin preview-manifest.json index.html ``` The zipped package contains: ```text index.json ifcx.geom.mesh.ndjson ifcx.geom.brep.ndjson ifcx.geom.curve.ndjson ifcx.geom.proc.ndjson ifcx.semantics.ndjson ``` BCF: ```text ids-validation.bcfzip ``` ## Publishing `ifcx_publish_layer_version` is intentionally conservative. By default: ```json { "dryRun": true } ``` In dry-run mode it validates the draft and returns the target URL, layer ID, generated version ID, and blob ID, but does not upload. With `dryRun: false`, it calls: ```text PUT {baseUrl}/ifcx-api/upload/{blobId} POST {baseUrl}/ifcx-api/layers/{layerId}/versions ``` Only use live publishing against an API endpoint you control. ## Development ```bash npm run check npm run test npm run test:mcp npm run build ``` `npm run test` tests the authoring kernel directly. `npm run test:mcp` builds the project, starts the MCP server over stdio with the SDK client transport, and drives the complete authoring workflow through MCP calls. ## Project Layout ```text src/server.ts MCP server and tool/resource registration src/ifcx-authoring/authoring-session.ts src/ifcx-authoring/alpha-builder.ts src/ifcx-authoring/tiered-builder.ts src/ifcx-authoring/element-factories.ts src/ifcx-authoring/geometry-factories.ts src/ifcx-authoring/advanced-geometry.ts src/ifcx-authoring/rich-factories.ts src/ifcx-authoring/planner.ts src/ifcx-authoring/preview-exporter.ts src/ifcx-authoring/layer-history.ts src/ifcx-authoring/validation-pipeline.ts src/ifcx-authoring/patch-builder.ts src/ifcx-authoring/writers.ts src/adapters/bsdd-adapter.ts src/adapters/ifc-lite-adapter.ts src/adapters/ifcx-core-adapter.ts test/authoring.test.ts test/mcp-elaborate.test.ts ``` The `src/ifcx/*` files are compatibility re-exports for early imports. New code should import from `src/ifcx-authoring`. ## Status This is early implementation work. It already creates valid draft structures and writes the current target formats, but the authoring vocabulary will keep expanding as the IFCX examples and layer API mature.