cnki-mcp-server 0.2.0__tar.gz

cnki_mcp_server-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,27 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Build
+        run: |
+          pip install hatchling
+          python -m hatchling build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

cnki_mcp_server-0.2.0/.github/workflows/test.yml

@@ -0,0 +1,36 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        os: [ubuntu-latest]
+
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check cnki_mcp/ tests/
+
+      - name: Unit tests
+        run: pytest tests/ -v

cnki_mcp_server-0.2.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.env
+.venv/
+venv/
+*.log
+.pytest_cache/
+.ruff_cache/
+.playwright/

cnki_mcp_server-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 CNKI MCP Contributors
+
+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.

cnki_mcp_server-0.2.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: cnki-mcp-server
+Version: 0.2.0
+Summary: CNKI (中国知网) MCP Server — 通过 Model Context Protocol 检索中文学术论文
+Author: CNKI MCP Contributors
+License: MIT
+License-File: LICENSE
+Keywords: chinese-academic,cnki,fastmcp,mcp,playwright,知网
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Requires-Dist: fastmcp>=2.0.0
+Requires-Dist: playwright>=1.40.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.3.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# CNKI MCP Server
+
+[![PyPI version](https://img.shields.io/pypi/v/cnki-mcp-server.svg)](https://pypi.org/project/cnki-mcp-server/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**CNKI (中国知网) MCP Server** — 通过 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 为 AI Agent 提供中文学术论文检索能力。
+
+## 功能
+
+| 工具 | 说明 | 需要浏览器 |
+|------|------|-----------|
+| `search_cnki` | 搜索 CNKI 论文，支持多页、多种搜索类型和排序 | 是 |
+| `get_paper_detail` | 获取论文详情（标题、摘要、作者、关键词、DOI 等 17 字段） | 是 |
+| `find_best_match` | 快速匹配论文标题，验证引用信息 | 是 |
+| `format_citation` | 引文格式化（GB/T 7714, APA, MLA, Chicago, Vancouver） | 否 |
+| `browse_journals` | 期刊浏览（学科分类、期刊搜索、最新文章） | 是 |
+| `export_papers` | 批量导出（CSV, JSON, BibTeX, RIS） | 否 |
+
+### 搜索类型
+
+支持 15 种搜索类型：主题、关键词、篇名、作者、作者单位、全文、DOI、基金、摘要等（中英文别名均可）。
+
+### 排序方式
+
+相关度 / 发表时间 / 被引 / 下载 / 综合（支持英文别名：relevance, date, cited, download, composite）。
+
+## 安装
+
+```bash
+pip install cnki-mcp-server
+python -m playwright install chromium
+```
+
+> **注意**: Playwright Chromium 约 300MB，首次安装需要下载，后续无需重复安装。
+
+## 使用
+
+### Claude Code
+
+在 `.claude/settings.json` 或 Claude Code 的 MCP 配置中添加：
+
+```json
+{
+  "mcpServers": {
+    "cnki": {
+      "command": "python",
+      "args": ["-m", "cnki_mcp"]
+    }
+  }
+}
+```
+
+### 命令行直接使用
+
+```bash
+python -m cnki_mcp
+```
+
+## 要求
+
+- Python >= 3.10
+- Playwright Chromium（首次使用时自动安装）
+
+## 引文格式
+
+| 风格 | 标准 | 适用场景 |
+|------|------|----------|
+| `gbt7714` | GB/T 7714-2015 | 中文学位论文、中文期刊 |
+| `apa` | APA 7th Edition | 心理学、教育学、社会科学 |
+| `mla` | MLA 9th Edition | 语言文学、人文学科 |
+| `chicago` | Chicago Notes & Bibliography | 历史学、艺术学 |
+| `vancouver` | Vancouver/ICMJE | 生物医学、临床医学 |
+
+## 导出格式
+
+| 格式 | 适用软件 |
+|------|----------|
+| JSON | 编程处理、数据分析 |
+| CSV | Excel、Google Sheets |
+| BibTeX | LaTeX、Zotero、JabRef |
+| RIS | EndNote、Mendeley、Zotero |
+
+## 技术实现
+
+- **引擎**: Playwright（自带签名 Chromium，消除 macOS codesign 问题，跨平台零配置）
+- **MCP 框架**: FastMCP
+- **并发**: 原生 async/await
+- **反检测**: 随机 User-Agent、模拟人类输入、navigator.webdriver 覆写
+- **会话复用**: 共享 BrowserContext，Cookie 互通，避免 CNKI 验证码
+
+## 开发
+
+```bash
+git clone https://github.com/xxxxchaos/cnki-mcp-server.git
+cd cnki-mcp-server
+pip install -e ".[dev]"
+python -m playwright install chromium
+pytest tests/ -v
+```
+
+## 许可
+
+MIT License

cnki_mcp_server-0.2.0/README.md

@@ -0,0 +1,103 @@
+# CNKI MCP Server
+
+[![PyPI version](https://img.shields.io/pypi/v/cnki-mcp-server.svg)](https://pypi.org/project/cnki-mcp-server/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**CNKI (中国知网) MCP Server** — 通过 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 为 AI Agent 提供中文学术论文检索能力。
+
+## 功能
+
+| 工具 | 说明 | 需要浏览器 |
+|------|------|-----------|
+| `search_cnki` | 搜索 CNKI 论文，支持多页、多种搜索类型和排序 | 是 |
+| `get_paper_detail` | 获取论文详情（标题、摘要、作者、关键词、DOI 等 17 字段） | 是 |
+| `find_best_match` | 快速匹配论文标题，验证引用信息 | 是 |
+| `format_citation` | 引文格式化（GB/T 7714, APA, MLA, Chicago, Vancouver） | 否 |
+| `browse_journals` | 期刊浏览（学科分类、期刊搜索、最新文章） | 是 |
+| `export_papers` | 批量导出（CSV, JSON, BibTeX, RIS） | 否 |
+
+### 搜索类型
+
+支持 15 种搜索类型：主题、关键词、篇名、作者、作者单位、全文、DOI、基金、摘要等（中英文别名均可）。
+
+### 排序方式
+
+相关度 / 发表时间 / 被引 / 下载 / 综合（支持英文别名：relevance, date, cited, download, composite）。
+
+## 安装
+
+```bash
+pip install cnki-mcp-server
+python -m playwright install chromium
+```
+
+> **注意**: Playwright Chromium 约 300MB，首次安装需要下载，后续无需重复安装。
+
+## 使用
+
+### Claude Code
+
+在 `.claude/settings.json` 或 Claude Code 的 MCP 配置中添加：
+
+```json
+{
+  "mcpServers": {
+    "cnki": {
+      "command": "python",
+      "args": ["-m", "cnki_mcp"]
+    }
+  }
+}
+```
+
+### 命令行直接使用
+
+```bash
+python -m cnki_mcp
+```
+
+## 要求
+
+- Python >= 3.10
+- Playwright Chromium（首次使用时自动安装）
+
+## 引文格式
+
+| 风格 | 标准 | 适用场景 |
+|------|------|----------|
+| `gbt7714` | GB/T 7714-2015 | 中文学位论文、中文期刊 |
+| `apa` | APA 7th Edition | 心理学、教育学、社会科学 |
+| `mla` | MLA 9th Edition | 语言文学、人文学科 |
+| `chicago` | Chicago Notes & Bibliography | 历史学、艺术学 |
+| `vancouver` | Vancouver/ICMJE | 生物医学、临床医学 |
+
+## 导出格式
+
+| 格式 | 适用软件 |
+|------|----------|
+| JSON | 编程处理、数据分析 |
+| CSV | Excel、Google Sheets |
+| BibTeX | LaTeX、Zotero、JabRef |
+| RIS | EndNote、Mendeley、Zotero |
+
+## 技术实现
+
+- **引擎**: Playwright（自带签名 Chromium，消除 macOS codesign 问题，跨平台零配置）
+- **MCP 框架**: FastMCP
+- **并发**: 原生 async/await
+- **反检测**: 随机 User-Agent、模拟人类输入、navigator.webdriver 覆写
+- **会话复用**: 共享 BrowserContext，Cookie 互通，避免 CNKI 验证码
+
+## 开发
+
+```bash
+git clone https://github.com/xxxxchaos/cnki-mcp-server.git
+cd cnki-mcp-server
+pip install -e ".[dev]"
+python -m playwright install chromium
+pytest tests/ -v
+```
+
+## 许可
+
+MIT License

cnki_mcp_server-0.2.0/cnki_mcp/__init__.py

@@ -0,0 +1,5 @@
+__version__ = "0.2.0"
+
+from cnki_mcp.server import mcp, main
+
+__all__ = ["mcp", "main", "__version__"]

cnki_mcp_server-0.2.0/cnki_mcp/__main__.py

@@ -0,0 +1,5 @@
+"""python -m cnki_mcp 入口"""
+
+from cnki_mcp.server import main
+
+main()

cnki_mcp_server-0.2.0/cnki_mcp/browser.py

@@ -0,0 +1,169 @@
+"""
+AsyncPlaywright 浏览器池管理。
+
+特性:
+- 懒初始化：首次调用时才启动浏览器
+- 实例复用：多次调用共享同一 browser 实例
+- 共享 BrowserContext：同一 context 内创建 Page，Cookie 互通
+- 空闲超时关闭（600s）
+- asyncio.Lock 保护并发访问
+"""
+
+import asyncio
+import random
+import subprocess
+import sys
+import time
+from typing import Optional
+
+from playwright.async_api import Browser, BrowserContext, Page, async_playwright
+
+from cnki_mcp.config import (
+    BROWSER_TIMEOUT,
+    IDLE_TIMEOUT,
+    USER_AGENTS,
+)
+from cnki_mcp.exceptions import BrowserError
+
+
+class AsyncBrowserPool:
+    """异步 Playwright 浏览器池（共享 BrowserContext，Cookie 互通）"""
+
+    def __init__(self) -> None:
+        self._playwright = None
+        self._browser: Optional[Browser] = None
+        self._context: Optional[BrowserContext] = None
+        self._last_used: float = 0
+        self._lock = asyncio.Lock()
+
+    async def _ensure_browser(self) -> Browser:
+        """确保浏览器实例可用"""
+        if self._browser is not None:
+            if time.time() - self._last_used > IDLE_TIMEOUT:
+                await self._close_browser()
+            elif not self._browser.is_connected():
+                self._browser = None
+                self._context = None
+
+        if self._browser is None:
+            try:
+                self._playwright = await async_playwright().start()
+                self._browser = await self._playwright.chromium.launch(
+                    headless=True,
+                    args=[
+                        "--disable-blink-features=AutomationControlled",
+                        "--no-sandbox",
+                        "--disable-dev-shm-usage",
+                        "--disable-gpu",
+                        "--disable-infobars",
+                        "--disable-extensions",
+                    ],
+                )
+            except Exception as e:
+                if "Executable doesn't exist" in str(e) or "playwright" in str(e).lower():
+                    await self._install_browser()
+                    self._playwright = await async_playwright().start()
+                    self._browser = await self._playwright.chromium.launch(
+                        headless=True,
+                        args=[
+                            "--disable-blink-features=AutomationControlled",
+                            "--no-sandbox",
+                            "--disable-dev-shm-usage",
+                        ],
+                    )
+                else:
+                    raise BrowserError(f"浏览器启动失败: {e}") from e
+
+            if self._browser is None:
+                raise BrowserError("浏览器启动失败")
+
+            # 创建共享的 BrowserContext
+            self._context = await self._browser.new_context(
+                user_agent=random.choice(USER_AGENTS),
+                viewport={"width": 1920, "height": 1080},
+                locale="zh-CN",
+            )
+            await self._context.add_init_script("""
+                Object.defineProperty(navigator, 'webdriver', {
+                    get: () => undefined,
+                });
+            """)
+
+        self._last_used = time.time()
+        return self._browser
+
+    async def _install_browser(self) -> None:
+        """安装 Playwright Chromium"""
+        try:
+            subprocess.check_call(
+                [sys.executable, "-m", "playwright", "install", "chromium"],
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                timeout=120,
+            )
+        except subprocess.CalledProcessError as e:
+            raise BrowserError(
+                "Playwright Chromium 安装失败。请手动运行: playwright install chromium"
+            ) from e
+
+    async def new_page(self) -> Page:
+        """创建新 Page（共享 Context，Cookie 互通）"""
+        async with self._lock:
+            await self._ensure_browser()
+
+        assert self._context is not None
+        page = await self._context.new_page()
+        page.set_default_timeout(BROWSER_TIMEOUT)
+        return page
+
+    async def navigate_to_cnki(self, page: Page) -> None:
+        """导航到 CNKI 首页（含弹窗处理）"""
+        await page.goto("https://www.cnki.net/", wait_until="domcontentloaded")
+        await asyncio.sleep(random.uniform(1, 2))
+        await self._dismiss_popups(page)
+
+    async def _dismiss_popups(self, page: Page) -> bool:
+        """尝试关闭 CNKI 弹窗/遮罩"""
+        dismiss_selectors = [
+            "#close",
+            ".close",
+            'div[class*="popup"] a:has-text("关闭")',
+            'div[class*="modal"] button:has-text("关闭")',
+            'div[class*="layui-layer"] a[class*="layui-layer-close"]',
+        ]
+        for selector in dismiss_selectors:
+            try:
+                elem = page.locator(selector).first
+                if await elem.count() > 0 and await elem.is_visible():
+                    await elem.click()
+                    await asyncio.sleep(0.5)
+                    return True
+            except Exception:
+                continue
+        return False
+
+    async def _close_browser(self) -> None:
+        """关闭浏览器实例和上下文"""
+        if self._context:
+            try:
+                await self._context.close()
+            except Exception:
+                pass
+            self._context = None
+        if self._browser:
+            try:
+                await self._browser.close()
+            except Exception:
+                pass
+            self._browser = None
+        if self._playwright:
+            try:
+                await self._playwright.stop()
+            except Exception:
+                pass
+            self._playwright = None
+
+    async def close(self) -> None:
+        """关闭浏览器池"""
+        async with self._lock:
+            await self._close_browser()