get_ad_detail

Instructions

Implementation Reference

• lbc_mcp_server.py:147-187 (handler)

  The `get_ad_detail` function is the core handler for the tool. It takes an `ad_id` integer, creates a client via `_get_client()`, calls `client.get_ad(ad_id)`, handles `NotFoundError` and `DatadomeError` exceptions, extracts attributes from the ad, and returns a JSON string with full ad details (id, subject, body, price, url, category, location with lat/lng, images, attributes, dates, etc.).

  @mcp.tool()
  def get_ad_detail(
      ad_id: Annotated[int, "Identifiant numérique de l'annonce Leboncoin."],
  ) -> str:
      """Retourne le détail complet d'une annonce Leboncoin (description, prix, localisation, images)."""
      client = _get_client()
      try:
          ad = client.get_ad(ad_id)
      except NotFoundError:
          return json.dumps({"error": f"Annonce {ad_id} introuvable."})
      except DatadomeError as e:
          return json.dumps({"error": f"DataDome: {e}. Utilisez un réseau résidentiel."})
  
      attributes = {}
      if ad.attributes:
          for attr in ad.attributes:
              attributes[attr.key] = attr.value
  
      return json.dumps({
          "id": ad.id,
          "subject": ad.subject,
          "body": ad.body,
          "price": ad.price,
          "url": ad.url,
          "category": ad.category_name,
          "category_id": ad.category_id,
          "location": {
              "city": ad.location.city,
              "zipcode": ad.location.zipcode,
              "department": ad.location.department_name,
              "region": ad.location.region_name,
              "lat": ad.location.lat,
              "lng": ad.location.lng,
          },
          "has_phone": ad.has_phone,
          "images": ad.images if ad.images else [],
          "images_count": len(ad.images) if ad.images else 0,
          "attributes": attributes,
          "first_publication_date": str(ad.first_publication_date) if ad.first_publication_date else None,
          "expiration_date": str(ad.expiration_date) if ad.expiration_date else None,
      }, ensure_ascii=False)

• lbc_mcp_server.py:7-7 (registration)

  The tool is registered via the `@mcp.tool()` decorator on line 147 (decorator on line 147, function defined on line 148). This registers 'get_ad_detail' with the FastMCP server instance.

  - get_ad_detail : full detail of one listing by ID

• lbc_mcp_server.py:148-150 (schema)

  The input schema for get_ad_detail is defined by the function signature: a single parameter `ad_id` of type `Annotated[int, "Identifiant numérique de l'annonce Leboncoin."]`. No output schema annotation is present; the return type is `str` (JSON).

  def get_ad_detail(
      ad_id: Annotated[int, "Identifiant numérique de l'annonce Leboncoin."],
  ) -> str:

• lbc_mcp_server.py:51-55 (helper)

  The `_get_client()` helper function provides a singleton `Client` instance (using the `lbc` library) that `get_ad_detail` uses to call `client.get_ad(ad_id)`.

  def _get_client() -> Client:
      global _client
      if _client is None:
          _client = Client(impersonate="safari18_4_ios", max_retries=2)
      return _client

• test_mcp_server.py:110-126 (helper)

  Test case for the get_ad_detail tool. It calls the tool with `ad_id=1`, parses the JSON response, and verifies either an error is handled gracefully (NotFoundError/DataDomeError) or a structured result with subject, price, and location is returned.

  # ── 4. get_ad_detail ─────────────────────────────────────────
  section("4. get_ad_detail — annonce id=1 (fictif)")
  try:
      result = await session.call_tool("get_ad_detail", {"ad_id": 1})
      content = result.content[0].text
      data = json.loads(content)
      if "error" in data:
          print(f"  ⚠️  {data['error']}")
          print(f"{PASS}  Erreur gérée proprement (NotFoundError ou DataDome)")
      else:
          print(f"  Titre : {data.get('subject')}")
          print(f"  Prix  : {data.get('price')} €")
          print(f"  Ville : {data.get('location', {}).get('city')}")
          print(f"{PASS}  get_ad_detail retourne un résultat structuré")
  except Exception as e:
      print(f"{FAIL}  Exception: {e}")
      failures += 1