Skip to content

Yuan1z0825/nature-skills / skills/nature-academic-search

nature-academic-search

Flagged

Search literature across sources, verify or manage citations, and build MeSH strategies or citation-impact audits. Use for 文献检索、引文核对、参考文献管理、严格他引 and evidence-backed citer profiles; not for translating a paper or drafting manuscript prose.

FileKindSize
README.mdmarkdown2.6 KB
README_EN.mdmarkdown3.0 KB
SKILL.mdexecutableskill md3.5 KB
agents/openai.yamlconfig265 B
config/mcp-snippet.jsonconfig502 B
config/settings-snippet.jsonconfig59 B
config/triggers-academic-search.tomlconfig978 B
install.shexecutablescript4.3 KB
manifest.yamlconfig3.1 KB
mcp-server/README.mdmarkdown1.9 KB
mcp-server/academic_search_server.pyscript20.9 KB
mcp-server/config.tomlconfig249 B
mcp-server/requirements.txtmanifest134 B
mcp-server/sources/__init__.pyscript352 B
mcp-server/sources/arxiv.pyscript11.4 KB
mcp-server/sources/crossref.pyscript8.0 KB
mcp-server/sources/elsevier_common.pyscript2.4 KB
mcp-server/sources/pubmed.pyscript13.7 KB
mcp-server/sources/sciencedirect.pyscript6.9 KB
mcp-server/sources/scopus.pyscript19.0 KB
mcp-server/tests/__init__.pyscript40 B
mcp-server/tests/test_arxiv_error_entries.pyscript1.4 KB
mcp-server/tests/test_citation_errors.pyscript1.6 KB
mcp-server/tests/test_crossref_version_relations.pyscript3.3 KB
mcp-server/tests/test_elsevier_live.pyscript2.6 KB
mcp-server/tests/test_format_converter_hardening.pyscript4.2 KB
mcp-server/tests/test_mcp_tools.pyscript2.6 KB
mcp-server/tests/test_pubmed_parsing.pyscript4.4 KB
mcp-server/tests/test_scopus_empty_result.pyscript1006 B
mcp-server/tests/test_script_converters.pyscript2.9 KB
mcp-server/tests/test_sources.pyscript30.5 KB
mcp-server/utils/__init__.pyscript359 B
mcp-server/utils/config.pyscript1.4 KB
mcp-server/utils/errors.pyscript620 B
mcp-server/utils/logging.pyscript1.1 KB
references/citation-parser.mdmarkdown2.7 KB
references/dedup-engine.mdmarkdown1.9 KB
references/pubmed-28344011.bibexecutablescript3.3 KB
references/pubmed-28344011.nbibexecutablescript11.9 KB
references/pubmed-28344011.risexecutablescript3.4 KB
references/ris-bibtex-format.mdexecutablescript4.5 KB
references/search-strategy.mdexecutablescript2.0 KB
references/source-tiers.mdmarkdown2.7 KB
references/workflows/wf1-multi-source-search.mdmarkdown1.9 KB
references/workflows/wf2-citation-verification.mdmarkdown1.6 KB
references/workflows/wf3-mesh-strategy.mdmarkdown538 B
references/workflows/wf4-citation-file-mgmt.mdmarkdown1.9 KB
references/workflows/wf5-reference-mgmt.mdmarkdown1.5 KB
references/workflows/wf6-strict-other-citation-impact-audit.mdmarkdown11.2 KB
scripts/academic_search.pyscript23.2 KB
scripts/converters.pyscript18.5 KB
scripts/format-converter.pyscript19.5 KB
scripts/preflight.pyscript3.7 KB
static/core/routing-and-ops.mdmarkdown6.1 KB
static/core/tools.mdmarkdown3.0 KB

mcp-server/academic_search_server.py

View on GitHub
"""Academic search MCP server.

Unified entry point exposing multi-source search and source-specific tools for
CrossRef, PubMed, arXiv, Scopus, and ScienceDirect.
"""

from __future__ import annotations

import asyncio
import json
import re
from typing import Any

from mcp.server import FastMCP

from sources import (
    ArxivSource,
    CrossRefSource,
    PubMedSource,
    ScienceDirectSource,
    ScopusSource,
)
from utils import AcademicSearchError, DataSourceError, setup_logging

mcp = FastMCP("academic-search")
logger = setup_logging()

# Singleton source instances (shared across tool calls)
_crossref = CrossRefSource()
_pubmed = PubMedSource()
_arxiv = ArxivSource()
_scopus = ScopusSource()
_sciencedirect = ScienceDirectSource()


# ---------------------------------------------------------------------------
# Helpers
# ---------------------------------------------------------------------------

def _detect_id_type(id: str) -> str:
    """Auto-detect identifier type.

    Returns one of: "doi", "pmid", "arxiv".
    Raises ValueError when detection fails.
    """
    id = id.strip()
    if id.startswith("10.") and "/" in id:
        return "doi"
    if re.match(r"^\d{7,8}$", id):
        return "pmid"
    if re.match(r"^\d{4}\.\d{4,5}(v\d+)?$", id):
        return "arxiv"
    raise ValueError(f"Cannot detect ID type for: {id}")


def _resolve_id_type(id: str, id_type: str) -> str:
    """Resolve the effective ID type.

    If id_type is "auto", delegate to _detect_id_type.
    Otherwise normalise the explicit type string.
    """
    if id_type == "auto":
        return _detect_id_type(id)
    normalised = id_type.lower().strip()
    if normalised in ("doi", "pmid", "arxiv"):
        return normalised
    raise ValueError(f"Unsupported id_type: {id_type}")


def _json_ok(data: Any) -> str:
    """Serialize a successful result to JSON string."""
    return json.dumps(data, ensure_ascii=False, indent=2)


def _json_error(message: str, source: str | None = None) -> str:
    """Serialize an error result to JSON string."""
    payload: dict[str, Any] = {"error": message}
    if source:
        payload["source"] = source
    return json.dumps(payload, ensure_ascii=False, indent=2)


# ---------------------------------------------------------------------------
# Async wrappers for synchronous sources
# ---------------------------------------------------------------------------

async def _search_crossref(query: str, rows: int, filter_type: str | None) -> dict:
    return await asyncio.to_thread(_crossref.search, query, rows, filter_type)


async def _search_pubmed(query: str, rows: int) -> dict:
    return await asyncio.to_thread(_pubmed.search, query, rows)


async def _search_arxiv(query: str, rows: int) -> dict:
    return await asyncio.to_thread(_arxiv.search, query, rows)


async def _search_scopus(query: str, rows: int) -> dict:
    return await asyncio.to_thread(_scopus.search, query, rows)


async def _search_sciencedirect(query: str, rows: int) -> dict:
    return await asyncio.to_thread(_sciencedirect.search, query, rows)


async def _search_all(
    query: str,
    sources: list[str],
    rows: int,
    filter_type: str | None,
) -> dict:
    """Dispatch concurrent searches and merge results."""
    tasks: list[asyncio.Task] = []
    source_order: list[str] = []

    if "crossref" in sources:
        tasks.append(asyncio.create_task(_search_crossref(query, rows, filter_type)))
        source_order.append("crossref")
    if "pubmed" in sources:
        tasks.append(asyncio.create_task(_search_pubmed(query, rows)))
        source_order.append("pubmed")
    if "arxiv" in sources:
        tasks.append(asyncio.create_task(_search_arxiv(query, rows)))
        source_order.append("arxiv")
    if "scopus" in sources:
        tasks.append(asyncio.create_task(_search_scopus(query, rows)))
        source_order.append("scopus")
    if "sciencedirect" in sources:
        tasks.append(asyncio.create_task(_search_sciencedirect(query, rows)))
        source_order.append("sciencedirect")

    if not tasks:
        return {"total": 0, "results": [], "errors": []}

    outcomes = await asyncio.gather(*tasks, return_exceptions=True)

    merged_results: list[dict] = []
    errors: list[dict] = []
    total = 0

    for src, outcome in zip(source_order, outcomes):
        if isinstance(outcome, BaseException):
            logger.error("Source %s failed: %s", src, outcome)
            errors.append({"source": src, "error": str(outcome)})
            continue
        total += outcome.get("total", 0)
        merged_results.extend(outcome.get("results", []))

    return {
        "total": total,
        "sources_queried": source_order,
        "result_count": len(merged_results),
        "results": merged_results,
        "errors": errors if errors else None,
    }


# ---------------------------------------------------------------------------
# Tools
# ---------------------------------------------------------------------------

@mcp.tool()
async def search_papers(
    query: str,
    sources: list[str] | None = None,
    rows: int = 5,
    type: str | None = None,
) -> str:
    """Search academic papers across multiple sources.

    Args:
        query: Search keywords or query string.
        sources: List of source names to query. Defaults to CrossRef, PubMed,
            and arXiv. Add "scopus" and/or "sciencedirect" explicitly to use
            Elsevier-backed providers; they require local pybliometrics config
            and may consume Elsevier API quota.
        rows: Number of results per source (max 50), not total result count.
        type: Optional CrossRef-only work type filter (e.g. "journal-article").

    Returns:
        JSON string with total count, merged results, and any per-source errors.
    """
    if not query or not query.strip():
        return _json_error("Empty search query")

    if sources is None:
        sources = ["crossref", "pubmed", "arxiv"]

    # Validate source names
    valid_sources = {"crossref", "pubmed", "arxiv", "scopus", "sciencedirect"}
    invalid = [s for s in sources if s not in valid_sources]
    if invalid:
        return _json_error(f"Invalid sources: {invalid}. Valid: {sorted(valid_sources)}")

    rows = max(1, min(rows, 50))

    logger.info("search_papers called", extra={
        "tool": "search_papers",
        "query": query,
        "sources": sources,
        "rows": rows,
    })

    try:
        result = await _search_all(query, sources, rows, type)
    except Exception as exc:
        logger.exception("search_papers failed")
        return _json_error(f"Search failed: {exc}")

    return _json_ok(result)


@mcp.tool()
def search_scopus(
    query: str,
    rows: int = 5,
    view: str | None = None,
    subscriber: bool = True,
) -> str:
    """Search Scopus documents using a Scopus advanced-search query.

    Args:
        query: Scopus advanced search query.
        rows: Number of normalized results to return (max 50).
        view: Optional Scopus view ("STANDARD" or "COMPLETE").
        subscriber: Whether to use subscriber cursor navigation.
    """
    try:
        return _json_ok(_scopus.search(query, rows, view=view, subscriber=subscriber))
    except DataSourceError as exc:
        logger.error("search_scopus failed: %s", exc)
        return _json_error(str(exc), source=exc.source)
    except Exception as exc:
        logger.exception("search_scopus failed unexpectedly")
        return _json_error(f"Unexpected error: {exc}")


@mcp.tool()
def get_scopus_abstract(
    identifier: str,
    id_type: str | None = None,
    view: str = "META_ABS",
) -> str:
    """Retrieve Scopus abstract metadata.

    Args:
        identifier: EID, Scopus ID, DOI, PMID, or PII.
        id_type: Optional pybliometrics ID type; auto-detected when omitted.
        view: Scopus abstract view, usually "META_ABS".
    """
    try:
        return _json_ok(_scopus.get_abstract(identifier, id_type=id_type, view=view))
    except DataSourceError as exc:
        logger.error("get_scopus_abstract failed: %s", exc)
        return _json_error(str(exc), source=exc.source)
    except Exception as exc:
        logger.exception("get_scopus_abstract failed unexpectedly")
        return _json_error(f"Unexpected error: {exc}")


@mcp.tool()
def get_scopus_citation_overview(
    identifiers: list[str],
    id_type: str = "scopus_id",
    date: str | None = None,
    citation: str | None = None,
) -> str:
    """Retrieve Scopus citation overview for one or more documents.

    Args:
        identifiers: Document identifiers.
        id_type: Identifier type, e.g. "scopus_id", "doi", or "eid".
        date: Optional year range such as "2020-2025".
        citation: Optional exclusion mode, e.g. "exclude-self".
    """
    try:
        result = _scopus.get_citation_overview(
            identifiers,
            id_type=id_type,
            date=date,
            citation=citation,
        )
        return _json_ok(result)
    except DataSourceError as exc:
        logger.error("get_scopus_citation_overview failed: %s", exc)
        return _json_error(str(exc), source=exc.source)
    except Exception as exc:
        logger.exception("get_scopus_citation_overview failed unexpectedly")
        return _json_error(f"Unexpected error: {exc}")


@mcp.tool()
def search_scopus_authors(query: str, rows: int = 5) -> str:
    """Search Scopus author profiles."""
    try:
        return _json_ok(_scopus.search_authors(query, rows))
    except DataSourceError as exc:
        logger.error("search_scopus_authors failed: %s", exc)
        return _json_error(str(exc), source=exc.source)
    except Exception as exc:
        logger.exception("search_scopus_authors failed unexpectedly")
        return _json_error(f"Unexpected error: {exc}")


@mcp.tool()
def get_scopus_author(author_id: str, view: str = "ENHANCED") -> str:
    """Retrieve a Scopus author profile by author ID."""
    try:
        return _json_ok(_scopus.get_author(author_id, view=view))
    except DataSourceError as exc:
        logger.error("get_scopus_author failed: %s", exc)
        return _json_error(str(exc), source=exc.source)
    except Exception as exc:
        logger.exception("get_scopus_author failed unexpectedly")
        return _json_error(f"Unexpected error: {exc}")


@mcp.tool()
def search_scopus_affiliations(query: str, rows: int = 5) -> str:
    """Search Scopus affiliations."""
    try:
        return _json_ok(_scopus.search_affiliations(query, rows))
    except DataSourceError as exc:
        logger.error("search_scopus_affiliations failed: %s", exc)
        return _json_error(str(exc), source=exc.source)
    except Exception as exc:
        logger.exception("search_scopus_affiliations failed unexpectedly")
        return _json_error(f"Unexpected error: {exc}")


@mcp.tool()
def get_scopus_affiliation(affiliation_id: str, view: str = "STANDARD") -> str:
    """Retrieve a Scopus affiliation by affiliation ID."""
    try:
        return _json_ok(_scopus.get_affiliation(affiliation_id, view=view))
    except DataSourceError as exc:
        logger.error("get_scopus_affiliation failed: %s", exc)
        return _json_error(str(exc), source=exc.source)
    except Exception as exc:
        logger.exception("get_scopus_affiliation failed unexpectedly")
        return _json_error(f"Unexpected error: {exc}")


@mcp.tool()
def search_scopus_serial_titles(
    title: str | None = None,
    issn: str | None = None,
    publisher: str | None = None,
    subject: str | None = None,
    subject_code: str | None = None,
    content: str | None = None,
    open_access: str | None = None,
    rows: int = 5,
    view: str = "ENHANCED",
) -> str:
    """Search Scopus serial titles.

    Args:
        title: Serial title query.
        issn: ISSN query.
        publisher: Publisher query.
        subject: Subject-area query.
        subject_code: Subject-area code query.
        content: Content type query.
        open_access: Open-access filter.
        rows: Number of results to return.
        view: Scopus serial title view.
    """
    query = {
        "title": title,
        "issn": issn,
        "pub": publisher,
        "subj": subject,
        "subjCode": subject_code,
        "content": content,
        "oa": open_access,
    }
    try:
        return _json_ok(_scopus.search_serial_titles(query, rows=rows, view=view))
    except DataSourceError as exc:
        logger.error("search_scopus_serial_titles failed: %s", exc)
        return _json_error(str(exc), source=exc.source)
    except Exception as exc:
        logger.exception("search_scopus_serial_titles failed unexpectedly")
        return _json_error(f"Unexpected error: {exc}")


@mcp.tool()
def get_scopus_serial_title(
    issn: str,
    view: str = "ENHANCED",
    years: str | None = None,
) -> str:
    """Retrieve a Scopus serial title by ISSN."""
    try:
        return _json_ok(_scopus.get_serial_title(issn, view=view, years=years))
    except DataSourceError as exc:
        logger.error("get_scopus_serial_title failed: %s", exc)
        return _json_error(str(exc), source=exc.source)
    except Exception as exc:
        logger.exception("get_scopus_serial_title failed unexpectedly")
        return _json_error(f"Unexpected error: {exc}")


@mcp.tool()
def get_scopus_plumx_metrics(identifier: str, id_type: str) -> str:
    """Retrieve PlumX metrics for a document identifier."""
    try:
        return _json_ok(_scopus.get_plumx_metrics(identifier, id_type))
    except DataSourceError as exc:
        logger.error("get_scopus_plumx_metrics failed: %s", exc)
        return _json_error(str(exc), source=exc.source)
    except Exception as exc:
        logger.exception("get_scopus_plumx_metrics failed unexpectedly")
        return _json_error(f"Unexpected error: {exc}")


@mcp.tool()
def search_sciencedirect(
    query: str,
    rows: int = 5,
    view: str | None = None,
) -> str:
    """Search ScienceDirect article metadata."""
    try:
        return _json_ok(_sciencedirect.search(query, rows=rows, view=view))
    except DataSourceError as exc:
        logger.error("search_sciencedirect failed: %s", exc)
        return _json_error(str(exc), source=exc.source)
    except Exception as exc:
        logger.exception("search_sciencedirect failed unexpectedly")
        return _json_error(f"Unexpected error: {exc}")


@mcp.tool()
def get_sciencedirect_article_metadata(
    query: str,
    rows: int = 5,
    view: str | None = None,
) -> str:
    """Retrieve ScienceDirect article metadata with a metadata API query."""
    try:
        result = _sciencedirect.get_article_metadata(query, rows=rows, view=view)
        return _json_ok(result)
    except DataSourceError as exc:
        logger.error("get_sciencedirect_article_metadata failed: %s", exc)
        return _json_error(str(exc), source=exc.source)
    except Exception as exc:
        logger.exception("get_sciencedirect_article_metadata failed unexpectedly")
        return _json_error(f"Unexpected error: {exc}")


@mcp.tool()
def get_paper_by_id(id: str, id_type: str = "auto") -> str:
    """Get paper details by identifier (DOI, PMID, or arXiv ID).

    Args:
        id: Paper identifier. Auto-detected if id_type is "auto":
            - Starts with "10." -> DOI (CrossRef)
            - 7-8 digit number -> PMID (PubMed)
            - YYMM.NNNNN format -> arXiv ID (arXiv)
        id_type: Force identifier type ("doi", "pmid", "arxiv", or "auto").

    Returns:
        JSON string with detailed paper metadata.
    """
    if not id or not id.strip():
        return _json_error("Empty identifier")

    try:
        resolved_type = _resolve_id_type(id, id_type)
    except ValueError as exc:
        return _json_error(str(exc))

    logger.info("get_paper_by_id called", extra={
        "tool": "get_paper_by_id",
        "id": id,
        "id_type": resolved_type,
    })

    try:
        if resolved_type == "doi":
            result = _crossref.get_by_doi(id.strip())
        elif resolved_type == "pmid":
            result = _pubmed.get_by_pmid(id.strip())
        elif resolved_type == "arxiv":
            result = _arxiv.get_by_id(id.strip())
        else:
            return _json_error(f"Unsupported ID type: {resolved_type}")
    except DataSourceError as exc:
        logger.error("get_paper_by_id failed: %s", exc)
        return _json_error(str(exc), source=exc.source)
    except Exception as exc:
        logger.exception("get_paper_by_id failed unexpectedly")
        return _json_error(f"Unexpected error: {exc}")

    return _json_ok(result)


@mcp.tool()
def get_citation(id: str, id_type: str = "auto", style: str = "apa") -> str:
    """Get formatted citation for a paper.

    Uses CrossRef content negotiation for DOI-based citations.
    For PMID/arXiv IDs, fetches metadata first then generates a basic citation.

    Args:
        id: Paper identifier (DOI, PMID, or arXiv ID).
        id_type: Force identifier type ("doi", "pmid", "arxiv", or "auto").
        style: Citation style. Supported: apa, nature, ieee, harvard,
               vancouver, chicago, mla.

    Returns:
        JSON string with the formatted citation.
    """
    if not id or not id.strip():
        return _json_error("Empty identifier")

    try:
        resolved_type = _resolve_id_type(id, id_type)
    except ValueError as exc:
        return _json_error(str(exc))

    logger.info("get_citation called", extra={
        "tool": "get_citation",
        "id": id,
        "id_type": resolved_type,
        "style": style,
    })

    try:
        if resolved_type == "doi":
            citation = _crossref.get_citation(id.strip(), style=style)
            return _json_ok({"id": id, "style": style, "citation": citation})

        # For non-DOI IDs, fetch metadata and build a basic citation
        if resolved_type == "pmid":
            paper = _pubmed.get_by_pmid(id.strip())
        elif resolved_type == "arxiv":
            paper = _arxiv.get_by_id(id.strip())
        else:
            return _json_error(f"Unsupported ID type: {resolved_type}")

        citation = _format_basic_citation(paper, style)
        return _json_ok({"id": id, "style": style, "citation": citation})

    except DataSourceError as exc:
        logger.error("get_citation failed: %s", exc)
        return _json_error(str(exc), source=exc.source)
    except Exception as exc:
        logger.exception("get_citation failed unexpectedly")
        return _json_error(f"Unexpected error: {exc}")


def _format_basic_citation(paper: dict, style: str) -> str:
    """Generate a basic citation string from unified paper metadata.

    This is a fallback for non-DOI papers where CrossRef content
    negotiation is not available.
    """
    # Sources set missing fields to None, which .get(key, default) would not replace.
    authors = paper.get("authors") or []
    title = paper.get("title") or "Untitled"
    year = paper.get("year")
    journal = paper.get("journal") or ""
    doi = paper.get("doi") or ""
    arxiv_id = paper.get("arxiv_id") or ""
    pmid = paper.get("pmid") or ""

    # Author formatting
    if len(authors) > 3:
        author_str = f"{authors[0]} et al."
    elif authors:
        author_str = ", ".join(authors)
    else:
        author_str = "Unknown"

    if style == "nature":
        parts = [f"{author_str}. {title}."]
        if journal:
            parts.append(f" *{journal}*.")
        if year:
            parts.append(f" ({year}).")
        if doi:
            parts.append(f" https://doi.org/{doi}")
        return "".join(parts)

    if style == "ieee":
        ref = f"{author_str}, \"{title}\""
        if journal:
            ref += f", *{journal}*"
        if year:
            ref += f", {year}"
        ref += "."
        if doi:
            ref += f" doi: {doi}."
        return ref

    # Default APA-like
    parts = [f"{author_str} ({year or 'n.d.'}). {title}."]
    if journal:
        parts.append(f" *{journal}*.")
    if doi:
        parts.append(f" https://doi.org/{doi}")
    elif arxiv_id:
        parts.append(f" arXiv:{arxiv_id}")
    elif pmid:
        parts.append(f" PMID:{pmid}")
    return "".join(parts)


@mcp.tool()
def lookup_mesh(term: str) -> str:
    """Lookup MeSH (Medical Subject Headings) terms.

    Queries the MeSH database via NCBI E-utilities to find matching
    descriptor names and unique IDs.

    Args:
        term: Search term to look up in the MeSH vocabulary.

    Returns:
        JSON string with matching MeSH descriptors.
    """
    if not term or not term.strip():
        return _json_error("Empty MeSH lookup term")

    logger.info("lookup_mesh called", extra={
        "tool": "lookup_mesh",
        "term": term,
    })

    try:
        result = _pubmed.lookup_mesh(term.strip())
    except DataSourceError as exc:
        logger.error("lookup_mesh failed: %s", exc)
        return _json_error(str(exc), source=exc.source)
    except Exception as exc:
        logger.exception("lookup_mesh failed unexpectedly")
        return _json_error(f"Unexpected error: {exc}")

    return _json_ok(result)


# ---------------------------------------------------------------------------
# Entry point
# ---------------------------------------------------------------------------

if __name__ == "__main__":
    mcp.run(transport="stdio")
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 196kUpdated Claude CodeCodexVerifiedInstall