IDS MCP Server
Uses Pydantic for data validation and type-safe model definitions throughout the IDS file creation and management process
Employs Pytest as the testing framework with 168 tests achieving 94% code coverage for validation and quality assurance
Built with Python 3.8+ as the core implementation language with full type hints and modern Python best practices
Utilizes Ruff for code linting to maintain code quality standards
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@IDS MCP Server create a new IDS for wall fire rating requirements"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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 propertiesPset_DoorCommon- Door propertiesPset_WindowCommon- Window propertiesPset_SpaceCommon- Space propertiesPset_Common- Custom/generic properties
Benefits of Early Validation
Immediate Feedback - Errors caught at tool invocation, not export time
Clear Error Messages - Includes workarounds and examples
Prevents Invalid States - IDS documents stay valid throughout creation
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=95TDD Workflow (Red-Green-Refactor)
RED - Write failing test
GREEN - Implement minimum code to pass
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.mdConstitution Principles
This project follows 6 non-negotiable principles:
100% IDS Schema Compliance - All exports validate against XSD
Test-Driven Development - 95%+ coverage, tests before code
IfcTester Integration First - No custom XML generation
Deterministic Generation - Identical input = identical output
FastMCP Context-Based Sessions - Automatic session management
Python Best Practices - Type hints, PEP 8, modern Python
See constitution.md for full details.
Documentation
Constitution - Non-negotiable principles
Design Specification - Complete technical design
AI Agent Guide - Guide for AI agents working on this project
Implementation Plans - Phase-by-phase PRDs
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
IDS Standard: https://www.buildingsmart.org/standards/bsi-standards/information-delivery-specification-ids/
IDS XSD Schema: https://standards.buildingsmart.org/IDS/1.0/ids.xsd
IfcTester Docs: https://docs.ifcopenshell.org/ifctester.html
FastMCP: https://gofastmcp.com/
buildingSMART: https://www.buildingsmart.org/
License
MIT License - see LICENSE file for details
Contributing
Read constitution.md for project principles
Follow TDD methodology (Red-Green-Refactor)
Ensure 95%+ test coverage
All exports must validate against IDS 1.0 XSD
Use IfcTester for all IDS operations
Support
Issues: https://github.com/Quasar-Consulting-Group/ifc-ids-mcp/issues
Discussions: https://github.com/Quasar-Consulting-Group/ifc-ids-mcp/discussions
Status: ✅ Implementation Complete | 94% Test Coverage | 17 MCP Tools | 168 Tests | Early Validation
Built with ❤️ using IfcOpenShell and FastMCP
Available Tools
17 toolsadd_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:
Required fields present (title, specifications, etc.)
Each specification has applicability
IFC versions are valid
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
Scored across 17 tools
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.
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.
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.
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
Related MCP Connectors
15 deterministic validation tools for AI agents: tax IDs (15 countries), VAT, IBAN, LEI, HS codes.
Agent verification tools: CSV quality, citation checks, AI-readiness audits, requirement extraction
Edit IFC/BIM building models by language: quantities, checks, edits, new elements, undoable.
Create and manage test cases, test runs and results in Testiny from your AI assistant.
Related MCP Servers
- AlicenseCqualityDmaintenanceEnables AI assistants to create, edit, and export IFC5/IFCX building information models through natural language, handling spatial structure, elements, geometry, metadata, validation, and export.7326MIT
- AlicenseAqualityDmaintenanceEnables AI agents to load, query, and analyze IFC building model files, including spatial structures, elements, properties, materials, and geometry.201MIT
- FlicenseAqualityDmaintenanceEnables AI assistants to query standardized building classifications, properties, and data dictionaries from buildingSMART for BIM model enrichment.93-
- AlicenseAqualityCmaintenanceEnables AI assistants to inspect, create, and report on IFC/BIM files locally, and to open models in a viewer with BCF viewpoint support.5155 npm13Apache 2.0