Unstop MCP Server

Instructions

Implementation Reference

• src/unstop_mcp/server.py:28-61 (registration)

  Registration of the 'search_hackathons' tool in the MCP server.

  @server.tool(
      name="search_hackathons",
      description="Search Unstop hackathons with filters, sorting, pagination, and optional cache usage.",
  )
  def search_hackathons(
      oppstatus: str | None = None,
      region: str | None = None,
      payment: str | None = None,
      teamsize: int | None = None,
      usertype: str | None = None,
      sort: str | None = None,
      direction: str | None = None,
      search: str | None = None,
      page: int = 1,
      per_page: int = 18,
      use_cache: bool = True,
  ) -> dict:
      try:
          query = SearchHackathonsInput(
              oppstatus=oppstatus,
              region=region,
              payment=payment,
              teamsize=teamsize,
              usertype=usertype,
              sort=sort,
              direction=direction,
              search=search,
              page=page,
              per_page=per_page,
              use_cache=use_cache,
          )
          return service.search_hackathons(query).model_dump(mode="json")
      except (UnstopValidationError, UnstopAPIError, ValueError) as exc:
          raise ValueError(str(exc)) from exc

• src/unstop_mcp/service.py:158-191 (handler)

  Implementation of the 'search_hackathons' logic in the service class.

  def search_hackathons(self, query: SearchHackathonsInput) -> SearchResponse:
      cache_eligible = query.use_cache and query.oppstatus in (None, "open")
  
      if cache_eligible:
          self.ensure_cache()
          filtered = self.filter_cached(
              region=query.region,
              payment=query.payment,
              teamsize=query.teamsize,
              usertype=query.usertype,
              search=query.search,
          )
          sorted_data = self.sort_data(filtered, query.sort, query.direction)
          return self.build_search_response(
              sorted_data,
              page=query.page,
              per_page=query.per_page,
              applied_filters=query.model_dump(),
              is_cached_result=True,
          )
  
      params = self.build_params(**query.model_dump())
      raw = self.request(params)
      result = self.parse_response(raw)
      return self.build_search_response(
          result["data"],
          page=result["current_page"],
          per_page=result["per_page"],
          total_override=result["total"],
          applied_filters=query.model_dump(),
          is_cached_result=False,
          has_more_override=result["has_more"],
          last_page_override=result["last_page"],
      )