gutenberg-mcp-server

---

概览

Project Gutenberg 收录了 78,000+ 本公版书籍。可按书名、作者、主题或语言进行搜索，获取完整的书籍元数据，并分块阅读受支持的 UTF-8 纯文本和 HTML 版本。

工具

工具	描述
gutenberg_search_books	按书名、作者、主题、语言或作者生卒年份搜索目录，支持分页和按热度排序
gutenberg_get_book	按 ID 获取书籍的完整元数据——作者、译者、编辑、完整格式映射、主题和版权状态
gutenberg_get_text	获取去除许可证声明文本后的纯文本内容，并支持基于 offset/limit 的分块读取
gutenberg_browse_popular	浏览下载量最高的书籍，可选按语言或主题筛选

---

功能参考

gutenberg_search_books _工具

• 筛选条件：query（书名/作者关键词）、topic、languages（ISO 639-1）、author_year_start/author_year_end、ids、mime_type 和 copyright（"true"、"false"、"null"；false 表示在美国属于公版）。实时回退查询不接受超过四个词的查询
• sort 可设为 popular（默认值），或按 Gutenberg ID 以 ascending/descending 排序。每页最多 32 本书；使用 totalCount 和 hasMore 翻页
• 每条结果都包含 is_readable（可通过 gutenberg_get_text 阅读）和 has_plain_text。可能返回 query_requires_mirror、page_out_of_range 或 catalog_unavailable 错误

---

gutenberg_get_book _工具

• 返回完整的 formats 映射（MIME 类型 → 下载 URL），以及包含出生和去世年份的作者、译者和编辑信息
• 还包含 is_readable、has_plain_text、summary、source_notes 和 download_count（过去 30 天的下载量，而非累计下载量）
• 失败时返回 not_found 或 catalog_unavailable

---

gutenberg_get_text _工具

• 以 offset/limit 分块读取图书（默认 limit 为 20,000，上限为 50,000），并剥除 Gutenberg 许可声明的页眉和页脚。requestedLimit 和 appliedLimit 会分别报告请求值和实际值
• 优先使用 UTF-8 纯文本，无法使用时则回退到转换为文本的 HTML；sourceFormat 会说明所用格式。返回 totalChars、length、remainingChars、hasMore 和 provenance（ID、标题、许可 URL）。计算下一个 offset 时请使用 length，而不是 limit
• 失败时返回 not_found、audio_book（media_type "Sound"）、no_text_format、offset_out_of_range、text_file_not_found、text_fetch_rejected、invalid_text_response、text_fetch_failed 或 catalog_unavailable

---

gutenberg_browse_popular _工具

• 返回最多 32 本图书（limit 默认值为 20），按过去 30 天的下载量从高到低排列。requestedLimit 和 appliedLimit 会报告上限
• 可选的 languages、topic、mime_type 和 copyright 筛选条件与搜索中的相同。totalInCatalog 提供目录中的完整条目数
• 输出会报告结果是否经过截断，并包含指向 gutenberg_search_books 的 continuation。无结果时会成功返回通知；失败时返回 catalog_unavailable

---

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可切换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及结构化日志和可选的 OpenTelemetry 跟踪。

Gutenberg 专属功能：

• 搜索和查询会读取本地 SQLite+FTS5 目录镜像；镜像尚未加载或缺少记录时，会回退到 Gutendex
• 从 Project Gutenberg 内容镜像获取完整纯文本，并在 UTF-8/HTML 之间回退
• 图书文本按租户缓存，因此后续分块读取无需再次获取
• 无需 API 密钥

便于 Agent 使用的输出：

• 每条搜索和浏览结果中的 is_readable 会标记 gutenberg_get_text 可读取的版本
• offset、length、totalChars、remainingChars 和 hasMore 支持可靠的顺序读取
• 每个文本响应中的 provenance 和 sourceFormat 都会提供来源归属和保真度信息

---

开始使用

公共托管实例

可使用公共实例 https://gutenberg.caseyjhand.com/mcp，无需安装。通过 Streamable HTTP 将任何 MCP 客户端指向该实例：

{
  "mcpServers": {
    "gutenberg-mcp-server": {
      "type": "streamable-http",
      "url": "https://gutenberg.caseyjhand.com/mcp"
    }
  }
}

自托管 / 本地部署

无需 API 密钥。将以下内容添加到 MCP 客户端配置文件中：

{
  "mcpServers": {
    "gutenberg-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/gutenberg-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

也可以使用 npx（无需 Bun）：

{
  "mcpServers": {
    "gutenberg-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/gutenberg-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

也可以使用 Docker：

{
  "mcpServers": {
    "gutenberg-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/gutenberg-mcp-server:latest"
      ]
    }
  }
}

若要使用 Streamable HTTP，请设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前置条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 无需 API 密钥 — Project Gutenberg 数据可免费获取。

安装

1. 克隆仓库：

git clone https://github.com/cyanheads/gutenberg-mcp-server.git

2. 进入目录：

cd gutenberg-mcp-server

3. 安装依赖项：

bun install

4. 配置环境：

cp .env.example .env
# edit .env if you need to override any defaults

---

配置

变量	描述	默认值
GUTENDEX_BASE_URL	Gutendex 目录 API 基础 URL。	https://gutendex.com/books/
GUTENBERG_TEXT_BASE_URL	提供 /cache/epub 文件树的内容镜像。	https://gutenberg.pglaf.org
GUTENBERG_MIRROR_PATH	SQLite 目录路径；在容器中请使用持久卷。	./.mirror/gutenberg-catalog.sqlite
GUTENBERG_MIRROR_REFRESH_CRON	进程内目录刷新的 Cron 计划。	未设置
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_SESSION_MODE	HTTP 会话模式：auto、stateful 或 stateless。覆盖服务在 createApp() 中声明的 stateless 状态。	stateless
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（RFC 5424）。	info
LOGS_DIR	日志文件目录（仅限 Node.js）。	<project-root>/logs
STORAGE_PROVIDER_TYPE	存储后端。	in-memory
OTEL_ENABLED	启用 OpenTelemetry 插桩。	false

使用 bun run mirror:init 构建本地目录，并使用 bun run mirror:verify 检查。服务启动时不会抓取数据，在首次抓取完成前会使用 Gutendex。可通过主机计划任务运行 bun run mirror:refresh 来更新目录，或设置 GUTENBERG_MIRROR_REFRESH_CRON。

---

运行服务

本地开发

• 构建并运行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t gutenberg-mcp-server .
docker run --rm -p 3010:3010 gutenberg-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/gutenberg-mcp-server。默认会安装 OpenTelemetry 对等依赖项——构建时使用 --build-arg OTEL_ENABLED=false 可省略这些依赖项。

---

项目结构

目录	用途
src/index.ts	createApp() 入口点——注册工具并初始化服务。
src/config/server-config.ts	服务专用环境变量解析（Gutendex 和文件服务 URL 覆盖项）。
src/mcp-server/tools/definitions/	工具定义（*.tool.ts）。
src/services/gutendex/	Gutendex 目录 API 客户端——搜索和书籍元数据。
src/services/catalog-mirror/	本地 SQLite+FTS5 目录镜像——RDF 导入和读取辅助函数。
src/services/gutenberg-text/	完整纯文本检索、模板内容剥离、租户范围缓存和分块。
tests/	与 src/ 对应的单元测试和集成测试。

---

开发指南

开发指南和架构规则请参阅 CLAUDE.md / AGENTS.md。简要来说：

• 处理器抛出异常，由框架捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 进行请求范围内的日志记录，使用 ctx.state 进行租户范围内的存储
• 通过 src/index.ts 中的入口数组注册新工具
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出模式；绝不捏造缺失字段

---

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

---

数据归属

Project Gutenberg 的数据属于公共领域。目录元数据来源于 Gutendex（MIT 许可证）。

---

许可证

Apache-2.0——详情请参阅 LICENSE。