inspirehep-mcp

Instructions

Implementation Reference

• src/inspirehep_mcp/server.py:100-118 (handler)

  The inspirehep_search_by_fulltext tool handler function decorated with @mcp.tool. It accepts FulltextSearchInput parameters, builds a fulltext query using build_fulltext_query, and executes the search via run_search.
  @mcp.tool( name="inspirehep_search_by_fulltext", annotations={ "title": "Search INSPIRE-HEP papers by full text", "readOnlyHint": True, "destructiveHint": False, "idempotentHint": True, "openWorldHint": True, }, ) async def inspirehep_search_by_fulltext(params: FulltextSearchInput) -> dict[str, Any]: """Search INSPIRE-HEP literature by full text.""" query = build_fulltext_query(params.fulltext, 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:53-59 (schema)

  FulltextSearchInput schema definition - a Pydantic BaseModel that validates the fulltext parameter (required string, min 1, max 300 chars) and inherits from BaseSearchInput for additional fields like limit, sort_by_citation, year, and large_collaboration.
  class FulltextSearchInput(BaseSearchInput): fulltext: str = Field( ..., min_length=1, max_length=300, description="Full-text keyword or phrase to search in paper body.", )
• src/inspirehep_mcp/server.py:19-41 (schema)

  BaseSearchInput schema - base Pydantic BaseModel with common search parameters including large_collaboration (bool), limit (int, 1-50), sort_by_citation (bool), and year (optional int).
  class BaseSearchInput(BaseModel): model_config = ConfigDict(str_strip_whitespace=True, extra="forbid") large_collaboration: bool = Field( default=False, description="Include large-collaboration papers. Default false excludes very large collaborations.", ) limit: int = Field( default=20, ge=1, le=50, description="Maximum number of papers to return (default: 20).", ) sort_by_citation: bool = Field( default=True, description="If true, sort by citation count. If false, sort by most recent date.", ) year: int | None = Field( default=None, ge=1900, le=2100, description="Optional publication year filter (e.g. 2020).", )
• src/inspirehep_mcp/client.py:41-44 (helper)

  build_fulltext_query helper function that constructs an INSPIRE-HEP fulltext search query string by escaping the input text and applying optional filters for year and collaboration size.
  def build_fulltext_query(fulltext: str, large_collaboration: bool, year: int | None = None) -> str: escaped = _escape_quotes(fulltext) base_query = f'ft "{escaped}"' return _apply_filters(base_query, large_collaboration, year)
• src/inspirehep_mcp/server.py:142-172 (helper)

  run_search helper function that executes the actual search request to INSPIRE-HEP API, handles 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, }