IDS MCP 서버

IDS 1.0 표준을 100% 준수하는 buildingSMART IDS 파일의 AI 기반 생성

buildingSMART IDS 1.0 표준을 완벽하게 준수하는 정보 전달 사양(IDS) 파일을 결정론적으로 생성, 검증 및 관리할 수 있도록 AI 에이전트를 지원하는 MCP(Model Context Protocol) 서버입니다.

ifc-ids-mcp MCP server

License: MIT Python 3.8+ Code style: black

주요 기능

✅ 100% IDS 1.0 준수 - 모든 내보내기는 공식 XSD 스키마에 따라 검증됨
✅ IfcTester 통합 - 공식 IfcOpenShell 라이브러리 사용
✅ FastMCP 컨텍스트 기반 세션 - 자동 세션 관리
✅ 테스트 주도 개발(TDD) - 포괄적인 테스트를 통한 95% 이상의 코드 커버리지
✅ 결정론적 출력 - 동일한 입력은 항상 동일한 출력을 생성
✅ 타입 안전성 - Pydantic 검증을 통한 완전한 타입 힌트 제공

빠른 시작

설치

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

Claude Desktop에서 사용

Claude Desktop 설정(claude_desktop_config.json)에 추가하세요:

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

프로그래밍 방식 사용

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

사용 가능한 MCP 도구

문서 관리

create_ids - 새 IDS 문서 생성
load_ids - 파일 또는 XML 문자열에서 기존 IDS 로드
export_ids - 검증과 함께 IDS를 XML로 내보내기
get_ids_info - 문서 구조 및 메타데이터 가져오기

사양 관리

add_specification - IFC 버전 및 카디널리티를 포함한 사양 추가

패싯(Facet) 관리

기본 패싯

add_entity_facet - IFC 엔티티 유형 필터 추가 (예: IFCWALL)
add_property_facet - 속성 요구 사항 추가
add_attribute_facet - IFC 속성(Attribute) 요구 사항 추가

고급 패싯

add_classification_facet - 분류 요구 사항 추가
add_material_facet - 재료 요구 사항 추가
add_partof_facet - 공간 관계 요구 사항 추가

제한 관리

add_enumeration_restriction - 유효한 값 목록으로 제한
add_pattern_restriction - 정규식 패턴으로 제한
add_bounds_restriction - 숫자 범위 제한
add_length_restriction - 문자열 길이 제한

검증

validate_ids - XSD 스키마에 대해 IDS 문서 검증
validate_ifc_model - IDS에 대해 IFC 모델 검증 (보너스 기능)

사전 검증 및 제약 조건 확인

이 MCP 서버에는 도구가 호출될 때 내보내기 시점까지 기다리지 않고 즉시 IDS 1.0 스키마 위반을 포착하는 사전 검증(early validation) 기능이 포함되어 있습니다. 이를 통해 AI 에이전트에게 명확하고 실행 가능한 오류 메시지를 제공합니다.

IDS 1.0 스키마 제약 조건

1. 적용 가능성(Applicability)당 단일 엔티티 패싯

제약 조건: IDS 1.0은 사양의 적용 가능성 섹션당 하나의 엔티티 패싯만 허용합니다.

사전 검증: add_entity_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..."

해결 방법: 각 엔티티 유형에 대해 별도의 사양을 만드세요:

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

제약 조건: IfcTester는 유효한 IDS 내보내기를 위해 property_set 매개변수를 요구합니다.

사전 검증: add_property_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"
)

일반적인 속성 세트:

Pset_WallCommon - 벽 속성
Pset_DoorCommon - 문 속성
Pset_WindowCommon - 창문 속성
Pset_SpaceCommon - 공간 속성
Pset_Common - 사용자 정의/일반 속성

사전 검증의 이점

즉각적인 피드백 - 내보내기 시점이 아닌 도구 호출 시 오류 포착
명확한 오류 메시지 - 해결 방법 및 예시 포함
유효하지 않은 상태 방지 - 생성 과정 전반에 걸쳐 IDS 문서가 유효하게 유지됨
더 나은 AI 에이전트 경험 - 에이전트가 실행 가능한 지침을 수신

IDS 1.0 제약 조건에 대한 자세한 문서는 CLAUDE.md를 참조하세요.

아키텍처

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

개발

테스트 주도 개발(TDD)

이 프로젝트는 엄격하게 TDD 방법론을 따릅니다:

# 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 워크플로우 (Red-Green-Refactor)

RED - 실패하는 테스트 작성
GREEN - 통과하기 위한 최소한의 코드 구현
REFACTOR - 코드 품질 개선

예시:

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

코드 품질

# Format code
black src/ tests/

# Lint code
ruff check src/ tests/

# Type checking (optional)
mypy src/

프로젝트 구조

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

헌법 원칙

이 프로젝트는 6가지의 양보할 수 없는 원칙을 따릅니다:

100% IDS 스키마 준수 - 모든 내보내기는 XSD에 대해 검증됨
테스트 주도 개발 - 95% 이상의 커버리지, 코드 작성 전 테스트
IfcTester 통합 우선 - 사용자 정의 XML 생성 금지
결정론적 생성 - 동일한 입력 = 동일한 출력
FastMCP 컨텍스트 기반 세션 - 자동 세션 관리
Python 모범 사례 - 타입 힌트, PEP 8, 현대적인 Python

자세한 내용은 constitution.md를 참조하세요.

문서

헌법(Constitution) - 양보할 수 없는 원칙
설계 사양(Design Specification) - 완전한 기술 설계
AI 에이전트 가이드(AI Agent Guide) - 이 프로젝트에서 작업하는 AI 에이전트를 위한 가이드
구현 계획(Implementation Plans) - 단계별 PRD

의존성

핵심

fastmcp - MCP 서버 프레임워크
ifctester - IDS 작성 및 검증 (IfcOpenShell 제공)
pydantic - 데이터 검증

개발

pytest - 테스트 프레임워크
pytest-asyncio - 비동기 테스트 지원
pytest-cov - 커버리지 보고
black - 코드 포맷팅
ruff - 린팅

참조

IDS 표준: https://www.buildingsmart.org/standards/bsi-standards/information-delivery-specification-ids/
IDS XSD 스키마: https://standards.buildingsmart.org/IDS/1.0/ids.xsd
IfcTester 문서: https://docs.ifcopenshell.org/ifctester.html
FastMCP: https://gofastmcp.com/
buildingSMART: https://www.buildingsmart.org/

라이선스

MIT 라이선스 - 자세한 내용은 LICENSE 파일을 참조하세요.

기여

프로젝트 원칙은 constitution.md를 읽어보세요.
TDD 방법론(Red-Green-Refactor)을 따르세요.
95% 이상의 테스트 커버리지를 보장하세요.
모든 내보내기는 IDS 1.0 XSD에 대해 검증되어야 합니다.
모든 IDS 작업에 IfcTester를 사용하세요.

지원

상태: ✅ 구현 완료 | 94% 테스트 커버리지 | 17개 MCP 도구 | 168개 테스트 | 사전 검증 완료

IfcOpenShell과 FastMCP를 사용하여 ❤️로 제작됨

IDS MCP Server