# sztu-library-mcp

深圳技术大学图书馆的 MCP server。让 AI 助手直接查馆藏、找书、看某本书在哪个楼层、还能不能借。

**一句话：问一句「图书馆有没有《三体》」，它告诉你五楼有三本、两本借出了、哪本现在还着。**

> 非官方项目，与深圳技术大学图书馆无隶属关系。基于图书馆公开的书目检索接口，仅供个人学习与日常查书使用。

## 能做什么

| 工具 | 用途 |
| --- | --- |
| `search_books` | 按关键词 / 题名 / 责任者 / 主题 / ISBN 检索馆藏 |
| `book_availability` | 查某本书当前能不能借、在哪个楼层、预计何时归还 |
| `recommend_books` | 热门借阅 / 新书速递 / 热门搜索词 / 馆员推荐书单 |
| `suggest_keywords` | 检索词联想，确认书名写法 |

输出已经处理过，不是原始 JSON：

```
《三体.[Ⅱ].黑暗森林》  刘慈欣著 / 重庆出版社 / 2022
  索书号 I247.55/L590/2 · ISBN 978-7-229-16690-8
  纸本 3 册，可借 1 册
    · C-2图书馆五楼：借出（应还 2026-11-17）
    · C-2图书馆五楼：借出（应还 2026-11-28）
    · C-2图书馆密集书库Ⅴ：可借
```

## 安装

```bash
pip install -r requirements.txt
```

需要 Python 3.10+。

## 配置

在 MCP 客户端的配置里加一段。以 WorkBuddy 为例，编辑 `~/.workbuddy/mcp.json`：

```json
{
  "mcpServers": {
    "sztu-library": {
      "command": "python",
      "args": ["/绝对路径/sztu-library-mcp/server.py"]
    }
  }
}
```

Claude Desktop 是 `claude_desktop_config.json`，Cursor 是 `.cursor/mcp.json`，格式相同。

`command` 建议写 Python 解释器的绝对路径，避免客户端找不到。

## 验证

```bash
python verify.py
```

会启动 server、握手、列出工具、实际查一次「三体」。通了就说明链路正常。

## 说明

- **不需要登录，不需要任何密钥。** 书目检索接口是公开的。
- 校园网内访问最快。校外如需访问图书馆系统，请走学校 WebVPN。
- `holdings` 字段原始值是 JSON 字符串，本项目做了解析，这是输出的主要价值所在。
- 请勿高频或批量请求。这是学校的生产系统，不属于个人可随意压测的资源。

## 已知限制

- 只覆盖纸质/电子馆藏检索。空间预约、借阅记录、数据库检索是另外的独立系统，接口不通用。
- 单次检索结果上限由对方的搜索引擎决定（`total` 会被截断在 10000），实际总量看 `actualTotal`。
- 馆藏状态是实时快照，刚被借走的书可能仍显示可借。

## License

MIT