mcp-open-library

MCP Open Library

一个用于 Open Library API 的模型上下文协议（MCP）服务，可让 AI 助手搜索图书和作者信息。

概览

本项目实现了一个 MCP 服务，提供工具供 AI 助手与 Open Library 交互。它支持按书名、作者、主题及其他字段搜索目录，按姓名搜索作者，使用 Open Library 键获取详细作者信息，以及获取图书封面和作者照片的 URL。该服务返回 Open Library 响应的 JSON 投影，而非原始负载。

功能

• 图书搜索：按书名、作者、主题、地点、人物、出版商和 ISBN 搜索，并支持排序和分页（search_books）。
• 按书名搜索图书：使用书名搜索图书（get_book_by_title）。
• 按姓名搜索作者：使用姓名搜索作者，并支持分页（get_authors_by_name）。
• 获取作者详情：使用作者的 Open Library 键获取指定作者的详细信息（get_author_info）。
• 获取作者照片：使用作者的 Open Library ID（OLID）获取照片 URL（get_author_photo）。
• 获取图书封面：使用各种标识符（ISBN、OCLC、LCCN、OLID、ID）获取图书封面图片的 URL（get_book_cover）。
• 按 ID 获取图书：使用各种标识符（ISBN、LCCN、OCLC、OLID）获取图书的详细信息（get_book_by_id）。

搜索结果采用分页方式返回——每个搜索工具最多返回 limit 条结果（默认值为 10，最大值为 50），并附带匹配总数 num_found。可通过 offset 翻页（最大值为 1000）。两个封面工具都会检查图片是否实际存在；若不存在，会明确说明，而不是返回解析后显示空白占位图的 URL。

所有工具都是只读查询，并通过 readOnlyHint 和 openWorldHint 注解标明这一点；客户端可能因此跳过针对可能更改内容的工具显示的确认提示。这些只是提示：MCP 规范要求客户端将注解视为不可信，除非服务端可信，因此确认策略由客户端决定。如果发生故障（例如 API 无法访问或参数被拒绝），工具会返回标记了 isError 的结果，让助手了解问题所在并修正下一次调用，而不是直接导致请求失败。

安装

快速开始

无需安装或构建。使用 npx 将 MCP 客户端指向此软件包，它会在首次运行时下载：

{
  "mcpServers": {
    "mcp-open-library": {
      "command": "npx",
      "args": ["-y", "mcp-open-library"]
    }
  }
}

在 Claude Desktop 中，将此配置添加到 claude_desktop_config.json；其他客户端使用相同格式。重启客户端后，即可使用以下七个工具。

MCP Registry

此服务自 v1.0.3 起以 io.github.8enSmith/mcp-open-library 的名称发布到官方 MCP Registry。支持 该 Registry 的客户端可以通过此名称安装。

查看已发布的条目：

curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.8enSmith/mcp-open-library"

手动安装

# Clone the repository
git clone https://github.com/8enSmith/mcp-open-library.git
cd mcp-open-library

# Install dependencies
npm install

# Build the project
npm run build

使用方法

运行服务

1. 确保你运行的是 node v22.23.4（较新版本的 node 可能也能运行，但我在此测试中使用的是这个版本）。如果已安装 nvm，请运行 nvm use。
2. 在 mcp-open-library 根目录中运行 npm run build
3. 接下来运行 npm run inspector。构建完成后，点击带有 MCP_PROXY_AUTH_TOKEN 查询字符串参数的 URL，打开 Inspector。
4. 在 Inspector 中，选择“STDIO”传输方式
5. 确保命令设置为“build/index.js”
6. 点击 Inspector 中的“Connect”按钮，即可连接到服务
7. 点击右上角菜单栏中的“Tools”
8. 尝试运行一个工具，例如点击 get_book_by_title
9. 搜索一本书，例如在标题框中输入“The Hobbit”，然后点击“Run Tool”。服务随后会返回图书详情。

与 MCP 客户端搭配使用

此服务实现了 Model Context Protocol，因此可以与任何兼容 MCP 的 AI 助手或客户端搭配使用，例如 Claude Desktop。此服务提供以下工具：

• search_books：按查询、标题、作者、主题、地点、人物、出版商和 ISBN 的任意组合搜索目录
• get_book_by_title：按标题搜索图书信息
• get_authors_by_name：按姓名搜索作者信息
• get_author_info：使用 Open Library Author Key 获取特定作者的详细信息
• get_author_photo：使用作者的 Open Library Author ID (OLID) 获取其照片的 URL
• get_book_cover：使用特定标识符（ISBN、OCLC、LCCN、OLID 或 ID）获取图书封面图片的 URL
• get_book_by_id：使用特定标识符（ISBN、LCCN、OCLC 或 OLID）获取图书详细信息

search_books 输入示例：

{
  "author": "Ursula K. Le Guin",
  "subject": "fantasy",
  "sort": "old",
  "limit": 2
}

search_books 输出示例：

{
  "num_found": 51,
  "offset": 0,
  "limit": 2,
  "results": [
    {
      "title": "A Wizard of Earthsea",
      "authors": ["Ursula K. Le Guin"],
      "first_publish_year": 1968,
      "open_library_work_key": "/works/OL59798W",
      "edition_count": 87,
      "author_keys": ["OL31353A"],
      "best_edition": {
        "edition_key": "OL5613890M"
      },
      "cover_url": "https://covers.openlibrary.org/b/id/13617691-M.jpg",
      "ratings_average": 3.95,
      "ebook_access": "borrowable"
    }
  ]
}

best_edition 是该作品的一个特定版本，也就是 Open Library 根据你的查询评为最佳的版本，并带有该版本自身的标识符。其他搜索结果标识的是作品（open_library_work_key），而没有工具接受这种标识符，因此这是从搜索结果转到具体图书的途径。

其 edition_key 是一个 OLID，可以直接传给 get_book_by_id，以获取完整的版本记录，包括完整的 ISBN 数组：

{ "idType": "olid", "idValue": "OL5613890M" }

如果 Open Library 中该版本没有 ISBN，则会省略 isbn_13 / isbn_10 字段——如上面的示例所示，约三分之一的结果也是如此；而 edition_key 几乎总是存在。如果某个版本列出了多个同类型 ISBN，则会报告第一个；get_book_by_id 会返回全部 ISBN。

search_books 工具接受以下参数：

• q、title、author、subject、place、person、publisher 或 isbn 中至少指定一个——由于未筛选的搜索会匹配整个目录，因此不指定任何一个时请求会被拒绝。q 接受自由格式的 Solr 查询，例如 subject:cyberpunk AND first_publish_year:[1980 TO 1990]
• language：可选的 3 字母 MARC 语言代码（例如 eng、fre）
• sort：可选的排序方式——new、old、random、key、rating、readinglog、want_to_read、currently_reading、already_read 或 title。省略时按相关性排序
• limit：可选，范围为 1–50，默认为 10
• offset：可选，范围为 0–1000，默认为 0

get_book_by_title 输入示例：

{
  "title": "The Hobbit",
  "limit": 1
}

get_book_by_title 输出示例：

{
  "num_found": 224,
  "offset": 0,
  "limit": 1,
  "results": [
    {
      "title": "The Hobbit",
      "authors": ["J.R.R. Tolkien"],
      "first_publish_year": 1937,
      "open_library_work_key": "/works/OL27482W",
      "edition_count": 481,
      "author_keys": ["OL26320A"],
      "best_edition": {
        "edition_key": "OL51709286M",
        "isbn_13": "9780395520215",
        "isbn_10": "0395520215"
      },
      "cover_url": "https://covers.openlibrary.org/b/id/14627509-M.jpg",
      "ratings_average": 4.29,
      "ebook_access": "borrowable"
    }
  ]
}

get_authors_by_name 输入示例：

{
  "name": "J. R. R. Tolkien",
  "limit": 2
}

get_authors_by_name 输出示例：

每个结果的 key 都可以传给 get_author_info，以获取该作者的完整记录。此处省略了部分 alternate_names 内容。

{
  "num_found": 2,
  "offset": 0,
  "limit": 2,
  "results": [
    {
      "key": "OL26320A",
      "name": "J.R.R. Tolkien",
      "alternate_names": ["John Ronald Reuel Tolkien", "Tolkien"],
      "birth_date": "3 January 1892",
      "top_work": "The Hobbit",
      "work_count": 355
    },
    {
      "key": "OL332676A",
      "name": "J. R. R. Tolkien Centenary Conference (1992 Keble College, Oxford)",
      "top_work": "Proceedings of the J.R.R. Tolkien Centenary Conference, 1992",
      "work_count": 2
    }
  ]
}

get_author_info 输入示例：

{
  "author_key": "OL26320A"
}

get_author_info 输出示例：

{
  "name": "J. R. R. Tolkien",
  "personal_name": "John Ronald Reuel Tolkien",
  "birth_date": "3 January 1892",
  "death_date": "2 September 1973",
  "bio": "John Ronald Reuel Tolkien (1892-1973) was a major scholar of the English language, specializing in Old and Middle English. He served as the Rawlinson and Bosworth Professor of Anglo-Saxon and later the Merton Professor of English Language and Literature at Oxford University.",
  "alternate_names": ["John Ronald Reuel Tolkien"],
  "photos": [6791763],
  "key": "/authors/OL26320A",
  "remote_ids": {
    "viaf": "95218067",
    "wikidata": "Q892"
  },
  "revision": 43,
  "last_modified": {
    "type": "/type/datetime",
    "value": "2023-02-12T05:50:22.881"
  }
}

get_author_photo 输入示例：

{
  "olid": "OL26320A"
}

get_author_photo 输出示例：

https://covers.openlibrary.org/a/olid/OL26320A-L.jpg

如果 Open Library 没有该作者的照片，工具会说明这一点，而不是返回 URL：

No author photo available for OLID OL99999999A.

get_book_cover 输入示例：

{
  "key": "ISBN",
  "value": "9780547928227",
  "size": "L"
}

get_book_cover 输出示例：

https://covers.openlibrary.org/b/isbn/9780547928227-L.jpg

与作者照片一样，如果图书没有封面，工具会返回一条说明，而不是 URL：

No cover image available for OLID OL00000000M.

get_book_cover 工具接受以下参数：

• key：标识符类型（可选：ISBN、OCLC、LCCN、OLID 或 ID）
• value：标识符的值
• size：可选的封面尺寸（S 表示小，M 表示中，L 表示大；默认值为 L）

get_book_by_id 输入示例：

{
  "idType": "isbn",
  "idValue": "9780547928227"
}

get_book_by_id 输出示例：

{
  "title": "The Hobbit",
  "authors": [
    "J. R. R. Tolkien"
  ],
  "publishers": [
    "Houghton Mifflin Harcourt"
  ],
  "publish_date": "October 21, 2012",
  "number_of_pages": 300,
  "isbn_13": [
    "9780547928227"
  ],
  "isbn_10": [
    "054792822X"
  ],
  "oclc": [
    "794607877"
  ],
  "olid": [
    "OL25380781M"
  ],
  "open_library_edition_key": "/books/OL25380781M",
  "open_library_work_key": "/works/OL45883W",
  "cover_url": "https://covers.openlibrary.org/b/id/8231496-M.jpg",
  "info_url": "https://openlibrary.org/books/OL25380781M/The_Hobbit",
  "preview_url": "https://archive.org/details/hobbit00tolkien"
}

get_book_by_id 工具接受以下参数：

• idType：标识符类型（可选：isbn、lccn、oclc、olid）
• idValue：标识符的值

此工具在 Claude Desktop 中的使用示例：

Docker

你可以使用 Docker 测试此 MCP 服务。首先运行：

docker build -t mcp-open-library .
docker run -p 8080:8080 mcp-open-library

然后，你可以通过 inspector 测试 Docker 中运行的服务，例如：

npm run inspector http://localhost:8080

开发

项目结构

• src/index.ts - MCP 服务：构建 HTTP 客户端，并通过工具注册表调用两个请求处理程序
• src/index.test.ts - 服务连线测试，包括已发布工具架构的快照
• src/tools/<tool-name>/ - 每个工具对应一个目录，其中包含 index.ts（处理程序、Zod 参数架构及其 ToolDefinition）、index.test.ts，以及——对于 API 响应较复杂的工具——描述响应结构的 types.ts
• src/tools/registry.ts - TOOLS 数组，即服务公开的唯一工具列表
• src/tools/types.ts - ToolDefinition 和 ToolHandler 合约
• src/utils/ - 共享基础设施：http.ts（API 和封面 Axios 客户端）、errors.ts（参数解析和错误结果）、results.ts、schema.ts（Zod → JSON Schema）、search.ts（共享的搜索投影和分页架构）、covers.ts
• scripts/ - 发布自动化脚本（sync-server-json.mjs、promote-changelog.mjs、assert-release-consistency.mjs）及其测试

工具的输入合约只需声明一次，使用 Zod 架构即可。MCP 客户端看到的 JSON Schema 由 toInputSchema 生成，因此二者不会出现偏差。字段描述来自 Zod 架构上的 .describe()。请注意，.refine() 约束在转换时会被丢弃——跨字段规则也必须写在工具的 description 中，否则客户端将无法获知。

添加工具时，需要创建对应目录，并在 src/tools/registry.ts 的 TOOLS 中添加一项。src/index.test.ts 会根据该数组生成预期结果，因此唯一需要更改的测试内容是更新架构快照（npx vitest run -u）。

可用脚本

• npm run build - 构建 TypeScript 代码
• npm run watch - 监视更改并重新构建
• npm test - 以监视模式运行测试套件
• npm run test:precommit - 运行一次测试套件后退出
• npm run lint / npm run lint:fix - 使用 ESLint 检查 src 和 scripts
• npm run format - 使用 Prettier 格式化代码
• npm run inspector - 对服务运行 MCP Inspector

运行测试

npm test 会以监视模式启动 Vitest：

npm test

如需单次运行（预提交钩子和 CI 所执行的方式），请使用：

npm run test:precommit

如需运行单个文件或单个测试用例：

npx vitest run src/tools/get-book-by-id/index.test.ts
npx vitest run -t "should return book details when given a valid OLID"

发布

发布流程已自动化。推送 v* 标签会触发 publish-mcp.yml，运行检查、将软件包发布到 npm、 向 MCP Registry 注册新版本，然后使用该版本的 CHANGELOG.md 条目作为说明创建 GitHub Release。npm 和注册表都通过 GitHub OIDC 进行身份验证，因此无需管理发布密钥。

package.json 中的 version 是唯一事实来源。npm version 会通过 version 生命周期钩子从中推导其他所有内容，因此发布只需一条命令：

npm version patch   # or minor / major
git push --follow-tags

这条命令会更新 package.json，将 server.json 重写为匹配的版本，将变更日志中的 ## [Unreleased] 标题替换为新版本和当天日期，并将所有更改提交到同一个标签下。

运行之前需要了解两件事：

• 先编写变更日志条目。 合并工作时，将条目写在 CHANGELOG.md 的 ## [Unreleased] 标题下。如果缺少该标题， npm version 会失败，而不会发布未记录的内容。如果确实失败，请用 git restore --source=HEAD --staged --worktree package.json package-lock.json server.json 撤销未完成的版本更新。
• 工作树必须干净，而且 npm version 运行时会执行提交前钩子（lint + 完整测试套件）。

在发布任何内容之前，CI 会再次确认标签、package.json、server.json 和 CHANGELOG.md 中的信息一致——请参阅 scripts/assert-release-consistency.mjs。对于修改这些文件的拉取请求，也会运行相同的检查。

npm version 不能用于重试

一旦它输出新标签，提交和标签就已创建，发布在本地也已完成——下一步应运行 git push --follow-tags，而不是再次运行 npm version。再次运行会尝试下一个 版本，并因缺少 ## [Unreleased] 标题而失败（第一次运行已将其移除）。这种失败是有意设计的， 但会导致 package.json、package-lock.json 和 server.json 已更新却尚未提交。使用以下命令撤销：

git restore --source=HEAD --staged --worktree package.json package-lock.json server.json

如果发布工作流失败

只有遇到暂时性故障时，从 Actions 选项卡重新运行任务才有帮助。GitHub 会运行 标签所指向的提交中包含的工作流版本，因此，工作流本身或 server.json 中的错误无法通过 重新运行修复——修复必须包含在标签所指向的提交中。

在工作流运行到 npm 步骤之前，不会发布任何内容；因此，如果它在此之前失败，版本仍可使用，你可以移动标签：

# fix the problem on main and commit it first
VERSION="$(node -p "require('./package.json').version")"

git push origin ":v${VERSION}"            # delete the remote tag e.g. git push origin :v1.0.3
git tag -d "v${VERSION}"                  # delete it locally
git tag -a "v${VERSION}" -m "${VERSION}"  # re-tag at the fixed commit
git push origin "v${VERSION}"

修复提交必须让 package.json 保持在同一版本，否则一致性检查会拒绝该标签。如果 npm 已经发布，请勿重复使用该版本——该发布不可更改。改用下一个补丁版本；受保护的 npm 步骤会在重新运行时跳过已成功的步骤。

参与贡献

欢迎贡献！请随时提交拉取请求。

致谢

• Open Library API
• Model Context Protocol