borme_lookup

Instructions

Implementation Reference

• entia_mcp/server.py:204-230 (handler)

  The MCP tool handler for borme_lookup. Calls the ENTIA REST API /v1/profile/{query} with country=ES, extracts the 'borme' section from the response, and returns a structured dict with found, entity, borme, acts count, officers, founding date, and trust score.

  @mcp.tool()
  def borme_lookup(query: str) -> dict[str, Any]:
      """Spanish mercantile acts from BORME (40M+ acts, 2009-2026).
  
      Use when: user asks "who founded X?", "when was X incorporated?",
                "directors of Santander", "corporate history of Inditex".
      Returns: Acts count, key officers, founding date, corporate events.
  
      Examples:
        borme_lookup("Telefonica")   → 17,320 acts
        borme_lookup("A28015865")    → Telefonica by CIF
        borme_lookup("Santander")    → 50,722 acts
  
      Args:
          query: Company name or Spanish CIF (without ES prefix, e.g. A28015865)
      """
      result = _get(f"/v1/profile/{query}", {"country": "ES"})
      borme = result.get("borme", {})
      return {
          "found": result.get("found", False),
          "entity": result.get("entity", {}),
          "borme": borme,
          "borme_acts_count": borme.get("acts_count", 0),
          "officers": borme.get("officers", []),
          "founding_date": borme.get("founding_date"),
          "trust_score": result.get("trust_score", {}),
      }

• entia_mcp/server.py:204-230 (registration)

  The borme_lookup function is registered as an MCP tool via the @mcp.tool() decorator on the FastMCP instance named 'mcp'.

  @mcp.tool()
  def borme_lookup(query: str) -> dict[str, Any]:
      """Spanish mercantile acts from BORME (40M+ acts, 2009-2026).
  
      Use when: user asks "who founded X?", "when was X incorporated?",
                "directors of Santander", "corporate history of Inditex".
      Returns: Acts count, key officers, founding date, corporate events.
  
      Examples:
        borme_lookup("Telefonica")   → 17,320 acts
        borme_lookup("A28015865")    → Telefonica by CIF
        borme_lookup("Santander")    → 50,722 acts
  
      Args:
          query: Company name or Spanish CIF (without ES prefix, e.g. A28015865)
      """
      result = _get(f"/v1/profile/{query}", {"country": "ES"})
      borme = result.get("borme", {})
      return {
          "found": result.get("found", False),
          "entity": result.get("entity", {}),
          "borme": borme,
          "borme_acts_count": borme.get("acts_count", 0),
          "officers": borme.get("officers", []),
          "founding_date": borme.get("founding_date"),
          "trust_score": result.get("trust_score", {}),
      }

• entia_mcp/server.py:69-79 (helper)

  Helper function that builds HTTP headers including the API key for calls to the ENTIA REST API.

  def _headers() -> dict[str, str]:
      h: dict[str, str] = {
          "Accept": "application/json",
          "User-Agent": "entia-mcp-server/3.2.4",
      }
      if API_KEY:
          h["X-ENTIA-Key"] = API_KEY
      return h
  
  
  def _get(path: str, params: Optional[dict[str, Any]] = None) -> dict[str, Any]:

• entia_mcp/server.py:79-90 (helper)

  Helper function used by borme_lookup to make GET requests to the ENTIA REST API with error handling.

  def _get(path: str, params: Optional[dict[str, Any]] = None) -> dict[str, Any]:
      """GET request to ENTIA REST API."""
      url = f"{BASE_URL}{path}"
      try:
          with httpx.Client(timeout=TIMEOUT) as client:
              r = client.get(url, headers=_headers(), params=params or {})
          r.raise_for_status()
          return r.json()
      except httpx.HTTPStatusError as exc:
          return {"error": str(exc), "status_code": exc.response.status_code}
      except Exception as exc:  # noqa: BLE001
          return {"error": str(exc)}