内容
# dspace-mcp
[](https://github.com/mpasternak/dspace-mcp/actions/workflows/ci.yml)
[](https://pypi.org/project/dspace-mcp/)
[](https://pypi.org/project/dspace-mcp/)
[](LICENSE)
一个只读的MCP服务器，允许AI助手与任何DSpace 7+仓库进行通信。
用普通语言向仓库提问 — *"我们发布了多少篇论文？"*，*"哪些作者在该收藏中出现得最频繁？"*，*"总结一下附在该项目上的PDF文件"* — 助手会直接查询DSpace REST API来回答。
## 构造而非承诺的只读
服务器不持有任何凭证，并且只发出`GET`请求。它不能存款、编辑或删除任何内容，也不能读取公共用户无法看到的内容 — 封闭的项目、工作流提交和受限的收藏保持不可见。
这是代码的属性，而不是模型的属性：没有任何东西需要提示注入。测试套件中的一个测试断言永远不会离开进程的其他HTTP方法。
## 安装
如果你有uv，则无需安装：
```bash
uvx dspace-mcp --base-url https://demo.dspace.org/server
```
或者使用pip：
```bash
pip install dspace-mcp
```
## 配置您的MCP客户端
**Claude 代码：**
```bash
claude mcp add dspace -- uvx dspace-mcp --base-url https://demo.dspace.org/server
```
**Claude 桌面版 / 任何使用 `mcp.json` 的客户端：**
```json
{
"mcpServers": {
"dspace": {
"command": "uvx",
"args": ["dspace-mcp", "--base-url", "https://demo.dspace.org/server"]
}
}
}
```
将 `--base-url` 指向您自己的仓库的REST API — 通常是您的DSpace URL后加上 `/server`。如果您省略 `/server`，服务器会检测到它并为您纠正URL。
要连接到多个仓库，请在不同名称下添加多个条目。一个进程只为一个仓库服务，这可以防止助手混淆它们。
## 工具
| 工具 | 功能 |
|---|---|
| `search_items` | 搜索项目；按年份范围、作者、收藏过滤；按相关性、日期或标题排序。 `limit=0` 返回计数。 |
| `get_item` | 通过 **UUID、Handle 或 DOI** 获取一个项目 — 您拥有的标识符即可。 |
| `list_communities` | 遍历社区树（最多3级）。 |
| `list_collections` | 列出一个社区或整个仓库的收藏。 |
| `list_bitstreams` | 列出项目的带有大小、MIME类型、校验和和下载URL的文件。 |
| `get_bitstream_text` | 提取PDF的文本，以便助手可以读取或总结它。 |
| `list_facet_values` | 计算一个面的值（作者、主题、年份） — 仓库进行计数，因此不会下载记录。 |
| `get_item_statistics` | 查看项目的计数。 |
| `get_repository_info` | 名称、版本、项目计数，以及此实例实际支持的搜索过滤器、排序字段和面。 |
### 两件值得注意的事情
**首先询问 `get_repository_info`。** DSpace安装有所不同：搜索过滤器和面的集合是按实例配置的，因此一个仓库中存在的过滤器在另一个仓库中可能会返回错误。此工具报告您所面对的实例支持的内容。
**计数是免费的。** `search_items` 带有 `limit=0`，以及 `list_facet_values`，以单个请求和少数几个令牌回答“多少”问题，而不是下载记录并计数它们。
## 配置
| 变量 | 默认值 | 含义 |
|---|---|---|
| `DSPACE_BASE_URL` | *(必填)* | REST API根目录，例如 `https://demo.dspace.org/server` |
| `DSPACE_TIMEOUT` | `15` | 每个HTTP请求的秒数 |
| `DSPACE_MAX_RESULTS` | `50` | 任何工具可能返回的记录数的上限 |
| `DSPACE_PDF_MAX_MB` | `20` | 拒绝下载大于此大小的PDF文件 |
每个变量都有一个匹配的标志： `--base-url`、 `--timeout`、 `--max-results`、 `--pdf-max-mb`。
## 兼容性
此处没有任何内容根据版本号进行分支。服务器询问每个实例支持哪些搜索过滤器、排序字段和面，并根据该答案进行工作，这是不同安装之间实际变化的内容 — 两个站点在同一个DSpace版本上可能比同一个站点的两个版本之间有更大的差异。
离线测试套件针对来自实时DSpace 10.1-SNAPSHOT (`demo.dspace.org`) 的记录响应运行，涵盖服务器触及的每个端点，以及来自 vanilla 7.6.5、DSpace-CRIS 8.2 和 11.0-SNAPSHOT的根和搜索响应，用于比较响应形状。合约测试 (`pytest -m live`) 每次针对一个实例运行 — 默认情况下为 `demo.dspace.org`，或者将 `DSPACE_TEST_URL` 指向您自己的实例。
在设计过程中，检查了该工具对REST API的假设与7.2.1、7.5、7.6.5、8.2、8.4、9.2、10.1和11.0-SNAPSHOT的实时实例的手动检查。这是对API的调查，而不是对该代码的测试运行。如果它在您无法测试的版本或配置上表现不佳，欢迎提交[错误报告](https://github.com/mpasternak/dspace-mcp/issues)。
## 开发
```bash
git clone https://github.com/mpasternak/dspace-mcp
cd dspace-mcp
uv sync --dev
uv run pytest # 单元测试，离线
uv run pytest -m live # 与demo.dspace.org的合约测试
uv run ruff check .
```
欢迎贡献。设计及其原理 — 包括为什么几个听起来很合理的DSpace API假设被证明是错误的 — 位于 `docs/superpowers/specs/`。
## 许可证
MIT — 请参阅 [LICENSE](LICENSE)。
