# CSL MCP Server

一个基于 Python + SQLite 的本地 MCP Server，用于把 [CSL 中文科学文献数据集](https://github.com/ydli-ai/CSL) 封装成可被 Trae、MCP Inspector 或其他 MCP Client 调用的文献检索工具。

## 功能

当前版本提供以下 MCP Tools：

| Tool | 说明 |
| --- | --- |
| `search_papers` | 根据标题、摘要、关键词检索论文，支持门类和学科过滤 |
| `get_paper` | 根据论文 ID 获取单篇论文详情 |
| `list_categories` | 列出 CSL 数据库中的门类及数量 |
| `list_disciplines` | 列出 CSL 数据库中的学科及数量，可按门类过滤 |
| `get_dataset_statistics` | 查看本地 SQLite 数据库中的论文、门类、学科统计 |

当前版本还提供一个 MCP Resource：

| Resource | 说明 |
| --- | --- |
| `csl://dataset/info` | 查看 CSL 数据集和当前 MCP Server 的简要说明 |

## 项目结构

```text
.
├── data/
│   └── csl.sqlite              # 导入后生成的本地 SQLite 数据库
├── src/
│   └── csl_mcp/
│       ├── __init__.py
│       ├── config.py           # 数据库路径配置
│       ├── database.py         # SQLite schema、连接和数据转换
│       ├── ingest.py           # CSL 数据导入脚本
│       ├── server.py           # MCP Server 入口和 tools 定义
│       └── service.py          # 文献检索和统计服务
├── mcp_config.example.json     # MCP Client 配置示例
├── pyproject.toml
└── README.md
```

## 环境要求

- Python 3.10+
- SQLite，Python 标准库已内置
- MCP Python SDK

安装依赖：

```powershell
cd D:\xm\CSL
pip install -e .
```

如果需要单独安装 MCP SDK：

```powershell
pip install "mcp>=1.0.0"
```

## 下载 CSL Benchmark 数据

CSL benchmark 数据在官方仓库中，可以克隆完整仓库：

```powershell
cd D:\xm
git clone https://github.com/ydli-ai/CSL.git CSL-source
```

benchmark 数据目录通常是：

```text
D:\xm\CSL-source\benchmark
```

也可以只拉取 benchmark 目录：

```powershell
cd D:\xm
git clone --filter=blob:none --sparse https://github.com/ydli-ai/CSL.git CSL-source
cd CSL-source
git sparse-checkout set benchmark
```

## 导入数据

将 CSL 数据导入到本地 SQLite：

```powershell
cd D:\xm\CSL
python -m csl_mcp.ingest "D:\xm\CSL-source\benchmark" --db "D:\xm\CSL\data\csl.sqlite"
```

导入成功后会看到类似输出：

```text
Imported 10000 records into D:\xm\CSL\data\csl.sqlite
```

导入脚本支持：

- `.json`
- `.jsonl`
- `.tsv`
- 包含以上文件的目录

对于 CSL benchmark 中的 text2text 格式，导入脚本会根据 `prompt` 做基础字段映射：

| prompt | 映射逻辑 |
| --- | --- |
| `to title` | `text_a` 作为摘要，`text_b` 作为标题 |
| `to keywords` | `text_a` 作为摘要，`text_b` 作为关键词 |
| `to category` | `text_a` 作为标题，`text_b` 作为门类 |
| `to discipline` | `text_a` 作为摘要，`text_b` 作为学科 |

## 在 MCP Inspector 中使用

启动 MCP Inspector 后，按以下方式配置：

| 配置项 | 值 |
| --- | --- |
| Transport Type | `STDIO` |
| Command | `python` |
| Arguments | `-m csl_mcp.server` |

环境变量：

| Name | Value |
| --- | --- |
| `PYTHONPATH` | `D:\xm\CSL\src` |
| `CSL_DB_PATH` | `D:\xm\CSL\data\csl.sqlite` |

然后点击 `Connect`。

连接成功后可以测试：

```json
{}
```

调用 `get_dataset_statistics`，或调用 `search_papers`：

```json
{
  "query": "文本分类",
  "limit": 5
}
```

## 在 Trae 中配置

可以参考 `mcp_config.example.json`：

```json
{
  "mcpServers": {
    "csl": {
      "command": "D:/xm/CSL/.venv/Scripts/python.exe",
      "args": [
        "-m",
        "csl_mcp.server"
      ],
      "env": {
        "PYTHONPATH": "D:/xm/CSL/src",
        "CSL_DB_PATH": "D:/xm/CSL/data/csl.sqlite"
      }
    }
  }
}
```

如果不使用虚拟环境，也可以把 `command` 改成：

```json
"python"
```

配置完成后，可以在 Trae 中直接提问：

```text
请用 csl 搜索“文本分类”相关论文，返回 5 篇。
```

```text
请列出 CSL 数据库中的门类。
```

```text
请查看 CSL 数据库统计信息。
```

## 直接启动说明

本项目的 MCP Server 使用 stdio transport。它不是普通命令行交互程序。

因此直接执行：

```powershell
python -m csl_mcp.server
```

如果没有 MCP Client 向 stdin 发送合法 JSON-RPC 消息，可能会看到类似错误：

```text
Invalid JSON: EOF while parsing a value
```

这是 stdio MCP Server 的正常表现。正确方式是由 Trae、MCP Inspector 或其他 MCP Client 启动它。

## Tool 参数示例

### search_papers

```json
{
  "query": "文本分类",
  "limit": 5,
  "category": "工学",
  "discipline": "计算机科学与技术"
}
```

其中 `category` 和 `discipline` 可选。

### get_paper

```json
{
  "paper_id": "csl_00026194"
}
```

### list_categories

```json
{}
```

### list_disciplines

```json
{
  "category": "工学"
}
```

### get_dataset_statistics

```json
{}
```

## 当前实现说明

- 使用 SQLite 保存论文元数据。
- 使用 SQLite FTS5 建立基础全文检索索引。
- 对 `category` 和 `discipline` 建立普通索引。
- `keywords` 在 SQLite 中以 JSON 字符串保存，返回时转换为数组。
- `limit` 最大限制为 50，避免一次返回过多内容。
- 查询结果统一使用：

```json
{
  "ok": true,
  "data": {},
  "error": null
}
```

失败时：

```json
{
  "ok": false,
  "data": null,
  "error": {
    "code": "PAPER_NOT_FOUND",
    "message": "Paper not found: csl_xxx"
  }
}
```

## 局限性

当前版本是本地 MVP，主要用于验证 MCP Server、SQLite 数据导入和基础检索流程。

已知限制：

- SQLite FTS5 对中文分词能力有限。
- 当前没有向量检索和语义召回。
- 当前没有远程 HTTP/SSE transport。
- 当前没有鉴权、审计和权限控制。
- 当前主要面向 CSL benchmark 数据，完整 396k 数据需要额外下载后导入。

## 后续计划

- 增加 `--reset` 导入参数和更详细导入统计。
- 增加 `sample_papers` 工具。
- 增加 `similar_papers` 工具。
- 接入 FAISS / Qdrant 做语义检索。
- 增加 hybrid search，将关键词检索和向量检索结合。
- 增加 HTTP/SSE 部署模式。
- 增加企业内部场景所需的鉴权、审计、限流和权限过滤。

## 参考

- [CSL: A Large-scale Chinese Scientific Literature Dataset](https://github.com/ydli-ai/CSL)
- [Model Context Protocol](https://modelcontextprotocol.io/)