search_jobs
Search jobs using filters for keywords, title, location, salary, experience, and visa sponsorship.
Instructions
Search for jobs using the HireBase API
Args:
query: Full text search query
and_keywords: Keywords that must all appear in results
or_keywords: Keywords where at least one must appear
not_keywords: Keywords that must not appear
title: Job titles to search for
category: Job categories to filter by
country: Countries to filter by
city: Cities to filter by
location_type: Location types (Remote, In-Person, Hybrid)
company: Companies to filter by
salary_from: Minimum salary
salary_to: Maximum salary
salary_currency: Salary currency (e.g. USD)
years_from: Minimum years of experience
years_to: Maximum years of experience
visa: Whether job offers visa sponsorship
limit: Maximum number of results to returnInput Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | ||
| and_keywords | No | ||
| or_keywords | No | ||
| not_keywords | No | ||
| title | No | ||
| category | No | ||
| country | No | ||
| city | No | ||
| location_type | No | ||
| company | No | ||
| salary_from | No | ||
| salary_to | No | ||
| salary_currency | No | ||
| years_from | No | ||
| years_to | No | ||
| visa | No | ||
| limit | No |
Implementation Reference
- src/server.py:138-182 (handler)The MCP tool handler function decorated with @mcp.tool() that defines the search_jobs tool with all its parameters and delegates to _search_jobs_logic.
@mcp.tool() def search_jobs( query: Optional[str] = None, and_keywords: Optional[List[str]] = None, or_keywords: Optional[List[str]] = None, not_keywords: Optional[List[str]] = None, title: Optional[List[str]] = None, category: Optional[List[str]] = None, country: Optional[List[str]] = None, city: Optional[List[str]] = None, location_type: Optional[List[str]] = None, company: Optional[List[str]] = None, salary_from: Optional[float] = None, salary_to: Optional[float] = None, salary_currency: Optional[str] = None, years_from: Optional[int] = None, years_to: Optional[int] = None, visa: Optional[bool] = None, limit: Optional[int] = 10, ) -> Dict[str, Any]: """Search for jobs using the HireBase API Args: query: Full text search query and_keywords: Keywords that must all appear in results or_keywords: Keywords where at least one must appear not_keywords: Keywords that must not appear title: Job titles to search for category: Job categories to filter by country: Countries to filter by city: Cities to filter by location_type: Location types (Remote, In-Person, Hybrid) company: Companies to filter by salary_from: Minimum salary salary_to: Maximum salary salary_currency: Salary currency (e.g. USD) years_from: Minimum years of experience years_to: Maximum years of experience visa: Whether job offers visa sponsorship limit: Maximum number of results to return """ # Pass all arguments to the internal logic function # Use locals() to capture all passed arguments args = locals() return _search_jobs_logic(**args) - src/server.py:110-135 (helper)Internal function _search_jobs_logic that performs the actual API call to HireBase. It converts kwargs to JobSearchParams, builds the request, calls the API, and returns JSON or an error dict.
def _search_jobs_logic(**kwargs) -> Dict[str, Any]: """Internal logic for searching jobs via HireBase API.""" print("--- DEBUG: Entering _search_jobs_logic ---") try: # Create JobSearchParams from kwargs kwargs_copy = kwargs.copy() if "query" in kwargs_copy: kwargs_copy["q"] = kwargs_copy.pop("query") search_params_obj = JobSearchParams(**kwargs_copy) response = requests.get( f"{HIREBASE_API_BASE}/jobs", headers=get_hirebase_headers(), params=search_params_obj.to_params(), ) response.raise_for_status() return response.json() except requests.exceptions.RequestException as e: # Log the error or handle it as needed # print(f"HireBase API Error: {e}") # Example logging return {"error": str(e)} except TypeError as e: # Handle cases where kwargs don't match JobSearchParams return {"error": f"Invalid search parameter: {e}"} - src/server.py:24-107 (schema)The JobSearchParams dataclass and its to_params() method that define the schema for search parameters, converting them to API query parameters with proper camelCase naming.
@dataclass class JobSearchParams: """Parameters for job search""" q: Optional[str] = None and_keywords: Optional[List[str]] = None or_keywords: Optional[List[str]] = None not_keywords: Optional[List[str]] = None title: Optional[List[str]] = None category: Optional[List[str]] = None country: Optional[List[str]] = None region: Optional[List[str]] = None city: Optional[List[str]] = None location_type: Optional[List[str]] = None company: Optional[List[str]] = None industry: Optional[List[str]] = None company_size_from: Optional[int] = None company_size_to: Optional[int] = None years_from: Optional[int] = None years_to: Optional[int] = None salary_from: Optional[float] = None salary_to: Optional[float] = None salary_currency: Optional[str] = None salary_period: Optional[str] = None visa: Optional[bool] = None days: Optional[int] = None expired: Optional[bool] = None limit: Optional[int] = None offset: Optional[int] = None def to_params(self) -> Dict[str, Any]: """Convert to API parameters""" params = {} if self.q: params["q"] = self.q if self.and_keywords: params["and"] = self.and_keywords if self.or_keywords: params["or"] = self.or_keywords if self.not_keywords: params["not"] = self.not_keywords if self.title: params["title"] = self.title if self.category: params["category"] = self.category if self.country: params["country"] = self.country if self.region: params["region"] = self.region if self.city: params["city"] = self.city if self.location_type: params["locationType"] = self.location_type if self.company: params["company"] = self.company if self.industry: params["industry"] = self.industry if self.company_size_from is not None: params["companySizeFrom"] = self.company_size_from if self.company_size_to is not None: params["companySizeTo"] = self.company_size_to if self.years_from is not None: params["yearsFrom"] = self.years_from if self.years_to is not None: params["yearsTo"] = self.years_to if self.salary_from is not None: params["salaryFrom"] = self.salary_from if self.salary_to is not None: params["salaryTo"] = self.salary_to if self.salary_currency: params["salaryCurrency"] = self.salary_currency if self.salary_period: params["salaryPeriod"] = self.salary_period if self.visa is not None: params["visa"] = self.visa if self.days is not None: params["days"] = self.days if self.expired is not None: params["expired"] = self.expired if self.limit is not None: params["limit"] = self.limit if self.offset is not None: params["offset"] = self.offset return params - src/server.py:6-9 (registration)The MCP server instance creation and the @mcp.tool() decorator on search_jobs registers it as a tool. The FastMCP server is named 'Hirebase'.
from mcp.server.fastmcp import FastMCP # Create a FastMCP server instance named "Hirebase" mcp = FastMCP("Hirebase") - src/server.py:16-21 (helper)Helper function get_hirebase_headers() used by _search_jobs_logic to construct API request headers.
def get_hirebase_headers(): """Get headers for HireBase API requests""" headers = {"Content-Type": "application/json"} if HIREBASE_API_KEY: headers["x-api-key"] = HIREBASE_API_KEY return headers