semantic_scholar_match_paper
Read-onlyIdempotent
Retrieves the best matching paper for a given title and returns a match score to assess relevance.
Instructions
Find the single best paper matching a title string. Returns match score.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- The `match_paper` async function is the handler for the 'semantic_scholar_match_paper' tool. It calls the Semantic Scholar API endpoint 'paper/search/match' with the query title, returns the best matching paper along with a match score. Supports both markdown and JSON response formats.
@mcp.tool( name="semantic_scholar_match_paper", annotations=ToolAnnotations(readOnlyHint=True, idempotentHint=True, openWorldHint=True), ) async def match_paper(params: PaperMatchInput) -> str: """Find the single best paper matching a title string. Returns match score.""" logger.info("Matching paper: %s", params.query) try: response = await _make_request( "GET", "paper/search/match", params={"query": params.query, "fields": ",".join(PAPER_SEARCH_FIELDS)}, api_key=params.api_key, ) papers = response.get("data", []) if isinstance(response, dict) else [] except SemanticScholarError as e: raise ToolError(str(e)) from e if not papers: return "No matching paper found." paper = papers[0] match_score = paper.get("matchScore", 0) if params.response_format == ResponseFormat.JSON: return json.dumps({"matchScore": match_score, "paper": paper}, indent=2) lines = [ "## Paper Match", f"**Match Score:** {match_score:.1f}", "", _format_paper_markdown(paper), ] return "\n".join(lines) - The `PaperMatchInput` Pydantic model defines the input schema for the tool, with fields: query (paper title, required), response_format (default 'markdown'), and api_key (optional).
class PaperMatchInput(BaseModel): model_config = ConfigDict(str_strip_whitespace=True, extra="forbid") query: str = Field(..., description="Paper title to match", min_length=1, max_length=500) response_format: ResponseFormat = Field( default=ResponseFormat.MARKDOWN, description="Output format" ) api_key: str | None = Field( default=None, description="API key (overrides SEMANTIC_SCHOLAR_API_KEY env var)", ) - src/semantic_scholar_mcp/server.py:1243-1246 (registration)The tool is registered via the `@mcp.tool(name='semantic_scholar_match_paper', ...)` decorator on the `match_paper` function. The decorator also sets annotations marking it as read-only, idempotent, and open-world.
@mcp.tool( name="semantic_scholar_match_paper", annotations=ToolAnnotations(readOnlyHint=True, idempotentHint=True, openWorldHint=True), )