内容
# Z39.50 图书馆系统 MCP 服务器
用于跨多个支持 Z39.50 的图书馆系统搜索图书馆目录的快速高效的 MCP（模型上下文协议）服务器。
## 功能特点
- **快速并行搜索**：使用异步 I/O 同时查询多个图书馆
- **多个图书馆系统**：国会图书馆、OCLC WorldCat、学术图书馆网络
- **丰富的搜索选项**：标题、作者、ISBN、主题、关键词搜索
- **可用性检查**：查找哪些图书馆有特定的书籍
- **详细的记录**：检索全面的书目信息
- **MARC 导出**：以二进制 MARC、JSON 或 XML 格式下载记录
- **结果去重**：跨图书馆智能合并结果
- **连接池**：为最佳性能使用持久连接
## 快速入门
### 安装
```bash
# 安装依赖
pip install -r requirements.txt
```
### 运行服务器
```bash
# 启动 MCP 服务器
python server.py
# 开启调试日志
python server.py --debug
```
### 与 Claude Desktop 一起使用
将以下内容添加到您的 Claude Desktop 配置中：
```json
{
"mcpServers": {
"z3950": {
"command": "python",
"args": ["/path/to/Z3950/server.py"]
}
}
}
```
然后重启 Claude Desktop，Z39.50 工具即可使用。
## 可用工具
### search_libraries
跨多个图书馆系统搜索。
```
search_libraries(
query: "Harry Potter",
libraries: "loc,worldcat", # 可选：默认为所有
query_type: "title", # title, author, isbn, subject, keyword
max_results: 50
)
```
**示例：**
- 查找书籍标题：`search_libraries("The Great Gatsby", query_type="title")`
- 查找书籍作者：`search_libraries("Stephen King", query_type="author")`
- 查找 ISBN：`search_libraries("978-0-262-03384-8", query_type="isbn")`
### check_availability
检查哪些图书馆有某本书库存。
```
check_availability(
isbn: "978-0-262-03384-8",
libraries: "loc,worldcat" # 可选：默认为所有
)
```
返回每个图书馆的可用状态和索书号。
### get_record_details
获取全面的书目信息。
```
get_record_details(
isbn: "978-0-262-03384-8",
library: "loc"
)
```
返回详细的元数据，包括作者、出版商、主题、出版年份等。
### browse_subjects
浏览可用的主题类别。
```
browse_subjects(
library: "loc",
subject_prefix: "History",
limit: 20
)
```
### list_libraries
获取可用的图书馆系统信息。
```
list_libraries()
```
### export_marc_record
下载 MARC 记录用于本地使用。
```
export_marc_record(
isbn: "978-0-262-03384-8",
library: "loc",
format: "binary" # binary, json, or xml
)
```
## 可用图书馆
### 国会图书馆 (loc)
- **主机**: z3950.loc.gov:7090
- **数据库**: Voyager
- **描述**: 世界上最大的图书馆，拥有综合性藏书
### OCLC WorldCat (worldcat)
- **主机**: z3950.oclc.org:210
- **数据库**: WorldCat
- **描述**: 世界上最大的图书馆目录，包含来自数千个图书馆的记录
### I-Share Consortium (i-share)
- **主机**: vufind.carli.illinois.edu:210
- **数据库**: i-share
- **描述**: 伊利诺伊州学术图书馆网络，包含主要大学的内容
### Ex Libris Alma (alma-template)
- **主机**: z3950.alma.exlibrisgroup.com:1921
- **描述**: 现代图书馆管理系统（需要 institution_id 配置）
## 配置
图书馆配置位于 `config/libraries.json`。要添加新图书馆：
```json
{
"my-library": {
"name": "我的图书馆系统",
"host": "z3950.mylib.edu",
"port": 210,
"database": "mylibdb",
"preferred_syntax": "USMARC",
"timeout": 5,
"max_records": 100
}
}
```
## 性能优化
服务器针对速度进行了优化：
1. **异步并行查询**：同时查询多个图书馆
2. **连接池**：持久连接消除握手开销
3. **智能超时**：5 秒超时，快速失败于慢速服务器
4. **二进制 MARC**：首选格式（比 JSON/XML 快）
5. **延迟解析**：默认情况下仅提取所需字段
6. **结果去重**：通过 ISBN/控制号的 O(1) 重复检测
7. **流式结果**：增量结果交付
**性能目标：**
- 单图书馆搜索：< 2 秒
- 多图书馆并行搜索：< 5 秒
- 缓存命中：< 100ms
## 架构
### 提取的 PyZ3950 模块 (`z3950_protocol/`)
从 PyZ3950 中提取的核心 Z39.50 协议实现：
- `asn1.py`: ASN.1 BER 编码器/解码器
- `zoom.py`: 高级查询的 ZOOM API 包装器
- `z3950.py`: 核心协议实现
- `pqf.py`: 前缀查询格式解析器
- `zmarc.py`: MARC 记录解析
### MCP 集成层 (`z3950_client/`)
用于高效 MCP 集成的自定义包装器：
- `connection_pool.py`: 异步连接管理
- `record_processor.py`: 快速 MARC 记录提取
- `query.py`: 查询构建和验证
### MCP 工具 (`tools/`)
FastMCP 工具实现：
- `search.py`: 并行多图书馆搜索
- `holdings.py`: 可用性检查
- `details.py`: 完整记录检索
- `browse.py`: 主题浏览
- `export.py`: MARC 记录导出
## 依赖
- **fastmcp** (>=0.1.0)：MCP 服务器框架
- **pymarc** (>=5.0.0)：MARC 记录处理
- **ply** (>=3.11)：查询解析器（PLY - Python Lex-Yacc）
所有 Z39.50 协议实现都是纯 Python，无需编译依赖。
## 搜索语法
### CCL（通用命令语言）
系统使用 CCL 进行直观搜索：
- **标题**: `title="The Great Gatsby"`
- **作者**: `author="F. Scott Fitzgerald"`
- **ISBN**: `isbn="978-0-7432-7356-5"`
- **主题**: `subject="American fiction"`
- **关键词**: `keyword="gatsby"`
- **出版商**: `publisher="Scribner"`
- **年份**: `year="1925"`
### 多条件
用 AND/OR 组合：
- `author="Shakespeare" AND title="Hamlet"`
- `subject="History" OR subject="Biography"`
## 开发
### 运行测试
```bash
# 所有测试
python -m pytest tests/ -v
# 性能基准测试
python -m pytest tests/ -v --benchmark
# 特定测试文件
python -m pytest tests/test_search.py -v
```
### 添加新图书馆
1. 编辑 `config/libraries.json`
2. 测试连接：`python -c "from z3950_client.connection_pool import AsyncConnectionPool; pool = AsyncConnectionPool(); print(asyncio.run(pool.test_connection('my-lib')))"`
3. 重启服务器
### 调试模式
运行调试日志：
```bash
python server.py --debug
```
## 故障排除
### 连接超时
- 检查图书馆是否在线：`list_libraries()` 验证配置
- 增加 `config/libraries.json` 中的超时时间
- 尝试特定图书馆而不是所有图书馆
### 未找到结果
- 尝试不同搜索类型（标题 vs. 关键词）
- 检查 ISBN 格式（可能需要删除连字符）
- 一些图书馆的藏书有限
### MARC 解析错误
- 确保图书馆返回 USMARC 格式
- 尝试不同查询以获取不同记录
- 联系图书馆支持以进行格式配置
## 参考
- [Z39.50 协议概述](https://zh.wikipedia.org/wiki/Z39.50)
- [MARC 记录指南](https://www.loc.gov/marc/)
- [PyZ3950 文档](http://www.panix.com/~asl2/software/PyZ3950/)
- [PyMARC 文档](https://pymarc.readthedocs.io/)
- [MCP 文档](https://modelcontextprotocol.io/)
## 许可证
该项目包含从 PyZ3950 提取的代码，该代码为开源代码。有关归属，请参见各个文件头。
## 贡献
要添加新功能或修复错误：
1. 创建测试用例
2. 实现功能
3. 确保所有测试通过
4. 更新文档
## 支持
对于以下问题：
- **Z39.50 协议**：查看 [PyZ3950 文档](http://www.panix.com/~asl2/software/PyZ3950/)
- **MARC 格式**：查看 [国会图书馆 MARC 指南](https://www.loc.gov/marc/)
- **MCP 集成**：参考 [MCP 文档](https://modelcontextprotocol.io/)
