inspirehep_search_by_fulltext

Search high-energy physics literature by keyword or phrase within paper content, with options to filter by year, collaboration size, and sort by citations or date.

Instructions

Search INSPIRE-HEP literature by full text.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`params`	Yes

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

inspirehep-mcp