search_routing_code

Instructions

Implementation Reference

• tools/directory_tools.py:315-389 (handler)

  The MCP tool handler for search_routing_code. Decorated with @mcp.tool(), it validates SIREN/SIRET inputs and delegates to DirectoryClient.search_routing_code.

  @mcp.tool()
  async def search_routing_code(
      siret: Annotated[
          Optional[str],
          Field(
              default=None,
              description=(
                  "Establishment SIRET (14 digits). "
                  "Returns all routing codes associated with this establishment. "
                  "Most common filter: use when building a directory line for a specific SIRET."
              ),
          ),
      ] = None,
      siren: Annotated[
          Optional[str],
          Field(
              default=None,
              description=(
                  "Company SIREN (9 digits). "
                  "Returns routing codes for all establishments under this company."
              ),
          ),
      ] = None,
      routing_code: Annotated[
          Optional[str],
          Field(
              default=None,
              description=(
                  "Exact routing code value to look up (e.g. 'ACCOUNTS-DEPT', 'REGION-WEST'). "
                  "Use to verify a routing code exists before referencing it in an invoice."
              ),
          ),
      ] = None,
      limit: Annotated[
          int,
          Field(default=50, ge=1, le=500, description="Maximum number of results per page (1-500, default 50)."),
      ] = 50,
  ) -> dict:
      """
      Search routing codes registered in the PPF directory for a recipient.
  
      Routing codes subdivide a SIRET receiving address to department or service level,
      allowing a company to route invoices to different internal units (e.g. purchasing, accounting).
  
      BEHAVIOR:
      - Returns a paginated list of matching routing codes; empty list if none defined for the criteria.
      - At least one of siret, siren, or routing_code should be provided.
      - A SIRET may have zero or more routing codes; zero means invoices go to the SIRET-level address.
  
      RESPONSE: each item includes instanceId, siret, siren, routingCode, label (optional), and timestamps.
      The instanceId is required to update or delete a routing code.
  
      USAGE GUIDELINES:
      - Call before create_directory_line with a routing_code to confirm the code exists on the target SIRET.
      - Call to enumerate available routing codes when helping a sender choose the correct recipient address.
      - If no routing codes exist for a SIRET, the invoice must be addressed at SIRET level without a routing code.
      - Use create_routing_code to create a new code; use update_routing_code with instanceId to rename it.
      """
      if siren is not None:
          try:
              siren = _validate_siren(siren)
          except ValueError as exc:
              return {"error": str(exc)}
      if siret is not None:
          try:
              siret = _validate_siret(siret)
          except ValueError as exc:
              return {"error": str(exc)}
      client = get_directory_client()
      return await client.search_routing_code(
          siret=siret,
          siren=siren,
          routing_code=routing_code,
          limit=limit,
      )

• tools/directory_tools.py:315-351 (schema)

  The input schema/type definitions for search_routing_code: siret (Optional[str]), siren (Optional[str]), routing_code (Optional[str]), limit (int, default 50, range 1-500). All parameters are optional.

  @mcp.tool()
  async def search_routing_code(
      siret: Annotated[
          Optional[str],
          Field(
              default=None,
              description=(
                  "Establishment SIRET (14 digits). "
                  "Returns all routing codes associated with this establishment. "
                  "Most common filter: use when building a directory line for a specific SIRET."
              ),
          ),
      ] = None,
      siren: Annotated[
          Optional[str],
          Field(
              default=None,
              description=(
                  "Company SIREN (9 digits). "
                  "Returns routing codes for all establishments under this company."
              ),
          ),
      ] = None,
      routing_code: Annotated[
          Optional[str],
          Field(
              default=None,
              description=(
                  "Exact routing code value to look up (e.g. 'ACCOUNTS-DEPT', 'REGION-WEST'). "
                  "Use to verify a routing code exists before referencing it in an invoice."
              ),
          ),
      ] = None,
      limit: Annotated[
          int,
          Field(default=50, ge=1, le=500, description="Maximum number of results per page (1-500, default 50)."),
      ] = 50,

• tools/directory_tools.py:315-389 (registration)

  Tool registered via @mcp.tool() decorator inside register_directory_tools(), alongside 11 other directory tools.

  @mcp.tool()
  async def search_routing_code(
      siret: Annotated[
          Optional[str],
          Field(
              default=None,
              description=(
                  "Establishment SIRET (14 digits). "
                  "Returns all routing codes associated with this establishment. "
                  "Most common filter: use when building a directory line for a specific SIRET."
              ),
          ),
      ] = None,
      siren: Annotated[
          Optional[str],
          Field(
              default=None,
              description=(
                  "Company SIREN (9 digits). "
                  "Returns routing codes for all establishments under this company."
              ),
          ),
      ] = None,
      routing_code: Annotated[
          Optional[str],
          Field(
              default=None,
              description=(
                  "Exact routing code value to look up (e.g. 'ACCOUNTS-DEPT', 'REGION-WEST'). "
                  "Use to verify a routing code exists before referencing it in an invoice."
              ),
          ),
      ] = None,
      limit: Annotated[
          int,
          Field(default=50, ge=1, le=500, description="Maximum number of results per page (1-500, default 50)."),
      ] = 50,
  ) -> dict:
      """
      Search routing codes registered in the PPF directory for a recipient.
  
      Routing codes subdivide a SIRET receiving address to department or service level,
      allowing a company to route invoices to different internal units (e.g. purchasing, accounting).
  
      BEHAVIOR:
      - Returns a paginated list of matching routing codes; empty list if none defined for the criteria.
      - At least one of siret, siren, or routing_code should be provided.
      - A SIRET may have zero or more routing codes; zero means invoices go to the SIRET-level address.
  
      RESPONSE: each item includes instanceId, siret, siren, routingCode, label (optional), and timestamps.
      The instanceId is required to update or delete a routing code.
  
      USAGE GUIDELINES:
      - Call before create_directory_line with a routing_code to confirm the code exists on the target SIRET.
      - Call to enumerate available routing codes when helping a sender choose the correct recipient address.
      - If no routing codes exist for a SIRET, the invoice must be addressed at SIRET level without a routing code.
      - Use create_routing_code to create a new code; use update_routing_code with instanceId to rename it.
      """
      if siren is not None:
          try:
              siren = _validate_siren(siren)
          except ValueError as exc:
              return {"error": str(exc)}
      if siret is not None:
          try:
              siret = _validate_siret(siret)
          except ValueError as exc:
              return {"error": str(exc)}
      client = get_directory_client()
      return await client.search_routing_code(
          siret=siret,
          siren=siren,
          routing_code=routing_code,
          limit=limit,
      )

• clients/directory_client.py:121-139 (helper)

  The HTTP client method that performs the actual API call: POST /v1/routing-code/search with optional siret, siren, routingCode, and limit parameters.

  async def search_routing_code(
      self,
      siret: Optional[str] = None,
      siren: Optional[str] = None,
      routing_code: Optional[str] = None,
      limit: int = 50,
  ) -> dict[str, Any]:
      """POST /v1/routing-code/search — Search routing codes."""
      body: dict[str, Any] = {"limit": limit}
      if siret:
          body["siret"] = siret
      if siren:
          body["siren"] = siren
      if routing_code:
          body["routingCode"] = routing_code
      response = await self._request("POST", "/v1/routing-code/search", json=body)
      if response.status_code == 204:
          return {"total": 0}
      return response.json()