inspirehep_search_by_title

Instructions

Implementation Reference

• src/inspirehep_mcp/server.py:79-97 (handler)

  The main handler function 'inspirehep_search_by_title' decorated with @mcp.tool(). It takes TitleSearchInput params, builds a query using build_title_query, and executes the search via run_search().

  @mcp.tool(
      name="inspirehep_search_by_title",
      annotations={
          "title": "Search INSPIRE-HEP papers by title",
          "readOnlyHint": True,
          "destructiveHint": False,
          "idempotentHint": True,
          "openWorldHint": True,
      },
  )
  async def inspirehep_search_by_title(params: TitleSearchInput) -> dict[str, Any]:
      """Search INSPIRE-HEP literature by title."""
  
      query = build_title_query(params.title, params.large_collaboration, params.year)
      return await run_search(
          query=query,
          limit=params.limit,
          sort_by_citation=params.sort_by_citation,
      )

• src/inspirehep_mcp/server.py:44-50 (schema)

  TitleSearchInput Pydantic model defining the input schema with title field (required, 1-300 chars) and inheriting common search parameters from BaseSearchInput (large_collaboration, limit, sort_by_citation, year).

  class TitleSearchInput(BaseSearchInput):
      title: str = Field(
          ...,
          min_length=1,
          max_length=300,
          description="Title keyword or phrase to search.",
      )

• src/inspirehep_mcp/server.py:142-172 (helper)

  run_search async helper function that executes the literature search using InspireHEPClient, handles HTTP errors, and returns formatted results with count and records.

  async def run_search(
      *,
      query: str,
      limit: int,
      sort_by_citation: bool,
      client: InspireHEPClient | None = None,
  ) -> dict[str, Any]:
      sort = _to_inspire_sort(sort_by_citation)
      try:
          if client is not None:
              search_result = await client.search_literature(query=query, limit=limit, sort=sort)
          else:
              async with InspireHEPClient() as default_client:
                  search_result = await default_client.search_literature(
                      query=query,
                      limit=limit,
                      sort=sort,
                  )
      except httpx.HTTPStatusError as exc:
          status = exc.response.status_code
          message = exc.response.text or "No response body."
          raise RuntimeError(
              f"INSPIRE API error ({status}): {message[:300]}"
          ) from exc
      except httpx.HTTPError as exc:
          raise RuntimeError(f"INSPIRE API request failed: {exc}") from exc
  
      return {
          "count": len(search_result.records),
          "records": search_result.records,
      }

• src/inspirehep_mcp/client.py:35-38 (helper)

  build_title_query function that constructs an INSPIRE-HEP title search query by escaping the title and applying optional filters (large_collaboration, year).

  def build_title_query(title: str, large_collaboration: bool, year: int | None = None) -> str:
      escaped = _escape_quotes(title)
      base_query = f'title "{escaped}"'
      return _apply_filters(base_query, large_collaboration, year)

• src/inspirehep_mcp/client.py:184-194 (helper)

  Helper functions _escape_quotes (line 184-185) and _apply_filters (line 188-194) that sanitize input and add year/author-count filters to the search query.

  def _escape_quotes(value: str) -> str:
      return value.replace("\\", "\\\\").replace('"', '\\"')
  
  
  def _apply_filters(base_query: str, large_collaboration: bool, year: int | None) -> str:
      clauses = [base_query]
      if year is not None:
          clauses.append(f"year {year}")
      if not large_collaboration:
          clauses.append(f"ac 1->{DEFAULT_NON_COLLAB_MAX_AUTHORS}")
      return " and ".join(clauses)