IDS MCP Server

Instructions

Implementation Reference

• src/ids_mcp_server/tools/facets.py:16-81 (handler)

  The main handler function for the 'add_entity_facet' tool. It adds an entity facet to the specified section (applicability or requirements) of an IDS specification, performs validation, creates the entity using IfcTester's ids.Entity, and handles errors.

  async def add_entity_facet(
      spec_id: str,
      location: str,
      entity_name: str,
      ctx: Context,
      predefined_type: Optional[str] = None,
      cardinality: str = "required"
  ) -> Dict[str, Any]:
      """
      Add an entity facet to a specification.
  
      IMPORTANT: IDS 1.0 allows only ONE entity facet per applicability section.
      If you need multiple entity types, create separate specifications.
  
      Args:
          spec_id: Specification identifier
          location: "applicability" or "requirements"
          entity_name: IFC entity name (e.g., "IFCWALL")
          ctx: FastMCP Context (auto-injected)
          predefined_type: Optional predefined type
          cardinality: "required", "optional", or "prohibited" (requirements only)
  
      Returns:
          {"status": "added", "facet_type": "entity", "spec_id": "S1"}
  
      Raises:
          ToolError: If trying to add second entity to applicability section
      """
      try:
          ids_obj = await get_or_create_session(ctx)
          spec = _find_specification(ids_obj, spec_id)
  
          # EARLY VALIDATION: Check IDS 1.0 constraint
          validate_single_entity_in_applicability(spec, location)
  
          await ctx.info(f"Adding entity facet: {entity_name} to {spec_id}")
  
          # Create entity facet using IfcTester
          entity = ids.Entity(
              name=entity_name.upper(),
              predefinedType=predefined_type
          )
  
          # Add to appropriate section
          if location == "applicability":
              spec.applicability.append(entity)
          elif location == "requirements":
              # Note: Entity facets in requirements don't have cardinality in IDS
              spec.requirements.append(entity)
          else:
              raise ToolError(f"Invalid location: {location}. Must be 'applicability' or 'requirements'")
  
          await ctx.info(f"Entity facet added: {entity_name}")
  
          return {
              "status": "added",
              "facet_type": "entity",
              "spec_id": spec_id
          }
  
      except ToolError:
          raise
      except Exception as e:
          await ctx.error(f"Failed to add entity facet: {str(e)}")
          raise ToolError(f"Failed to add entity facet: {str(e)}")

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

  Registers the add_entity_facet function as a tool in the FastMCP server.

  mcp_server.tool(facets.add_entity_facet)

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

  Imports the facets module which contains the add_entity_facet tool.

  from ids_mcp_server.tools import document, specification, facets, validation, restrictions

• src/ids_mcp_server/tools/facets.py:10-12 (helper)

  Imports helper validators used in add_entity_facet, such as validate_single_entity_in_applicability for IDS 1.0 constraints.

  from ids_mcp_server.tools.validators import (
      validate_single_entity_in_applicability,
      validate_property_set_required