Metadata-Version: 2.3
Name: cnki-mcp
Version: 0.2.0
Summary: MCP server and CLI for CNKI search and metadata
Keywords: cnki,mcp,cli,academic,papers,metadata
Author: SongTan
Author-email: SongTan <sepinetam@gmail.com>
Requires-Dist: mcp[cli]>=1.28.1,<2.0
Requires-Dist: playwright>=1.40.0
Requires-Dist: pytest>=8.0.0 ; extra == 'dev'
Requires-Dist: ruff>=0.12.0 ; extra == 'dev'
Requires-Dist: mkdocs>=1.6,<2 ; extra == 'docs'
Requires-Dist: mkdocs-material>=9,<10 ; extra == 'docs'
Requires-Python: >=3.11
Project-URL: Homepage, https://github.com/sepinetam/cnki-mcp
Project-URL: Documentation, https://sepinetam.github.io/cnki-mcp/
Project-URL: Repository, https://github.com/sepinetam/cnki-mcp
Project-URL: Issues, https://github.com/sepinetam/cnki-mcp/issues
Project-URL: Changelog, https://github.com/sepinetam/cnki-mcp/releases
Provides-Extra: dev
Provides-Extra: docs
Description-Content-Type: text/markdown

# cnki-mcp
An MCP server for reach CNKI. 

[![PyPI version](https://img.shields.io/pypi/v/cnki-mcp.svg)](https://pypi.org/project/cnki-mcp/)
[![PyPI Downloads](https://static.pepy.tech/badge/cnki-mcp)](https://pepy.tech/projects/cnki-mcp)
[![License](https://img.shields.io/github/license/sepinetam/cnki-mcp)](LICENSE)

> 免责声明：该项目仅为个人学习项目，且仅供学习参考。 
> 该项目不隶属任何公司、机构，与中国知网（下简称为知网或CNKI）无任何所属关系。 
> 该项目不应用于非法手段，包括但不限于：批量访问知网进行搜索，以非正规途径获取知网论文，利用该项目进行违法违规的行为。 
> 如有上述行为，本项目不构成任何因果利害关系，由使用者自行负责。最终解释权归本项目所有。 

## 快速开始
本项目提供了配套的 Skill，且同时支持 MCP，CLI，Python API 等多种使用方式，以便为研究者的 Agent 助理快速稳定地使用中国知网搜索论文查找论文。

如果你是人类研究者，将下面这句话发送给你的 Agent 即可：
```plain text
帮我从 GitHub 上安装 SepineTam/cnki-mcp 这个项目的 skill，subagents 等，并通过命令行的形式初始化这个项目。
成功初始化后，去查看《世界经济》这本期刊的 ISSN 号，并告诉我这个期刊在 2025 年是否发表过任何和人才引进相关的文章。
```

如果你是 Agent，参考 [CNKI-MCP 的 Agent 安装文档](./docs/install.md)

## 首次初始化

首次使用时运行：

```bash
uv run cnki-mcp init
```

命令会询问 Profile 名称，直接回车使用 `default`。也可以直接指定名称：

```bash
uv run cnki-mcp init --profile school
```

请在打开的浏览器中完成学校或机构认证。初始化成功后，该 Profile 会成为默认
Profile，后续启动和检索无需重复指定。

## 推荐启动方式

推荐使用 HTTP。下面两条命令效果相同，默认监听 `127.0.0.1:7788`：

```bash
uv run cnki-mcp
uv run cnki-mcp serve --transport http --host 127.0.0.1 --port 7788
```

服务启动时会打开一个持久浏览器，并在服务进程退出时关闭。项目只提供知网检索和
文章信息读取，不提供全文下载。

按 ISSN 获取某一期的全部文章 metadata：

```bash
uv run cnki-mcp tool journal --issn 1002-9621 --year 2026 --vol 1
```

这里的 `--vol` 表示知网页面上的期号。返回结果会把真正的卷号 `volume` 和期号
`issue` 分开提供。尚未发行的年份或期号会返回 `IssueNotAvailable`。

通过期刊名称搜索 ISSN：

```bash
uv run cnki-mcp tool issn --journal "世界经济"
```

搜索会忽略期刊名中的空格和标点，并返回知网搜索到的全部候选期刊。期刊目录来自
知网期刊导航页。工具每次都会通过 ISSN 重新定位期刊并获取当次有效的页面地址，
不会保存其中会失效的 `p` 参数。

## 通过 Python 使用
该项目提供了 Python API 供学习参考：

```python
# pip install cnki-mcp

from cnki_mcp import CnkiClient

with CnkiClient(profile="profile1") as client:
    results = client.search(
        "TI='生态' and KY='生态文明'",
        sort_by="date",
    )
```

## 文档

- [Agent 安装指南](./docs/install.md)
- [Python API 与专业检索式](docs/api.md)
