Ifc Ids MCP

🚀 IDS MCP 服務器

由人工智能驅動，可創建 100% 符合標準的 buildingSMART IDS 文件

這是一個 MCP（模型上下文協議）服務器，它使 AI 代理能夠確定性地創建、驗證和管理完全符合 buildingSMART IDS 1.0 標準的信息交付規範（IDS）文件。

✨ 主要特性

• ✅ 100% 符合 IDS 1.0 標準 - 所有導出文件均通過官方 XSD 模式驗證。
• ✅ 集成 IfcTester - 使用官方 IfcOpenShell 庫。
• ✅ 基於 FastMCP 上下文的會話 - 自動會話管理。
• ✅ 測試驅動開發 - 代碼覆蓋率達 95% 以上，擁有全面的測試。
• ✅ 確定性輸出 - 相同輸入始終產生相同輸出。
• ✅ 類型安全 - 藉助 Pydantic 驗證實現完整的類型提示。

🚀 快速開始

📦 安裝指南

# 克隆倉庫
git clone https://github.com/Quasar-Consulting-Group/ifc-ids-mcp.git
cd ifc-ids-mcp

# 安裝依賴
pip install -r requirements.txt

# 以開發模式安裝
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

# MCP 服務器會通過工具自動處理此操作
# 但你也可以直接使用 IfcTester：

# 創建新的 IDS
my_ids = ids.Ids(title="項目需求")

# 添加規範
spec = ids.Specification(name="牆體需求", ifcVersion=["IFC4"])
spec.applicability.append(ids.Entity(name="IFCWALL"))

requirement = ids.Property(
    baseName="防火等級",
    propertySet="Pset_WallCommon",
    cardinality="required"
)
spec.requirements.append(requirement)

my_ids.specifications.append(spec)

# 導出為 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 版本和基數的規範。

方面管理

基本方面

• add_entity_facet - 添加 IFC 實體類型過濾器（例如，IFCWALL）。
• add_property_facet - 添加屬性要求。
• add_attribute_facet - 添加 IFC 屬性要求。

高級方面

• 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 模式違規，而無需等到導出時。這為 AI 代理提供了清晰、可操作的錯誤消息。

IDS 1.0 模式約束

1. 每個適用性部分僅允許一個實體方面

約束：IDS 1.0 規定每個規範的適用性部分僅允許一個實體方面。 早期驗證：add_entity_facet 工具在添加方面之前會驗證此約束：

# ✅ 正確：第一個實體方面
add_entity_facet(spec_id="S1", location="applicability", entity_name="IFCWALL")

# ❌ 錯誤：第二個實體方面會立即引發 ToolError
add_entity_facet(spec_id="S1", location="applicability", entity_name="IFCDOOR")
# 錯誤："IDS 1.0 XSD 約束違規：每個適用性部分僅允許一個實體方面..."

解決方法：為每個實體類型創建單獨的規範：

# 規範 1：牆體
add_specification(name="牆體需求", ifc_versions=["IFC4"], identifier="S1")
add_entity_facet(spec_id="S1", location="applicability", entity_name="IFCWALL")

# 規範 2：門
add_specification(name="門需求", ifc_versions=["IFC4"], identifier="S2")
add_entity_facet(spec_id="S2", location="applicability", entity_name="IFCDOOR")

2. 屬性方面需要屬性集

約束：IfcTester 要求在有效 IDS 導出時提供 property_set 參數。 早期驗證：add_property_facet 工具在添加方面之前會驗證此要求：

# ❌ 錯誤：缺少 property_set 會立即引發 ToolError
add_property_facet(
    spec_id="S1",
    location="requirements",
    property_name="防火等級"
)
# 錯誤："屬性方面驗證錯誤：'property_set' 參數是必需的..."

# ✅ 正確：包含 property_set 參數
add_property_facet(
    spec_id="S1",
    location="requirements",
    property_name="防火等級",
    property_set="Pset_WallCommon"
)

常見屬性集：

• Pset_WallCommon - 牆體屬性。
• Pset_DoorCommon - 門屬性。
• Pset_WindowCommon - 窗戶屬性。
• Pset_SpaceCommon - 空間屬性。
• Pset_Common - 自定義/通用屬性。

早期驗證的好處

1. 即時反饋 - 在調用工具時捕獲錯誤，而不是在導出時。
2. 清晰的錯誤消息 - 包含解決方法和示例。
3. 防止無效狀態 - IDS 文檔在創建過程中始終保持有效。
4. 更好的 AI 代理體驗 - 代理獲得可操作的指導。

有關 IDS 1.0 約束的詳細文檔，請參閱 CLAUDE.md。

🔧 技術細節

架構

┌─────────────────────────────────────────────┐
│           AI 代理 (Claude, GPT)             │
└────────────────────┬────────────────────────┘
                     │ MCP 協議
┌────────────────────▼────────────────────────┐
│            FastMCP 服務器                    │
│  ┌──────────────────────────────────────┐   │
│  │     MCP 工具 (15 種以上工具)            │   │
│  └───────────────┬──────────────────────┘   │
│  ┌───────────────▼──────────────────────┐   │
│  │     會話管理器 (上下文)        │   │
│  └───────────────┬──────────────────────┘   │
│  ┌───────────────▼──────────────────────┐   │
│  │  IfcTester 集成 (IDS 引擎)  │   │
│  └──────────────────────────────────────┘   │
└─────────────────────────────────────────────┘
                     │
                     ▼
        IDS XML 文件 (100% 符合 XSD)

開發

測試驅動開發

本項目嚴格遵循 TDD 方法：

# 運行所有測試
pytest tests/ -v

# 運行並生成覆蓋率報告
pytest tests/ --cov=src/ids_mcp_server --cov-report=html

# 運行特定測試類別
pytest tests/unit/ -v        # 單元測試
pytest tests/integration/ -v  # 集成測試
pytest tests/validation/ -v   # XSD 驗證測試

# 必須保持 95% 以上的覆蓋率
pytest tests/ --cov-fail-under=95

TDD 工作流程（紅 - 綠 - 重構）

1. 紅 - 編寫失敗的測試。
2. 綠 - 實現最少的代碼以通過測試。
3. 重構 - 提高代碼質量。

示例：

# 紅：編寫失敗的測試
def test_create_specification():
    result = add_specification(name="測試", ifc_versions=["IFC4"])
    assert result["status"] == "成功"

# 綠：實現
def add_specification(name, ifc_versions):
    return {"status": "成功"}

# 重構：改進（保持測試通過）

代碼質量

# 格式化代碼
black src/ tests/

# 代碼檢查
ruff check src/ tests/

# 類型檢查（可選）
mypy src/

項目結構

ifc-ids-mcp/
├── src/
│   └── ids_mcp_server/
│       ├── __init__.py
│       ├── __main__.py
│       ├── server.py          # FastMCP 服務器
│       ├── config.py          # 配置
│       ├── version.py         # 版本管理
│       ├── session/           # 會話管理
│       │   ├── manager.py
│       │   ├── storage.py
│       │   ├── cleanup.py
│       │   └── models.py      # 會話數據模型
│       └── tools/             # MCP 工具 (共 17 種)
│           ├── document.py
│           ├── specification.py
│           ├── facets.py
│           ├── restrictions.py    # 階段 007
│           ├── validation.py      # 階段 008
│           └── validators.py      # 早期驗證輔助工具
├── tests/                     # 168 個測試，94% 覆蓋率
│   ├── unit/                  # 單元測試
│   ├── component/             # 組件測試
│   ├── integration/           # 集成測試
│   └── validation/            # XSD 合規性測試
│       └── fixtures/          # 測試夾具
├── samples/                   # 示例 IDS/IFC 文件
│   ├── wall_fire_rating.ids
│   └── walls-fire-rating.ifc
├── specs/                     # 實施計劃 (PRD)
├── .mcp.json                  # MCP 服務器配置
├── .coveragerc                # 覆蓋率配置
├── constitution.md            # 項目原則
├── DESIGN_SPECIFICATION.md    # 技術規範
├── CLAUDE.md                  # AI 代理指南
├── pyproject.toml
├── pytest.ini
└── README.md

項目原則

本項目遵循 6 項不可協商的原則：

1. 100% 符合 IDS 模式 - 所有導出文件均通過 XSD 驗證。
2. 測試驅動開發 - 覆蓋率達 95% 以上，先編寫測試再編寫代碼。
3. 優先集成 IfcTester - 不進行自定義 XML 生成。
4. 確定性生成 - 相同輸入產生相同輸出。
5. 基於 FastMCP 上下文的會話 - 自動會話管理。
6. Python 最佳實踐 - 類型提示、PEP 8 規範、現代 Python。

完整詳細信息請參閱 constitution.md。

文檔

• Constitution - 不可協商的原則。
• Design Specification - 完整的技術設計。
• 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 文件。

貢獻指南

1. 閱讀 constitution.md 瞭解項目原則。
2. 遵循 TDD 方法（紅 - 綠 - 重構）。
3. 確保測試覆蓋率達到 95% 以上。
4. 所有導出文件必須通過 IDS 1.0 XSD 驗證。
5. 所有 IDS 操作使用 IfcTester。

支持

• 問題反饋：https://github.com/Quasar-Consulting-Group/ifc-ids-mcp/issues
• 討論區：https://github.com/Quasar-Consulting-Group/ifc-ids-mcp/discussions

狀態：✅ 實現完成 | 94% 測試覆蓋率 | 17 種 MCP 工具 | 168 個測試 | 早期驗證

使用 IfcOpenShell 和 FastMCP 精心打造 ❤️