Hex API MCP Server

Instructions

Args:
    search_pattern: Regex pattern to search for in project titles
    limit: Maximum number of projects to return (default: 100)
    offset: Number of projects to skip for pagination (default: 0)

Returns:
    JSON string with matching projects

Implementation Reference

• src/hex_mcp/server.py:77-158 (handler)

  The main handler function for the 'search_hex_projects' tool. It is registered via the @mcp.tool() decorator and implements searching Hex projects by applying a regex pattern to project titles. It fetches projects in batches to handle pagination, filters matches, and returns a JSON-formatted result with metadata.

  @mcp.tool()
  async def search_hex_projects(search_pattern: str, limit: int = 100, offset: int = 0) -> str:
      """Search for Hex projects using regex pattern matching on project titles.
  
      Args:
          search_pattern: Regex pattern to search for in project titles
          limit: Maximum number of projects to return (default: 100)
          offset: Number of projects to skip for pagination (default: 0)
  
      Returns:
          JSON string with matching projects
      """
      # Set a reasonable batch size for fetching projects - balance between
      # reducing API calls and not fetching too much at once
      batch_size = min(100, limit)  # Don't request more than needed
      matched_projects = []
      current_offset = offset
      total_fetched = 0
      max_projects_to_search = 1000  # Safeguard against searching too many projects
  
      try:
          # Compile the regex pattern
          pattern = re.compile(search_pattern, re.IGNORECASE)
  
          # Continue fetching until we have enough matches or run out of projects
          while len(matched_projects) < limit and total_fetched < max_projects_to_search:
              # Adjust batch size dynamically based on match rate to minimize API calls
              if total_fetched > 0:
                  match_rate = len(matched_projects) / total_fetched
                  if match_rate > 0:
                      # Estimate how many more projects we need to fetch
                      remaining_matches_needed = limit - len(matched_projects)
                      estimated_total_needed = remaining_matches_needed / match_rate
                      # Adjust batch size based on estimate, with minimum of 20 and max of 100
                      batch_size = min(max(20, int(estimated_total_needed * 1.2)), 100)  # Add 20% buffer
  
              params = {"limit": batch_size, "offset": current_offset}
  
              try:
                  response = await hex_request("GET", "/projects", params=params)
  
                  projects = response.get("values", [])
  
                  # If no more projects, break
                  if not projects:
                      break
  
                  # Filter projects by title using the regex pattern
                  for project in projects:
                      if "title" in project and pattern.search(project["title"]):
                          matched_projects.append(project)
                          if len(matched_projects) >= limit:
                              break
  
                  # Update for next batch
                  total_fetched += len(projects)
                  current_offset += len(projects)
  
                  # Check pagination info
                  pagination = response.get("pagination", {})
                  if not pagination.get("after"):
                      break
  
              except httpx.HTTPStatusError as e:
                  # If it's not a rate limit error that backoff can handle, raise it
                  if e.response.status_code != 429:
                      raise
  
          # Prepare the response with pagination info
          result = {
              "values": matched_projects[:limit],
              "total_matched": len(matched_projects),
              "total_searched": total_fetched,
              "has_more": len(matched_projects) >= limit or total_fetched >= max_projects_to_search,
          }
  
          return json.dumps(result)
  
      except re.error as e:
          return json.dumps({"error": f"Invalid regex pattern: {str(e)}"})
      except Exception as e:
          return json.dumps({"error": f"Error searching projects: {str(e)}"})

• src/hex_mcp/server.py:77-77 (registration)

  The @mcp.tool() decorator registers the search_hex_projects function as an MCP tool.

  @mcp.tool()

• src/hex_mcp/server.py:78-88 (schema)

  The function signature and docstring define the input schema (search_pattern: str, limit: int=100, offset: int=0) and output (str JSON).

  async def search_hex_projects(search_pattern: str, limit: int = 100, offset: int = 0) -> str:
      """Search for Hex projects using regex pattern matching on project titles.
  
      Args:
          search_pattern: Regex pattern to search for in project titles
          limit: Maximum number of projects to return (default: 100)
          offset: Number of projects to skip for pagination (default: 0)
  
      Returns:
          JSON string with matching projects
      """