paper_citation_graph

Visualize academic citation networks using Mermaid diagrams and structured data. Generate citation graphs from Semantic Scholar API to analyze paper relationships and dependencies.

Instructions

生成论文引用图谱（Mermaid 可视化 + 结构化数据）。

通过 Semantic Scholar API 获取论文的引用(citations)和参考文献(references)，输出 Mermaid 图谱代码（可直接在 Markdown 中渲染）和结构化 JSON。

Args: doi: 论文的 DOI，例如 "10.1109/tim.2021.3106677" depth: 递归深度 (1=直接引用/参考, 2=二层引用)，默认 1 max_per_level: 每层最多获取的论文数，默认 10

Returns: 引用图谱 JSON，包含 mermaid (图谱代码), nodes, edges, statistics 等

Input Schema

TableJSON Schema

Name	Required	Description	Default
`doi`	Yes
`depth`	No
`max_per_level`	No

Implementation Reference

scholar_mcp_server.py:226-241 (handler)

The handler function for the 'paper_citation_graph' MCP tool in scholar_mcp_server.py. It calls get_citation_graph and returns a JSON string.

def paper_citation_graph(doi: str, depth: int = 1, max_per_level: int = 10) -> str:
    """生成论文引用图谱（Mermaid 可视化 + 结构化数据）。

    通过 Semantic Scholar API 获取论文的引用(citations)和参考文献(references)，
    输出 Mermaid 图谱代码（可直接在 Markdown 中渲染）和结构化 JSON。

    Args:
        doi: 论文的 DOI，例如 "10.1109/tim.2021.3106677"
        depth: 递归深度 (1=直接引用/参考, 2=二层引用)，默认 1
        max_per_level: 每层最多获取的论文数，默认 10

    Returns:
        引用图谱 JSON，包含 mermaid (图谱代码), nodes, edges, statistics 等
    """
    result = get_citation_graph(doi, depth, max_per_level)
    return json.dumps(result, ensure_ascii=False, indent=2)

scholar_mcp_server.py:225-226 (registration)
The registration of the 'paper_citation_graph' tool using the @mcp.tool() decorator.
```
@mcp.tool()
def paper_citation_graph(doi: str, depth: int = 1, max_per_level: int = 10) -> str:
```

citation_graph.py:39-100 (helper)

The core logic that implements the citation graph generation, used by the paper_citation_graph tool handler.

def get_citation_graph(doi: str, depth: int = 1, max_per_level: int = 10) -> dict:
    """获取论文引用图谱

    Args:
        doi: 论文 DOI 或标识符
        depth: 递归深度 (1=直接引用/参考, 2=二层引用)
        max_per_level: 每层最多获取的论文数

    Returns:
        包含 mermaid 图谱代码和结构化数据的字典
    """
    paper_id = _s2_id(doi)
    fields = "title,authors,year,citationCount,externalIds"
    ref_fields = "title,authors,year,citationCount,externalIds"

    # 获取中心论文信息
    try:
        r = requests.get(
            f"{S2_API}/{paper_id}",
            params={"fields": fields},
            timeout=15,
        )
        if r.status_code != 200:
            return {"success": False, "error": f"paper not found: {doi} (HTTP {r.status_code})"}
        center = r.json()
    except Exception as e:
        return {"success": False, "error": f"API error: {str(e)}"}

    center_title = center.get("title", "Unknown")
    center_year = center.get("year", "")
    center_cited = center.get("citationCount", 0)
    center_doi = (center.get("externalIds") or {}).get("DOI", doi)

    nodes = [{
        "id": "center",
        "title": center_title,
        "year": center_year,
        "cited_by": center_cited,
        "doi": center_doi,
        "type": "center",
    }]
    edges = []

    # 获取参考文献 (references = 这篇论文引用了哪些)
    try:
        r = requests.get(
            f"{S2_API}/{paper_id}/references",
            params={"fields": ref_fields, "limit": max_per_level},
            timeout=15,
        )
        if r.status_code == 200:
            for i, item in enumerate(r.json().get("data") or []):
                cited_paper = item.get("citedPaper", {})
                if not cited_paper or not cited_paper.get("title"):
                    continue
                node_id = f"ref_{i}"
                ref_doi = (cited_paper.get("externalIds") or {}).get("DOI", "")
                nodes.append({
                    "id": node_id,
                    "title": cited_paper.get("title", "Unknown"),
                    "year": cited_paper.get("year", ""),
                    "cited_by": cited_paper.get("citationCount", 0),

Scholar MCP Server