create_routing_code

Instructions

Implementation Reference

• tools/directory_tools.py:391-450 (handler)

  The MCP tool handler for create_routing_code. Decorated with @mcp.tool() inside register_directory_tools(). Accepts siret, routing_code, and optional label. The implementation returns an error message indicating this endpoint was removed in XP Z12-013 v1.2.0 and must be performed through the Approved Platform portal.

  @mcp.tool()
  async def create_routing_code(
      siret: Annotated[
          str,
          Field(
              description=(
                  "Establishment SIRET to associate this routing code with (14 digits). "
                  "The SIRET must already be registered and Active in the PPF directory."
              )
          ),
      ],
      routing_code: Annotated[
          str,
          Field(
              description=(
                  "Routing code value to create (free-form string, e.g. 'PURCHASING-DEPT', 'PARIS-OFFICE'). "
                  "This exact value will appear in invoicing addresses and must be communicated to senders."
              )
          ),
      ],
      label: Annotated[
          Optional[str],
          Field(
              default=None,
              description=(
                  "Human-readable label for the routing code (e.g. 'Purchasing department - HQ'). "
                  "Optional but recommended for clarity when multiple codes exist."
              ),
          ),
      ] = None,
  ) -> dict:
      """
      Create a new routing code for a SIRET in the PPF directory.
  
      Routing codes let a recipient company route incoming invoices to specific departments or services.
      Once created, the code can be referenced in a directory line (create_directory_line)
      and communicated to senders to use in invoice addressing.
  
      BEHAVIOR:
      - Returns the created routing code object including its instanceId.
      - Fails if the SIRET is not registered or not Active in the PPF directory.
      - Fails if a routing code with the same value already exists for this SIRET (duplicate check).
      - The routing_code value is case-sensitive and must be unique per SIRET.
  
      RESPONSE: includes instanceId (required for update/delete), siret, siren, routingCode, label, createdAt.
  
      USAGE GUIDELINES:
      - Call get_establishment_by_siret first to verify the SIRET is Active before creating a routing code.
      - After creating, call create_directory_line with routing_code set to register the receiving address.
      - If a routing code already exists (duplicate error), use search_routing_code to retrieve its instanceId,
        then update it with update_routing_code if needed.
      - Routing codes are optional; omit them if the company routes all invoices to a single SIRET address.
      """
      return {
          "error": (
              "create_routing_code is not available. "
              "POST /v1/routing-code was removed in XP Z12-013 v1.2.0. "
              "Routing code creation must be performed through your Approved Platform portal."
          )
      }

• tools/directory_tools.py:70-71 (registration)

  The register_directory_tools() function that registers create_routing_code (and all other directory tools) on the FastMCP instance via the @mcp.tool() decorator.

  def register_directory_tools(mcp: FastMCP) -> None:
      """Registers the 12 Directory Service tools on the FastMCP instance."""

• clients/directory_client.py:141-148 (helper)

  The DirectoryClient.create_routing_code() method in the HTTP client layer. Raises NotImplementedError because POST /v1/routing-code was removed in XP Z12-013 v1.2.0.

  async def create_routing_code(
      self, siret: str, routing_code: str, label: Optional[str] = None
  ) -> dict[str, Any]:
      """POST /v1/routing-code — REMOVED in XP Z12-013 v1.2.0."""
      raise NotImplementedError(
          "POST /v1/routing-code was removed in XP Z12-013 v1.2.0. "
          "Routing code creation is now managed through the Approved Platform portal."
      )

• tests/test_mcp_protocol.py:42-55 (schema)

  Expected directory tools set in tests that includes 'create_routing_code' as one of the 12 required directory tools.

  EXPECTED_DIRECTORY_TOOLS = {
      "search_company",
      "get_company_by_siren",
      "search_establishment",
      "get_establishment_by_siret",
      "search_routing_code",
      "create_routing_code",
      "update_routing_code",
      "search_directory_line",
      "get_directory_line",
      "create_directory_line",
      "update_directory_line",
      "delete_directory_line",
  }

• audit/audit_vs_core.py:161-174 (helper)

  Audit list of required directory tools, listing 'create_routing_code' as a required tool for the FR implementation.

  _REQUIRED_DIRECTORY_TOOLS: dict[str, str] = {
      "search_company":          "Search companies (SIRENs) in the PPF directory",
      "get_company_by_siren":    "Look up a company by SIREN",
      "search_establishment":    "Search establishments (SIRETs) in the PPF directory",
      "get_establishment_by_siret": "Look up an establishment by SIRET",
      "search_routing_code":     "Search routing codes for a recipient",
      "create_routing_code":     "Create a routing code for a SIRET",
      "update_routing_code":     "Update an existing routing code",
      "search_directory_line":   "Search directory lines (receiving addresses)",
      "get_directory_line":      "Look up a directory line by addressing identifier",
      "create_directory_line":   "Create a directory line (receiving address)",
      "update_directory_line":   "Update an existing directory line",
      "delete_directory_line":   "Delete a directory line",
  }