Skip to main content
Glama

IDS MCP Server

AI-powered creation of buildingSMART IDS files with 100% compliance

An MCP (Model Context Protocol) server that enables AI agents to deterministically create, validate, and manage Information Delivery Specification (IDS) files that are fully compliant with the buildingSMART IDS 1.0 standard.

ifc-ids-mcp MCP server

License: MIT Python 3.8+ Code style: black

Features

  • ✅ 100% IDS 1.0 Compliant - All exports validate against official XSD schema

  • ✅ IfcTester Integration - Uses the official IfcOpenShell library

  • ✅ FastMCP Context-Based Sessions - Automatic session management

  • ✅ Test-Driven Development - 95%+ code coverage with comprehensive tests

  • ✅ Deterministic Output - Same input always produces identical output

  • ✅ Type-Safe - Full type hints with Pydantic validation

Related MCP server: ifc-mcp

Quick Start

Installation

# Clone repository
git clone https://github.com/Quasar-Consulting-Group/ifc-ids-mcp.git
cd ifc-ids-mcp

# Install dependencies
pip install -r requirements.txt

# Install in development mode
pip install -e .

Usage with Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "ids-mcp": {
      "command": "python",
      "args": ["-m", "ids_mcp_server"],
      "env": {
        "IDS_LOG_LEVEL": "INFO"
      }
    }
  }
}

Programmatic Usage

from ifctester import ids

# The MCP server handles this automatically via tools
# But you can also use IfcTester directly:

# Create new IDS
my_ids = ids.Ids(title="Project Requirements")

# Add specification
spec = ids.Specification(name="Wall Requirements", ifcVersion=["IFC4"])
spec.applicability.append(ids.Entity(name="IFCWALL"))

requirement = ids.Property(
    baseName="FireRating",
    propertySet="Pset_WallCommon",
    cardinality="required"
)
spec.requirements.append(requirement)

my_ids.specifications.append(spec)

# Export to XML
my_ids.to_xml("requirements.ids")

Available MCP Tools

Document Management

  • create_ids - Create new IDS document

  • load_ids - Load existing IDS from file or XML string

  • export_ids - Export IDS to XML with validation

  • get_ids_info - Get document structure and metadata

Specification Management

  • add_specification - Add specification with IFC version and cardinality

Facet Management

Basic Facets

  • add_entity_facet - Add IFC entity type filter (e.g., IFCWALL)

  • add_property_facet - Add property requirements

  • add_attribute_facet - Add IFC attribute requirements

Advanced Facets

  • add_classification_facet - Add classification requirements

  • add_material_facet - Add material requirements

  • add_partof_facet - Add spatial relationship requirements

Restriction Management

  • add_enumeration_restriction - Constrain to list of valid values

  • add_pattern_restriction - Constrain with regex pattern

  • add_bounds_restriction - Constrain numeric ranges

  • add_length_restriction - Constrain string length

Validation

  • validate_ids - Validate IDS document against XSD schema

  • validate_ifc_model - Validate IFC model against IDS (bonus feature)

Early Validation & Constraint Checking

The MCP server includes early validation to catch IDS 1.0 schema violations immediately when tools are called, rather than waiting until export time. This provides AI agents with clear, actionable error messages.

IDS 1.0 Schema Constraints

1. Single Entity Facet per Applicability

Constraint: IDS 1.0 allows only ONE entity facet per specification's applicability section.

Early Validation: The add_entity_facet tool validates this constraint before adding the facet:

# ✅ CORRECT: First entity facet
add_entity_facet(spec_id="S1", location="applicability", entity_name="IFCWALL")

# ❌ INCORRECT: Second entity facet raises ToolError immediately
add_entity_facet(spec_id="S1", location="applicability", entity_name="IFCDOOR")
# Error: "IDS 1.0 XSD constraint violation: Only ONE entity facet is allowed..."

Workaround: Create separate specifications for each entity type:

# Specification 1: Walls
add_specification(name="Wall Requirements", ifc_versions=["IFC4"], identifier="S1")
add_entity_facet(spec_id="S1", location="applicability", entity_name="IFCWALL")

# Specification 2: Doors
add_specification(name="Door Requirements", ifc_versions=["IFC4"], identifier="S2")
add_entity_facet(spec_id="S2", location="applicability", entity_name="IFCDOOR")

2. Property Set Required for Property Facets

Constraint: IfcTester requires property_set parameter for valid IDS export.

Early Validation: The add_property_facet tool validates this requirement before adding the facet:

# ❌ INCORRECT: Missing property_set raises ToolError immediately
add_property_facet(
    spec_id="S1",
    location="requirements",
    property_name="FireRating"
)
# Error: "Property facet validation error: 'property_set' parameter is required..."

# ✅ CORRECT: Include property_set parameter
add_property_facet(
    spec_id="S1",
    location="requirements",
    property_name="FireRating",
    property_set="Pset_WallCommon"
)

Common Property Sets:

  • Pset_WallCommon - Wall properties

  • Pset_DoorCommon - Door properties

  • Pset_WindowCommon - Window properties

  • Pset_SpaceCommon - Space properties

  • Pset_Common - Custom/generic properties

Benefits of Early Validation

  1. Immediate Feedback - Errors caught at tool invocation, not export time

  2. Clear Error Messages - Includes workarounds and examples

  3. Prevents Invalid States - IDS documents stay valid throughout creation

  4. Better AI Agent Experience - Agents receive actionable guidance

See CLAUDE.md for detailed documentation on IDS 1.0 constraints.

Architecture

┌─────────────────────────────────────────────┐
│           AI Agent (Claude, GPT)             │
└────────────────────┬────────────────────────┘
                     │ MCP Protocol
┌────────────────────▼────────────────────────┐
│            FastMCP Server                    │
│  ┌──────────────────────────────────────┐   │
│  │     MCP Tools (15+ tools)            │   │
│  └───────────────┬──────────────────────┘   │
│  ┌───────────────▼──────────────────────┐   │
│  │     Session Manager (Context)        │   │
│  └───────────────┬──────────────────────┘   │
│  ┌───────────────▼──────────────────────┐   │
│  │  IfcTester Integration (IDS Engine)  │   │
│  └──────────────────────────────────────┘   │
└─────────────────────────────────────────────┘
                     │
                     ▼
        IDS XML File (100% XSD compliant)

Development

Test-Driven Development

This project strictly follows TDD methodology:

# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=src/ids_mcp_server --cov-report=html

# Run specific test category
pytest tests/unit/ -v        # Unit tests
pytest tests/integration/ -v  # Integration tests
pytest tests/validation/ -v   # XSD validation tests

# Must maintain 95%+ coverage
pytest tests/ --cov-fail-under=95

TDD Workflow (Red-Green-Refactor)

  1. RED - Write failing test

  2. GREEN - Implement minimum code to pass

  3. REFACTOR - Improve code quality

Example:

# RED: Write failing test
def test_create_specification():
    result = add_specification(name="Test", ifc_versions=["IFC4"])
    assert result["status"] == "success"

# GREEN: Implement
def add_specification(name, ifc_versions):
    return {"status": "success"}

# REFACTOR: Improve (keep tests passing)

Code Quality

# Format code
black src/ tests/

# Lint code
ruff check src/ tests/

# Type checking (optional)
mypy src/

Project Structure

ifc-ids-mcp/
├── src/
│   └── ids_mcp_server/
│       ├── __init__.py
│       ├── __main__.py
│       ├── server.py          # FastMCP server
│       ├── config.py          # Configuration
│       ├── version.py         # Version management
│       ├── session/           # Session management
│       │   ├── manager.py
│       │   ├── storage.py
│       │   ├── cleanup.py
│       │   └── models.py      # Session data models
│       └── tools/             # MCP tools (17 total)
│           ├── document.py
│           ├── specification.py
│           ├── facets.py
│           ├── restrictions.py    # Phase 007
│           ├── validation.py      # Phase 008
│           └── validators.py      # Early validation helpers
├── tests/                     # 168 tests, 94% coverage
│   ├── unit/                  # Unit tests
│   ├── component/             # Component tests
│   ├── integration/           # Integration tests
│   └── validation/            # XSD compliance tests
│       └── fixtures/          # Test fixtures
├── samples/                   # Sample IDS/IFC files
│   ├── wall_fire_rating.ids
│   └── walls-fire-rating.ifc
├── specs/                     # Implementation plans (PRDs)
├── .mcp.json                  # MCP server configuration
├── .coveragerc                # Coverage configuration
├── constitution.md            # Project principles
├── DESIGN_SPECIFICATION.md    # Technical specification
├── CLAUDE.md                  # AI agent guide
├── pyproject.toml
├── pytest.ini
└── README.md

Constitution Principles

This project follows 6 non-negotiable principles:

  1. 100% IDS Schema Compliance - All exports validate against XSD

  2. Test-Driven Development - 95%+ coverage, tests before code

  3. IfcTester Integration First - No custom XML generation

  4. Deterministic Generation - Identical input = identical output

  5. FastMCP Context-Based Sessions - Automatic session management

  6. Python Best Practices - Type hints, PEP 8, modern Python

See constitution.md for full details.

Documentation

Dependencies

Core

  • fastmcp - MCP server framework

  • ifctester - IDS authoring and validation (from IfcOpenShell)

  • pydantic - Data validation

Development

  • pytest - Testing framework

  • pytest-asyncio - Async test support

  • pytest-cov - Coverage reporting

  • black - Code formatting

  • ruff - Linting

References

License

MIT License - see LICENSE file for details

Contributing

  1. Read constitution.md for project principles

  2. Follow TDD methodology (Red-Green-Refactor)

  3. Ensure 95%+ test coverage

  4. All exports must validate against IDS 1.0 XSD

  5. Use IfcTester for all IDS operations

Support


Status: ✅ Implementation Complete | 94% Test Coverage | 17 MCP Tools | 168 Tests | Early Validation

Built with ❤️ using IfcOpenShell and FastMCP

Available Tools

17 tools
add_attribute_facetC

Add an attribute facet to a specification.

Args: spec_id: Specification identifier location: "applicability" or "requirements" attribute_name: Attribute name (e.g., "Name", "Description") ctx: FastMCP Context (auto-injected) value: Required value or pattern cardinality: "required", "optional", or "prohibited"

Returns: {"status": "added", "facet_type": "attribute", "spec_id": "S1"}

Inputs: spec_id (required), location (required), attribute_name (required), value, +1 more. Returns: object

add_bounds_restrictionB

Add numeric bounds restriction.

Args: spec_id: Specification identifier or name facet_index: Index of facet in location (0-based) parameter_name: Which parameter to restrict (e.g., "value") base_type: XSD base type (e.g., "xs:double", "xs:integer") ctx: FastMCP Context (auto-injected) location: "applicability" or "requirements" (default: "requirements") min_inclusive: Minimum value (inclusive) max_inclusive: Maximum value (inclusive) min_exclusive: Minimum value (exclusive) max_exclusive: Maximum value (exclusive)

Returns: {"status": "added", "restriction_type": "bounds", "spec_id": "S1"}

Example: Add bounds to property value: Height must be between 2.4 and 3.0 meters

Inputs: spec_id (required), facet_index (required), parameter_name (required), base_type (required), +5 more. Returns: object

add_classification_facetA

Add a classification facet to a specification.

Args: spec_id: Specification identifier location: "applicability" or "requirements" classification_value: Classification code or pattern ctx: FastMCP Context (auto-injected) classification_system: Classification system name or URI cardinality: "required", "optional", or "prohibited"

Returns: {"status": "added", "facet_type": "classification", "spec_id": "S1"}

Inputs: spec_id (required), location (required), classification_value (required), classification_system, +1 more. Returns: object

add_entity_facetA

Add an entity facet to a specification.

IMPORTANT: IDS 1.0 allows only ONE entity facet per applicability section. If you need multiple entity types, create separate specifications.

Args: spec_id: Specification identifier location: "applicability" or "requirements" entity_name: IFC entity name (e.g., "IFCWALL") ctx: FastMCP Context (auto-injected) predefined_type: Optional predefined type cardinality: "required", "optional", or "prohibited" (requirements only)

Returns: {"status": "added", "facet_type": "entity", "spec_id": "S1"}

Raises: ToolError: If trying to add second entity to applicability section

Inputs: spec_id (required), location (required), entity_name (required), predefined_type, +1 more. Returns: object

add_enumeration_restrictionA

Add enumeration restriction (list of allowed values).

Args: spec_id: Specification identifier or name facet_index: Index of facet in location (0-based) parameter_name: Which parameter to restrict (e.g., "value", "propertySet") base_type: XSD base type (e.g., "xs:string", "xs:integer") values: List of allowed values ctx: FastMCP Context (auto-injected) location: "applicability" or "requirements" (default: "requirements")

Returns: {"status": "added", "restriction_type": "enumeration", "spec_id": "S1"}

Example: Add enumeration to property value: FireRating must be "REI30", "REI60", or "REI90"

Inputs: spec_id (required), facet_index (required), parameter_name (required), base_type (required), +2 more. Returns: object

add_length_restrictionB

Add string length restriction.

Args: spec_id: Specification identifier or name facet_index: Index of facet in location (0-based) parameter_name: Which parameter to restrict (e.g., "value") base_type: XSD base type (e.g., "xs:string") ctx: FastMCP Context (auto-injected) location: "applicability" or "requirements" (default: "requirements") length: Exact length min_length: Minimum length max_length: Maximum length

Returns: {"status": "added", "restriction_type": "length", "spec_id": "S1"}

Example: Add length restriction to attribute value: Tag must be between 5 and 50 characters

Inputs: spec_id (required), facet_index (required), parameter_name (required), base_type (required), +4 more. Returns: object

add_material_facetB

Add a material facet to a specification.

Args: spec_id: Specification identifier location: "applicability" or "requirements" material_value: Material name, category, or URI ctx: FastMCP Context (auto-injected) cardinality: "required", "optional", or "prohibited"

Returns: {"status": "added", "facet_type": "material", "spec_id": "S1"}

Inputs: spec_id (required), location (required), material_value (required), cardinality. Returns: object

add_partof_facetC

Add a partOf facet to a specification.

Args: spec_id: Specification identifier location: "applicability" or "requirements" relation: Relationship type (e.g., "IFCRELCONTAINEDINSPATIALSTRUCTURE") parent_entity: Parent entity name (e.g., "IFCSPACE") ctx: FastMCP Context (auto-injected) parent_predefined_type: Optional predefined type for parent cardinality: "required", "optional", or "prohibited"

Returns: {"status": "added", "facet_type": "partof", "spec_id": "S1"}

Inputs: spec_id (required), location (required), relation (required), parent_entity (required), +2 more. Returns: object

add_pattern_restrictionA

Add pattern restriction (regex matching).

Args: spec_id: Specification identifier or name facet_index: Index of facet in location (0-based) parameter_name: Which parameter to restrict (e.g., "value") base_type: XSD base type (e.g., "xs:string") pattern: Regular expression pattern ctx: FastMCP Context (auto-injected) location: "applicability" or "requirements" (default: "requirements")

Returns: {"status": "added", "restriction_type": "pattern", "spec_id": "S1"}

Example: Add pattern to attribute value: Name must match "EW-[0-9]{3}"

Inputs: spec_id (required), facet_index (required), parameter_name (required), base_type (required), +2 more. Returns: object

add_property_facetA

Add a property facet to a specification.

IMPORTANT: The property_set parameter is REQUIRED for valid IDS export.

Args: spec_id: Specification identifier location: "applicability" or "requirements" property_name: Property name (e.g., "FireRating") ctx: FastMCP Context (auto-injected) property_set: Property set name (e.g., "Pset_WallCommon") - REQUIRED data_type: IFC data type (e.g., "IFCLABEL") value: Required value or pattern cardinality: "required", "optional", or "prohibited"

Returns: {"status": "added", "facet_type": "property", "spec_id": "S1"}

Raises: ToolError: If property_set is None or empty

Inputs: spec_id (required), location (required), property_name (required), property_set, +3 more. Returns: object

add_specificationB

Add a specification to the current session's IDS document.

Args: name: Specification name ifc_versions: List of IFC versions (e.g., ["IFC4", "IFC4X3"]) ctx: FastMCP Context (auto-injected) identifier: Optional unique identifier description: Why this information is required instructions: How to fulfill requirements min_occurs: Minimum occurrences (0 = optional) max_occurs: Maximum occurrences (int or "unbounded")

Returns: { "status": "added", "spec_id": "S1", "ifc_versions": ["IFC4"] }

Inputs: name (required), ifc_versions (required), identifier, description, +3 more. Returns: object

create_idsA

Create a new IDS document for this session.

Session is automatically tracked by FastMCP - no session_id parameter needed!

Args: title: Document title (required) ctx: FastMCP Context (auto-injected) author: Author email or name version: Version string date: Date in YYYY-MM-DD format description: Document description copyright: Copyright notice milestone: Project milestone purpose: Purpose of this IDS

Returns: { "status": "created", "session_id": "auto-generated-by-fastmcp", "title": "..." }

Inputs: title (required), author, version, date, +4 more. Returns: object

export_idsA

Export IDS document to XML file using IfcTester.

Uses current session automatically - no session_id parameter needed!

Args: ctx: FastMCP Context (auto-injected) output_path: File path (optional, returns XML string if not provided) validate: Whether to validate against XSD (default: True)

Returns: { "status": "exported", "xml": "...", # If no output_path "file_path": "...", # If output_path provided "validation": {"valid": true, "errors": []} }

Inputs: output_path, validate. Returns: object

get_ids_infoA

Get current session's IDS document structure.

Uses current session automatically - no session_id parameter needed!

Args: ctx: FastMCP Context (auto-injected)

Returns: { "title": "...", "author": "...", "specification_count": 3, "specifications": [...] }

Inputs: no named parameters. Returns: object

load_idsA

Load an existing IDS file into the current session.

Replaces any existing IDS in this session.

Args: source: File path or XML string ctx: FastMCP Context (auto-injected) source_type: "file" or "string"

Returns: { "status": "loaded", "title": "...", "specification_count": 3, "specifications": [...] }

Inputs: source (required), source_type. Returns: object

validate_idsA

Validate current session's IDS document.

Validates:

  1. Required fields present (title, specifications, etc.)

  2. Each specification has applicability

  3. IFC versions are valid

  4. XSD schema compliance (via IfcTester)

Args: ctx: FastMCP Context (auto-injected)

Returns: { "valid": true, "errors": [], "warnings": [], "specifications_count": 3, "details": { "has_title": true, "has_specifications": true, "xsd_valid": true } }

Inputs: no named parameters. Returns: object

validate_ifc_modelA

Validate an IFC model against the current session's IDS specifications.

This bonus feature leverages IfcTester's IFC validation capabilities.

Args: ifc_file_path: Path to IFC file ctx: FastMCP Context (auto-injected) report_format: "console", "json", or "html"

Returns (json format): { "status": "validation_complete", "total_specifications": 3, "passed_specifications": 2, "failed_specifications": 1, "report": { "specifications": [ { "name": "Wall Fire Rating", "status": "passed", "applicable_entities": 25, "passed_entities": 25, "failed_entities": 0 }, ... ] } }

Inputs: ifc_file_path (required), report_format. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 17 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with no overlap. The 'add_' tools create specific facet or restriction types (e.g., attribute, bounds, classification), while the management tools (create_ids, export_ids, etc.) handle document lifecycle operations. The descriptions clearly differentiate what each tool does, preventing agent confusion.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern with snake_case throughout. The 'add_' prefix is used uniformly for facet/restriction creation tools, while management tools use clear verbs like create, export, get, load, and validate. This predictable naming makes the tool set easy to navigate and understand.

    Tool Count5/5

    With 17 tools, this server provides comprehensive coverage for IDS document creation and validation. The count is well-scoped for the domain, including core operations (create, export, validate), facet types (entity, property, material, etc.), and restriction types (bounds, enumeration, pattern). Each tool earns its place without redundancy.

    Completeness5/5

    The tool set provides complete coverage for IDS document lifecycle management. It includes document creation (create_ids), loading (load_ids), editing (add_* facets/restrictions), inspection (get_ids_info), validation (validate_ids), export (export_ids), and even model validation (validate_ifc_model). All essential CRUD operations are present with no apparent gaps.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      D
      maintenance
      Enables AI assistants to create, edit, and export IFC5/IFCX building information models through natural language, handling spatial structure, elements, geometry, metadata, validation, and export.
      73
      26
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI agents to load, query, and analyze IFC building model files, including spatial structures, elements, properties, materials, and geometry.
      20
      1
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI assistants to inspect, create, and report on IFC/BIM files locally, and to open models in a viewer with BCF viewpoint support.
      5
      155 npm
      13
      Apache 2.0