apaper-mcp 0.3.0__tar.gz

apaper_mcp-0.3.0/.github/workflows/release-publish.yml

@@ -0,0 +1,137 @@
+name: Release and Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Tag to publish (e.g. v0.2.1)"
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.tag || github.ref }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Resolve tag name
+        id: tag
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            echo "tag_name=${{ github.event.inputs.tag }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "tag_name=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Verify project version matches tag
+        run: |
+          PROJECT_VERSION=$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')
+          TAG_NAME="${{ steps.tag.outputs.tag_name }}"
+          EXPECTED_TAG="v${PROJECT_VERSION}"
+
+          if [ "$TAG_NAME" != "$EXPECTED_TAG" ]; then
+            echo "Tag ${TAG_NAME} does not match project version ${PROJECT_VERSION}"
+            exit 1
+          fi
+
+      - name: Run tests
+        run: uv run pytest
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload package artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package
+          path: dist/*
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Download package artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package
+          path: dist/
+
+      - name: Publish package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+
+  create-release:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.tag || github.ref }}
+
+      - name: Download package artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package
+          path: dist/
+
+      - name: Resolve tag name
+        id: tag
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            echo "tag_name=${{ github.event.inputs.tag }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "tag_name=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Extract release notes from changelog
+        run: |
+          TAG_NAME="${{ steps.tag.outputs.tag_name }}"
+          VERSION="${TAG_NAME#v}"
+
+          awk -v version="$VERSION" '
+            $0 ~ "^## \\[" version "\\]" { in_section = 1; next }
+            in_section && /^## \[/ { exit }
+            in_section { print }
+          ' CHANGELOG.md > RELEASE_NOTES.md
+
+          if [ ! -s RELEASE_NOTES.md ]; then
+            echo "Release notes for ${TAG_NAME} were not found in CHANGELOG.md" > RELEASE_NOTES.md
+          fi
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ steps.tag.outputs.tag_name }}
+          name: Release ${{ steps.tag.outputs.tag_name }}
+          draft: false
+          prerelease: false
+          body_path: RELEASE_NOTES.md
+          files: |
+            dist/*

apaper_mcp-0.3.0/.gitignore

@@ -0,0 +1,10 @@
+.DS_Store
+node_modules/
+*.log
+.idea/
+.vscode/
+__pycache__/
+.pytest_cache/
+.venv/
+/downloads
+/.claude/worktrees

apaper_mcp-0.3.0/CHANGELOG.md

@@ -0,0 +1,85 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on Keep a Changelog, and this project follows Semantic Versioning.
+
+## [Unreleased]
+
+## [0.3.0] - 2026-07-28
+
+### Added
+
+- Python 3.12+ package with `uv` project management and an `apaper-mcp` console entry point. (@isomoes)
+- PyPI publishing workflow with GitHub Actions Trusted Publishing support. (@isomoes)
+- MIT license and complete package metadata for distribution on PyPI. (@isomoes)
+
+### Removed
+
+- Legacy TypeScript, Bun, and npm implementation and release artifacts. (@isomoes)
+
+## [0.2.0] - 2026-06-26
+
+### Added
+
+- `SPIDER_PROXY` env var routes outbound requests (arXiv, IACR, DBLP, Google Scholar, and PDF downloads) through a proxy. CNKI is excluded because it authenticates by institutional IP. Accepts `socks5`/`socks4`/`http`/`https` URLs in both the standard `scheme://user:pass@host:port` form and the colon-delimited `scheme://host:port:user:pass` form (e.g. Kookeey), on both the Node and Bun runtimes (under Bun, SOCKS is tunnelled via a local HTTP→SOCKS bridge). Idempotent requests are retried on transient proxy connection failures, and if the proxy is set but invalid or can't be initialised, requests are blocked rather than sent direct so the real IP never leaks. (#2, @isomoes)
+- IACR per-request timeouts are configurable via `IACR_TIMEOUT_MS` (default `30000`) and `IACR_DOWNLOAD_TIMEOUT_MS` (default `60000`), raised from the previous fixed 15s/30s to tolerate slow proxies. (#2, @isomoes)
+
+### Fixed
+
+- IACR requests now detect Cloudflare's bot challenge (which intermittently blocks downloads/searches) and report it with an actionable message and the URL to open in a browser, instead of an opaque `HTTP 403` — and never save a challenge HTML page as a `.pdf`. Requests also send browser-like headers (full User-Agent, `Accept`, `Referer`). (#2, @isomoes)
+
+## [0.1.5] - 2026-06-08
+
+### Added
+
+- arXiv requests are throttled and retried on HTTP 429 / 5xx with exponential backoff honouring `Retry-After`; a persistent block reports the throttled IP and wait time. Tunable via `ARXIV_MIN_INTERVAL_MS`, `ARXIV_MAX_RETRIES`, `ARXIV_BACKOFF_BASE_MS`, `ARXIV_BACKOFF_MAX_MS`, `ARXIV_BACKOFF_JITTER_MS`, and `ARXIV_IP_ECHO_URL`. (#1, @isomoes)
+
+### Fixed
+
+- arXiv tools no longer fail on the first HTTP 429, and the search tool description no longer claims rate-limiting that was not implemented. (#1, @isomoes)
+
+## [0.1.4] - 2026-05-17
+
+### Added
+
+- arXiv search support via the `search_arxiv_papers` tool, with category, date-range, and sort options. (@isomoes)
+- arXiv PDF download support via the `download_arxiv_paper` tool. (@isomoes)
+- `ARXIV_SEARCH_URL`, `ARXIV_ADVANCED_URL`, and `ARXIV_PDF_BASE` env overrides for routing arXiv traffic through a reachable mirror. (@isomoes)
+
+### Changed
+
+- arXiv search scrapes the `arxiv.org/search/` HTML page instead of `export.arxiv.org/api/query` so it works on networks where the Atom API endpoint is blocked or aggressively rate-limited. (@isomoes)
+
+## [0.1.3] - 2026-05-16
+
+### Added
+
+- CNKI (中国知网) search support via the `search_cnki_papers` tool. (@isomoes)
+- CNKI PDF download support via the `download_cnki_paper` tool. (@isomoes)
+- Automatic IP-based CNKI session login on whitelisted institutional networks; no manual cookie management required. (@isomoes)
+
+## [0.1.2] - 2026-03-26
+
+### Added
+
+- Test release to verify tag-triggered GitHub Actions publishing now that the workflow is active. (@isomoes)
+
+## [0.1.1] - 2026-03-26
+
+### Added
+
+- npm packaging for `@ai4paper/apaper-mcp`, including the `apaper-mcp` CLI entrypoint. (@isomoes)
+- Tag-driven GitHub Actions release publishing and changelog-backed release notes. (@isomoes)
+- README updates covering npm installation and local release verification workflow. (@isomoes)
+
+## [0.1.0] - 2026-03-26
+
+### Added
+
+- Initial Bun + TypeScript MCP server for academic paper research. (@isomoes)
+- IACR ePrint search support with optional detail fetching and year filters. (@isomoes)
+- IACR PDF download support. (@isomoes)
+- DBLP search support with year filtering, venue filtering, and optional BibTeX output. (@isomoes)
+- Google Scholar search support with year filtering. (@isomoes)
+- Text formatters for MCP tool responses and stdio server startup entrypoint. (@isomoes)

apaper_mcp-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 isomoes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

apaper_mcp-0.3.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: apaper-mcp
+Version: 0.3.0
+Summary: Academic paper research MCP server
+Project-URL: Homepage, https://github.com/ai4paper/apaper-mcp
+Project-URL: Repository, https://github.com/ai4paper/apaper-mcp
+Project-URL: Issues, https://github.com/ai4paper/apaper-mcp/issues
+Author: isomoes
+License-Expression: MIT
+License-File: LICENSE
+Keywords: academic research,mcp,papers
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.12
+Requires-Dist: beautifulsoup4>=4.12
+Requires-Dist: httpx[socks]>=0.27
+Requires-Dist: mcp>=1.12
+Description-Content-Type: text/markdown
+
+# apaper-mcp
+
+An MCP (Model Context Protocol) server that gives AI assistants direct access to academic paper databases. It exposes a unified set of tools for searching and downloading papers across arXiv, IACR ePrint, DBLP, Google Scholar, and CNKI (中国知网), so an MCP-compatible client (Claude Code, Claude Desktop, or any other) can run literature searches, pull BibTeX entries, and fetch PDFs without leaving the chat.
+
+## Tools
+
+| Tool | Source | Description |
+| --- | --- | --- |
+| `search_arxiv_papers` | arXiv | Search with category, date-range, and sort options |
+| `download_arxiv_paper` | arXiv | Download a PDF |
+| `search_iacr_papers` | IACR ePrint | Search the ePrint archive |
+| `download_iacr_paper` | IACR ePrint | Download a PDF |
+| `search_dblp_papers` | DBLP | Search, optionally with BibTeX |
+| `search_google_scholar_papers` | Google Scholar | Search |
+| `search_cnki_papers` | CNKI (中国知网) | Search |
+| `download_cnki_paper` | CNKI (中国知网) | Download a PDF |
+
+arXiv tools scrape the public `arxiv.org/search/` HTML page, which works on
+networks where the `export.arxiv.org` Atom API is blocked or rate-limited. If
+you need to route through a mirror, set `ARXIV_SEARCH_URL`,
+`ARXIV_ADVANCED_URL`, and/or `ARXIV_PDF_BASE`.
+
+The arXiv tools throttle themselves and retry HTTP 429 / 5xx with exponential
+backoff, honouring `Retry-After`; on a persistent block the error names the
+throttled IP and wait time. Tune with `ARXIV_MIN_INTERVAL_MS` (`3000`),
+`ARXIV_MAX_RETRIES` (`3`), `ARXIV_BACKOFF_BASE_MS` (`3000`),
+`ARXIV_BACKOFF_MAX_MS` (`60000`), `ARXIV_BACKOFF_JITTER_MS` (`500`), and
+`ARXIV_IP_ECHO_URL` (`""` to disable the IP lookup).
+
+CNKI tools require institutional access. On IP-based networks the session
+cookie is obtained automatically on first use — no manual login needed.
+
+IACR ePrint sits behind Cloudflare, which intermittently serves a JS bot
+challenge that automated HTTP clients can't solve — most often on PDF downloads.
+Search keeps working; when a download is challenged the tool reports it clearly
+(rather than saving the challenge page) and gives you the URL to fetch in a
+browser. This is server-side and unrelated to any proxy.
+
+## Proxy
+
+Set `SPIDER_PROXY` to route outbound requests — arXiv, IACR, DBLP, Google
+Scholar, and their PDF downloads — through a proxy. CNKI is excluded on purpose:
+it authenticates by institutional IP and always uses this host's real address.
+Both a standard URL and the colon-delimited form some mobile-proxy providers
+hand out are accepted:
+
+```bash
+SPIDER_PROXY="socks5://user:pass@host:1086"   # standard
+SPIDER_PROXY="socks5://host:1086:user:pass"   # host:port:user:pass (e.g. Kookeey)
+SPIDER_PROXY="http://user:pass@host:8080"     # HTTP CONNECT proxy
+```
+
+`socks5`, `socks4`, `http`, and `https` schemes are supported (the scheme
+defaults to `http` when omitted) by the Python runtime. The scheme must match
+the proxy's port — a SOCKS port won't accept `http://` and vice versa. If
+`SPIDER_PROXY` is set but invalid or can't be initialised, requests are blocked
+rather than sent direct, so a misconfigured proxy never leaks this host's real
+IP.
+
+Flaky residential/mobile proxies routinely drop or refuse connections;
+idempotent (GET) requests through the proxy are retried automatically on such
+transient failures. IACR fires the most requests per search (a detail fetch per
+result), so its per-request timeouts default high for slow proxies — tune with
+`IACR_TIMEOUT_MS` (`30000`) and `IACR_DOWNLOAD_TIMEOUT_MS` (`60000`).
+
+## Install from PyPI
+
+The maintained runtime requires Python 3.12+. Run the published package
+directly with `uvx`:
+
+```bash
+uvx apaper-mcp
+```
+
+To install the command for repeated use:
+
+```bash
+uv tool install apaper-mcp
+apaper-mcp
+```
+
+For an MCP client, use the published package as the local stdio command:
+
+```json
+{
+  "mcp": {
+    "apaper-mcp": {
+      "type": "local",
+      "command": ["uvx", "apaper-mcp"],
+      "enabled": true
+    }
+  }
+}
+```
+
+## Development
+
+Clone the repository and install its development dependencies with `uv`:
+
+```bash
+uv sync
+uv run apaper-mcp
+```
+
+Run tests with `uv run pytest`.
+
+The Python source uses a standard `src` package layout. Platform-specific
+clients live under `src/apaper_mcp/platforms/`, while shared server, proxy,
+formatter, and model code stays in `src/apaper_mcp/`.
+
+### Local MCP testing
+
+Start the MCP Inspector against the Python stdio server:
+
+```bash
+npx @modelcontextprotocol/inspector uv run --directory . apaper-mcp
+```
+
+The equivalent module command is:
+
+```bash
+npx @modelcontextprotocol/inspector \
+  uv run --directory . python -m apaper_mcp
+```
+
+To pass the proxy to the inspected server:
+
+```bash
+npx @modelcontextprotocol/inspector \
+  -e SPIDER_PROXY="$SPIDER_PROXY" \
+  uv run --directory . apaper-mcp
+```
+
+The Inspector opens a local web UI for listing tools, inspecting schemas, and
+calling tools.
+
+### Tool schemas
+
+- `search_arxiv_papers`
+  - input: `{ "query": string, "max_results"?: number, "date_from"?: string, "date_to"?: string, "categories"?: string[], "sort_by"?: "relevance" | "date" }`
+- `download_arxiv_paper`
+  - input: `{ "paper_id": string, "save_path"?: string }` (paper_id like `2103.12345` or `2103.12345v2`)
+- `search_iacr_papers`
+  - input: `{ "query": string, "max_results"?: number, "fetch_details"?: boolean, "year_min"?: number | string, "year_max"?: number | string }`
+- `download_iacr_paper`
+  - input: `{ "paper_id": string, "save_path"?: string }`
+- `search_dblp_papers`
+  - input: `{ "query": string, "max_results"?: number, "year_from"?: number | string, "year_to"?: number | string, "venue_filter"?: string, "include_bibtex"?: boolean }`
+- `search_google_scholar_papers`
+  - input: `{ "query": string, "max_results"?: number, "year_low"?: number | string, "year_high"?: number | string }`
+- `search_cnki_papers`
+  - input: `{ "query": string, "page_num"?: number, "page_size"?: number }`
+- `download_cnki_paper`
+  - input: `{ "href": string, "save_path"?: string }` (use an `href` from `search_cnki_papers`)

apaper_mcp-0.3.0/README.md

@@ -0,0 +1,154 @@
+# apaper-mcp
+
+An MCP (Model Context Protocol) server that gives AI assistants direct access to academic paper databases. It exposes a unified set of tools for searching and downloading papers across arXiv, IACR ePrint, DBLP, Google Scholar, and CNKI (中国知网), so an MCP-compatible client (Claude Code, Claude Desktop, or any other) can run literature searches, pull BibTeX entries, and fetch PDFs without leaving the chat.
+
+## Tools
+
+| Tool | Source | Description |
+| --- | --- | --- |
+| `search_arxiv_papers` | arXiv | Search with category, date-range, and sort options |
+| `download_arxiv_paper` | arXiv | Download a PDF |
+| `search_iacr_papers` | IACR ePrint | Search the ePrint archive |
+| `download_iacr_paper` | IACR ePrint | Download a PDF |
+| `search_dblp_papers` | DBLP | Search, optionally with BibTeX |
+| `search_google_scholar_papers` | Google Scholar | Search |
+| `search_cnki_papers` | CNKI (中国知网) | Search |
+| `download_cnki_paper` | CNKI (中国知网) | Download a PDF |
+
+arXiv tools scrape the public `arxiv.org/search/` HTML page, which works on
+networks where the `export.arxiv.org` Atom API is blocked or rate-limited. If
+you need to route through a mirror, set `ARXIV_SEARCH_URL`,
+`ARXIV_ADVANCED_URL`, and/or `ARXIV_PDF_BASE`.
+
+The arXiv tools throttle themselves and retry HTTP 429 / 5xx with exponential
+backoff, honouring `Retry-After`; on a persistent block the error names the
+throttled IP and wait time. Tune with `ARXIV_MIN_INTERVAL_MS` (`3000`),
+`ARXIV_MAX_RETRIES` (`3`), `ARXIV_BACKOFF_BASE_MS` (`3000`),
+`ARXIV_BACKOFF_MAX_MS` (`60000`), `ARXIV_BACKOFF_JITTER_MS` (`500`), and
+`ARXIV_IP_ECHO_URL` (`""` to disable the IP lookup).
+
+CNKI tools require institutional access. On IP-based networks the session
+cookie is obtained automatically on first use — no manual login needed.
+
+IACR ePrint sits behind Cloudflare, which intermittently serves a JS bot
+challenge that automated HTTP clients can't solve — most often on PDF downloads.
+Search keeps working; when a download is challenged the tool reports it clearly
+(rather than saving the challenge page) and gives you the URL to fetch in a
+browser. This is server-side and unrelated to any proxy.
+
+## Proxy
+
+Set `SPIDER_PROXY` to route outbound requests — arXiv, IACR, DBLP, Google
+Scholar, and their PDF downloads — through a proxy. CNKI is excluded on purpose:
+it authenticates by institutional IP and always uses this host's real address.
+Both a standard URL and the colon-delimited form some mobile-proxy providers
+hand out are accepted:
+
+```bash
+SPIDER_PROXY="socks5://user:pass@host:1086"   # standard
+SPIDER_PROXY="socks5://host:1086:user:pass"   # host:port:user:pass (e.g. Kookeey)
+SPIDER_PROXY="http://user:pass@host:8080"     # HTTP CONNECT proxy
+```
+
+`socks5`, `socks4`, `http`, and `https` schemes are supported (the scheme
+defaults to `http` when omitted) by the Python runtime. The scheme must match
+the proxy's port — a SOCKS port won't accept `http://` and vice versa. If
+`SPIDER_PROXY` is set but invalid or can't be initialised, requests are blocked
+rather than sent direct, so a misconfigured proxy never leaks this host's real
+IP.
+
+Flaky residential/mobile proxies routinely drop or refuse connections;
+idempotent (GET) requests through the proxy are retried automatically on such
+transient failures. IACR fires the most requests per search (a detail fetch per
+result), so its per-request timeouts default high for slow proxies — tune with
+`IACR_TIMEOUT_MS` (`30000`) and `IACR_DOWNLOAD_TIMEOUT_MS` (`60000`).
+
+## Install from PyPI
+
+The maintained runtime requires Python 3.12+. Run the published package
+directly with `uvx`:
+
+```bash
+uvx apaper-mcp
+```
+
+To install the command for repeated use:
+
+```bash
+uv tool install apaper-mcp
+apaper-mcp
+```
+
+For an MCP client, use the published package as the local stdio command:
+
+```json
+{
+  "mcp": {
+    "apaper-mcp": {
+      "type": "local",
+      "command": ["uvx", "apaper-mcp"],
+      "enabled": true
+    }
+  }
+}
+```
+
+## Development
+
+Clone the repository and install its development dependencies with `uv`:
+
+```bash
+uv sync
+uv run apaper-mcp
+```
+
+Run tests with `uv run pytest`.
+
+The Python source uses a standard `src` package layout. Platform-specific
+clients live under `src/apaper_mcp/platforms/`, while shared server, proxy,
+formatter, and model code stays in `src/apaper_mcp/`.
+
+### Local MCP testing
+
+Start the MCP Inspector against the Python stdio server:
+
+```bash
+npx @modelcontextprotocol/inspector uv run --directory . apaper-mcp
+```
+
+The equivalent module command is:
+
+```bash
+npx @modelcontextprotocol/inspector \
+  uv run --directory . python -m apaper_mcp
+```
+
+To pass the proxy to the inspected server:
+
+```bash
+npx @modelcontextprotocol/inspector \
+  -e SPIDER_PROXY="$SPIDER_PROXY" \
+  uv run --directory . apaper-mcp
+```
+
+The Inspector opens a local web UI for listing tools, inspecting schemas, and
+calling tools.
+
+### Tool schemas
+
+- `search_arxiv_papers`
+  - input: `{ "query": string, "max_results"?: number, "date_from"?: string, "date_to"?: string, "categories"?: string[], "sort_by"?: "relevance" | "date" }`
+- `download_arxiv_paper`
+  - input: `{ "paper_id": string, "save_path"?: string }` (paper_id like `2103.12345` or `2103.12345v2`)
+- `search_iacr_papers`
+  - input: `{ "query": string, "max_results"?: number, "fetch_details"?: boolean, "year_min"?: number | string, "year_max"?: number | string }`
+- `download_iacr_paper`
+  - input: `{ "paper_id": string, "save_path"?: string }`
+- `search_dblp_papers`
+  - input: `{ "query": string, "max_results"?: number, "year_from"?: number | string, "year_to"?: number | string, "venue_filter"?: string, "include_bibtex"?: boolean }`
+- `search_google_scholar_papers`
+  - input: `{ "query": string, "max_results"?: number, "year_low"?: number | string, "year_high"?: number | string }`
+- `search_cnki_papers`
+  - input: `{ "query": string, "page_num"?: number, "page_size"?: number }`
+- `download_cnki_paper`
+  - input: `{ "href": string, "save_path"?: string }` (use an `href` from `search_cnki_papers`)

apaper_mcp-0.3.0/docs/introducing-apaper-mcp.md

@@ -0,0 +1,83 @@
+# Introducing apaper-mcp
+
+`apaper-mcp` is an MCP server for one very practical job: supporting paper work inside the conversation. Today that starts with paper discovery, but the larger direction is a more complete academic writing server where an AI client can search literature, collect references, organize source material, and assist with drafting around the same workflow. Instead of wiring separate scripts to different research sites, this project packages focused research tools behind a single Model Context Protocol interface.
+
+The project is built with **Python** and the official **Model Context Protocol SDK**. It runs over stdio, which makes it easy to plug into MCP-compatible clients and local inspection tools. The current implementation supports **arXiv**, **IACR ePrint**, **DBLP**, **Google Scholar**, and **CNKI**.
+
+## Why this project exists
+
+Research and writing workflows often break into too many manual steps. You search one index for cryptography preprints, another for publication metadata, and another for broad citation discovery, then move that material into notes, citations, and draft sections. `apaper-mcp` narrows that gap by turning the research side of that process into MCP tools that an assistant can call directly.
+
+That design is especially useful when the goal is not just to find one paper, but to support iterative paper-writing tasks such as:
+
+- narrowing a topic by year range
+- comparing results across multiple sources
+- pulling BibTeX-ready metadata from DBLP
+- downloading an IACR PDF for closer reading
+- building a cleaner literature base before outlining or drafting
+
+## What the server exposes
+
+At the moment, the server registers four tools:
+
+- `search_iacr_papers` for querying the IACR ePrint archive, with optional detail fetching and year filters
+- `download_iacr_paper` for saving an IACR paper PDF locally
+- `search_dblp_papers` for publication lookup in DBLP, including venue filtering and optional BibTeX output
+- `search_google_scholar_papers` for broader paper discovery through Google Scholar with year bounds
+
+Each tool returns formatted text responses so MCP clients can display results cleanly without extra response shaping. That keeps the server simple while still making it useful in real workflows.
+
+## Using it in an MCP client
+
+One simple local configuration looks like this:
+
+```json
+{
+  "mcp": {
+    "apaper-mcp": {
+      "type": "local",
+      "command": ["uv", "run", "--directory", "/path/to/apaper-mcp", "apaper-mcp"],
+      "enabled": true
+    }
+  }
+}
+```
+
+With that setup, an MCP-compatible client can start the server locally and call its tools during a research session.
+
+## Example use cases
+
+In practice, that means an assistant can use `apaper-mcp` to:
+
+- search papers on a topic across multiple sources
+- collect metadata and BibTeX for references
+- download an IACR paper for closer reading
+- prepare source material before outlining or drafting a paper
+
+## How it is put together
+
+The codebase keeps the implementation intentionally direct. The MCP entrypoint lives in `src/apaper_mcp/server.py`, where each tool is registered with the Python MCP SDK. Platform-specific fetching and parsing live in separate modules under `src/apaper_mcp/`, which keeps the transport layer and the scraping/API logic from bleeding into each other.
+
+That split also reflects the nature of the supported sources:
+
+- **IACR** and **Google Scholar** are handled by fetching and parsing HTML
+- **DBLP** uses its JSON API and can optionally fetch BibTeX records
+
+This is not trying to be a full academic knowledge graph or a large orchestration framework. It is a compact MCP server with a clear surface area, aimed at making paper search easier to automate and easier to integrate into AI-assisted research and writing sessions.
+
+## Future directions
+
+Today, `apaper-mcp` focuses on search and retrieval. The next step is to extend it into a more complete paper-writing server.
+
+- reference management tools for collecting, deduplicating, and exporting citations across sources
+- PDF processing tools for extracting metadata, section text, figures, or notes from downloaded papers
+- literature review helpers for clustering papers by topic, method, or publication venue
+- outlining and drafting support for turning research notes into section plans, related-work summaries, or first-pass prose
+- revision tools for checking consistency between claims, citations, and bibliography entries
+- submission-oriented utilities for format checks, metadata cleanup, and venue-specific packaging
+
+Those additions would move the project from paper search into a broader research-writing workspace.
+
+## Closing thought
+
+`apaper-mcp` is a focused example of what MCP is good at: exposing useful capabilities in a form that AI clients can call reliably. Right now, that means less context switching, less glue code, and a cleaner path from a research question to a usable set of papers. With the right extensions, it can grow into a practical MCP server for the full paper-writing workflow rather than only the search stage.