apaper-mcp 0.3.0__py3-none-any.whl

apaper_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Python implementation of the apaper-mcp server."""
+
+__version__ = "0.2.0"

apaper_mcp/__main__.py

@@ -0,0 +1,7 @@
+"""Run the apaper-mcp server as a Python module."""
+
+from .server import main
+
+
+if __name__ == "__main__":
+    main()

apaper_mcp/formatters.py

@@ -0,0 +1,176 @@
+from datetime import datetime
+from typing import Any
+
+
+def _year_filter(minimum: int | None, maximum: int | None) -> str:
+    if minimum is None and maximum is None:
+        return ""
+    return f" in year range ({minimum if minimum is not None else 'earliest'}-{maximum if maximum is not None else 'latest'})"
+
+
+def format_iacr_search_response(
+    papers: list[dict[str, Any]],
+    query: str,
+    year_min: int | None = None,
+    year_max: int | None = None,
+) -> str:
+    if not papers:
+        return f"No papers found for query: {query}{_year_filter(year_min, year_max)}"
+    lines = [
+        f"Found {len(papers)} IACR papers for query '{query}'{_year_filter(year_min, year_max)}:",
+        "",
+    ]
+    for index, paper in enumerate(papers, 1):
+        lines += [
+            f"{index}. **{paper['title']}**",
+            f"   - Paper ID: {paper['paper_id']}",
+            f"   - Authors: {', '.join(paper['authors'])}",
+            f"   - URL: {paper['url']}",
+            f"   - PDF: {paper['pdf_url']}",
+        ]
+        if paper["categories"]:
+            lines.append(f"   - Categories: {', '.join(paper['categories'])}")
+        if paper["keywords"]:
+            lines.append(f"   - Keywords: {', '.join(paper['keywords'])}")
+        if paper["abstract"]:
+            lines.append(f"   - Abstract: {paper['abstract']}")
+        lines.append("")
+    return "\n".join(lines)
+
+
+def format_dblp_search_response(
+    results: list[dict[str, Any]], query: str, options: dict[str, Any]
+) -> str:
+    filters = []
+    if options.get("year_from") is not None or options.get("year_to") is not None:
+        filters.append(
+            f"year range ({options.get('year_from', 'earliest')}-{options.get('year_to', 'latest')})"
+        )
+    if options.get("venue_filter"):
+        filters.append(f"venue '{options['venue_filter']}'")
+    suffix = f" with filters: {', '.join(filters)}" if filters else ""
+    if not results:
+        return f"No papers found for query: {query}{suffix}"
+    if options.get("include_bibtex"):
+        lines = [
+            f"Found {len(results)} DBLP BibTeX entries for query '{query}'{suffix}:",
+            "",
+        ]
+        for index, result in enumerate(results, 1):
+            lines += [
+                f"{index}. DBLP Key: {result['dblp_key']}",
+                "```bibtex",
+                result["bibtex"],
+                "```",
+                "",
+            ]
+        return "\n".join(lines)
+    lines = [f"Found {len(results)} DBLP papers for query '{query}'{suffix}:", ""]
+    for index, result in enumerate(results, 1):
+        lines += [
+            f"{index}. **{result['title'] or 'Untitled'}**",
+            f"   - DBLP Key: {result['dblp_key']}",
+            f"   - Authors: {', '.join(result['authors'])}",
+        ]
+        if result.get("venue"):
+            lines.append(f"   - Venue: {result['venue']}")
+        if result.get("year"):
+            lines.append(f"   - Year: {result['year']}")
+        if result.get("doi"):
+            lines.append(f"   - DOI: {result['doi']}")
+        if result.get("url"):
+            lines.append(f"   - URL: {result['url']}")
+        lines.append("")
+    return "\n".join(lines)
+
+
+def format_google_scholar_search_response(
+    papers: list[dict[str, Any]],
+    query: str,
+    year_low: int | None = None,
+    year_high: int | None = None,
+) -> str:
+    if not papers:
+        return f"No papers found for query: {query}{_year_filter(year_low, year_high)}"
+    lines = [
+        f"Found {len(papers)} Google Scholar papers for query '{query}'{_year_filter(year_low, year_high)}:",
+        "",
+    ]
+    for index, paper in enumerate(papers, 1):
+        lines += [
+            f"{index}. **{paper['title']}**",
+            f"   - Authors: {', '.join(paper['authors'])}",
+        ]
+        if paper["citations"] > 0:
+            lines.append(f"   - Citations: {paper['citations']}")
+        if paper.get("published_date"):
+            try:
+                lines.append(
+                    f"   - Year: {datetime.fromisoformat(paper['published_date'].replace('Z', '+00:00')).year}"
+                )
+            except ValueError:
+                pass
+        if paper.get("url"):
+            lines.append(f"   - URL: {paper['url']}")
+        if paper.get("abstract"):
+            lines.append(f"   - Abstract: {paper['abstract']}")
+        lines.append("")
+    return "\n".join(lines)
+
+
+def format_arxiv_search_response(
+    papers: list[dict[str, Any]], query: str, options: dict[str, Any] | None = None
+) -> str:
+    options = options or {}
+    filters = []
+    if options.get("date_from") or options.get("date_to"):
+        filters.append(
+            f"date range ({options.get('date_from', 'earliest')} to {options.get('date_to', 'latest')})"
+        )
+    if options.get("categories"):
+        filters.append(f"categories [{', '.join(options['categories'])}]")
+    suffix = f" with filters: {', '.join(filters)}" if filters else ""
+    if not papers:
+        return f"No arXiv papers found for query: {query}{suffix}"
+    lines = [f"Found {len(papers)} arXiv papers for query '{query}'{suffix}:", ""]
+    for index, p in enumerate(papers, 1):
+        lines += [
+            f"{index}. **{p['title'] or 'Untitled'}**",
+            f"   - Paper ID: {p['paper_id']}",
+        ]
+        if p["authors"]:
+            lines.append(f"   - Authors: {', '.join(p['authors'])}")
+        if p["primary_category"]:
+            lines.append(f"   - Primary Category: {p['primary_category']}")
+        if p["categories"]:
+            lines.append(f"   - Categories: {', '.join(p['categories'])}")
+        if p["published_date"]:
+            lines.append(f"   - Published: {p['published_date']}")
+        if p["doi"]:
+            lines.append(f"   - DOI: {p['doi']}")
+        if p["journal_ref"]:
+            lines.append(f"   - Journal Ref: {p['journal_ref']}")
+        if p["url"]:
+            lines.append(f"   - URL: {p['url']}")
+        if p["pdf_url"]:
+            lines.append(f"   - PDF: {p['pdf_url']}")
+        if p["abstract"]:
+            lines.append(f"   - Abstract: {p['abstract']}")
+        lines.append("")
+    return "\n".join(lines)
+
+
+def format_cnki_search_response(papers: list[dict[str, Any]], query: str) -> str:
+    if not papers:
+        return f"No CNKI papers found for query: {query}"
+    lines = [f"Found {len(papers)} CNKI papers for query '{query}':", ""]
+    for index, p in enumerate(papers, 1):
+        lines.append(f"{index}. **{p['title'] or 'Untitled'}**")
+        if p["authors"]:
+            lines.append(f"   - Authors: {', '.join(p['authors'])}")
+        if p["source"]:
+            lines.append(f"   - Source: {p['source']}")
+        if p["href"]:
+            lines.append(f"   - URL: {p['href']}")
+        lines.append("")
+    return "\n".join(lines)

apaper_mcp/models.py

@@ -0,0 +1,42 @@
+from typing import Any, TypedDict
+
+
+class Paper(TypedDict):
+    paper_id: str
+    title: str
+    authors: list[str]
+    abstract: str
+    doi: str
+    published_date: str | None
+    pdf_url: str
+    url: str
+    source: str
+    categories: list[str]
+    keywords: list[str]
+    citations: int
+    references: list[str]
+    extra: dict[str, Any]
+
+
+class ArxivPaper(TypedDict):
+    paper_id: str
+    title: str
+    authors: list[str]
+    abstract: str
+    categories: list[str]
+    primary_category: str
+    published_date: str
+    updated_date: str
+    pdf_url: str
+    url: str
+    doi: str
+    journal_ref: str
+    comment: str
+
+
+class CnkiPaper(TypedDict):
+    title: str
+    authors: list[str]
+    source: str
+    source_link: str
+    href: str

apaper_mcp/platforms/__init__.py

@@ -0,0 +1 @@
+"""Platform-specific academic paper clients and parsers."""

apaper_mcp/platforms/arxiv.py

@@ -0,0 +1,257 @@
+import os
+import random
+import re
+import time
+from datetime import datetime, timezone
+from urllib.parse import urlencode
+from bs4 import BeautifulSoup
+
+from ..models import ArxivPaper
+
+_GROUPS = {
+    "cs": "computer_science",
+    "econ": "economics",
+    "eess": "eess",
+    "math": "mathematics",
+    "physics": "physics",
+    "astro-ph": "physics",
+    "cond-mat": "physics",
+    "gr-qc": "physics",
+    "hep-ex": "physics",
+    "hep-lat": "physics",
+    "hep-ph": "physics",
+    "hep-th": "physics",
+    "math-ph": "physics",
+    "nlin": "physics",
+    "nucl-ex": "physics",
+    "nucl-th": "physics",
+    "quant-ph": "physics",
+    "q-bio": "q_biology",
+    "q-fin": "q_finance",
+    "stat": "statistics",
+}
+
+
+def build_arxiv_search_params(
+    query: str, options: dict[str, object] | None = None
+) -> dict[str, str]:
+    options = options or {}
+    term = query.strip()
+    field = "all"
+    for prefix, name in (
+        ("ti:", "title"),
+        ("au:", "author"),
+        ("abs:", "abstract"),
+        ("cat:", "all"),
+        ("doi:", "doi"),
+    ):
+        if term.lower().startswith(prefix):
+            term, field = term[len(prefix) :].strip(), name
+            break
+    date_from, date_to = options.get("date_from"), options.get("date_to")
+    categories = options.get("categories") or []
+    if not term and not date_from and not date_to:
+        raise ValueError("No search criteria provided")
+    max_results = max(1, int(options.get("max_results", 10)))
+    size = (
+        25
+        if max_results <= 25
+        else 50
+        if max_results <= 50
+        else 100
+        if max_results <= 100
+        else 200
+    )
+    if not categories and not date_from and not date_to and field == "all":
+        result = {"searchtype": "all", "query": term, "start": "0", "size": str(size)}
+        if options.get("sort_by") == "date":
+            result["order"] = "-announced_date_first"
+        return result
+    result = {
+        "advanced": "",
+        "terms-0-operator": "AND",
+        "terms-0-term": term,
+        "terms-0-field": field,
+    }
+    groups = {
+        _GROUPS.get(str(category).split(".")[0].lower()) for category in categories
+    }
+    groups.discard(None)
+    for group in groups:
+        result[f"classification-{group}"] = "y"
+    result.update(
+        {
+            "classification-physics_archives": "all",
+            "classification-include_cross_list": "include",
+        }
+    )
+    if date_from or date_to:
+        for label, value in (("date_from", date_from), ("date_to", date_to)):
+            if value and not re.fullmatch(r"\d{4}-\d{2}-\d{2}", str(value)):
+                raise ValueError(f"Invalid {label} format. Use YYYY-MM-DD: {value}")
+        result.update(
+            {
+                "date-filter_by": "date_range",
+                "date-year": "",
+                "date-from_date": str(date_from or ""),
+                "date-to_date": str(date_to or ""),
+                "date-date_type": "submitted_date",
+            }
+        )
+    else:
+        result.update(
+            {
+                "date-filter_by": "all_dates",
+                "date-year": "",
+                "date-from_date": "",
+                "date-to_date": "",
+                "date-date_type": "submitted_date",
+            }
+        )
+    result.update(
+        {
+            "abstracts": "show",
+            "size": str(size),
+            "order": "-announced_date_first"
+            if options.get("sort_by") == "date"
+            else "",
+            "start": "0",
+        }
+    )
+    return result
+
+
+def parse_arxiv_search_html(html: str) -> list[ArxivPaper]:
+    soup = BeautifulSoup(html, "html.parser")
+    papers = []
+    for item in soup.select("li.arxiv-result"):
+        link = item.select_one("p.list-title a[href*='/abs/']")
+        if not link:
+            continue
+        match = re.search(r"/abs/([^/?#]+)", link.get("href", ""))
+        if not match:
+            continue
+        paper_id = re.sub(r"v\d+$", "", match.group(1), flags=re.I)
+        clean = lambda value: re.sub(r"\s+", " ", value or "").strip()
+        tags = [
+            clean(x.get_text())
+            for x in item.select("div.tags span.tag")
+            if clean(x.get_text())
+        ]
+        pdf = next(
+            (
+                x.get("href", "")
+                for x in item.select("p.list-title a")
+                if "/pdf/" in x.get("href", "")
+            ),
+            f"https://arxiv.org/pdf/{paper_id}",
+        )
+        date_match = re.search(
+            r"Submitted\s+(\d{1,2}\s+\w+,?\s+\d{4})",
+            clean(
+                item.select_one("p.is-size-7").get_text()
+                if item.select_one("p.is-size-7")
+                else ""
+            ),
+            re.I,
+        )
+        published = ""
+        if date_match:
+            try:
+                published = (
+                    datetime.strptime(date_match.group(1).replace(",", ""), "%d %B %Y")
+                    .replace(tzinfo=timezone.utc)
+                    .isoformat()
+                    .replace("+00:00", "Z")
+                )
+            except ValueError:
+                pass
+        comments = {"comment": "", "journal_ref": "", "doi": ""}
+        for paragraph in item.select("p.comments"):
+            text = clean(paragraph.get_text())
+            for label, key in (
+                ("Comments", "comment"),
+                ("Journal ref", "journal_ref"),
+                ("doi", "doi"),
+            ):
+                if re.match(label + r"\s*:", text, re.I):
+                    comments[key] = re.sub(label + r"\s*:\s*", "", text, flags=re.I)
+        papers.append(
+            {
+                "paper_id": paper_id,
+                "title": clean(
+                    item.select_one("p.title").get_text()
+                    if item.select_one("p.title")
+                    else ""
+                ),
+                "authors": [
+                    clean(x.get_text())
+                    for x in item.select("p.authors a")
+                    if clean(x.get_text())
+                ],
+                "abstract": clean(
+                    (
+                        item.select_one("span.abstract-full")
+                        or item.select_one("span.abstract-short")
+                    ).get_text()
+                    if (
+                        item.select_one("span.abstract-full")
+                        or item.select_one("span.abstract-short")
+                    )
+                    else ""
+                )
+                .removesuffix("▽ More")
+                .removesuffix("△ Less")
+                .strip(),
+                "categories": tags,
+                "primary_category": tags[0] if tags else "",
+                "published_date": published,
+                "updated_date": published,
+                "pdf_url": pdf,
+                "url": f"https://arxiv.org/abs/{paper_id}",
+                **comments,
+            }
+        )
+    return papers
+
+
+def parse_retry_after_ms(value: str | None, now: float | None = None) -> int | None:
+    if not value or not value.strip():
+        return None
+    if value.strip().isdigit():
+        return int(value.strip()) * 1000
+    if " " not in value:
+        return None
+    try:
+        return max(
+            0,
+            int(
+                datetime.strptime(value.strip(), "%a, %d %b %Y %H:%M:%S GMT")
+                .replace(tzinfo=timezone.utc)
+                .timestamp()
+                * 1000
+                - (now if now is not None else time.time() * 1000)
+            ),
+        )
+    except ValueError:
+        return None
+
+
+def compute_backoff_ms(
+    attempt: int,
+    retry_after_ms: int | None,
+    options: dict[str, int],
+    rand=random.random,
+) -> int:
+    delay = (
+        max(options["base_ms"] * 2**attempt, retry_after_ms or 0)
+        + rand() * options["jitter_ms"]
+    )
+    return int(min(delay, options["max_ms"]))
+
+
+def looks_like_ip(text: str) -> bool:
+    return bool(
+        re.fullmatch(r"(\d{1,3}\.){3}\d{1,3}", text)
+        or (":" in text and re.fullmatch(r"[0-9a-fA-F:]{2,45}", text))
+    )

apaper_mcp/platforms/cnki.py

@@ -0,0 +1,103 @@
+import re
+from urllib.parse import unquote, urljoin
+from bs4 import BeautifulSoup
+
+
+def build_cnki_query_json(value: str) -> dict:
+    return {
+        "Platform": "",
+        "Resource": "CROSSDB",
+        "Classid": "WD0FTY92",
+        "Products": "CJFQ,CAPJ,WWJD,CJTL,CDFD,CMFD,CPFD,IPFD,CPVD,WWPD,CCND,SCSF,SCHF,SCSD,SOSD,SNAD,CCJD,WBFD,WWBD,CCVD,CJFN",
+        "QNode": {
+            "QGroup": [
+                {
+                    "Key": "Subject",
+                    "Title": "",
+                    "Logic": 0,
+                    "Items": [
+                        {
+                            "Field": "SU",
+                            "Value": value,
+                            "Operator": "TOPRANK",
+                            "Logic": 0,
+                            "Title": "主题",
+                        }
+                    ],
+                    "ChildItems": [],
+                }
+            ]
+        },
+        "ExScope": 1,
+        "SearchType": 2,
+        "Rlang": "BOTH",
+        "KuaKuCode": "YSTT4HG0,LSTPFY1C,JUP3MUPD,MPMFIG1A,WQ0UVIAA,BLZOG7CK,PWFIRAGL,EMRPGLPA,NLBO1Z6R,NN3FJMUV",
+        "Expands": {},
+        "SearchFrom": 4,
+    }
+
+
+def parse_cnki_search_html(
+    html: str, base_url: str = "https://kns.cnki.net/"
+) -> list[dict]:
+    soup = BeautifulSoup(html, "html.parser")
+    papers = []
+    for row in soup.select(
+        "table.result-table-list tbody tr, table.result-table-list tr"
+    ):
+        title = row.select_one("td.name a.fz14")
+        if (
+            not title
+            or not title.get("href")
+            or title["href"].startswith("javascript:")
+            or "/kcms2/article/abstract" not in title["href"]
+        ):
+            continue
+        source = row.select_one("td.source")
+        source_link = ""
+        source_name = ""
+        if source:
+            source_a = next(
+                (
+                    x
+                    for x in source.select("a")
+                    if x.get("href")
+                    and ("knavi/detail" in x["href"] or "thinker.cnki.net" in x["href"])
+                ),
+                None,
+            )
+            if source_a:
+                source_name, source_link = (
+                    source_a.get_text(strip=True),
+                    urljoin(base_url, source_a["href"]),
+                )
+            else:
+                source_name = next(
+                    (
+                        x.get_text(strip=True)
+                        for x in source.select("span")
+                        if x.get_text(strip=True) not in ("—",)
+                    ),
+                    source.get_text(" ", strip=True),
+                )
+        papers.append(
+            {
+                "title": title.get_text(strip=True),
+                "authors": [
+                    x.get_text(strip=True)
+                    for x in row.select("td.author a.KnowledgeNetLink")
+                ],
+                "source": source_name,
+                "source_link": source_link,
+                "href": urljoin(base_url, title["href"]),
+            }
+        )
+    return papers
+
+
+def extract_filename_from_content_disposition(disposition: str) -> str:
+    match = re.search(r"filename\*\s*=\s*[^']*''([^;]+)", disposition, re.I)
+    if match:
+        return unquote(match.group(1).strip())
+    match = re.search(r"filename\s*=\s*\"?([^\";]+)", disposition, re.I)
+    return unquote(match.group(1).strip()) if match else ""

apaper_mcp/platforms/dblp.py

@@ -0,0 +1,57 @@
+from typing import Any
+
+
+def parse_dblp_api_response(payload: Any) -> list[dict]:
+    hits = (
+        payload.get("result", {}).get("hits", {}).get("hit", [])
+        if isinstance(payload, dict)
+        else []
+    )
+    if not isinstance(hits, list):
+        hits = [hits] if hits else []
+    result = []
+    for publication in hits:
+        info = publication.get("info", {})
+        authors = info.get("authors", {}).get("author", [])
+        if not isinstance(authors, list):
+            authors = [authors] if authors else []
+        authors = [a if isinstance(a, str) else a.get("text", "") for a in authors]
+        url = info.get("url", "")
+        result.append(
+            {
+                "title": info.get("title", ""),
+                "authors": [a for a in authors if a],
+                "venue": info.get("venue", ""),
+                "year": int(info["year"])
+                if str(info.get("year", "")).isdigit()
+                else None,
+                "type": info.get("type", ""),
+                "doi": info.get("doi", ""),
+                "ee": info.get("ee", ""),
+                "url": url,
+                "dblp_key": url.replace("https://dblp.org/rec/", "")
+                or publication.get("key", "").removeprefix("dblp:"),
+            }
+        )
+    return result
+
+
+def filter_dblp_results(results: list[dict], options: dict[str, Any]) -> list[dict]:
+    return [
+        r
+        for r in results
+        if not (
+            options.get("year_from") is not None
+            and r.get("year") is not None
+            and r["year"] < options["year_from"]
+        )
+        and not (
+            options.get("year_to") is not None
+            and r.get("year") is not None
+            and r["year"] > options["year_to"]
+        )
+        and not (
+            options.get("venue_filter")
+            and options["venue_filter"].lower() not in r.get("venue", "").lower()
+        )
+    ]