IDS MCP 服务器

AI 驱动的 100% 合规 buildingSMART IDS 文件创建

一个 MCP（模型上下文协议）服务器，使 AI 智能体能够确定性地创建、验证和管理完全符合 buildingSMART IDS 1.0 标准的信息交付规范 (IDS) 文件。

ifc-ids-mcp MCP server

License: MIT Python 3.8+ Code style: black

特性

✅ 100% 符合 IDS 1.0 标准 - 所有导出文件均通过官方 XSD 模式验证
✅ IfcTester 集成 - 使用官方 IfcOpenShell 库
✅ 基于 FastMCP 上下文的会话 - 自动会话管理
✅ 测试驱动开发 - 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 属性要求

高级方面

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 工具在添加该方面之前会验证此约束：

# ✅ 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. 属性方面需要属性集

约束：IfcTester 要求 property_set 参数以进行有效的 IDS 导出。

早期验证：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 方法论：

# 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: 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。

文档

宪法 - 不可逾越的原则
设计规范 - 完整的技术设计
AI 智能体指南 - 为从事本项目工作的 AI 智能体提供的指南
实施计划 - 分阶段的产品需求文档 (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 方法论 (红-绿-重构)
确保 95% 以上的测试覆盖率
所有导出文件必须通过 IDS 1.0 XSD 验证
所有 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

IDS MCP Server