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 精心打造 ❤️