内容
# zenodo-mcp-server
一个MCP服务器，允许LLM代理使用[Zenodo](https://zenodo.org)存储库查询和交互，使用[Zenodo REST API](https://developers.zenodo.org)。
## 功能
- **无需身份验证的访问** – 在无需API密钥的情况下搜索和查看公共记录
- **会话API密钥** – 通过`set_api_key`工具在运行时提供个人访问令牌
- **持久服务账户** – 设置`ZENODO_API_KEY`环境变量以获取长期有效的密钥
- **可选的写入访问** – 创建、更新和发布稿件（通过`ZENODO_ALLOW_WRITE=true`启用）
- 使用完整的Elasticsearch查询语法、分页和筛选搜索记录
- 浏览和筛选Zenodo社区
- 检索记录元数据、文件和文件内容（文本或二进制）
- 列出、创建、更新、发布和版本化稿件（写入工具需要`ZENODO_ALLOW_WRITE=true`）
- 可配置的Zenodo基准URL，用于沙盒或自托管实例
- 通过`ZENODO_COMMUNITY`设置可选的默认社区筛选
## 快速入门
### 先决条件
- Node.js 18 或更高版本
- npm
### 安装
```bash
git clone https://github.com/eic/zenodo-mcp-server.git
cd zenodo-mcp-server
npm install
npm run build
```
### 运行服务器
```bash
# 无身份验证（仅限公共记录）
node build/src/index.js
# 使用持久API密钥（服务账户）
ZENODO_API_KEY=your_token node build/src/index.js
# 使用Zenodo沙盒
ZENODO_BASE_URL=https://sandbox.zenodo.org ZENODO_API_KEY=your_sandbox_token node build/src/index.js
```
## 身份验证
Zenodo使用[个人访问令牌](https://zenodo.org/account/settings/applications/tokens/new/)进行身份验证。
### 选项1 – 会话密钥（推荐用于交互式使用）
连接到服务器后，调用`set_api_key`工具：
```json
{ "name": "set_api_key", "arguments": { "api_key": "your_personal_access_token" } }
```
令牌存储在内存中，仅在服务器进程生命周期内有效，永不写入磁盘。
### 选项2 – 环境变量（服务账户/CI）
```bash
export ZENODO_API_KEY=your_personal_access_token
node build/src/index.js
```
### 创建令牌
1. 登录 [zenodo.org](https://zenodo.org)
2. 进入 **账户 → 设置 → 应用程序 → 个人访问令牌**
3. 点击 **新建令牌** 并选择所需的范围：
- `deposit:write` – 创建和更新稿件
- `deposit:actions` – 发布稿件
- `user:email` – 验证身份（可选）
4. 安全保存令牌 – 它仅显示一次
## 可用工具
| 工具 | 描述 | 需要身份验证 | 需要写入权限 |
|------|-------------|:-------------:|:--------------:|
| `get_auth_status` | 检查身份验证状态并获取设置指南 | 否 | 否 |
| `set_api_key` | 为当前会话设置个人访问令牌 | 否 | 否 |
| `search_records` | 使用Elasticsearch查询语法搜索Zenodo记录 | 否 | 否 |
| `get_community` | 获取特定Zenodo社区的详细信息 | 否 | 否 |
| `list_communities` | 搜索或列出Zenodo社区 | 否 | 否 |
| `get_record` | 获取记录的完整元数据，ID或DOI | 否 | 否 |
| `list_record_files` | 列出记录所附的文件 | 否 | 否 |
| `get_file_content` | 下载文件内容（文本或base64） | 否 | 否 |
| `list_depositions` | 列出您自己的稿件（草稿 + 已发布） | **是** | 否 |
| `create_deposition` | 创建新的空稿件（草稿） | **是** | **是** |
| `get_deposition` | 检索单个稿件，ID | **是** | **是** |
| `update_deposition` | 更新草稿稿件的元数据 | **是** | **是** |
| `delete_deposition` | 删除未发布的草稿稿件 | **是** | **是** |
| `upload_file` | 上传文件到稿件 | **是** | **是** |
| `delete_deposition_file` | 从未发布的稿件中删除文件 | **是** | **是** |
| `publish_deposition` | 发布稿件并注册DOI | **是** | **是** |
| `edit_deposition` | 解锁已发布的稿件进行元数据编辑 | **是** | **是** |
| `discard_deposition` | 放弃编辑并恢复到已发布状态 | **是** | **是** |
| `new_version` | 创建已发布的稿件的新版本 | **是** | **是** |
> 仅当设置`ZENODO_ALLOW_WRITE=true`（或`ZENODO_ALLOW_WRITE=1`）时，写入工具才可用。有关完整的参数详细信息，请参见 [docs/TOOLS.md](docs/TOOLS.md)。
### `search_records`
```json
{
"name": "search_records",
"arguments": {
"query": "electron ion collider",
"size": 10,
"page": 1,
"sort": "mostrecent",
"type": "publication",
"subtype": "article",
"communities": "zenodo",
"all_versions": false,
"bounds": "143.37,-38.99,146.90,-37.35"
}
}
```
排序选项：`bestmatch`、`mostrecent`、`mostviewed`、`mostdownloaded`（前缀`-`表示降序）。
资源类型：`publication`、`poster`、`presentation`、`dataset`、`image`、`video`、`software`、`lesson`、`other`。
`bounds` — 可选的地理位置边界框：`"west,south,east,north"`，单位为十进制度。
当设置`ZENODO_COMMUNITY`时，如果未提供`communities`参数，则默认为该值。
### `get_record`
接受数字ID或DOI：
```json
{ "name": "get_record", "arguments": { "id": "1234567" } }
{ "name": "get_record", "arguments": { "id": "10.5281/zenodo.1234567" } }
```
### `get_file_content`
```json
{
"name": "get_file_content",
"arguments": {
"id": "1234567",
"filename": "data.csv",
"max_bytes": 1048576
}
}
```
文本文件以UTF-8字符串返回。二进制文件以base64返回。`truncated`字段指示文件是否在`max_bytes`处被截断。
## 环境变量
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `ZENODO_BASE_URL` | `https://zenodo.org` | Zenodo实例的基准URL |
| `ZENODO_API_KEY` | *(无)* | 用于持久身份验证的个人访问令牌 |
| `ZENODO_ALLOW_WRITE` | *(未设置)* | 设置为`true`或`1`以启用写入工具（稿件） |
| `ZENODO_COMMUNITY` | *(无)* | 应用于搜索的默认社区标识符 |
| `ZENODO_MAX_UPLOAD_BYTES` | `52428800`（50 MiB） | `upload_file`的最大文件大小 |
## MCP客户端配置
将服务器添加到MCP客户端配置中（例如Claude Desktop `claude_desktop_config.json`）：
```json
{
"mcpServers": {
"zenodo": {
"command": "node",
"args": ["/path/to/zenodo-mcp-server/build/src/index.js"],
"env": {
"ZENODO_API_KEY": "your_token_here"
}
}
}
}
```
## 开发
```bash
npm run build # 编译TypeScript
npm run watch # 监视模式
npm test # 构建并运行测试
npm run test:coverage # 测试并生成覆盖率报告
```
## 许可证
MIT
