inspirehep-mcp

Instructions

Implementation Reference

• src/inspirehep_mcp/server.py:121-139 (handler)

  Main async handler for inspirehep_search_by_author tool. Decorated with @mcp.tool, it takes AuthorSearchInput parameters, builds an author query using build_author_query, and executes the search via run_search.

  @mcp.tool(
      name="inspirehep_search_by_author",
      annotations={
          "title": "Search INSPIRE-HEP papers by author",
          "readOnlyHint": True,
          "destructiveHint": False,
          "idempotentHint": True,
          "openWorldHint": True,
      },
  )
  async def inspirehep_search_by_author(params: AuthorSearchInput) -> dict[str, Any]:
      """Search INSPIRE-HEP literature by author."""
  
      query = build_author_query(params.author, 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:62-76 (schema)

  Pydantic schema for AuthorSearchInput. Defines the author field as a list of strings with validation, extends BaseSearchInput for common parameters like limit, year, large_collaboration, and sort_by_citation.

  class AuthorSearchInput(BaseSearchInput):
      author: list[str] = Field(
          ...,
          min_length=1,
          max_length=10,
          description="Author names to search (e.g. ['Witten, Edward', 'Maldacena, Juan']).",
      )
  
      @field_validator("author")
      @classmethod
      def validate_author_list(cls, value: list[str]) -> list[str]:
          cleaned = [item.strip() for item in value]
          if any(not item for item in cleaned):
              raise ValueError("author entries must be non-empty strings.")
          return cleaned

• src/inspirehep_mcp/server.py:121-129 (registration)

  Tool registration decorator that registers inspirehep_search_by_author with MCP. Sets tool name, title description, and hints (readOnly, idempotent, etc.).

  @mcp.tool(
      name="inspirehep_search_by_author",
      annotations={
          "title": "Search INSPIRE-HEP papers by author",
          "readOnlyHint": True,
          "destructiveHint": False,
          "idempotentHint": True,
          "openWorldHint": True,
      },

• src/inspirehep_mcp/client.py:47-52 (helper)

  Helper function that builds the INSPIRE-HEP query string from a list of author names. Escapes quotes and joins author clauses with 'and', then applies year and collaboration filters.

  def build_author_query(
      authors: list[str], large_collaboration: bool, year: int | None = None
  ) -> str:
      clauses = [f'author "{_escape_quotes(author)}"' for author in authors]
      base_query = " and ".join(clauses)
      return _apply_filters(base_query, large_collaboration, year)

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

  Helper function that executes the search query using InspireHEPClient. Handles HTTP errors, converts sort preference, and returns formatted results with record count and list.

  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,
      }