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