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