IDS MCP Server

KI-gestützte Erstellung von buildingSMART IDS-Dateien mit 100%iger Konformität

Ein MCP-Server (Model Context Protocol), der es KI-Agenten ermöglicht, deterministisch Information Delivery Specification (IDS)-Dateien zu erstellen, zu validieren und zu verwalten, die vollständig dem buildingSMART IDS 1.0-Standard entsprechen.

Funktionen

• ✅ 100% IDS 1.0-konform - Alle Exporte werden gegen das offizielle XSD-Schema validiert

• ✅ IfcTester-Integration - Verwendet die offizielle IfcOpenShell-Bibliothek

• ✅ FastMCP kontextbasierte Sitzungen - Automatische Sitzungsverwaltung

• ✅ Testgetriebene Entwicklung - Über 95% Codeabdeckung mit umfassenden Tests

• ✅ Deterministische Ausgabe - Gleiche Eingabe erzeugt immer identische Ausgabe

• ✅ Typsicher - Vollständige Typ-Hinweise mit Pydantic-Validierung

Schnellstart

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 .

Verwendung mit Claude Desktop

Zur Konfiguration von Claude Desktop hinzufügen (claude_desktop_config.json):

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

Programmatische Verwendung

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")

Verfügbare MCP-Tools

Dokumentenverwaltung

• create_ids - Neues IDS-Dokument erstellen

• load_ids - Bestehendes IDS aus Datei oder XML-String laden

• export_ids - IDS mit Validierung als XML exportieren

• get_ids_info - Dokumentenstruktur und Metadaten abrufen

Spezifikationsverwaltung

• add_specification - Spezifikation mit IFC-Version und Kardinalität hinzufügen

Facettenverwaltung

Grundlegende Facetten

• add_entity_facet - IFC-Entitätstyp-Filter hinzufügen (z. B. IFCWALL)

• add_property_facet - Eigenschaftsanforderungen hinzufügen

• add_attribute_facet - IFC-Attributanforderungen hinzufügen

Erweiterte Facetten

• add_classification_facet - Klassifizierungsanforderungen hinzufügen

• add_material_facet - Materialanforderungen hinzufügen

• add_partof_facet - Anforderungen an räumliche Beziehungen hinzufügen

Einschränkungsverwaltung

• add_enumeration_restriction - Auf eine Liste gültiger Werte beschränken

• add_pattern_restriction - Mit Regex-Muster einschränken

• add_bounds_restriction - Numerische Bereiche einschränken

• add_length_restriction - Zeichenfolgenlänge einschränken

Validierung

• validate_ids - IDS-Dokument gegen XSD-Schema validieren

• validate_ifc_model - IFC-Modell gegen IDS validieren (Bonusfunktion)

Frühzeitige Validierung & Einschränkungsprüfung

Der MCP-Server enthält eine frühzeitige Validierung, um Verstöße gegen das IDS 1.0-Schema sofort beim Aufruf der Tools zu erkennen, anstatt bis zum Export zu warten. Dies bietet KI-Agenten klare, umsetzbare Fehlermeldungen.

IDS 1.0 Schema-Einschränkungen

1. Eine Entitätsfacette pro Anwendbarkeit

Einschränkung: IDS 1.0 erlaubt nur EINE Entitätsfacette pro Anwendbarkeitsabschnitt einer Spezifikation.

Frühzeitige Validierung: Das Tool add_entity_facet validiert diese Einschränkung, bevor die Facette hinzugefügt wird:

# ✅ 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..."

Problemumgehung: Erstellen Sie separate Spezifikationen für jeden Entitätstyp:

# 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. Eigenschaftssatz für Eigenschaftsfacetten erforderlich

Einschränkung: IfcTester erfordert den Parameter property_set für einen gültigen IDS-Export.

Frühzeitige Validierung: Das Tool add_property_facet validiert diese Anforderung, bevor die Facette hinzugefügt wird:

# ❌ 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"
)

Gängige Eigenschaftssätze:

• Pset_WallCommon - Wandeigenschaften

• Pset_DoorCommon - Türeigenschaften

• Pset_WindowCommon - Fenstereigenschaften

• Pset_SpaceCommon - Raumeigenschaften

• Pset_Common - Benutzerdefinierte/allgemeine Eigenschaften

Vorteile der frühzeitigen Validierung

1. Sofortiges Feedback - Fehler werden beim Tool-Aufruf erkannt, nicht erst beim Export

2. Klare Fehlermeldungen - Enthält Problemumgehungen und Beispiele

3. Verhindert ungültige Zustände - IDS-Dokumente bleiben während der Erstellung gültig

4. Bessere Erfahrung für KI-Agenten - Agenten erhalten umsetzbare Anleitungen

Siehe CLAUDE.md für eine detaillierte Dokumentation zu IDS 1.0-Einschränkungen.

Architektur

┌─────────────────────────────────────────────┐
│           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)

Entwicklung

Testgetriebene Entwicklung

Dieses Projekt folgt strikt der TDD-Methodik:

# 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 - Fehlgeschlagenen Test schreiben

2. GREEN - Minimalen Code implementieren, um den Test zu bestehen

3. REFACTOR - Codequalität verbessern

Beispiel:

# 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)

Codequalität

# Format code
black src/ tests/

# Lint code
ruff check src/ tests/

# Type checking (optional)
mypy src/

Projektstruktur

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

Verfassungsprinzipien

Dieses Projekt folgt 6 nicht verhandelbaren Prinzipien:

1. 100% IDS-Schema-Konformität - Alle Exporte validieren gegen XSD

2. Testgetriebene Entwicklung - Über 95% Abdeckung, Tests vor dem Code

3. IfcTester-Integration zuerst - Keine benutzerdefinierte XML-Generierung

4. Deterministische Generierung - Identische Eingabe = identische Ausgabe

5. FastMCP kontextbasierte Sitzungen - Automatische Sitzungsverwaltung

6. Python Best Practices - Typ-Hinweise, PEP 8, modernes Python

Siehe constitution.md für vollständige Details.

Dokumentation

• Verfassung - Nicht verhandelbare Prinzipien

• Design-Spezifikation - Vollständiges technisches Design

• KI-Agenten-Leitfaden - Leitfaden für KI-Agenten, die an diesem Projekt arbeiten

• Implementierungspläne - Phasenweise PRDs

Abhängigkeiten

Kern

• fastmcp - MCP-Server-Framework

• ifctester - IDS-Erstellung und -Validierung (von IfcOpenShell)

• pydantic - Datenvalidierung

Entwicklung

• pytest - Test-Framework

• pytest-asyncio - Unterstützung für asynchrone Tests

• pytest-cov - Abdeckungsberichte

• black - Code-Formatierung

• ruff - Linting

Referenzen

• 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-Dokumentation: https://docs.ifcopenshell.org/ifctester.html

• FastMCP: https://gofastmcp.com/

• buildingSMART: https://www.buildingsmart.org/

Lizenz

MIT-Lizenz - siehe LICENSE-Datei für Details

Mitwirken

1. Lesen Sie constitution.md für Projektprinzipien

2. Befolgen Sie die TDD-Methodik (Red-Green-Refactor)

3. Stellen Sie eine Testabdeckung von über 95% sicher

4. Alle Exporte müssen gegen IDS 1.0 XSD validieren

5. Verwenden Sie IfcTester für alle IDS-Operationen

Support

• Probleme: https://github.com/Quasar-Consulting-Group/ifc-ids-mcp/issues

• Diskussionen: https://github.com/Quasar-Consulting-Group/ifc-ids-mcp/discussions

Status: ✅ Implementierung abgeschlossen | 94% Testabdeckung | 17 MCP-Tools | 168 Tests | Frühzeitige Validierung

Erstellt mit ❤️ unter Verwendung von IfcOpenShell und FastMCP