IDS MCP Server

Instructions

Implementation Reference

• src/ids_mcp_server/tools/facets.py:83-153 (handler)

  The core handler function that executes the add_property_facet tool. It validates inputs, creates an ids.Property facet using IfcTester, adds it to the specification's applicability or requirements section, and returns success status.

  async def add_property_facet(
      spec_id: str,
      location: str,
      property_name: str,
      ctx: Context,
      property_set: Optional[str] = None,
      data_type: Optional[str] = None,
      value: Optional[str] = None,
      cardinality: str = "required"
  ) -> Dict[str, Any]:
      """
      Add a property facet to a specification.
  
      IMPORTANT: The property_set parameter is REQUIRED for valid IDS export.
  
      Args:
          spec_id: Specification identifier
          location: "applicability" or "requirements"
          property_name: Property name (e.g., "FireRating")
          ctx: FastMCP Context (auto-injected)
          property_set: Property set name (e.g., "Pset_WallCommon") - REQUIRED
          data_type: IFC data type (e.g., "IFCLABEL")
          value: Required value or pattern
          cardinality: "required", "optional", or "prohibited"
  
      Returns:
          {"status": "added", "facet_type": "property", "spec_id": "S1"}
  
      Raises:
          ToolError: If property_set is None or empty
      """
      try:
          ids_obj = await get_or_create_session(ctx)
          spec = _find_specification(ids_obj, spec_id)
  
          # EARLY VALIDATION: Check property_set required
          validate_property_set_required(property_set, property_name)
  
          await ctx.info(f"Adding property facet: {property_name} to {spec_id}")
  
          # Create property facet using IfcTester
          prop = ids.Property(
              baseName=property_name,
              propertySet=property_set,
              dataType=data_type.upper() if data_type else None,
              value=value,
              cardinality=cardinality if location == "requirements" else None
          )
  
          # Add to appropriate section
          if location == "applicability":
              spec.applicability.append(prop)
          elif location == "requirements":
              spec.requirements.append(prop)
          else:
              raise ToolError(f"Invalid location: {location}")
  
          await ctx.info(f"Property facet added: {property_name}")
  
          return {
              "status": "added",
              "facet_type": "property",
              "spec_id": spec_id
          }
  
      except ToolError:
          raise
      except Exception as e:
          await ctx.error(f"Failed to add property facet: {str(e)}")
          raise ToolError(f"Failed to add property facet: {str(e)}")

• src/ids_mcp_server/server.py:34-34 (registration)

  Registers the add_property_facet tool function with the FastMCP server instance.

  mcp_server.tool(facets.add_property_facet)

• src/ids_mcp_server/tools/validators.py:59-101 (helper)

  Helper function called by the handler to validate that the property_set parameter is provided, enforcing IfcTester export requirements.

  def validate_property_set_required(
      property_set: Optional[str],
      property_name: str
  ) -> None:
      """
      Validate that property_set is provided for property facets.
  
      IfcTester requirement: property_set must be specified for valid XML export.
      While the IDS schema technically allows property_set to be optional,
      IfcTester's XML generation requires it for successful validation.
  
      Args:
          property_set: Property set name (can be None)
          property_name: Property name (for error message)
  
      Raises:
          ToolError: If property_set is None or empty
  
      Example:
          >>> validate_property_set_required("Pset_WallCommon", "FireRating")
          >>> # Succeeds
          >>> validate_property_set_required(None, "FireRating")
          >>> # Raises ToolError
      """
      if not property_set or property_set.strip() == "":
          raise ToolError(
              f"Property facet validation error: 'property_set' parameter is required.\n\n"
              f"Property '{property_name}' must belong to a property set for valid IDS export.\n\n"
              "COMMON PROPERTY SETS:\n"
              "  - Pset_WallCommon (for walls)\n"
              "  - Pset_DoorCommon (for doors)\n"
              "  - Pset_WindowCommon (for windows)\n"
              "  - Pset_SpaceCommon (for spaces)\n"
              "  - Pset_SlabCommon (for slabs)\n"
              "  - Pset_BeamCommon (for beams)\n"
              "  - Pset_ColumnCommon (for columns)\n\n"
              "CUSTOM PROPERTY SETS:\n"
              "  - Pset_Common (generic custom properties)\n"
              "  - Pset_CustomProperties (organization-specific)\n\n"
              "This requirement ensures valid XML export via IfcTester.\n"
              "See CLAUDE.md for more details on this IfcTester requirement."
          )