inspirehep-mcp

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)