qbo_search_vendors

Instructions

Implementation Reference

• qbo_mcp/server.py:124-149 (handler)

  The MCP tool function 'qbo_search_vendors' registered with @mcp.tool(). Validates input, calls client.search_vendors(), returns JSON envelope.

  @mcp.tool()
  def qbo_search_vendors(query: str, limit: int = 50) -> str:
      """Search vendors by display name (substring, case-insensitive).
  
      Args:
          query: Free-text fragment matched against Vendor.DisplayName.
          limit: Cap on returned vendors (1-1000, default 50).
  
      Returns:
          JSON envelope: {"ok": true, "data": {"vendors": [...], "count": N}}.
      """
      if not query or not query.strip():
          return _err("query is required and must be non-empty")
      try:
          capped = max(1, min(limit, 1000))
          vendors = _get_client().search_vendors(query=query.strip(), limit=capped)
          return _ok(
              {
                  "vendors": vendors,
                  "count": len(vendors),
                  "query": query.strip(),
                  "limit": capped,
              }
          )
      except (ValueError, QBOError, RuntimeError) as exc:
          return _err(str(exc))

• qbo_mcp/server.py:126-134 (schema)

  Parameters: query (str, required), limit (int, default 50). Returns JSON with vendors list and count.

  """Search vendors by display name (substring, case-insensitive).
  
  Args:
      query: Free-text fragment matched against Vendor.DisplayName.
      limit: Cap on returned vendors (1-1000, default 50).
  
  Returns:
      JSON envelope: {"ok": true, "data": {"vendors": [...], "count": N}}.
  """

• qbo_mcp/server.py:124-124 (registration)

  Registered via @mcp.tool() decorator on FastMCP instance 'mcp' (line 24).

  @mcp.tool()

• qbo_mcp/client.py:338-354 (helper)

  Client-side search_vendors() builds a QBO query with LIKE clause on DisplayName, delegates to _paginate_query.

  def search_vendors(
      self, query: str, *, limit: int = 50
  ) -> list[dict]:
      """Search active vendors by display name (substring, case-insensitive)."""
      if not query or not query.strip():
          raise ValueError("query must be non-empty")
      safe = _escape_qbo_string(query.strip())
      where = f"DisplayName LIKE '%{safe}%'"
      return list(
          self._paginate_query(
              select_clause="SELECT * FROM Vendor",
              entity="Vendor",
              where=where,
              order_by="DisplayName",
              limit=limit,
          )
      )

• qbo_mcp/client.py:465-478 (helper)

  _escape_qbo_string() escapes special characters (backslash, single-quote, underscore) for QBO string literals in LIKE expressions.

  def _escape_qbo_string(value: str) -> str:
      """Escape characters that would break a QBO string literal.
  
      QBO's query language uses single quotes for strings and a backslash as
      the escape character for both `'` and `\\`. `%` and `_` are also
      metacharacters inside `LIKE` expressions; we leave `%` alone so that
      callers don't lose substring semantics, but escape `_` so a literal
      underscore in a customer name doesn't silently match anything.
      """
      return (
          value.replace("\\", "\\\\")
          .replace("'", "\\'")
          .replace("_", "\\_")
      )