get_paper_references
Retrieve a list of academic papers referenced by a specific paper using the Semantic Scholar API. Specify paper ID, results limit, offset, and fields for tailored output.
Instructions
Get papers referenced by a specific paper.
Args:
paper_id: Paper ID to get references for
limit: Maximum number of results (default: 10, max: 1000)
offset: Number of results to skip (default: 0)
fields: Comma-separated list of fields to return
Returns:
List of referenced papers
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| fields | No | ||
| limit | No | ||
| offset | No | ||
| paper_id | Yes |
Input Schema (JSON Schema)
{
"properties": {
"fields": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Fields"
},
"limit": {
"default": 10,
"title": "Limit",
"type": "integer"
},
"offset": {
"default": 0,
"title": "Offset",
"type": "integer"
},
"paper_id": {
"title": "Paper Id",
"type": "string"
}
},
"required": [
"paper_id"
],
"title": "get_paper_referencesArguments",
"type": "object"
}
Implementation Reference
- The handler function that implements the get_paper_references tool. It fetches references for a given paper ID from the Semantic Scholar API, handles errors, formats the results using format_paper helper, and returns a formatted string listing the references.@mcp.tool() async def get_paper_references( paper_id: str, limit: int = 10, offset: int = 0, fields: Optional[str] = None ) -> str: """ Get papers referenced by a specific paper. Args: paper_id: Paper ID to get references for limit: Maximum number of results (default: 10, max: 1000) offset: Number of results to skip (default: 0) fields: Comma-separated list of fields to return Returns: List of referenced papers """ params: Dict[str, Any] = {"limit": min(limit, 1000), "offset": offset} if fields: params["fields"] = fields else: params["fields"] = "paperId,title,authors,year,venue,citationCount" encoded_id = quote(paper_id, safe="") result = await make_api_request(f"paper/{encoded_id}/references", params) if result is None: return "Error: Failed to fetch references" if "error" in result: return f"Error: {result['error']}" references = result.get("data", []) total = result.get("total", 0) if not references: return "No references found for this paper." formatted_references = [] for i, reference in enumerate(references, 1): cited_paper = reference.get("citedPaper", {}) if cited_paper: formatted_references.append(f"{i}. {format_paper(cited_paper)}") result_text = ( f"Found {total} total references (showing {len(formatted_references)}):\n\n" ) result_text += "\n\n".join(formatted_references) return result_text
- Helper function used by get_paper_references to format individual paper information into a readable string.def format_paper(paper: Dict[str, Any]) -> str: """Format a paper for display.""" title = paper.get("title", "Unknown Title") authors = paper.get("authors", []) author_names = [author.get("name", "Unknown") for author in authors[:3]] author_str = ", ".join(author_names) if len(authors) > 3: author_str += f" (and {len(authors) - 3} others)" year = paper.get("year") year_str = f" ({year})" if year else "" venue = paper.get("venue", "") venue_str = f" - {venue}" if venue else "" citation_count = paper.get("citationCount", 0) paper_id = paper.get("paperId", "") return f"Title: {title}\nAuthors: {author_str}{year_str}{venue_str}\nCitations: {citation_count}\nPaper ID: {paper_id}"
- Core helper function that makes HTTP requests to the Semantic Scholar API, handles authentication, errors, and rate limiting. Used by get_paper_references.async def make_api_request( endpoint: str, params: Optional[Dict[str, Any]] = None, method: str = "GET" ) -> Optional[Dict[str, Any]]: """Make a request to the Semantic Scholar API.""" url = f"{BASE_URL}/{endpoint.lstrip('/')}" headers = { "Accept": "application/json", "User-Agent": f"semantic-scholar-mcp/{USER_AGENT_VERSION}", } if API_KEY: headers["x-api-key"] = API_KEY try: async with httpx.AsyncClient(timeout=API_TIMEOUT) as client: if method == "GET": response = await client.get(url, headers=headers, params=params) elif method == "POST": response = await client.post(url, headers=headers, json=params) else: raise ValueError(f"Unsupported HTTP method: {method}") response.raise_for_status() return response.json() except httpx.HTTPStatusError as e: if e.response.status_code == 403: if not API_KEY: return { "error": "Rate limit exceeded. The shared public rate limit (1000 req/sec) may be exceeded. Get a free API key from https://www.semanticscholar.org/product/api for dedicated limits." } else: return { "error": f"API key may be invalid or rate limit exceeded: {str(e)}" } elif e.response.status_code == 429: return { "error": "Rate limit exceeded. Please wait a moment and try again, or get an API key for dedicated higher limits." } else: return {"error": f"HTTP error: {str(e)}"} except httpx.HTTPError as e: return {"error": f"HTTP error: {str(e)}"} except Exception as e: return {"error": f"Request failed: {str(e)}"}
- src/semantic_scholar_mcp/server.py:485-485 (registration)The @mcp.tool() decorator registers the get_paper_references function as an MCP tool.@mcp.tool()