search_establishment

Instructions

Implementation Reference

• tools/directory_tools.py:196-283 (handler)

  MCP tool handler for search_establishment — validates SIREN/SIRET via Luhn checks, then delegates to the HTTP client.

  async def search_establishment(
      siret: Annotated[
          Optional[str],
          Field(
              default=None,
              description=(
                  "Establishment SIRET number (14 digits, no spaces). "
                  "Example: '12345678900012'. "
                  "Use when you know the exact establishment; returns at most one result."
              ),
          ),
      ] = None,
      siren: Annotated[
          Optional[str],
          Field(
              default=None,
              description=(
                  "Parent company SIREN (9 digits). "
                  "Returns all establishments registered under this company. "
                  "Use to discover all SIRETs for a given SIREN."
              ),
          ),
      ] = None,
      administrative_status: Annotated[
          Optional[str],
          Field(
              default=None,
              description=(
                  "Administrative status of the establishment in the PPF directory. "
                  "Active: establishment is open and reachable for invoicing. "
                  "Inactive: establishment is closed; invoices cannot be sent to it."
              ),
          ),
      ] = None,
      updated_after: Annotated[
          Optional[str],
          Field(
              default=None,
              description=(
                  "Pagination cursor: only return establishments updated after this "
                  "date/time (ISO 8601, e.g. 2024-09-01T00:00:00Z). "
                  "Use the 'nextUpdatedAfter' field from the previous response to fetch the next page."
              ),
          ),
      ] = 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 for establishments (SIRETs) in the PPF directory by criteria.
  
      An establishment is a physical place of business activity identified by its 14-digit SIRET.
      Each company (SIREN) can have multiple establishments.
  
      BEHAVIOR:
      - Returns a paginated list of matching establishments; empty list if none match.
      - At least one search criterion should be provided; omitting all returns an error.
      - Pagination: if the response includes 'nextUpdatedAfter', pass it as updated_after to get the next page.
  
      RESPONSE: each item includes siret, siren, name, administrativeStatus (Active/Inactive),
      approvedPlatformId, and timestamps (createdAt, updatedAt).
  
      USAGE GUIDELINES:
      - Prefer get_establishment_by_siret when you already know the exact SIRET (faster, direct lookup).
      - Use search_establishment with siren to enumerate all establishments of a company.
      - Always verify administrativeStatus == Active before sending an invoice to that establishment.
      - Call this before create_directory_line to confirm the target SIRET is registered in the PPF directory.
      """
      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_establishment(
          siret=siret,
          siren=siren,
          administrative_status=administrative_status,
          updated_after=updated_after,
          limit=limit,
      )

• clients/directory_client.py:89-110 (helper)

  HTTP client method that sends POST /v1/siret/search to the PPF Directory Service API.

  async def search_establishment(
      self,
      siret: Optional[str] = None,
      siren: Optional[str] = None,
      administrative_status: Optional[str] = None,
      updated_after: Optional[str] = None,
      limit: int = 50,
  ) -> dict[str, Any]:
      """POST /v1/siret/search — Search establishments in the directory."""
      body: dict[str, Any] = {"limit": limit}
      if siret:
          body["siret"] = siret
      if siren:
          body["siren"] = siren
      if administrative_status:
          body["administrativeStatus"] = administrative_status
      if updated_after:
          body["updatedAfter"] = updated_after
      response = await self._request("POST", "/v1/siret/search", json=body)
      if response.status_code == 204:
          return {"total": 0}
      return response.json()

• tools/directory_tools.py:197-245 (schema)

  Pydantic Field annotations defining the input parameters for the search_establishment tool.

      siret: Annotated[
          Optional[str],
          Field(
              default=None,
              description=(
                  "Establishment SIRET number (14 digits, no spaces). "
                  "Example: '12345678900012'. "
                  "Use when you know the exact establishment; returns at most one result."
              ),
          ),
      ] = None,
      siren: Annotated[
          Optional[str],
          Field(
              default=None,
              description=(
                  "Parent company SIREN (9 digits). "
                  "Returns all establishments registered under this company. "
                  "Use to discover all SIRETs for a given SIREN."
              ),
          ),
      ] = None,
      administrative_status: Annotated[
          Optional[str],
          Field(
              default=None,
              description=(
                  "Administrative status of the establishment in the PPF directory. "
                  "Active: establishment is open and reachable for invoicing. "
                  "Inactive: establishment is closed; invoices cannot be sent to it."
              ),
          ),
      ] = None,
      updated_after: Annotated[
          Optional[str],
          Field(
              default=None,
              description=(
                  "Pagination cursor: only return establishments updated after this "
                  "date/time (ISO 8601, e.g. 2024-09-01T00:00:00Z). "
                  "Use the 'nextUpdatedAfter' field from the previous response to fetch the next page."
              ),
          ),
      ] = None,
      limit: Annotated[
          int,
          Field(default=50, ge=1, le=500, description="Maximum number of results per page (1-500, default 50)."),
      ] = 50,
  ) -> dict:

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

  The @mcp.tool() decorator on search_establishment (line 195) registers it as an MCP tool when register_directory_tools(mcp) is called.

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