inspirehep_search_by_title

Search high-energy physics literature on INSPIRE-HEP using title keywords to find relevant papers with citation counts, abstracts, and arXiv links.

Instructions

Search INSPIRE-HEP literature by title.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`params`	Yes

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)

inspirehep-mcp