Open Library MCP Server

一个基于Model Context Protocol (MCP)的服务器，用于访问Open Library的所有API接口。这个包通过MCP协议为AI助手和研究工具提供无缝的图书馆数据集成。

⚠️ 重要说明

网络环境要求: 本服务需要稳定的网络连接才能正常访问Open Library API。在某些网络环境下（如企业内网、某些地区网络或网络不稳定时），可能会出现连接超时或失败的情况。这是正常现象，不影响MCP服务器的核心功能，只是API调用会返回网络错误信息。

✨ 功能特性

• 🔍 智能书籍搜索 - 搜索Open Library中的数百万本书籍
• 👤 作者信息查询 - 获取作者详细信息和作品列表
• 📚 主题分类浏览 - 根据主题分类浏览相关书籍
• 🔎 内容搜索 - 在书籍内容中搜索特定文本
• 📖 版本管理 - 获取书籍的不同版本信息
• 🖼️ 封面图片 - 获取书籍封面图片
• 📊 最近更新 - 查看Open Library的最新更改
• 📝 用户列表 - 访问用户的阅读列表和收藏
• 🔗 ISBN查询 - 通过ISBN号码快速查找书籍
• ⚡ 快速响应 - 30秒超时，优化性能
• 🛡️ 健壮错误处理 - 全面的错误管理
• 📊 详细日志 - 调试友好的日志系统
• 🔧 易于集成 - 简单的MCP协议实现
• 🌐 网络自适应 - 自动处理网络连接问题，提供详细错误信息

🚀 快速开始

安装

# 全局安装（可选）
npm install -g giisp-openlibrary-mcp

# 或直接使用npx（推荐）
npx -y giisp-openlibrary-mcp

使用方法

使用npx运行（推荐）

npx -y giisp-openlibrary-mcp

作为全局命令

giisp-openlibrary-mcp

作为MCP服务器

服务器将启动并监听通过stdio的MCP协议消息。

与Claude Desktop集成

要在Claude Desktop中使用此MCP服务器，请将以下内容添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "giisp-openlibrary-mcp": {
      "command": "npx",
      "args": ["-y", "giisp-openlibrary-mcp"]
    }
  }
}

添加此配置后，重启Claude Desktop，您就可以通过MCP界面直接搜索图书馆数据。

开发安装

git clone https://github.com/giisp/giisp-openlibrary-mcp.git
cd giisp-openlibrary-mcp
npm install
npm start

📖 使用说明

MCP工具集成

服务器提供以下工具来访问Open Library的各种功能：

1. 搜索书籍 (searchBooks)

搜索书籍、作者和其他内容。

参数:

• query (string, 必需): 搜索关键词
• page (number, 可选): 页码（默认为1）
• limit (number, 可选): 每页结果数量（默认为10）

示例:

{
  "name": "searchBooks",
  "arguments": {
    "query": "artificial intelligence",
    "page": 1,
    "limit": 10
  }
}

2. 获取作品信息 (getWork)

根据工作ID获取特定作品信息。

参数:

• workId (string, 必需): Open Library工作ID（如OL15626917W）

示例:

{
  "name": "getWork",
  "arguments": {
    "workId": "OL15626917W"
  }
}

3. 获取版本信息 (getEdition)

根据版本ID获取特定版本信息。

参数:

• editionId (string, 必需): Open Library版本ID（如OL12345678M）

示例:

{
  "name": "getEdition",
  "arguments": {
    "editionId": "OL12345678M"
  }
}

4. 获取作者信息 (getAuthor)

根据作者ID获取作者信息及其作品。

参数:

• authorId (string, 必需): Open Library作者ID（如OL33421A）

示例:

{
  "name": "getAuthor",
  "arguments": {
    "authorId": "OL33421A"
  }
}

5. 根据主题获取书籍 (getBooksBySubject)

根据主题名称获取相关书籍。

参数:

• subject (string, 必需): 主题名称（如science fiction, biography等）
• page (number, 可选): 页码（默认为1）
• limit (number, 可选): 每页结果数量（默认为10）

示例:

{
  "name": "getBooksBySubject",
  "arguments": {
    "subject": "science fiction",
    "page": 1,
    "limit": 10
  }
}

6. 搜索书籍内容 (searchInside)

在数百万本书中搜索匹配的文本。

参数:

• query (string, 必需): 要搜索的文本内容
• page (number, 可选): 页码（默认为1）
• limit (number, 可选): 每页结果数量（默认为10）

示例:

{
  "name": "searchInside",
  "arguments": {
    "query": "machine learning algorithms",
    "page": 1,
    "limit": 10
  }
}

7. 根据ISBN获取书籍 (getBookByISBN)

根据ISBN获取书籍信息。

参数:

• isbn (string, 必需): 书籍的ISBN号码

示例:

{
  "name": "getBookByISBN",
  "arguments": {
    "isbn": "9780140328721"
  }
}

8. 获取书籍封面 (getBookCover)

获取书籍封面图片。

参数:

• isbn (string, 可选): 书籍的ISBN号码
• olid (string, 可选): Open Library ID
• size (string, 可选): 封面尺寸：S（小）、M（中）、L（大）（默认为M）

示例:

{
  "name": "getBookCover",
  "arguments": {
    "isbn": "9780140328721",
    "size": "M"
  }
}

9. 获取最近更改 (getRecentChanges)

获取Open Library的最近更改。

参数:

• page (number, 可选): 页码（默认为1）
• limit (number, 可选): 每页结果数量（默认为10）

示例:

{
  "name": "getRecentChanges",
  "arguments": {
    "page": 1,
    "limit": 10
  }
}

10. 获取用户列表 (getUserLists)

获取用户的阅读列表。

参数:

• username (string, 必需): 用户名
• page (number, 可选): 页码（默认为1）
• limit (number, 可选): 每页结果数量（默认为10）

示例:

{
  "name": "getUserLists",
  "arguments": {
    "username": "example_user",
    "page": 1,
    "limit": 10
  }
}

11. 获取我的书籍 (getMyBooks)

获取用户的公开阅读日志中的书籍。

参数:

• username (string, 必需): 用户名
• page (number, 可选): 页码（默认为1）
• limit (number, 可选): 每页结果数量（默认为10）

示例:

{
  "name": "getMyBooks",
  "arguments": {
    "username": "example_user",
    "page": 1,
    "limit": 10
  }
}

响应格式

所有API调用都返回统一的响应格式：

{
  "success": true,
  "status": 200,
  "data": {
    // API响应数据
  },
  "message": "操作完成"
}

🔧 技术细节

• 超时时间: 30秒
• 请求头: 自动设置Content-Type和User-Agent
• 错误处理: 区分网络、API和超时错误
• 日志记录: 详细的请求和响应日志
• 图片处理: 自动将封面图片转换为base64格式
• 重试机制: 自动重试3次，每次间隔1秒
• 网络诊断: 内置网络连接检测工具

🛠️ 错误处理

服务器处理以下错误类型：

• 超时错误: 请求超过30秒
• 网络错误: 无法连接到Open Library服务器（常见于网络环境限制）
• API错误: 服务器返回错误状态码
• 参数错误: 缺少必需参数或类型不正确
• 连接重置: 网络连接被重置（网络不稳定）
• 域名解析失败: DNS解析问题
• 连接被拒绝: 服务器暂时不可用

网络环境说明

由于Open Library服务器位于海外，在某些网络环境下可能出现连接问题：

• 企业内网: 可能被防火墙阻止
• 地区限制: 某些地区网络访问受限
• 网络不稳定: 导致连接超时或重置
• DNS问题: 域名解析失败

这些都是正常现象，不影响MCP服务器的核心功能。

🧪 测试

运行测试套件：

npm test

这将测试：

• API连接性
• 参数验证
• 错误处理
• 所有主要功能

📁 项目结构

├── server.js              # 主服务器文件
├── package.json           # 项目配置和依赖
├── README.md             # 项目文档
├── LICENSE               # MIT许可证
├── INSTALLATION.md       # 安装说明
├── mcp-config-example.json # MCP配置示例
└── test/
    └── test-api.js       # 测试套件

🚀 开发

调试模式

使用Node.js调试器运行调试模式：

npm run dev

在调试器中设置断点进行开发。

贡献

1. Fork仓库
2. 创建功能分支
3. 进行更改
4. 为新功能添加测试
5. 提交拉取请求

📄 许可证

MIT许可证 - 详见LICENSE文件。

🤝 支持

• 邮箱: [email protected]

🔗 相关链接

• Open Library
• Model Context Protocol

📝 更新日志

v1.0.3

• 改进网络错误处理机制
• 添加自动重试功能
• 优化错误信息提示
• 添加网络诊断工具

v1.0.2

• 项目结构优化
• 移除冗余文件
• 简化配置

v1.0.1

• 支持npx运行格式
• 完善Claude Desktop集成

v1.0.0

• 初始版本发布
• 实现所有Open Library API接口
• 支持MCP协议集成
• 完整的错误处理和日志记录